内容
# YouGile 安全 MCP
适用于 [YouGile](https://yougile.com) API v2 的本地stdio [模型上下文协议](https://modelcontextprotocol.io/) 服务器。默认情况下为只读；写入需要用户在聊天中确认确切的有效载荷后颁发的明确、一次性批准。
## 工具列表
### 只读
| 工具 | 用途 |
| --- | --- |
| `get_current_user` | 拥有 API 密钥的个人资料 |
| `list_projects`, `get_project` | 项目 |
| `list_boards`, `get_board` | 看板 |
| `list_columns` | 列 |
| `list_tasks` | 带有服务器端过滤（列、指派人、标题、贴纸）的任务概要 |
| `get_task` | 按 UUID 获取完整任务对象 |
| `find_task_by_short_id` | 通过类似 `ID-484` / `DEV-484` 的人类可读 ID 查找任务 |
| `list_task_comments` | 任务聊天消息 |
| `list_users` | 公司用户（按项目或电子邮件过滤） |
| `list_string_stickers` | 自定义贴纸及其状态 |
所有列表工具返回 `{"items": [...], "has_more": bool}`；`limit`上限为 100，请使用 `offset` 获取下一页。
### 分阶段写入（需要明确批准）
| 工具 | 用途 |
| --- | --- |
| `propose_task_create` | 分阶段新建任务，返回预览和一次性批准令牌 |
| `propose_task_update` | 分阶段更新现有任务，合同相同 |
| `apply_approved_action` | 执行分阶段操作；唯一可以改变 YouGile 的工具 |
流程为：代理分阶段操作 → 向用户显示预览 → 用户在聊天中批准 → 代理使用令牌调用 `apply_approved_action`。令牌与确切的载荷绑定，只能使用一次，并在 `YOUGILE_APPROVAL_TTL_SECONDS`（默认为 600）后过期。**删除操作未实现。**
### 安全模型
- 仅使用 `YOUGILE_API_KEY`；从不接受、存储或发送帐户登录/密码。
- 从不创建、列出或删除 YouGile API 密钥、Webhook 或用户。
- 从不将凭证写入磁盘；API 错误从不包含响应正文，因此密钥无法通过错误消息泄露。
- 所有插入 URL 路径的对象 ID 均验证为 UUID（无路径遍历）。
- `YOUGILE_BASE_URL` 必须是 `https`（纯 `http` 仅允许用于 localhost）。
- 使用有界重试处理 YouGile 速率限制（50 请求/分钟）以应对 HTTP 429。
## 安装
```bash
git clone https://github.com/ropuwz-dot/MCP-Yougile.git
cd MCP-Yougile
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]' # Linux/macOS
# .venv\Scripts\python -m pip install -e .[dev] # Windows
```
在环境中运行它并设置 API 密钥：
```bash
export YOUGILE_API_KEY='your-api-key' # Windows: $env:YOUGILE_API_KEY='your-api-key'
.venv/bin/python run_server.py # Windows: .venv\Scripts\python run_server.py
```
## 配置
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `YOUGILE_API_KEY` | — （必填） | YouGile API v2 密钥 |
| `YOUGILE_BASE_URL` | `https://yougile.com` | 自托管部署：`conf.json` 中的 `mainPageUrl` |
| `YOUGILE_TIMEOUT_SECONDS` | `30` | HTTP 超时 |
| `YOUGILE_APPROVAL_TTL_SECONDS` | `600` | 分阶段写入批准的生命周期 |
| `YOUGILE_SSL_CA_CERT` | — | 自托管服务器的 CA 捆绑路径，适用于自签名证书 |
| `YOUGILE_ALLOW_INSECURE_HTTP` | `false` | 显式选择加入纯 http 本地自托管服务器 |
### 自托管（盒装）YouGile
[自托管 Linux 服务器版](https://docs.yougile.com/docs/admin-guide-linux/api/) 在您自己的域上公开相同的 API v2。将 `YOUGILE_BASE_URL` 指向 `conf.json` 中的 `mainPageUrl` 值：
- **具有自签名证书的 HTTPS** — 将 `YOUGILE_SSL_CA_CERT` 设置为证书（或其 CA）的路径，以便 TLS 验证继续工作。验证永远无法关闭。
- **在受信任的本地网络上使用纯 HTTP** — YouGile 允许本地使用，但此处需要 `YOUGILE_ALLOW_INSECURE_HTTP=true`，以便 API 密钥不会意外地以明文发送。`http://localhost` 无需标志即可工作。
## 客户端配置
### Claude Code
```bash
claude mcp add yougile -e YOUGILE_API_KEY=your-api-key -- /绝对路径/MCP-Yougile/.venv/bin/python /绝对路径/MCP-Yougile/run_server.py
```
### Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"yougile": {
"command": "/绝对路径/MCP-Yougile/.venv/bin/python",
"args": ["/绝对路径/MCP-Yougile/run_server.py"],
"env": { "YOUGILE_API_KEY": "your-api-key" }
}
}
}
```
### Hermes
将密钥保存在 `~/.hermes/.env` 中，并使用 `0600` 权限：
```dotenv
YOUGILE_API_KEY=your-api-key
```
然后在 `~/.hermes/config.yaml` 中添加此服务器：
```yaml
mcp_servers:
yougile:
command: /绝对路径/MCP-Yougile/.venv/bin/python
args: [/绝对路径/MCP-Yougile/run_server.py]
env:
YOUGILE_API_KEY: "${YOUGILE_API_KEY}"
timeout: 60
connect_timeout: 30
sampling:
enabled: false
```
在重启 Hermes 之前验证它：`hermes mcp test yougile`.
## 开发
```bash
.venv/bin/python -m pytest -q
.venv/bin/python -m ruff check src tests
.venv/bin/python -m mypy
```
CI 在 Python 3.11–3.13 上为每次推送和拉取请求运行相同的三个检查。
## 许可证
[MIT](LICENSE)
