Teamcity Mcp

Teamcity Mcp

开发 Go

🚀 TeamCity MCP 服务器

TeamCity MCP 服务器是一个全面的模型上下文协议（MCP）服务器，它将 JetBrains TeamCity 作为结构化的、适用于大语言模型（LLM）代理和集成开发环境（IDE）插件的资源和工具进行公开。

🚀 快速开始

IDE 集成（Cursor）

TeamCity MCP 服务器旨在与 Cursor 等支持人工智能的 IDE 无缝协作。以下是配置步骤：

Cursor 配置

将以下内容添加到你的 Cursor MCP 设置中：

{
"mcpServers": {
"teamcity": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"TC_URL",
"-e",
"TC_TOKEN",
"itcaat/teamcity-mcp:latest",
"--transport",
"stdio"
],
"env": {
"TC_URL": "https://your-teamcity-server.com",
"TC_TOKEN": "your-teamcity-api-token"
}
}
}
}

📦 安装指南

本地开发

1. 构建服务器

make build
# 此命令将创建 ./bin/teamcity-mcp 并生成一个符号链接 ./server

2. 设置环境变量

# 必需
export TC_URL="https://your-teamcity-server.com"

# 可选（启用 HMAC 身份验证）
export SERVER_SECRET="your-hmac-secret-key"

# 身份验证
export TC_TOKEN="your-teamcity-api-token"

3. 运行服务器

./server
# 服务器默认在 :8123 端口启动

4. 测试服务器

# 健康检查
curl http://localhost:8123/healthz

# MCP 协议测试
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-hmac-secret-key" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}'

预期结果：健康检查端点应返回 {"status":"ok"}，MCP 端点应返回初始化响应。

✨ 主要特性

  • MCP 协议合规性：全面支持基于 HTTP/WebSocket 的 JSON-RPC 2.0 协议。
  • TeamCity 集成：通过身份验证与 TeamCity 的 REST API 进行完整集成。
  • 资源访问：可访问项目、构建类型、构建、代理和工件等资源。
  • 构建操作：支持触发、取消、固定构建，设置标签，下载工件以及搜索构建等操作。
  • 高级搜索：提供全面的构建搜索功能，支持多种过滤条件（状态、分支、用户、日期、标签等）。
  • 生产就绪：支持 Docker、Kubernetes 部署，具备监控、缓存和全面的日志记录功能。
  • 基于环境的配置：无需配置文件，所有配置均可通过环境变量完成。

🔧 技术细节

环境变量参考

必需变量

属性 详情 示例
TC_URL TeamCity 服务器的 URL https://teamcity.company.com
SERVER_SECRET 用于客户端身份验证的 HMAC 密钥（可选） my-secure-secret-123

身份验证变量

属性 详情 示例
TC_TOKEN TeamCity API 令牌 eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

可选变量

属性 默认值 详情 示例
LISTEN_ADDR :8123 服务器监听地址 :8080 或 0.0.0.0:8123
TC_TIMEOUT 30s TeamCity API 超时时间 60s 或 2m
TLS_CERT TLS 证书路径 /path/to/cert.pem
TLS_KEY TLS 私钥路径 /path/to/key.pem
LOG_LEVEL info 日志级别 debug、info、warn、error
LOG_FORMAT json 日志格式 json 或 console
CACHE_TTL 10s API 响应缓存的 TTL 30s 或 1m

配置示例

开发环境

export TC_URL=http://localhost:8111
export TC_TOKEN=dev-token-123
export SERVER_SECRET=dev-secret
export LOG_LEVEL=debug
export LOG_FORMAT=console
./server

生产环境

export TC_URL=https://teamcity.company.com
export TC_TOKEN=$TEAMCITY_API_TOKEN
export SERVER_SECRET=$MCP_SERVER_SECRET
export TLS_CERT=/etc/ssl/certs/teamcity-mcp.pem
export TLS_KEY=/etc/ssl/private/teamcity-mcp.key
export LOG_LEVEL=warn
export CACHE_TTL=30s
./server

Docker 部署

构建并运行

# 构建 Docker 镜像
make docker

# 使用环境变量运行
docker run -p 8123:8123 \
-e TC_URL=https://teamcity.company.com \
-e TC_TOKEN=your-token \
-e SERVER_SECRET=your-secret \
teamcity-mcp:latest

Docker Compose

# 使用 Docker Compose 启动
docker-compose up -d

# 查看日志
docker-compose logs -f teamcity-mcp

Kubernetes 部署

使用 Helm

# 使用 Helm 部署
helm install teamcity-mcp ./helm/teamcity-mcp \
--set teamcity.url=https://teamcity.company.com \
--set secrets.teamcityToken=your-token \
--set secrets.serverSecret=your-secret

手动 Kubernetes 部署

apiVersion: v1
kind: Secret
metadata:
name: teamcity-mcp-secrets
type: Opaque
stringData:
teamcity-token: "your-teamcity-token"
server-secret: "your-server-secret"
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: teamcity-mcp
spec:
replicas: 1
selector:
matchLabels:
app: teamcity-mcp
template:
metadata:
labels:
app: teamcity-mcp
spec:
containers:
- name: teamcity-mcp
image: teamcity-mcp:latest
ports:
- containerPort: 8123
env:
- name: TC_URL
value: "https://teamcity.company.com"
- name: TC_TOKEN
valueFrom:
secretKeyRef:
name: teamcity-mcp-secrets
key: teamcity-token
- name: SERVER_SECRET
valueFrom:
secretKeyRef:
name: teamcity-mcp-secrets
key: server-secret

命令行选项

标志 描述 默认值
--help 显示环境变量帮助信息
--version 显示版本信息
--transport 传输模式：http 或 stdio http

帮助和文档

# 显示环境变量帮助信息
./server --help

# 显示版本信息
./server --version

# 显示命令行使用说明
./server -h

💻 使用示例

测试和验证

自动化验证

使用包含的验证脚本来测试所有功能：

# 运行所有测试
./scripts/verify.sh

# 可用选项：
./scripts/verify.sh help     # 显示帮助信息
./scripts/verify.sh start    # 仅启动服务器
./scripts/verify.sh stop     # 仅停止服务器
./scripts/verify.sh clean    # 清理进程

手动测试

# 1. 设置环境变量
export TC_URL=http://localhost:8111
export TC_TOKEN=test-token
export SERVER_SECRET=test-secret

# 2. 启动服务器
./server &

# 3. 测试健康状态
curl http://localhost:8123/healthz

# 4. 测试 MCP 协议
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer test-secret" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}'

# 5. 停止服务器
pkill -f teamcity-mcp

开发测试

# 安装依赖
make deps

# 运行单元测试
make test

# 运行集成测试
make test-integration

# 运行负载测试
make test-load

# 运行代码检查
make lint

# 格式化代码
make format

# 清理构建产物
make clean

可用的 Make 命令

使用 make help 查看所有可用命令：

# 基本命令
make build                # 构建二进制文件
make test                 # 运行测试
make clean                # 清理构建产物
make deps                 # 下载依赖
make lint                 # 运行代码检查
make format               # 格式化代码

# Docker 命令
make docker               # 构建 Docker 镜像
make docker-push          # 推送 Docker 镜像

# 运行命令
make run                  # 运行应用程序
make run-stdio            # 以 STDIO 模式运行
make dev                  # 以开发模式运行，支持热重载

# Docker Compose 命令
make compose-up           # 使用 Docker Compose 启动服务
make compose-down         # 停止服务
make compose-logs         # 显示日志

# 测试命令
make test-integration     # 使用 Docker 运行集成测试
make test-load            # 运行负载测试

# 开发工具
make install-tools        # 安装开发工具

# 发布命令
make release-snapshot     # 使用 GoReleaser 构建快照版本
make release-check        # 检查 GoReleaser 配置

# CI 命令
make ci                   # 运行 CI 检查（依赖、代码检查、测试、构建）
make check                # 运行所有检查（代码检查、测试、构建）

MCP 协议测试

初始化 MCP 会话

curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": {
"name": "test-client",
"version": "1.0.0"
}
}
}'

列出资源

curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "resources/list",
"params": {}
}'

列出工具

curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/list",
"params": {}
}'

可用工具

TeamCity MCP 服务器提供了 6 个强大的工具来管理构建：

1. trigger_build

在 TeamCity 中触发新的构建。 参数：

  • buildTypeId（必需）：构建配置的 ID。
  • branchName（可选）：要构建的分支名称。
  • properties（可选）：构建属性对象。

示例：

curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "trigger_build",
"arguments": {
"buildTypeId": "YourProject_BuildConfiguration",
"branchName": "main",
"properties": {
"env.DEPLOY_ENV": "staging"
}
}
}
}'

2. cancel_build

取消正在运行的构建。 参数：

  • buildId（必需）：要取消的构建 ID。
  • comment（可选）：取消构建的注释。

示例：

curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "cancel_build",
"arguments": {
"buildId": "12345",
"comment": "Cancelled due to urgent hotfix"
}
}
}'

3. pin_build

固定或取消固定构建，以防止其被清理。 参数：

  • buildId（必需）：要固定或取消固定的构建 ID。
  • pin（必需）：true 表示固定，false 表示取消固定。
  • comment（可选）：固定构建的注释。

示例：

curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "pin_build",
"arguments": {
"buildId": "12345",
"pin": true,
"comment": "Release candidate build"
}
}
}'

4. set_build_tag

为构建添加或移除标签。 参数：

  • buildId（必需）：构建的 ID。
  • tags（可选）：要添加的标签数组。
  • removeTags（可选）：要移除的标签数组。

示例：

curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "set_build_tag",
"arguments": {
"buildId": "12345",
"tags": ["release", "v1.2.3"],
"removeTags": ["beta"]
}
}
}'

5. download_artifact

下载构建工件。 参数：

  • buildId（必需）：构建的 ID。
  • artifactPath（必需）：工件的路径。

示例：

curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 8,
"method": "tools/call",
"params": {
"name": "download_artifact",
"arguments": {
"buildId": "12345",
"artifactPath": "dist/app.zip"
}
}
}'

6. search_builds

使用全面的过滤选项搜索构建。 参数（均为可选）：

  • buildTypeId：按构建配置 ID 过滤。
  • status：按构建状态过滤（SUCCESS、FAILURE、ERROR、UNKNOWN）。
  • state：按构建状态过滤（排队、运行、完成）。
  • branch：按分支名称过滤。
  • agent：按代理名称过滤。
  • user：按触发构建的用户过滤。
  • sinceBuild：从指定构建 ID 开始搜索构建。
  • sinceDate：从指定日期（YYYYMMDDTHHMMSS+HHMM）开始搜索构建。
  • untilDate：搜索截至指定日期（YYYYMMDDTHHMMSS+HHMM）的构建。
  • tags：按标签数组过滤。
  • personal：是否包含个人构建（布尔值）。
  • pinned：按固定状态过滤（布尔值）。
  • count：返回的最大构建数量（1 - 1000，默认值：100）。

示例：

  • 搜索失败的构建：
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 9,
"method": "tools/call",
"params": {
"name": "search_builds",
"arguments": {
"status": "FAILURE",
"count": 10
}
}
}'
  • 搜索主分支上的近期构建：
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 10,
"method": "tools/call",
"params": {
"name": "search_builds",
"arguments": {
"branch": "main",
"state": "finished",
"count": 20
}
}
}'
  • 搜索带有特定标签的构建：
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 11,
"method": "tools/call",
"params": {
"name": "search_builds",
"arguments": {
"tags": ["release", "production"],
"pinned": true
}
}
}'

本地二进制配置

如果你更喜欢使用本地二进制文件而不是 Docker，可以使用以下配置：

{
"teamcity": {
"command": "/path/to/teamcity-mcp",
"args": ["--transport", "stdio"],
"env": {
"TC_URL": "https://your-teamcity-server.com",
"TC_TOKEN": "your-teamcity-api-token"
}
}
}

在 Cursor 中的使用

配置完成后，你可以使用自然语言命令，例如：

  • “搜索上周失败的构建”
  • “触发主分支的构建”
  • “显示项目 X 的近期构建”
  • “固定最新的成功构建”
  • “取消正在运行的构建 12345”
  • “为构建 12345 添加发布标签”

人工智能将自动使用相应的 TeamCity 工具来满足你的需求。

可用资源

服务器将 TeamCity 数据作为 MCP 资源公开：

  • teamcity://projects - 列出所有项目
  • teamcity://buildTypes - 列出所有构建配置
  • teamcity://builds - 列出近期构建
  • teamcity://agents - 列出构建代理

📚 详细文档

故障排除

常见问题

  1. 缺少必需的环境变量
Error: TC_URL environment variable is required

解决方案：设置所有必需的环境变量。

  1. 身份验证失败
Error: TC_TOKEN environment variable is required

解决方案：使用你的 TeamCity API 令牌设置 TC_TOKEN。

  1. 无效的超时格式
Error: invalid TC_TIMEOUT format

解决方案：使用有效的持续时间格式，如 30s、1m、2h。

  1. 端口已被使用
Error: listen tcp :8123: bind: address already in use

解决方案：将 LISTEN_ADDR 设置为不同的端口，或停止冲突的服务。

调试模式

启用调试日志记录：

export LOG_LEVEL=debug
export LOG_FORMAT=console
./server

健康检查

服务器提供了一个健康检查端点：

curl http://localhost:8123/healthz
# 预期结果：{"service":"teamcity-mcp","status":"ok","timestamp":"..."}

指标

可以获取 Prometheus 指标：

curl http://localhost:8123/metrics

TeamCity 集成测试

验证 TeamCity 连接性：

# 检查 TeamCity 服务器的可访问性
curl -H "Authorization: Bearer your-token" \
http://your-teamcity-url/app/rest/projects

# 验证身份验证
curl -H "Authorization: Bearer your-token" \
http://your-teamcity-url/app/rest/server

协议参考

有关详细的 MCP 协议实现和 TeamCity API 映射，请参阅 Protocol.md。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE。

默认排序 时间排序

0 个评论

« 上一篇
Mcptools
下一篇 »
Haproxy Mcp Server
  • 0 关注
  • 0 收藏，29 浏览
  • system 提出于 2025-10-06 07:03

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »