# 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

```bash
npm install
npm run build
```

## Cấu hình

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

```bash
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):

```json
{
  "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:

```json
{
  "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:

```json
{
  "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.