tfs-mcp-server

MCP server kết nối trực tiếp với TFS (Team Foundation Server) on-premise qua REST API, cho phép Claude đọc/ghi work item, backlog, sprint, và Pull Request mà không cần copy/paste thủ công.

Lưu ý về phiên bản: bạn nhắc "TFS 2027" — hiện tại chưa có phiên bản TFS nào tên như vậy (dòng TFS dừng ở 2018, sau đó đổi tên thành Azure DevOps Server 2019/2020/2022). Có thể ý bạn là TFS 2017 hoặc TFS 2018. Server này được viết để dùng với REST API chuẩn của TFS 2017/2018 (và tương thích ngược với Azure DevOps Server các bản sau nếu chỉnh TFS_API_VERSION). Nếu bạn cho biết đúng phiên bản, mình chỉnh lại api-version mặc định cho khớp.

Yêu cầu

• Node.js 18 trở lên, chạy trên máy có thể truy cập mạng nội bộ tới server TFS
• TFS đã bật Personal Access Token (PAT) — có từ TFS 2017 Update 1 trở lên. Vào TFS: góc trên phải → Security → Personal access tokens → tạo token mới với quyền:
  • Work Items: Read & write
  • Code: Read
  • Project and Team: Read

Nếu TFS của bạn chỉ hỗ trợ NTLM/Windows Authentication (chưa bật được PAT), báo lại — code hiện tại cần chỉnh lại phần xác thực trong src/tfsClient.ts bằng thư viện hỗ trợ NTLM (ví dụ axios-ntlm) thay vì Basic Auth với PAT.

Cài đặt

npm install
npm run build

Cấu hình

Copy .env.example thành .env và điền thông tin:

cp .env.example .env

TFS_BASE_URL=http://tfs.congty.local:8080/tfs
TFS_COLLECTION=DefaultCollection
TFS_DEFAULT_PROJECT=YourProject
TFS_PAT=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TFS_API_VERSION=4.1

Nếu không chắc TFS_API_VERSION, cứ thử 4.1 trước — nếu tool báo lỗi HTTP 400/404 khi gọi, hạ xuống 3.2 rồi 2.3 (đây là các phiên bản REST API tương ứng TFS 2017).

Đăng ký với Claude

Claude Code

Thêm vào file .mcp.json ở thư mục project (hoặc ~/.claude.json cho toàn cục):

{
  "mcpServers": {
    "tfs": {
      "command": "node",
      "args": ["/duong-dan-tuyet-doi-toi/tfs-mcp-server/dist/index.js"],
      "env": {
        "TFS_BASE_URL": "http://tfs.congty.local:8080/tfs",
        "TFS_COLLECTION": "DefaultCollection",
        "TFS_DEFAULT_PROJECT": "YourProject",
        "TFS_PAT": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "TFS_API_VERSION": "4.1"
      }
    }
  }
}

Claude Desktop

Mở claude_desktop_config.json (Settings → Developer → Edit Config), thêm mục tương tự vào mcpServers.

Sau khi thêm, khởi động lại Claude Code/Desktop — các tool tfs_* sẽ xuất hiện trong danh sách tool khả dụng.

Danh sách tool

Tool	Chức năng
tfs_query_wiql	Chạy truy vấn WIQL tùy chỉnh
tfs_get_work_items	Lấy chi tiết work item theo ID
tfs_get_backlog	Lấy danh sách work item trong một sprint/iteration
tfs_get_iterations	Lấy danh sách sprint theo cấp project, trả iterationPath dùng trực tiếp cho backlog
tfs_list_pull_requests	Liệt kê Pull Request theo trạng thái
tfs_get_pull_request	Chi tiết một Pull Request
tfs_get_pr_changes	Danh sách file thay đổi trong PR
tfs_create_work_item	Tạo work item mới: User Story, Task, Bug, Test Case...
tfs_add_work_item_comment	Thêm comment vào work item (thao tác ghi dữ liệu)

Các tool này khớp trực tiếp với input mà các skill trong bộ em-toolkit (sprint-retro, sprint-planning-summary, pr-review-checklist, bug-triage) cần — khi cả hai được cài cùng lúc, Claude có thể tự lấy dữ liệu từ TFS thay vì bạn phải copy/paste.

Tạo work item

Tool tfs_create_work_item dùng REST API JSON Patch của TFS/Azure DevOps. Ví dụ tạo User Story:

{
  "workItemType": "User Story",
  "title": "[SAMPLE] Báo cáo tổng kết vòng lặp có đủ metric",
  "description": "User story mẫu để kiểm tra báo cáo velocity, bug ratio và chất lượng kiểm thử.",
  "areaPath": "EngineeringManagerToolkit",
  "iterationPath": "EngineeringManagerToolkit\\Alpha",
  "assignedTo": "user@example.com",
  "tags": ["em-toolkit-sample", "reporting"],
  "fields": {
    "Microsoft.VSTS.Scheduling.StoryPoints": 8,
    "Microsoft.VSTS.Common.Priority": 1
  }
}

Ví dụ tạo Bug:

{
  "workItemType": "Bug",
  "title": "[SAMPLE] Báo cáo thiếu phân tích nguyên nhân bug",
  "iterationPath": "EngineeringManagerToolkit\\Alpha",
  "tags": ["em-toolkit-sample", "bug-ratio"],
  "fields": {
    "Microsoft.VSTS.Common.Severity": "2 - High",
    "Microsoft.VSTS.Common.Priority": 1
  }
}

Có thể truyền validateOnly: true để kiểm tra request nếu phiên bản TFS hỗ trợ, và truyền thêm field tùy biến qua object fields theo reference name.

Bảo mật

• Không commit file .env — đã có PAT thật trong đó. Thêm .env vào .gitignore.
• PAT nên đặt hạn dùng ngắn (30-90 ngày) và chỉ cấp đúng quyền cần thiết.
• Server này chạy local trên máy bạn (qua stdio), không có thành phần nào gửi dữ liệu ra ngoài ngoại trừ chính TFS server bạn cấu hình.

Gỡ lỗi thường gặp

• 401 Unauthorized: kiểm tra PAT còn hạn không, có đúng quyền không, và TFS đã bật tính năng PAT chưa.
• 404 Not Found: kiểm tra TFS_COLLECTION, tên project, tên repository có đúng chính xác (phân biệt hoa/thường và khoảng trắng) không.
• 400 Bad Request ở các tool liên quan work item: thường do TFS_API_VERSION không khớp phiên bản server — thử các giá trị 2.3 / 3.0 / 3.2 / 4.1.