回转-MCP服务器

Name: 回转-MCP服务器
Author: vsaranyuk

作者：vsaranyuk3 星标更新：2025-10-22

安装使用来源：spider==github.com

项目介绍

Kaiten MCP 服务器

用于 Kaiten API 与 Claude Desktop 集成的 MCP 服务器。允许您直接从 Claude 管理 Kaiten 卡片、评论和空间。

功能

卡片: 读取、创建、更新、删除、搜索
评论: 完整处理卡片评论
空间和看板: 按 Kaiten 结构导航
搜索: 带过滤器的高级搜索
默认空间: 在选定的空间中自动操作
🎛️ 详细程度控制: 管理响应细节（最小/正常/详细）- 节省高达 90% 的令牌
📊 响应格式: 根据不同场景选择输出格式（json/markdown）
🛡️ 自动截断: 自动上下文溢出保护（100k 字符）
🧪 测试套件: 准备好的模板用于质量测试
🔒 生产就绪:
- 所有参数的 Zod 验证
- 带指数退避的自动重试
- 并发控制（速率限制）
- 带 TTL 的 LRU 缓存（空间/看板/用户）
- 带提示的高级错误处理
- 日志中的令牌编辑
- 全面的日志记录和监控系统

快速开始

1. 安装

npm install

2. 设置 .env 文件

创建一个 .env 文件：

cp .env.example .env

用您的数据填充它：

KAITEN_API_URL=https://your-domain.kaiten.ru/api/latest
KAITEN_API_TOKEN=your_api_token_here
KAITEN_DEFAULT_SPACE_ID=12345  # 您的主要 space_id

# 可选性能设置（默认值）
KAITEN_MAX_CONCURRENT_REQUESTS=5     # 最大并发请求数（1-20）
KAITEN_CACHE_TTL_SECONDS=300         # 缓存生存时间（秒）（0 = 关闭）
KAITEN_REQUEST_TIMEOUT_MS=10000      # 请求超时时间（毫秒）（1-60000）

如何获取 API 令牌：

登录到 Kaiten
打开个人资料设置
创建一个新的 API 令牌
复制并粘贴到 .env 文件中

3. 构建

npm run build

4. 配置 Claude Desktop

打开配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

添加（替换路径为您完整的路径）：

{
  "mcpServers": {
    "kaiten": {
      "command": "node",
      "args": [
        "/完整的/路径/到/MCP Kaiten/dist/index.js"
      ],
      "cwd": "/完整的/路径/到/MCP Kaiten"
    }
  }
}

替代方法（无需 .env）:

{
  "mcpServers": {
    "kaiten": {
      "command": "node",
      "args": ["/完整的/路径/到/MCP Kaiten/dist/index.js"],
      "env": {
        "KAITEN_API_URL": "https://your-domain.kaiten.ru/api/latest",
        "KAITEN_API_TOKEN": "your_api_token_here",
        "KAITEN_DEFAULT_SPACE_ID": "12345"
      }
    }
  }
}

5. 重启 Claude Desktop

完全关闭（关闭 + Q / Alt + F4），然后重新打开 Claude Desktop。

6. 验证

向 Claude 输入：

显示 Kaiten 空间列表

可用工具（26 个工具）

卡片

kaiten_get_card - 获取卡片 ID [格式: json/markdown]
kaiten_create_card - 创建新卡片
kaiten_update_card - 更新卡片
kaiten_delete_card - 删除卡片
kaiten_search_cards - 使用过滤器搜索卡片 [详细程度: 最小/正常/详细]
kaiten_get_space_cards - 获取空间卡片 [详细程度]
kaiten_get_board_cards - 获取看板卡片 [详细程度]

kaiten_get_card_comments - 获取卡片评论
kaiten_create_comment - 创建评论
kaiten_update_comment - 更新评论
kaiten_delete_comment - 删除评论

空间和看板

kaiten_list_spaces 列出所有空间
kaiten_get_space - 获取空间 [格式: json/markdown]
kaiten_list_boards - 列出看板 [详细程度: 最小/正常/详细]
kaiten_get_board - 获取看板 [格式: json/markdown]

目录（正确 ID）

kaiten_list_columns - 列出看板的状态列
kaiten_list_lanes - 列出泳道
kaiten_list_types - 列出看板卡片类型

用户

kaiten_get_current_user - 获取当前用户
kaiten_list_users - 列出用户 [详细程度: 最小/正常/详细]

人力资源管理和诊断

kaiten_cache_invalidate_spaces - 清除空间缓存
kaiten_cache_invalidate_boards - 清除看板缓存
kaiten_cache_invalidate_users - 清除用户缓存
kaiten_cache_invalidate_all - 清除整个缓存
kaiten_get_status - 获取服务器状态（缓存、队列、配置、日志、指标）
kaiten_set_log_level - 运行时更改登录配置

使用示例

基本操作

显示卡片 789

创建卡片 "修复 Bug" 在看板 456 上，描述为 "授权问题"

更新卡片 789: 更改状态为 3

在卡片 789 上添加评论: "工作已完成"

详细程度控制 - 节省令牌

最小 - 超紧凑格式（节省 90%）：

在看板 456 上查找卡片，最小详细程度
# 输出: 1. [12345] 修复 Bug
#       2. [12346] 添加功能

正常 - 平衡（默认，节省 80%）：

在看板 456 上查找卡片
# 输出: 包含 owner、看板、状态、URL 的完整信息

详细 - 完整 API 响应：

在看板 456 上查找卡片，详细详细程度
# 输出: 所有元数据、权限、内部字段

何时使用：

最小 - 快速搜索、获取 ID、短列表
正常 - 处理卡片、常规任务（默认）
详细 - 调试、集成、需要所有字段

响应格式控制

Markdown - 易于阅读（默认）：

显示卡片 12345
# 输出: # 卡片标题
#       🔗 https://...
#       📋 看板: ...

JSON - 结构化数据：

以 JSON 格式显示卡片 12345
# 输出: {"id": 12345, "title": "...", ...}

何时使用：

markdown - 用户展示、演示（默认）
json - 集成、软件处理、解析

搜索

在看板 456 上查找带有“授权”字样的卡片

显示我在空间 123 中的卡片

在看板 456 上查找所有正在工作的卡片

默认空间

默认情况下，所有操作都在 KAITEN_DEFAULT_SPACE_ID 指定的空间中执行。这使命令更简洁：

查找关于保加利亚的卡片
# 自动在 DEFAULT_SPACE_ID 中搜索

要搜索所有空间，请明确指定：

查找关于保加利亚的卡片，在所有空间中

默认空间的工作原理：

所有卡片交易都自动使用 KAITEN_DEFAULT_SPACE_ID
要在其他区域搜索，请明确指定 space_id
要搜索所有地方，请明确要求“在所有空间”

优化和生产力

✅ 最佳搜索实践

DO (这样做)：

在看板 456 上查找带有“Bug”的卡片

Don't do it (不要这样做)：

显示空间中的所有卡片，并从中查找“Bug”

搜索选项

limit - 卡片数量（默认 10）
sort_by - 排序：created、updated、title
sort_direction - 方向：asc、desc
condition - 1=活动（默认），2=归档

带参数的例子

在看板 456 上查找 20 张卡片

显示看板 456 上的归档卡片

在看板 456 上查找按更新日期排序的卡片

项目结构

MCP Kaiten/
├── src/
│   ├── index.ts          # MCP 服务器
│   ├── kaiten-client.ts  # Kaiten API 客户端
│   ├── config.ts         # 配置和验证
│   ├── cache.ts          # LRU 缓存
│   ├── schemas.ts        # Zod 验证模式
│   ├── utils.ts          # 工具函数（11 个辅助函数）
│   ├── logging/          # 日志系统
│   │   ├── index.ts      # 导出
│   │   ├── types.ts      # TypeScript 类型
│   │   ├── logger.ts     # 统一日志器（单例）
│   │   ├── file-logger.ts    # Pino 文件日志器
│   │   ├── mcp-logger.ts     # MCP 通知日志器
│   │   └── metrics.ts        # 性能指标收集器
│   └── middleware/       # HTTP 中间件
│       └── logging-middleware.ts  # Axios 日志拦截器
├── evaluations/          # 测试套件
│   ├── README.md         # 测试套件指南
│   └── kaiten-eval-template.xml  # 包含 10 个问题的模板
├── logs/                 # 日志文件（在 .gitignore 中）
├── dist/                 # 编译后的文件
├── .env                  # 配置（不在 git 中）
├── .env.example          # 配置示例
├── tsconfig.json         # TypeScript 配置
├── package.json
├── README.md             # 此文件
├── CHANGELOG.md          # 变更历史
└── CLAUDE.md             # Claude Code 指南

卡片的可能性

收到卡片后，返回以下字段：

{
  "id": 12345,
  "title": "卡片标题",
  "url": "https://your-domain.kaiten.ru/space/12345/card/12345",
  "description": "完整描述...",
  "created": "2025-07-23T07:55:52.934Z",
  "updated": "2025-10-01T12:14:47.754Z",
  "state": 2,
  "owner_id": 67890,
  "owner_name": "伊万 伊万诺夫",
  "board_id": 54321,
  "board_title": "项目看板",
  "blocked": true,
  "block_reason": "等待团队的数据",
  "blocked_at": "2025-08-04T09:10:22.528Z",
  "blocker_name": "伊万 伊万诺夫",
  "archived": false,
  "tags": ["重要", "紧急"],
  "members": ["伊万 伊万诺夫", "玛丽亚 彼得罗娃"],
  "due_date": "2025-10-19T00:00:00.000Z"
}

故障排除

服务器无法连接

检查 Claude 配置中的路径
确保项目已编译：npm run build
检查 .env 文件
完全重启 Claude Desktop（重启 + Q）

API 错误

验证令牌是否有效
URL 必须以 /api/latest 结尾
检查 Kaiten 设置中的令牌访问权限

错误 "工具结果太大"

使用过滤器和参数 board_id：

# 不好
在空间 123 中查找卡片

# 好
在空间 123 的看板 456 上查找卡片

调试

高级日志

服务器支持灵活的日志系统用于调试和监控。所有日志设置都可以通过环境变量或运行时使用工具 kaiten_set_log_level 控制。

环境变量（可选）：

# 启用/禁用日志（默认: true）
KAITEN_LOG_ENABLED=true

# 日志级别（默认: error）
# debug | info | notice | warning | error | critical | alert | emergency
KAITEN_LOG_LEVEL=error

# 将日志发送到 MCP 客户端（默认: false）
KAITEN_LOG_MCP_ENABLED=false

# 记录日志到文件（默认: false）
KAITEN_LOG_FILE_ENABLED=false

# 日志文件路径（默认: ./logs/kaiten-mcp.log）
KAITEN_LOG_FILE_PATH=./logs/kaiten-mcp.log

# 记录所有 HTTP 请求（默认: false）
KAITEN_LOG_REQUESTS=false

# 收集性能指标（默认: false）
KAITEN_LOG_METRICS=false

完成配置文件：

生产（最少日志）：

KAITEN_LOG_LEVEL=error
KAITEN_LOG_FILE_ENABLED=false
KAITEN_LOG_REQUESTS=false
KAITEN_LOG_METRICS=false

开发（适度日志用于调试）：

KAITEN_LOG_LEVEL=info
KAITEN_LOG_FILE_ENABLED=true
KAITEN_LOG_REQUESTS=false
KAITEN_LOG_METRICS=true

调试（完整日志用于深入分析）：

KAITEN_LOG_LEVEL=debug
KAITEN_LOG_MCP_ENABLED=true
KAITEN_LOG_FILE_ENABLED=true
KAITEN_LOG_REQUESTS=true
KAITEN_LOG_METRICS=true

运行时日志管理：

使用工具 kaiten_set_log_level 在不重启的情况下更改配置：

# 启用调试模式
设置日志级别为 debug，启用文件和指标

# 关闭所有日志
设置日志级别为 off

# 只启用性能指标
设置日志级别为 info，启用指标

查看日志：

服务器日志输出到 stderr。在 macOS/Linux 上，可以通过 Console.app 或从终端运行 Claude 来查看。日志文件位于 logs/ 目录中，格式为 JSON（用于进一步分析）。

性能指标：

启用指标（KAITEN_LOG_METRICS=true）后，可以使用 kaiten_get_status 查看：

显示服务器状态

指标包括：

总请求数量
工具的聚合统计（延迟、成功率、缓存命中率）
最近 100 个请求及其详细信息

技术细节

Node.js: 版本 20 或更高（必需）engines
TypeScript: 5.0+
MCP SDK: @modelcontextprotocol/sdk v1.20.0
API 客户端: axios 带有 retry/backoff 和 AbortSignal 支持
大小: 约 600 行 TypeScript，编译代码 25KB

MCP I/O 协议

对于调试至关重要： MCP 使用 stdio 传输在客户端和服务器之间通信。

stdout — 仅 JSON-RPC 协议消息（纯通信通道）
stderr — 所有日志、调试信息、错误

重要：

代码中的任何 console.log() 都违反了协议 → 使用 console.error() 用于日志
该服务器通过 safeLog 包装器保证 stdout 的清洁度（src/config.ts:126-152）
调试时查看 stderr：node dist/index.js 2>debug.log 或使用 MCP Inspector

更多信息：构建一个 MCP 服务器

许可证

MIT

文档

CHANGELOG.md - 变更历史
CLAUDE.md - Claude Code 开发指南