TeamCity MCP服务器
一个全面的模型上下文协议(MCP)服务器,将JetBrains TeamCity暴露为LLM代理和IDE插件的结构化AI就绪资源和工具。
快速开始
IDE集成(游标)
TeamCity MCP服务器旨在与Cursor等AI驱动的IDE无缝协作。以下是如何配置它:
光标配置
将此添加到光标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
# This creates ./bin/teamcity-mcp and a symlink ./server2.设置环境变量
# Required
export TC_URL="https://your-teamcity-server.com"
# Optional (enables HMAC authentication)
export SERVER_SECRET="your-hmac-secret-key"
# Authentication
export TC_TOKEN="your-teamcity-api-token"3.运行服务器
./server
# Server starts on :8123 by default4.测试服务器
# Health check
curl http://localhost:8123/healthz
# MCP protocol test
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集成:完成REST API与身份验证的集成
- 资源访问:项目、构建类型、构建、代理和工件
- 构建操作:触发、取消、引脚构建、设置标签、下载工件、搜索构建
- 高级搜索:具有多个过滤器(状态、分支、用户、日期、标签)的全面构建搜索
- 生产就绪:Docker、Kubernetes、监控、缓存和全面的日志记录
- 基于环境的配置:不需要配置文件,一切都通过环境变量
- AI时间感知:提供真实的当前日期/时间,以防止AI模型使用训练数据日期
环境变量引用
必需变量
| 变量 | 描述 | 示例 |
|---|---|---|
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
./serverDocker部署
构建并运行
# Build Docker image
make docker
# Run with environment variables
docker run -p 8123:8123 \
-e TC_URL=https://teamcity.company.com \
-e TC_TOKEN=your-token \
-e SERVER_SECRET=your-secret \
teamcity-mcp:latestDocker Compose
# Start with docker-compose
docker-compose up -d
# Check logs
docker-compose logs -f teamcity-mcpKubernetes部署
使用Helm
# Deploy with Helm
helm install teamcity-mcp ./helm/teamcity-mcp \
--set teamcity.url=https://teamcity.company.com \
--set secrets.teamcityToken=your-token \
--set secrets.serverSecret=your-secretKubernetes手动部署
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 |
帮助和文档
# Show environment variable help
./server --help
# Show version
./server --version
# Show command line usage
./server -h测试和验证
自动验证
使用附带的验证脚本测试所有功能:
# Run all tests
./scripts/verify.sh
# Available options:
./scripts/verify.sh help # Show help
./scripts/verify.sh start # Start server only
./scripts/verify.sh stop # Stop server only
./scripts/verify.sh clean # Clean up processes手动测试
# 1. Set environment variables
export TC_URL=http://localhost:8111
export TC_TOKEN=test-token
export SERVER_SECRET=test-secret
# 2. Start server
./server &
# 3. Test health
curl http://localhost:8123/healthz
# 4. Test MCP protocol
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. Stop server
pkill -f teamcity-mcp开发测试
# Install dependencies
make deps
# Run unit tests
make test
# Run integration tests
make test-integration
# Run load tests
make test-load
# Run linter
make lint
# Format code
make format
# Clean build artifacts
make clean可用的生成命令
使用 make help 查看所有可用命令:
# Basic commands
make build # Build the binary
make test # Run tests
make clean # Clean build artifacts
make deps # Download dependencies
make lint # Run linters
make format # Format code
# Docker commands
make docker # Build Docker image
make docker-push # Push Docker image
# Running commands
make run # Run the application
make run-stdio # Run in STDIO mode
make dev # Run in development mode with hot reload
# Docker Compose commands
make compose-up # Start services with Docker Compose
make compose-down # Stop services
make compose-logs # Show logs
# Testing commands
make test-integration # Run integration tests with Docker
make test-load # Run load tests
# Development tools
make install-tools # Install development tools
# Release commands
make release-snapshot # Build snapshot release with GoReleaser
make release-check # Check GoReleaser configuration
# CI commands
make ci # Run CI checks (deps, lint, test, build)
make check # Run all checks (lint, test, build)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服务器提供了10个强大的工具来管理构建:
1.触发器_构建
在TeamCity中触发新的构建。
参数:
buildTypeId(必需):生成配置IDbranchName(可选):要构建的分支名称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.取消构建
取消正在运行的构建。
参数:
buildId(必填):要取消的内部版本IDcomment(可选):取消评论
例子:
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(必填):对pin为true,对unpin为falsecomment(可选):固定评论
例子:
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(必填):内部版本IDtags(可选):要添加的标签数组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.下载_广告
下载构建工件。
参数:
buildId(必填):内部版本IDartifactPath(必填):工件路径
例子:
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.搜索建筑
搜索具有全面过滤选项的版本。
参数(全部可选):
buildTypeId:按构建配置ID筛选status:按构建状态筛选(成功、失败、错误、未知)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
}
}
}'7.fetch_build_log
获取特定构建的构建日志,并使用过滤选项来处理大型日志。
参数:
buildId(必需):生成ID以获取日志plain(可选):以纯文本形式返回日志(默认值:true)archived(可选):将日志作为zip存档返回(默认值:false)dateFormat(可选):自定义时间戳格式(Java SimpleDateFormat)maxLines(可选):返回的最大行数(过滤后应用)filterPattern(可选):用于过滤日志行的正则表达式模式severity(可选):按严重性级别筛选:“错误”、“警告”或“信息”tailLines(可选):仅返回最后N行(过滤后应用)
示例:
仅提取错误(限制为50行):
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 12,
"method": "tools/call",
"params": {
"name": "fetch_build_log",
"arguments": {
"buildId": "12345",
"severity": "error",
"maxLines": 50
}
}
}'获取与模式匹配的行:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 13,
"method": "tools/call",
"params": {
"name": "fetch_build_log",
"arguments": {
"buildId": "12345",
"filterPattern": "test.*failed",
"maxLines": 100
}
}
}'获取最后200行:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 14,
"method": "tools/call",
"params": {
"name": "fetch_build_log",
"arguments": {
"buildId": "12345",
"tailLines": 200
}
}
}'获取存档的构建日志:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 15,
"method": "tools/call",
"params": {
"name": "fetch_build_log",
"arguments": {
"buildId": "12345",
"archived": true
}
}
}'8.搜索_建筑配置
搜索具有全面过滤选项的构建配置,包括基本过滤器、参数、步骤和VCS根。
参数(全部可选):
基本过滤器:
projectId:按项目ID筛选name:按配置名称搜索(部分匹配)enabled:按启用状态筛选(布尔值)paused:按暂停状态筛选(布尔值)template:筛选模板(true)或常规配置(false)(布尔值)count:要返回的最大配置数(1-1000,默认值:100)
高级过滤器:
parameterName:按参数名称搜索(部分匹配)parameterValue:按参数值搜索(部分匹配)stepType:按构建步骤类型搜索(例如,“gradle”、“docker”、“powershell”)stepName:按构建步骤名称搜索(部分匹配)vcsType:按VCS类型搜索(例如“git”、“subversion”)includeDetails:在结果中包含详细信息(参数、步骤、VCS)(布尔值,默认值:false)
示例:
按名称进行基本搜索:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 15,
"method": "tools/call",
"params": {
"name": "search_build_configurations",
"arguments": {
"name": "Test",
"enabled": true
}
}
}'使用参数筛选器搜索:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 16,
"method": "tools/call",
"params": {
"name": "search_build_configurations",
"arguments": {
"parameterName": "env.DEPLOY_TARGET",
"parameterValue": "production",
"includeDetails": true
}
}
}'搜索Gradle配置:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 17,
"method": "tools/call",
"params": {
"name": "search_build_configurations",
"arguments": {
"stepType": "gradle",
"projectId": "MyProject",
"includeDetails": true
}
}
}'搜索基于Git的配置:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 18,
"method": "tools/call",
"params": {
"name": "search_build_configurations",
"arguments": {
"vcsType": "git",
"stepName": "Deploy"
}
}
}'9.get_current_time
获取当前服务器日期和时间,以确保AI模型使用实时时间而不是训练数据日期。
参数:
format(可选):日期格式(rfc3339、日期、时间戳或自定义Go格式)timezone(可选):时区(例如,“UTC”、“本地”、“美国/纽约”)
例子:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 19,
"method": "tools/call",
"params": {
"name": "get_current_time",
"arguments": {
"format": "rfc3339",
"timezone": "UTC"
}
}
}'10.测试结果
通过可选的按测试状态筛选,获取特定构建的测试结果。
参数:
buildId(必填):生成ID以获取测试结果status(可选):按测试状态筛选:成功、失败、未知、忽略includeDetails(可选):包括堆栈跟踪等测试详细信息(默认值:false)count(可选):要返回的最大测试数(默认值:100,最大值:1000)
示例:
获取构建的所有测试结果:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 20,
"method": "tools/call",
"params": {
"name": "get_test_results",
"arguments": {
"buildId": "12345"
}
}
}'仅获取包含详细信息的失败测试:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 21,
"method": "tools/call",
"params": {
"name": "get_test_results",
"arguments": {
"buildId": "12345",
"status": "FAILURE",
"includeDetails": true
}
}
}'以有限的计数获得成功的测试:
curl -X POST http://localhost:8123/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret" \
-d '{
"jsonrpc": "2.0",
"id": 22,
"method": "tools/call",
"params": {
"name": "get_test_results",
"arguments": {
"buildId": "12345",
"status": "SUCCESS",
"count": 50
}
}
}'本地二进制配置
如果你更喜欢使用本地二进制文件而不是Docker:
{
"teamcity": {
"command": "/path/to/teamcity-mcp",
"args": ["--transport", "stdio"],
"env": {
"TC_URL": "https://your-teamcity-server.com",
"TC_TOKEN": "your-teamcity-api-token"
}
}
}游标中的用法
配置后,您可以使用自然语言命令,如:
- “搜索上周失败的构建”
- “触发主分支的构建”
- “显示项目X的最新版本”
- “固定最新成功构建”
- “取消正在运行的版本12345”
- “添加发布标签以构建12345”
- “获取生成12345的生成日志”
- “获取最新版本的存档日志”
- “查找名称中包含'Test'的所有生成配置”
- “在MyProject中搜索已启用的配置”
- “显示所有生成配置模板”
- “查找使用Gradle构建步骤的配置”
- “搜索DEPLOY_TARGET参数设置为生产的配置”
- “使用Git VCS显示所有配置”
- “查找基于Docker的构建配置”
- “搜索具有特定参数名称的配置”
- “当前日期和时间是什么?”
- “获取UTC当前时间”
- “显示今天的日期”
- “获取版本12345的测试结果”
- “显示最新版本的失败测试”
- “获取包含版本12345详细信息的测试结果”
- “显示此版本的所有通过测试的内容”
- “版本12345中哪些测试失败?”
AI将自动使用适当的TeamCity工具来满足您的请求。
可用资源
服务器将TeamCity数据作为MCP资源公开:
teamcity://projects-列出所有项目teamcity://buildTypes-列出所有构建配置teamcity://builds-列出最新版本teamcity://agents-列出构建代理teamcity://runtime-当前服务器日期、时间和运行时信息
故障排除
常见问题
- 缺少必需的环境变量
Error: TC_URL environment variable is required解决方案:设置所有必需的环境变量
- 身份验证失败
Error: TC_TOKEN environment variable is required解决方案:设置 TC_TOKEN 使用TeamCity API代币
- 超时格式无效
Error: invalid TC_TIMEOUT format解决方案:使用有效的持续时间格式,如 30s, 1m, 2h
- 端口已在使用中
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
# Expected: {"service":"teamcity-mcp","status":"ok","timestamp":"..."}指标
Prometheus指标可用:
curl http://localhost:8123/metricsTeamCity集成测试
验证TeamCity连接:
# Check TeamCity server accessibility
curl -H "Authorization: Bearer your-token" \
http://your-teamcity-url/app/rest/projects
# Verify authentication
curl -H "Authorization: Bearer your-token" \
http://your-teamcity-url/app/rest/server协议参考
看 协议.md 用于详细的MCP协议实现和TeamCity API映射。
许可证
MIT许可证-请参阅 许可证 了解详情。
