内容
# 米特拉 MCP 服务器
米特拉是一个模块化、无状态的模型上下文协议（MCP）服务器，它集成了Clockify、WakaTime和Azure DevOps。它使开发人员和本地AI助手能够获取活动项目、管理Azure DevOps工作项（卡片）并直接使用统一的工作流程将时间条目记录到Clockify中。
服务器是完全**无状态的**：各个团队成员通过请求头（在远程/SSE模式下）或本地环境变量（在stdio模式下）提供他们的凭证（API密钥、工作区ID、个人访问令牌）。
---
## 代码架构
米特拉使用**每个文件夹集成**的架构，带有**自动发现**功能。每个集成都是自包含的——它的客户端、工具、提示和上下文都生活在同一个文件夹中：
```text
src/mitra/
├── __init__.py
├── server.py # FastMCP 实例 + 自动发现（永远不需要编辑）
├── cli.py # CLI 入口点（永远不需要编辑）
│
├── core/ # 共享基础设施
│ ├── __init__.py
│ ├── context.py # 基本凭证解析助手
│ └── registry.py # 自动发现引擎
│
└── integrations/ # ← 每个集成都是一个自包含的文件夹
├── __init__.py
│
├── clockify/ # Clockify 时间跟踪
│ ├── __init__.py # register(mcp) 入口点
│ ├── client.py # ClockifyClient（API 包装器）
│ ├── tools.py # @mcp.tool() 定义
│ ├── prompts.py # @mcp.prompt() + @mcp.resource()
│ └── context.py # 上下文变量、HTTP 头、解析器
│
├── wakatime/ # WakaTime 编码活动
│ ├── __init__.py
│ ├── client.py
│ ├── tools.py
│ └── context.py
│
├── azure_devops/ # Azure DevOps 工作项
│ ├── __init__.py
│ ├── client.py
│ ├── tools.py
│ ├── prompts.py
│ └── context.py
│
└── workflows/ # 跨集成复合工具
├── __init__.py
├── linkage.py # Clockify ↔ Azure DevOps 链接
├── fill_clockify.py # 复合填充时间表工具
└── prompts.py # 统一米特拉代理指南
```
### 添加新集成（开发者指南）
添加新的集成（例如，`Jira`或`Github`）需要创建**一个文件夹**——不需要修改其他文件：
```bash
mkdir -p src/mitra/integrations/jira
```
**1. 创建入口点** (`__init__.py`)：
```python
# src/mitra/integrations/jira/__init__.py
from mitra.integrations.jira.tools import register_tools
def register(mcp):
register_tools(mcp)
```
**2. 创建API客户端** (`client.py`)：
```python
# src/mitra/integrations/jira/client.py
class JiraClient:
def __init__(self, api_key: str): ...
async def list_issues(self, project: str): ...
```
**3. 创建工具** (`tools.py`)：
```python
# src/mitra/integrations/jira/tools.py
from mitra.integrations.jira.client import JiraClient
def register_tools(mcp):
@mcp.tool()
async def jira_list_issues(project: str, api_key: str) -> list:
"""列出Jira项目的问题。"""
client = JiraClient(api_key)
return await client.list_issues(project)
```
**4. （可选）添加凭证头** (`context.py`)：
```python
# src/mitra/integrations/jira/context.py
import contextvars
from mitra.core.context import resolve_credential
request_jira_api_key = contextvars.ContextVar("jira_api_key", default=None)
HEADERS = {"x-jira-api-key": request_jira_api_key}
def get_jira_api_key():
return resolve_credential(request_jira_api_key, "JIRA_API_KEY")
```
**就是这样。** 自动发现引擎会自动拾取您的新文件夹。SSE中间件会自动收集您的头部。不需要触摸其他文件。
---
## 安装
克隆仓库并在可编辑模式下安装：
```bash
pip install -e .
```
---
## 用法
### 1. 本地_stdio模式（适用于本地IDE/Claude Desktop）
在此模式下，服务器直接从shell环境中读取凭证。
设置所需的环境变量：
```bash
export CLOCKIFY_API_KEY="您的Clockify API密钥"
export CLOCKIFY_WORKSPACE_ID="您的Clockify工作区ID"
export WAKATIME_API_KEY="您的WakaTime API密钥"
export AZURE_DEVOPS_PAT="您的Azure DevOps个人访问令牌"
export AZURE_DEVOPS_ORG="https://dev.azure.com/您的组织"
```
启动服务器：
```bash
mitra start --transport stdio
```
#### Claude Desktop集成
要将米特拉与Claude Desktop应用程序一起本地使用，请在Claude Desktop配置文件中配置服务器：
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
在`mcpServers`键下添加以下JSON片段：
```json
{
"mcpServers": {
"mitra": {
"command": "/绝对路径/到/您的/venv/bin/mitra",
"args": [
"start",
"--transport",
"stdio"
],
"env": {
"CLOCKIFY_API_KEY": "您的Clockify API密钥",
"CLOCKIFY_WORKSPACE_ID": "您的Clockify工作区ID",
"WAKATIME_API_KEY": "您的WakaTime API密钥",
"AZURE_DEVOPS_PAT": "您的Azure DevOps个人访问令牌",
"AZURE_DEVOPS_ORG": "https://dev.azure.com/您的组织"
}
}
}
}
```
> [!NOTE]
> 确保将`/绝对路径/到/您的/venv/bin/mitra`替换为Python虚拟环境中`mitra`可执行文件的实际路径（例如，`which mitra`）。
#### Claude Code（CLI）集成
要将米特拉与**Claude Code CLI**一起使用，请使用`claude mcp add`命令注册它。
在终端中运行以下命令来配置服务器（添加`--scope user`标志，如果您希望它在所有项目中全局可用）：
```bash
claude mcp add mitra --scope user \
-e CLOCKIFY_API_KEY="您的Clockify API密钥" \
-e CLOCKIFY_WORKSPACE_ID="您的Clockify工作区ID" \
-e WAKATIME_API_KEY="您的WakaTime API密钥" \
-e AZURE_DEVOPS_PAT="您的Azure DevOps个人访问令牌" \
-e AZURE_DEVOPS_ORG="https://dev.azure.com/您的组织" \
-- /绝对路径/到/您的/venv/bin/mitra start --transport stdio
```
您可以通过在Claude Code会话中输入`/mcp`来查看活动服务器，或使用`claude mcp list`查看列表。
### 2. 远程SSE模式（适用于Web服务）
在远程模式下，服务器作为HTTP应用程序托管。客户端在每个请求的基础上使用HTTP头部提供凭证：
- `X-Clockify-Api-Key`
- `X-Clockify-Workspace-Id`
- `X-Wakatime-Api-Key`
- `X-Azure-Devops-Pat`
- `X-Azure-Devops-Org`
启动服务器：
```bash
mitra start --transport sse --host 127.0.0.1 --port 8000
```
