内容
# 7pace 时间跟踪器 MCP（自托管）
一个小型 [模型上下文协议](https://modelcontextprotocol.io) 服务器，使用 [REST CRUD API](https://timehub.7pace.com/api_reference/index.html) 在 **7pace 时间跟踪器 for Azure DevOps** 中创建工作日志。可从 **Cursor** 或 **VS Code** 与 GitHub Copilot MCP 支持一起使用。
组织、项目、令牌和路径 **不** 硬编码：请在 MCP 主机（`mcp.json` 中的 `env` 或等效文件中）中配置它们。
## 前提条件
- Node.js 20+
- **7pace API 令牌**（不是用于 7pace 调用的 Azure DevOps PAT）：时间跟踪器 → **设置** → **报告和 API** → 创建令牌。参见 [7pace API 重要信息](https://support.7pace.com/hc/en-us/articles/360050677831-7pace-Timetracker-API-Important-Information)。
- **Azure DevOps PAT**（可选）：仅适用于工作项工具。**用户设置** → **个人访问令牌**，至少具有 **工作项（读取）** 权限。参见 [使用 PAT](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate)。
## 安装和构建
```bash
cd /path/to/this-repo
npm install
npm run build
```
## 环境变量
在 MCP 服务器 `env`（Cursor、VS Code 等）中设置。不要提交实际的机密。
| 变量 | 是否必需 | 描述 |
| --- | --- | --- |
| `SEVENPACE_ORG` | 是（7pace） | Azure DevOps 组织名称；7pace 主机为 `https://{SEVENPACE_ORG}.timehub.7pace.com` |
| `SEVENPACE_API_TOKEN` | 是（7pace） | 7pace 时间跟踪器 Bearer 令牌 |
| `SEVENPACE_API_VERSION` | 否 | 7pace API 版本查询参数（默认为 `3.2`） |
| `SEVENPACE_BASE_URL` | 否 | 覆盖 7pace REST 根目录（参见 `src/config.ts`） |
| `AZURE_DEVOPS_PAT` | 是（ADO 工具） | 具有工作项（读取）权限的 PAT |
| `AZURE_DEVOPS_PROJECT` | 是（ADO 工具） | Azure DevOps **团队项目** 名称，与 URL 中一致 |
| `AZURE_DEVOPS_ORG` | 否 | `dev.azure.com` 的 ADO 组织；如果未设置，则使用 `SEVENPACE_ORG` |
| `AZURE_DEVOPS_API_VERSION` | 否 | REST `api-version`（默认为 `7.1`） |
工作日志 **长度** 以 **秒** 为单位发送（按 [7pace 示例](https://github.com/7pace/timetracker-rest-api-samplecode)）；此服务器将 **小时** 转换为秒（`小时 × 3600`）。
## 工具
- **`health`** — `GET /me` 以验证 7pace 令牌和组织。
- **`list_activity_types`** — 7pace 活动类型名称和 ID。
- **`log_time`** — 结构化：`workItemId`、`date`（`YYYY-MM-DD`）、`hours`、`description`，可选 `activityType`。
- **`log_time_natural`** — 单个自由文本行；解析工作项 ID、持续时间、日期、描述。
- **`list_completed_work_items`** — WIQL：分配给您、终端状态、关闭时间早于或等于某个日期。可选 `project` 覆盖 `AZURE_DEVOPS_PROJECT`。
- **`list_work_items_touched_in_range`** — WIQL：分配给您、`ChangedDate` 在某个日期范围内。可选 `project` 覆盖 `AZURE_DEVOPS_PROJECT`。
## Cursor
`mcp.json` 示例格式（替换路径并使用您自己的 `env` 值）：
```json
{
"mcpServers": {
"7pace-timetracker": {
"command": "node",
"args": ["/absolute/path/to/repo/dist/index.js"],
"env": {
"SEVENPACE_ORG": "<your-azure-devops-org>",
"SEVENPACE_API_TOKEN": "<your-7pace-api-token>",
"AZURE_DEVOPS_PAT": "<your-ado-pat>",
"AZURE_DEVOPS_PROJECT": "<your-team-project>"
}
}
}
}
```
## VS Code（GitHub Copilot MCP）
与上述相同的 `command`、`args` 和 `env`。参见 [VS Code 中的 MCP 配置](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration)。
使用工作区相对 `dist` 和提示令牌的示例：
```json
{
"servers": {
"7pace-timetracker": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/dist/index.js"],
"env": {
"SEVENPACE_ORG": "<your-azure-devops-org>",
"SEVENPACE_API_TOKEN": "${input:sevenpaceToken}",
"AZURE_DEVOPS_PAT": "${input:adoPat}",
"AZURE_DEVOPS_PROJECT": "<your-team-project>"
}
}
},
"inputs": [
{
"id": "sevenpaceToken",
"type": "promptString",
"description": "7pace 时间跟踪器 API 令牌",
"password": true
},
{
"id": "adoPat",
"type": "promptString",
"description": "Azure DevOps PAT（工作项读取）",
"password": true
}
]
}
```
架构键可能因 VS Code 版本而异；请与官方 MCP 文档保持一致。
## 在本地运行（stdio）
```bash
export SEVENPACE_ORG="<your-org>"
export SEVENPACE_API_TOKEN="<token>"
node dist/index.js
```
在 Windows PowerShell 上，请使用 `$env:SEVENPACE_ORG = "..."` 代替。
## 许可证
MIT
