内容
# yougile-mcp
[](https://github.com/IvanTereshin/yougile-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/yougile-mcp)
[](./LICENSE)
[](https://nodejs.org)
一款适用于 [YouGile](https://yougile.com) 的生产级 [Model Context Protocol](https://modelcontextprotocol.io) 服务器 - 让 AI 代理（如 Claude Desktop、Cursor 和任何 MCP 客户端）能够读取和管理您的 YouGile 项目、板块、任务、员工等。
> 与薄 API 包装不同，该服务器提供 **完整的 CRUD 支持**、**MCP 资源** 和 **预制的提示**，并具有重试、严格的输入验证、测试和 CI。
_[中文版本](#中文版本)_
---
## 为什么选择这个服务器
| | 典型的 YouGile MCP 包装 | **yougile-mcp** |
| ---------------- | --------------------------- | -------------------------------------------- |
| API 支持 | 部分（少数资源） | **所有核心资源** （项目 → 网络钩子） |
| MCP 原语 | 仅限工具 | **工具 + 资源 + 提示** |
| 输入验证 | 最小 | **每个工具的 Zod 模式** |
| 可靠性 | 单次尝试 | **重试 + 退避，429/重试后通知** |
| 测试/CI | 无 | **单元 + 集成，GitHub Actions** |
| 传输方式 | stdio | **stdio + 流式 HTTP** |
## 功能
**工具（44）** - 完整的 `list` / `get` / `create` / `update` （通过 `update` 进行软删除）适用于：
`projects`、`boards`、`columns`、`tasks`、`users`、`departments`、`group_chats`、
`string_stickers`、`sprint_stickers`、`webhooks` - 以及任务聊天
（`yougile_chat_list_messages`、`yougile_chat_send_message`）和公司
（`yougile_company_get`、`yougile_company_update`）。
**资源** - `yougile://projects`、`yougile://users` 和模板
`yougile://board/{boardId}` （带有列的板块）。
**提示** - `triage_board`、`create_task_from_note`、`standup_report`、`find_stale_tasks`。
查看 [docs/TOOLS.md](./docs/TOOLS.md) 以获取完整参考。
## 快速开始
您需要一个 YouGile API 密钥：**设置 → API**，或通过
`POST https://yougile.com/api-v2/auth/keys`。
```bash
# 直接使用 npx 运行
YOUGILE_API_KEY=您的密钥 npx yougile-mcp
```
### Claude Desktop
添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"yougile": {
"command": "npx",
"args": ["-y", "yougile-mcp"],
"env": { "YOUGILE_API_KEY": "您的密钥" }
}
}
}
```
### Cursor
添加到 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"yougile": {
"command": "npx",
"args": ["-y", "yougile-mcp"],
"env": { "YOUGILE_API_KEY": "您的密钥" }
}
}
}
```
## 配置
所有配置均通过环境变量完成（参见 [.env.example](./.env.example)）：
| 变量 | 必需 | 默认 | 描述 |
| ----------------------- | -------- | ---------------------------- | --------------------------------------- |
| `YOUGILE_API_KEY` | ✅ | — | YouGile API 承载令牌 |
| `YOUGILE_BASE_URL` | | `https://yougile.com/api-v2` | API 基本 URL（覆盖自托管） |
| `YOUGILE_TIMEOUT_MS` | | `30000` | 每个请求的超时时间 |
| `YOUGILE_MAX_RETRIES` | | `3` | 429/5xx/网络重试次数 |
| `YOUGILE_MCP_TRANSPORT` | | `stdio` | `stdio` 或 `http` |
| `YOUGILE_MCP_HTTP_PORT` | | `3000` | `transport=http` 时的端口 |
### HTTP 传输
```bash
YOUGILE_API_KEY=您的密钥 YOUGILE_MCP_TRANSPORT=http YOUGILE_MCP_HTTP_PORT=3000 npx yougile-mcp
# 无状态流式 HTTP 端点，POST http://localhost:3000/mcp
```
## 开发
```bash
npm install
npm run build # 打包到 dist/（tsup）
npm run typecheck # tsc --noEmit（严格）
npm run lint # eslint（类型检查）
npm test # vitest（单元 + 集成）
```
### 架构
```
src/
config.ts # 环境配置，通过 Zod 验证
client/ # 类型化的 YouGile API 客户端
http.ts # fetch + 超时 + 重试/退避
yougile.ts # 资源命名空间（client.tasks.list(...)）
types.ts errors.ts
tools/ # MCP 工具（通过共享助手进行 CRUD）+ 聊天/公司
resources/ # MCP 资源（项目，用户，板块模板）
prompts/ # MCP 提示（分类，站立会议，...）
transport/http.ts # 无状态流式 HTTP
server.ts # 工厂：连接客户端 + 工具/资源/提示
index.ts # 二进制入口点（stdio | http）
```
## 许可证
[MIT](./LICENSE) © Ivan Tereshin
---
## 中文版本
适用于 [YouGile](https://yougile.com) 的生产级 [Model Context Protocol](https://modelcontextprotocol.io) 服务器 - 让 AI 代理（如 Claude Desktop、Cursor 和任何 MCP 客户端）能够读取和管理您的 YouGile 项目、板块、任务、员工等。
> 与薄 API 包装不同，该服务器提供 **完整的 CRUD 支持**、**MCP 资源** 和 **预制的提示**，并具有重试、严格的输入验证、测试和 CI。
### 功能
**工具（44）** - 完整的 `list` / `get` / `create` / `update` （通过 `update` 进行软删除）适用于：
`projects`、`boards`、`columns`、`tasks`、`users`、`departments`、`group_chats`、
`string_stickers`、`sprint_stickers`、`webhooks`。此外还有任务聊天
（`yougile_chat_list_messages`、`yougile_chat_send_message`）和公司
（`yougile_company_get`、`yougile_company_update`）。
**资源** - `yougile://projects`、`yougile://users` 和模板
`yougile://board/{boardId}` （带有列的板块）。
**提示** - `triage_board`、`create_task_from_note`、`standup_report`、`find_stale_tasks`。
### 快速开始
您需要一个 YouGile API 密钥：**设置 → API** （或 `POST .../api-v2/auth/keys`）。
```bash
YOUGILE_API_KEY=您的密钥 npx yougile-mcp
```
Claude Desktop / Cursor 配置 - 见上文；所有环境变量均在 [.env.example](./.env.example) 和 [配置](#配置) 中描述。
### 许可证
[MIT](./LICENSE) © Иван Терешин
