星战科技xingzhan.cloud
返回市场
团队城-mcp

团队城-mcp

作者：Daghis5 星标更新：2025-11-10
安装使用来源：spider==github.com

项目介绍

TeamCity MCP 服务器

CI CodeQL codecov License: MIT

一个模型控制协议（MCP）服务器，连接AI编码助手与JetBrains TeamCity CI/CD服务器，将TeamCity操作暴露为MCP工具。

概述

TeamCity MCP服务器允许使用AI驱动的编码助手（如Claude Code、Cursor、Windsurf）的开发者通过MCP工具直接从他们的开发环境中与TeamCity进行交互。

特性

🚀 两种操作模式

  • 开发模式：安全的CI/CD操作

    • 触发构建
    • 监控构建状态和进度
    • 获取构建日志
    • 调查测试失败原因
    • 列出项目和配置

  • 完全模式：完整的基础设施管理

    • 包含所有开发模式的功能，加上：
    • 创建和克隆构建配置
    • 管理构建步骤和触发器
    • 配置VCS根目录和代理
    • 设置新项目
    • 修改基础设施设置

🎯 关键能力

  • 触发和监控构建，获取日志，检查测试失败原因
  • 基于令牌的身份验证到TeamCity；日志中敏感值被删除
  • 现代架构：简单直接的实现，采用单例客户端
  • 性能优化：快速启动，最小化开销
  • 清晰的代码库，模块边界明确

安装

先决条件

  • Node.js >= 20.10.0
  • TeamCity Server 2020.1+，具有REST API访问权限
  • TeamCity身份验证令牌

快速开始

# 克隆仓库
git clone https://github.com/Daghis/teamcity-mcp.git
cd teamcity-mcp

# 安装依赖
npm install

# 配置环境
cp .env.example .env
# 编辑.env文件，填写你的TeamCity URL和令牌

# 在开发模式下运行
npm run dev

npm 包

通过npx运行MCP服务器（需要Node 20.x）。在命令行或工作目录中的.env文件中设置你的TeamCity环境变量。

# 单次运行（内联环境变量）
TEAMCITY_URL="https://teamcity.example.com" \
TEAMCITY_TOKEN="<your_token>" \
MCP_MODE=dev \
npx -y @daghis/teamcity-mcp

# 或者依赖当前目录下的.env文件
npx -y @daghis/teamcity-mcp

Claude Code

  • 添加MCP：
    • claude mcp add [-s user] teamcity -- npx -y @daghis/teamcity-mcp
  • 使用环境变量（如果未使用.env）：
    • claude mcp add [-s user] teamcity -- env TEAMCITY_URL="https://teamcity.example.com" TEAMCITY_TOKEN="tc_<your_token>" MCP_MODE=dev npx -y @daghis/teamcity-mcp
  • 上下文使用（Opus 4.1，估算）：
    • 开发（默认）：~14k令牌用于MCP工具
    • 完整（MCP_MODE=full）：~26k令牌用于MCP工具

配置

环境变量在中心位置通过Zod进行验证。支持的变量及其默认值：

# 服务器配置
PORT=3000
NODE_ENV=development
LOG_LEVEL=info

# TeamCity配置（支持别名）
TEAMCITY_URL=https://teamcity.example.com
TEAMCITY_TOKEN=your-auth-token
# 可选别名：
# TEAMCITY_SERVER_URL=...
# TEAMCITY_API_TOKEN=...

# MCP模式（开发或完全）
MCP_MODE=dev

# 可选高级TeamCity选项（显示默认值）
# 连接
# TEAMCITY_TIMEOUT=30000
# TEAMCITY_MAX_CONCURRENT=10
# TEAMCITY_KEEP_ALIVE=true
# TEAMCITY_COMPRESSION=true

# 重试
# TEAMCITY_RETRY_ENABLED=true
# TEAMCITY_MAX_RETRIES=3
# TEAMCITY_RETRY_DELAY=1000
# TEAMCITY_MAX_RETRY_DELAY=30000

# 分页
# TEAMCITY_PAGE_SIZE=100
# TEAMCITY_MAX_PAGE_SIZE=1000
# TEAMCITY_AUTO_FETCH_ALL=false

# 断路器
# TEAMCITY_CIRCUIT_BREAKER=true
# TEAMCITY_CB_FAILURE_THRESHOLD=5
# TEAMCITY_CB_RESET_TIMEOUT=60000
# TEAMCITY_CB_SUCCESS_THRESHOLD=2

这些值在src/config/index.ts中进行规范化，并通过辅助getter由src/teamcity/config.ts消费。

使用示例

一旦集成到您的AI编码助手：

"在特性分支上构建前端"
"为什么昨晚的测试失败了？"
"用最新构建部署预发布环境"
"为移动应用创建新的构建配置"

工具响应和分页

  • 响应：工具现在返回一致的MCP内容。对于列表/获取操作，content[0].text包含一个JSON字符串。示例形状： { "items": [...], "pagination": { "page": 1, "pageSize": 100 } } 或 { "items": [...], "pagination": { "mode": "all", "pageSize": 100, "fetched": 250 } }。
  • 分页：大多数列表_*工具接受pageSize、maxPages和all：
    • pageSize控制每页的项数。
    • all: true获取多个页面直到maxPages。
    • 旧版list_builds上的count为了兼容性而保留，但推荐使用pageSize。

验证和错误

  • 输入验证：工具输入通过Zod模式进行验证；无效输入返回响应内容中的结构化错误负载（JSON字符串），其中success: false且error.code = VALIDATION_ERROR。
  • 错误格式化：通过全局处理器一致地格式化错误。在生产中，消息可能被清理；敏感值（例如令牌）在日志中被删除。

API 使用

import { TeamCityAPI } from '@/api-client';

// 获取API客户端实例
const api = TeamCityAPI.getInstance();

// 列出项目
const projects = await api.listProjects();

// 获取构建状态
const build = await api.getBuild('BuildId123');

// 触发新的构建
const newBuild = await api.triggerBuild('BuildConfigId', {
  branchName: 'main',
});

注意：从src/teamcity/index.ts导出的遗留帮助函数仅出于兼容性目的保留，并包括占位符实现。建议使用MCP工具（参见上面提供的参考链接）或此处展示的TeamCityAPI来自动化工作流。

开发

# 运行测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

# 检查代码风格
npm run lint

# 格式化代码
npm run format

# 类型检查
npm run typecheck

# 构建生产环境
npm run build

# 分析捆绑包以供Codecov
npm run build:bundle

CI中的捆绑包分析

CI工作流程运行npm run build:bundle并使用codecov/codecov-action插件上传生成的coverage/bundles JSON。

项目结构

teamcity-mcp/
├── src/               # 源代码
│   ├── tools/        # MCP工具实现
│   ├── utils/        # 实用函数
│   ├── types/        # TypeScript类型定义
│   └── config/       # 配置管理
├── tests/            # 测试文件
├── docs/             # 文档
└── .agent-os/        # 代理操作系统规范

API 文档

MCP服务器提供了针对TeamCity操作的工具。每个工具对应特定的TeamCity REST API端点：

构建管理

  • TriggerBuild - 排队新的构建
  • GetBuildStatus - 检查构建进度
  • FetchBuildLog - 获取构建日志
  • ListBuilds - 按标准搜索构建

测试分析

  • ListTestFailures - 获取失败的测试
  • GetTestDetails - 详细的测试信息
  • AnalyzeBuildProblems - 识别失败原因

配置（仅限完全模式）

  • create_build_config - 创建新的TeamCity构建配置，全面支持：
    • 带认证的VCS根目录（Git、SVN、Perforce）
    • 构建步骤（脚本、Maven、Gradle、npm、Docker、PowerShell）
    • 触发器（VCS、计划、完成构建、maven-snapshot）
    • 参数和基于模板的配置
    • 详情参见MCP工具参考中的参数细节和附加选项。
  • clone_build_config - 将现有配置复制到任何项目，保留步骤、触发器和参数。
  • update_build_config - 调整配置的名称、描述、制品规则和暂停状态。
  • manage_build_steps - 通过单一工具界面添加、更新、移除或重新排序构建步骤。
  • manage_build_triggers - 添加或删除构建触发器，支持全部属性。
  • create_vcs_root & add_vcs_root_to_build - 定义VCS根目录并将它们附加到构建配置。

另见：docs/TEAMCITY_MCP_TOOLS_GUIDE.md中的扩展工作流和示例，与当前MCP实现相匹配。

贡献

我们欢迎贡献！请参阅CONTRIBUTING.md了解详情。

安全

  • 通过环境配置TEAMCITY_TOKEN（参见.env.example）；切勿提交真实令牌
  • 仅支持基于令牌的身份验证
  • 日志中删除敏感值

支持

致谢

  • JetBrains TeamCity 提供了卓越的CI/CD平台
  • Anthropic 提供了模型控制协议规范
  • 开源社区持续的支持

为热爱高效CI/CD工作流的开发者打造，充满❤️