@manohub/tfs-mcp-server
v0.0.2
Published
MCP Server for TFS 2018 — query and manage Bugs / Work Items
Maintainers
Readme
tfs-mcp-server
基于 TFS 2018 REST API 的 MCP Server(TypeScript / Node.js 20+ / stdio)。
面向 Agent 的工作项读写:通用增删改查(list / get / create / update / delete)、WIQL 查询与类型枚举,不限 Bug 一种类型。
要求
- Node.js >= 20
- pnpm 11(
packageManager已锁定版本)
安装与构建
pnpm install
pnpm build # 产出 dist/
pnpm test # 构建 + node:test配置
复制 .env.example 为 .env 并填写;生产环境更推荐由 MCP 客户端通过 env 注入(优先级最高)。
| 变量 | 必填 | 说明 |
|---|---|---|
| TFS_URL | 是 | 集合层地址,如 http://tfs.example.com:8080/tfs |
| TFS_COLLECTION | 是 | 集合名 |
| TFS_PROJECT | 是 | 项目名 |
| TFS_USERNAME | 是 | 域账号(PAT 认证不参与鉴权,保留用于展示/后续 NTLM) |
| TFS_PAT | 是 | 个人访问令牌 |
| TFS_TIMEOUT_MS | 否 | 请求超时,默认 30000 |
| TFS_CLOSED_STATES | 否 | 视为「已关闭」的状态名,逗号分隔;默认 已关闭,Closed,已移除,Removed |
| MCP_PROXY_URL | 否 | 显式代理;缺省直连 |
TFS 的状态值随流程模板本地化:中文模板里没有 Closed,只有 已关闭。list 默认按 TFS_CLOSED_STATES 排除,状态名不同就在这个变量里改。
接入 MCP 客户端
全局安装(或直接用 npx,不落盘):
npm i -g @manohub/tfs-mcp-server
# npx @manohub/tfs-mcp-server之后 MCP 配置里 command 写 tfs-mcp-server,env 注入 TFS_*(见上表)。可直接套用 templates/mcp.json,替换其中的地址、集合、项目与 PAT 即可。
工具
| 工具 | 说明 |
|---|---|
| list | 按 work_item_type / state / assignee / keyword 列出工作项;默认排除已关闭,include_closed 可放开 |
| get | 按 ID 取详情(描述/重现步骤/验收标准,HTML 已转纯文本),不限类型 |
| create | 创建任意类型工作项(work_item_type 必填,可透传 extra_fields) |
| update | 改状态/指派人/描述,或追加讨论(System.History);不限类型 |
| delete | 按 ID 删除,默认进回收站,permanent: true 才永久删除 |
| query | 自定义 WIQL,默认最多 100 条 |
| types | 不传参:列出类型名;传 work_item_type:返回该类型必填字段(含默认值) |
工具名不带 Bug 后缀:所有类型走同一套 CRUD。assignee: '@Me' 即「分配给我的」,keyword 即标题搜索。
work_item_type 用的是 TFS 显示名,不是英文类型名:中文本地化环境写 产品积压工作项,写 Product Backlog Item 会查不到。不确定就先调 types。
建单前建议先 types { work_item_type: "Bug" }:本项目 Bug 有 11 个 alwaysRequired 字段,另有「指派给」「重现步骤」等规则必填项,缺一个就 400。types 只反映 alwaysRequired,规则必填以建单报错为准——该报错会整理成字段清单,而不是原样吐 JSON。
工具失败返回 isError: true 并带状态码提示;成功同时返回 structuredContent,便于 Agent 解析。
开发
pnpm dev # 构建并启动(stdio)
pnpm test # 构建 + 单测(不发真实网络请求)
pnpm test:connection # 用 .env 做连通性自检(打印项目列表 + 前 3 条 Bug)
pnpm pack:verify # 校验 tarball 只含 package.json / README.md / dist
pnpm release:check # test + pack:verify全局命令跑的是哪份代码
全局装的 @manohub/tfs-mcp-server 是发布版,改本地 src/ 不会影响它。要在 MCP 客户端里调试本地改动:
pnpm dev:link # 构建 + npm link,全局命令改指向本地目录
pnpm dev:unlink # 移回发布版两者都占用同一个 bin 名 tfs-mcp-server,切换后需重启 MCP 客户端才生效。跑 dev:link 期间 dist/ 是手改的产物,验证完记得 dev:unlink,否则会把本地未发布的行为当成线上版本。
目录
src/
├─ index.ts # stdio 入口
├─ config.ts # zod 校验 env
├─ core/ # http(超时/重试/错误归一/显式代理)、errors、logger
├─ domain/ # IssueProvider 接口 + TFS 实现(WIQL/批量详情)
├─ tools/ # 工具注册与处理器(与 MCP 解耦,可单测)
└─ format/ # HTML 字段 → 纯文本换领域(Jira / 禅道等)只需实现 IssueProvider,工具层不动。
配套 Skill
skills/SKILL.md 是给 Agent 的工作项读写技能,沉淀了人工查文档才会知道的坑:类型名是本地化的、Bug 的规则必填项、assigned_to 要唯一名、删单默认进回收站。
安装(二选一):
mkdir -p .agents/skills/tfs-work-items && cp skills/SKILL.md .agents/skills/tfs-work-items/ # 项目级
mkdir -p ~/.agents/skills/tfs-work-items && cp skills/SKILL.md ~/.agents/skills/tfs-work-items/ # 全局.agents/skills/ 下一个技能一个目录,目录名要与 frontmatter 的 name 一致(这里是 tfs-work-items),所以命令先建目录再拷文件。该目录是 Agent Skills 规范的通用约定,Claude Code / Cursor / Codex / Warp 等客户端都会扫描;尚未跟进该约定的客户端按其文档放到自有目录即可,SKILL.md 本身不含任何客户端专属内容。
技能随 npm 包一起发布,全局安装后在 $(npm root -g)/@manohub/tfs-mcp-server/skills/SKILL.md,直接拷出来用即可;从仓库使用时也支持上面另一种拷法。
