# @daghis/teamcity-mcp 中文文档

规范地址：https://npmcn.com/package/%40daghis/teamcity-mcp/

版本：2\.12\.15
npm 元数据更新时间：2026-11-06T21:39:37.788Z
中文译文更新时间：2026-11-11T08:40:39.307Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40daghis/teamcity-mcp
原文对照：https://npmcn.com/package/%40daghis/teamcity-mcp/?lang=original
项目主页：https://github.com/Daghis/teamcity-mcp#readme
源码仓库：https://github.com/Daghis/teamcity-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.8 MB，12 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：7 个
- 首次发布：2025-09-11T18:11:12.773Z
- 最新版本发布：2026-11-06T21:39:37.428Z
- 近 30 天下载量：10295（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：120（近 12 个月 71 个）

## 中文简介

TeamCity CI/CD 集成的模型控制协议服务器与 AI 编码助理

## 安装

```sh
npm install @daghis/teamcity-mcp
```

也可以使用：`pnpm add @daghis/teamcity-mcp`、`yarn add @daghis/teamcity-mcp`、`bun add @daghis/teamcity-mcp`

## README

# 团队城 MCP 服务器

[![CI](https://github.com/Daghis/teamcity-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Daghis/teamcity-mcp/actions/workflows/ci.yml) [![CodeQL](https://github.com/Daghis/teamcity-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/Daghis/teamcity-mcp/actions/workflows/codeql.yml) [![codecov](https://codecov.io/gh/Daghis/teamcity-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/Daghis/teamcity-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://npmcn.com/package/%40daghis/teamcity-mcp/LICENSE)

一个模型控制协议(MCP)服务器,将AI编码助手与JetBrains TeamCity CI/CD服务器相接,将TeamCity操作暴露为MCP工具.

[![TeamCity Server MCP server](https://glama.ai/mcp/servers/@Daghis/teamcity-mcp/badge)](https://glama.ai/mcp/servers/@Daghis/teamcity-mcp)

> \[注\] **项目状况(2026年10月):稳定,低调维护.** 这是它所要做的事情,现在已不再在积极发展之中。 它仍然有效,仍然可以安装;问题和PR可能会得到缓慢或没有反应,而安全修复是最佳的.
> 
> JetBrains现在为TeamCity(TeamCity)搭载了官方AI集成——一个MCP服务器被建入TeamCity 2026.1+和 [团队城市CLI](https://github.com/JetBrains/teamcity-cli) 具有可安装的代理技能——这是大多数工作流程更好的默认. 见 [_比起JetBrains的官方工具_](https://npmcn.com/package/%40daghis/teamcity-mcp/#readme-how-this-compares-to-jetbrains-official-tooling) 以下为收养前.

## 概览

TeamCity MCP Server允许使用AI动力编码助理(Claude Code, Cursor, Windsurf)的开发者通过MCP工具直接从开发环境与TeamCity互动.

> **从1.x升级?** 2.0.0版本将15个工具从Dev移动到Full模式,包括队列管理,代理兼容性检查,以及服务器健康监测等. 如果您在 Dev 模式中依赖于这些工具, 请切换到 `MCP_MODE=full` 或使用运行时模式切换(v2.1.0+). 见 [变动情况](https://npmcn.com/package/%40daghis/teamcity-mcp/CHANGELOG.md) 详细情况.

## 特征

### 双业务模式

-   **开发模式** (默认):安全 CI/CD 操作(31个工具,~14k上下文符)
    
    -   触发器构建并监视状态
    -   获取构建日志并检查测试失败
    -   列出工程、配置和队列
    -   读取参数并调查问题
-   **完整模式**: 完成基础设施管理(87个工具,~26k上下文符)
    
    -   所有 Dev 模式特性, 外加 :
    -   创建和克隆构建配置
    -   管理构建步骤、触发和依赖
    -   配置 VCS 根和代理
    -   参数的完整 CRUD( 构建配置、 项目和输出参数)
    -   队列管理和服务器管理

**运行时间模式切换(v2.1.0+):** 运行时在模式间切换 `get_mcp_mode` 财务报告和审定财务报表 `set_mcp_mode` 工具 - 不需要重新启动 。 支持通知的MCP客户端会自动看到工具列表更新.

见 [工具模式矩阵](https://npmcn.com/package/%40daghis/teamcity-mcp/docs/mcp-tools-mode-matrix.md) 用于87个工具的完整清单及其按模式的可用性.

### 关键能力

-   触发和监视器构建、获取日志并检查测试失败
-   基于 Token 对 TeamCity 的认证; 在日志中编辑的敏感值
-   现代架构:简单,有单通客户端的直接执行
-   性能意识:快速启动,间接费用最低
-   模块界限明确的清洁编码库

## 比起JetBrains的官方工具

**截止2026年10月** (TeamCity 2026.2,TeamCity CLI 1.6),JetBrains为AI代理的两条一线航道,两者均普遍可用并获得官方支持:

-   **内建的 MCP 服务器** – 每个 TeamCity 2026.1+ 服务器( Cloud and On-Premises) 都会在 `<server-url>/app/mcp`,所以没有安装。 这是一个刻意的小工具: 建立日志,通用 REST API `GET`编号 :`POST` 通过工具,以及(自2026.2)管道工具。 默认情况下, 它运行在一个安全模式中, 代理可以读取并排队列个人构建; 一个选择中的“ 勇敢模式” 允许它发送任意 REST `POST` 请求并编辑或删除管道。 自2026.2起,您也可以与OAuth签约,而不是粘贴访问符.
-   **[团队城市CLI](https://github.com/JetBrains/teamcity-cli)** ——开源 `teamcity` 命令(TeamCity 2020.1+),具有可安装代理技能(`teamcity skill install`Claude Code, Cursor, 和其他探员的 它覆盖运行,日志,测试,队列,代理,池,项目,VCS根,参数,以及管道,返回到原始的REST访问通过 `teamcity api`,并具有只读模式(`TEAMCITY_RO=1`JetBrains自己的文件将其描述为两个选项中更广泛的.

teamcity-mcp 预示着工具化和重合性很强. 官方工具是今天更好的默认. MCP仍然提供什么 比以前更狭窄:

-   **一个MCP服务器,服务于2026.1.** 如果您的客户端只说MCP,而您的TeamCity服务器在内置端点之前就已经存在,这仍然可行(TeamCity 2020.1+).
-   **目的性制造的MCP工具,而不是REST通过.** 它暴露出87个打字工具(由 Dev/Full 模式指定),因此代理商不需要了解REST路径和定位器——它涵盖了由支持的操作 `PUT`编号 :`DELETE` (例如赋能剂或删除参数),内置的MCP通用 `GET`编号 :`POST` 工具无法到达.

JetBrains的工具正在迅速演变,因此与其在这里按特点进行对比(它会很快被扭曲),不如检查当前的文件并选择合适的:

-   [2026.2号城市公告](https://blog.jetbrains.com/teamcity/2026/09/teamcity-20262/) ——管道工具,勇者模式,以及内置MCP的OAuth
-   [TeamCity 2026.1 公告](https://blog.jetbrains.com/teamcity/2026/05/teamcity-20261/) ——官方AI整合首发地
-   [AI 代理集成文件](https://www.jetbrains.com/help/teamcity/ai-agent-integration.html) ——内置的MCP,其工具,安全与勇敢模式
-   [团队城市 CLI 文件](https://www.jetbrains.com/help/teamcity/teamcity-cli.html) 财务报告和审定财务报表 [代理技能](https://www.jetbrains.com/help/teamcity/teamcity-cli-ai-agent-integration.html) ——终端+代理技能路径

如果你对JetBrains的CLI很满意,你可能根本不需要这个项目. 它仍然有麻省理工学院的许可,并且可以安装,不管内置设施还没有达到什么——如果你想自己更进一步,就把它叉开.

## 安装

### 先决条件

-   节点.js >= 20.1.0 (LTS版本20,22,24在CI测试)
-   TeamCity Server 2020.1+ 有 REST API 访问权限
-   TeamCity 认证符

### 快速启动

```bash
# Clone the repository
git clone https://github.com/Daghis/teamcity-mcp.git
cd teamcity-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your TeamCity URL and token

# Run in development mode
npm run dev
```

### npm 软件包

通过npx运行MCP服务器(需要node 20.x). 设置您的 TeamCity 环境变量内置或通过 `.env` 在工作目录中.

```bash
# One-off run (inline envs)
TEAMCITY_URL="https://teamcity.example.com" \
TEAMCITY_TOKEN="<your_token>" \
MCP_MODE=dev \
npx -y @daghis/teamcity-mcp

# Or rely on .env in the current directory
npx -y @daghis/teamcity-mcp
```

## 克劳德代码

-   添加 MCP( 依赖 `.env` 用于配置 :
    -   `claude mcp add teamcity -- npx -y @daghis/teamcity-mcp`
-   带有env vars(如果不使用.env):
    -   `claude mcp add teamcity -e TEAMCITY_URL="https://teamcity.example.com" -e TEAMCITY_TOKEN="tc_<your_token>" -- npx -y @daghis/teamcity-mcp`
-   带有 CLI 参数( 建议用于 Windows ):
    -   `claude mcp add teamcity -- npx -y @daghis/teamcity-mcp --url "https://teamcity.example.com" --token "tc_<your_token>" --mode dev`
-   添加 `-s user` 以安装全用户范围而不是工程范围(默认)
-   上下文使用量(Opus 4.1,估计数):
    -   Dev (默认): MCP 工具的 ~ 14k 令牌
    -   完整( E)`MCP_MODE=full`: MCP 工具的 ~ 26k 令牌

### 窗口用户

在 Windows 上, Claude 代码的 MCP 配置 [可能无法正确合并环境变量](https://github.com/anthropics/claude-code/issues/1254)。使用 CLI 参数作为变通:

```json
{
  "mcpServers": {
    "teamcity": {
      "command": "npx",
      "args": [
        "-y",
        "@daghis/teamcity-mcp",
        "--url",
        "https://teamcity.example.com",
        "--token",
        "YOUR_TOKEN"
      ]
    }
  }
}
```

或使用配置文件来改善安全性( 在进程列表中无法显示) :

```json
{
  "mcpServers": {
    "teamcity": {
      "command": "npx",
      "args": ["-y", "@daghis/teamcity-mcp", "--config", "C:\\path\\to\\teamcity.env"]
    }
  }
}
```

## 配置

环境与Zod统一验证. 支持的变量和默认值 :

```env
# Server Configuration
PORT=3000
NODE_ENV=development
LOG_LEVEL=info

# TeamCity Configuration (aliases supported)
TEAMCITY_URL=https://teamcity.example.com
TEAMCITY_TOKEN=your-auth-token
# Optional aliases:
# TEAMCITY_SERVER_URL=...
# TEAMCITY_API_TOKEN=...

# MCP Mode (dev or full)
MCP_MODE=dev

# Optional advanced TeamCity options (defaults shown)
# Connection
# TEAMCITY_TIMEOUT=30000
# TEAMCITY_MAX_CONCURRENT=10
# TEAMCITY_KEEP_ALIVE=true
# TEAMCITY_COMPRESSION=true

# Extra headers attached to every TeamCity request — useful when TeamCity
# sits behind a reverse proxy that gates access on custom headers (e.g.
# Cloudflare Zero Trust service tokens). One env var per header; the part
# after `TEAMCITY_HEADER_` is used verbatim as the HTTP header name.
# Example (note the literal hyphens — most shells need quoting):
# TEAMCITY_HEADER_CF-Access-Client-Id=<id>
# TEAMCITY_HEADER_CF-Access-Client-Secret=<secret>

# Retry
# TEAMCITY_RETRY_ENABLED=true
# TEAMCITY_MAX_RETRIES=3
# TEAMCITY_RETRY_DELAY=1000
# TEAMCITY_MAX_RETRY_DELAY=30000

# Pagination
# TEAMCITY_PAGE_SIZE=100
# TEAMCITY_MAX_PAGE_SIZE=1000
# TEAMCITY_AUTO_FETCH_ALL=false

# Circuit Breaker
# TEAMCITY_CIRCUIT_BREAKER=true
# TEAMCITY_CB_FAILURE_THRESHOLD=5
# TEAMCITY_CB_RESET_TIMEOUT=60000
# TEAMCITY_CB_SUCCESS_THRESHOLD=2
```

这些值在 `src/config/index.ts` 消耗量 `src/teamcity/config.ts` 通过帮助获得者.

## 用法实例

与您的 AI 编码助理合并后 :

```
"Build the frontend on feature branch"
"Why did last night's tests fail?"
"Deploy staging with the latest build"
"Create a new build config for the mobile app"
```

### 工具响应和插座

-   答复:工具现在返回一致的MCP内容. 对于列表/操作 `content[0].text` 包含一个JSON字符串。 示例形状 : `{ "items": [...], "pagination": { "page": 1, "pageSize": 100 } }` 或者说 `{ "items": [...], "pagination": { "mode": "all", "pageSize": 100, "fetched": 250 } }`。 。 。 .
-   PGination: 大多数列表QQ 工具被接受 `pageSize`, (中文(简体) ), `maxPages`,以及 `all`数字 :
    -   `pageSize` 每页控制项.
    -   `all: true` 获取多页 `maxPages`。 。 。 .
    -   遗产 `count` 打开 `list_builds` 用于兼容,但 `pageSize` 优先选择.

### 校验和错误

-   输入验证: 用 Zod schemas 验证工具输入; 无效输入返回响应内容中的结构化错误有效载荷( JSON string) 与 `success: false` 财务报告和审定财务报表 `error.code = VALIDATION_ERROR`。 。 。 .
-   设定错误: 通过全局处理器格式化错误 。 在制作中,消息可能进行分泌;敏感值(如信使等)被重新刻入日志.

### API 使用量

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

// Get the API client instance
const api = TeamCityAPI.getInstance();

// List projects
const projects = await api.listProjects();

// Get build status
const build = await api.getBuild('BuildId123');

// Trigger a new build
const newBuild = await api.triggerBuild('BuildConfigId', {
  branchName: 'main',
});
```

> **说明:** 从 `src/teamcity/index.ts` 仅用于兼容性,并包括占位符执行。 优先使用MCP工具(见上文链接的参考资料)或 `TeamCityAPI` 自动工作流程时显示在此 .

## 发展

```bash
# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

# Type check
npm run typecheck

# Build for production
npm run build

# Analyze bundle for Codecov
npm run build:bundle
```

### CI 中的装订分析

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

## 项目结构

```
teamcity-mcp/
├── src/                    # Source code
│   ├── tools.ts           # All 87 MCP tool definitions
│   ├── server.ts          # MCP server setup
│   ├── api-client.ts      # TeamCity API singleton
│   ├── config/            # Configuration with Zod validation
│   ├── teamcity/          # Domain logic (build, agent, config managers)
│   ├── teamcity-client/   # Auto-generated OpenAPI client
│   ├── types/             # TypeScript type definitions
│   └── utils/             # Logger, MCP helpers, pagination
├── tests/                  # Unit and integration tests
├── docs/                   # Documentation
└── scripts/                # Build and maintenance scripts
```

## 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 工具参考](https://npmcn.com/package/%40daghis/teamcity-mcp/docs/mcp-tools-reference.md) 用于参数细节和补充选项.
-   `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`](https://npmcn.com/package/%40daghis/teamcity-mcp/docs/TEAMCITY_MCP_TOOLS_GUIDE.md) (c) 扩大工作流程和实例,使之与当前的多边CP执行相一致.

## 捐款

我们欢迎捐款! 请看 [捐款额](https://npmcn.com/package/%40daghis/teamcity-mcp/CONTRIBUTING.md) 详细情况.

## 警卫

### 托肯管理

-   配置 `TEAMCITY_TOKEN` 通过环境变量或配置文件(参见 `.env.example`; 从不执行真实的标志
-   使用最小权限的指使; 只读指使为大多数 Dev 模式操作工作
-   仅基于托肯认证; MCP 服务器不支持用户名/ 密码字
-   日志编辑敏感值,包括符号

### 模式选择

-   偏爱 **开发模式** 除非明确需要完全模式——这限制了任何配置错误或迅速注射的爆炸半径
-   完整模式可以实现无法轻易消除的破坏性操作(项目删除、代理管理)

### 网络安全

-   总是使用 HTTPS 进行TeamCity 连接; 服务器不执行,而是强烈推荐
-   MCP 服务器只连接到配置的 TeamCity URL; 没有进行其他网络呼叫

### AI 助理考虑

-   AI 助手可以通过在构建日志、测试输出或其他TeamCity数据中的即时注入来被操纵
-   Dev 模式的有限工具集可以减少这种攻击的影响
-   所有动作都出现在 TeamCity 的相关用户下的审计日志中
-   构建日志和测试失败细节可能包含AI助手可见的敏感信息(机密,路径,内部URL)

### 仓库安全

此寄存器已启用 GitHub 秘密扫描和推取保护 。 见 [警卫](https://npmcn.com/package/%40daghis/teamcity-mcp/SECURITY.md) 脆弱性报告.

## 支助

-   GitHub 问题 : [报告错误或请求特性](https://github.com/Daghis/teamcity-mcp/issues)
-   文号: `docs/` 此仓库中的文件夹

## 承认

-   优秀CI/CD平台城市
-   用于示范控制议定书规格的
-   持续支持的开源社区
-   见 [第三次议会 NoTICES.md](https://npmcn.com/package/%40daghis/teamcity-mcp/THIRD_PARTY_NOTICES.md) 第三方许可证

* * *

为喜欢高效 CI/ CD 工作流程的开发者所建 QQ

## 常见问题

### @daghis/teamcity-mcp 是什么？

TeamCity CI/CD 集成的模型控制协议服务器与 AI 编码助理

### 如何安装 @daghis/teamcity-mcp？

在项目目录运行 npm install @daghis/teamcity-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 teamcity-mcp，可以用 npx teamcity-mcp 直接运行。

### @daghis/teamcity-mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @daghis/teamcity-mcp 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @daghis/teamcity-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @daghis/teamcity-mcp 可以商用吗？

@daghis/teamcity-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @daghis/teamcity-mcp 的下载量有多少？

根据 npm 官方下载统计，@daghis/teamcity-mcp 在 2026/10/11 – 2026/11/09 这 30 天内被下载 10,295 次，日均约 343 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @daghis/teamcity-mcp 还在维护吗？

最新版本 2\.12\.15 发布于 2026/11/07（4 天前）；至今共发布 120 个版本，其中过去 12 个月发布了 71 个；首次发布于 2025/09/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。