🚀 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

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

2. 身份验证失败

Error: TC_TOKEN environment variable is required

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

3. 无效的超时格式

Error: invalid TC_TIMEOUT format

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

4. 端口已被使用

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。