精益时间-MCP

Name: 精益时间-MCP
Author: Leantime

作者：Leantime6 星标更新：2025-07-31

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

项目介绍

Leantime MCP Bridge

适用于Leantime项目管理系统的强大Model Context Protocol (MCP)代理桥。使用TypeScript和官方MCP SDK构建，此工具提供了一个可靠的MCP客户端与Leantime服务器之间的桥梁。

✨ 特性

使用官方MCP SDK：使用@modelcontextprotocol/sdk进行强大的协议处理
多种身份验证方法：Bearer、API Key、Token 和 X-API-Key 头
协议版本支持：MCP 2025-03-26（最新）并具有向后兼容性
高级传输支持：HTTP/HTTPS、服务端发送事件（SSE）和流响应
TypeScript实现：类型安全且易于维护的代码库

预备条件

如果您是自托管，请需要MCPServer插件 https://marketplace.leantime.io/product/mcp-server/
通过Leantime UI生成的个人访问令牌（或API密钥）

🚀 安装

从npm

npm install -g leantime-mcp

从源码

git clone https://github.com/leantime/leantime-mcp.git
cd leantime-mcp
npm install
npm run build
npm install -g .

📖 使用

🖥️ Claude Desktop配置

添加到您的claude_desktop_config.json：

基本配置

{
  "mcpServers": {
    "leantime": {
      "command": "leantime-mcp",
      "args": [
        "https://yourworkspace.leantime.io/mcp",
        "--token",
        "YOUR_TOKEN_HERE"
      ]
    }
  }
}

本地开发使用自签名证书

{
  "mcpServers": {
    "leantime": {
      "command": "leantime-mcp",
      "args": [
        "https://yourworkspace.leantime.io/mcp",
        "--token",
        "YOUR_TOKEN_HERE",
        "--insecure"
      ]
    }
  }
}

使用绝对路径

{
  "mcpServers": {
    "leantime": {
      "command": "node",
      "args": [
        "/path/to/leantime-mcp/dist/index.js",
        "https://your-leantime.com/mcp",
        "--token",
        "YOUR_TOKEN_HERE"
      ]
    }
  }
}

生产环境配置增强安全性

{
  "mcpServers": {
    "leantime": {
      "command": "leantime-mcp",
      "args": [
        "https://yourworkspace.leantime.io/mcp",
        "--token",
        "YOUR_TOKEN_HERE",
        "--auth-method",
        "Bearer",
        "--max-retries",
        "5",
        "--retry-delay",
        "2000"
      ]
    }
  }
}

💻 Claude Code配置

对于Claude Code，添加到您的claude_config.json或使用命令行：

配置文件

{
  "mcp": {
    "servers": {
      "leantime": {
        "command": "leantime-mcp",
        "args": [
          "https://yourworkspace.leantime.io/mcp",
          "--token",
          "YOUR_TOKEN_HERE"
        ]
      }
    }
  }
}

命令行使用

claude --mcp-server leantime="leantime-mcp https://your-leantime.com/mcp --token YOUR_TOKEN_HERE"

🎯 Cursor配置

对于Cursor IDE，添加到您的工作区设置或全局设置：

工作区设置（`.vscode/settings.json`）

{
  "mcp.servers": {
    "leantime": {
      "command": "leantime-mcp",
      "args": [
        "https://yourworkspace.leantime.io/mcp",
        "--token",
        "YOUR_TOKEN_HERE"
      ]
    }
  }
}

全局设置

打开Cursor设置 → 扩展 → MCP 并添加：

{
  "leantime": {
    "command": "leantime-mcp",
    "args": [
      "https://yourworkspace.leantime.io/mcp",
      "--token",
      "YOUR_TOKEN_HERE"
    ]
  }
}

🤖 OpenAI/ChatGPT 自定义GPT配置

对于支持MCP的ChatGPT或OpenAI API集成：

OpenAI API配置

# 使用OpenAI和MCP的Python示例
import openai
from mcp_client import MCPClient

# 初始化MCP客户端
mcp_client = MCPClient(
    command="leantime-mcp",
    args=[
        "https://yourworkspace.leantime.io/mcp",
        "--token",
        "YOUR_TOKEN_HERE"
    ]
)

# 与OpenAI一起使用
client = openai.OpenAI(api_key="your-openai-key")
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Show me my Leantime projects"}],
    tools=mcp_client.get_tools()
)

自定义GPT动作配置

# 对于自定义GPT动作
openapi: 3.0.0
info:
  title: Leantime MCP Proxy
  version: 2.0.0
servers:
  - url: https://yourworkspace.leantime.io/mcp
paths:
  /tools/list:
    post:
      summary: 列出可用工具
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                jsonrpc:
                  type: string
                  default: "2.0"
                method:
                  type: string
                  default: "tools/list"
                id:
                  type: integer
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

🌐 普通MCP客户端配置

对于任何MCP兼容客户端：

标准MCP配置

{
  "name": "leantime",
  "command": "leantime-mcp",
  "args": [
    "https://yourworkspace.leantime.io/mcp",
    "--token",
    "YOUR_TOKEN_HERE"
  ],
  "env": {
    "NODE_ENV": "production"
  }
}

Docker配置

# docker-compose.yml
version: '3.8'
services:
  leantime-mcp:
    image: node:18-alpine
    command: npx leantime-mcp https://yourworkspace.leantime.io/mcp --token YOUR_TOKEN_HERE
    environment:
      - NODE_ENV=production
    volumes:
      - ./config:/config
    stdin_open: true
    tty: true

📱 环境特定示例

开发环境

# 使用调试日志进行本地测试
leantime-mcp https://localhost:8080/mcp \
  --token "dev-token-123" \
  --insecure \
  --no-cache \
  --max-retries 1 \
  2>debug.log

预发布环境

# 中等可靠性的预发布环境
leantime-mcp https://staging.leantime.com/mcp \
  --token "staging-token-456" \
  --max-retries  3 \
  --retry-delay 1000

生产环境

# 高可靠性的生产环境
leantime-mcp https://leantime.company.com/mcp \
  --token "prod-token-789" \
  --auth-method Bearer \
  --max-retries 5 \
  --retry-delay 2000

🔧 命令行用法

leantime-mcp <url> --token <token> [选项]

参数

<url> - Leantime MCP端点URL（必需）
--token <token> - 认证令牌（必需）
--auth-method <method> - 认证方法（可选，默认：Bearer）
--insecure - 跳过SSL证书验证（可选）
--protocol-version <version> - MCP协议版本（可选）
--max-retries <num> - 最大重试次数（可选，默认：3）
--retry-delay <ms> - 基础重试延迟（毫秒）（可选，默认：1000）
--no-cache - 禁用响应缓存（可选）

认证方法

方法	头格式	示例
`Bearer`（默认）	`Authorization: Bearer <token>`	`--auth-method Bearer`
`X-API-Key`	`X-API-Key: <token>`	`--auth-method X-API-Key`

示例

使用Bearer令牌的基本用法

leantime-mcp https://leantime.example.com/mcp --token abc123

使用API密钥认证

leantime-mcp https://leantime.example.com/mcp --token abc123 --auth-method x-api-key

使用自签名证书进行本地开发

leantime-mcp https://localhost/mcp --token abc123 --insecure

指定协议版本

leantime-mcp https://leantime.example.com/mcp --token abc123 --protocol-version 2025-03-26

高可靠性设置及自定义重试设置

leantime-mcp https://leantime.example.com/mcp --token abc123 --max-retries 5 --retry-delay 2000

开发/测试时禁用缓存

leantime-mcp https://leantime.example.com/mcp --token abc123 --no-cache

🔧 工作原理

协议处理：使用官方MCP SDK进行强大的JSON-RPC消息处理
认证：根据选择的方法添加适当的认证头
传输层：支持常规HTTP响应和服务端发送事件（SSE）
错误处理：全面的错误处理，带有正确的JSON-RPC错误响应
会话管理：跟踪MCP会话ID以实现有状态交互
重试逻辑：指数退避加抖动防止雷击效应
智能缓存：缓存工具/资源/提示列表以减少服务器负载

🔄 高级功能

带指数退避的重试逻辑

自动重试：失败请求自动重试（默认：3次尝试）
指数退避：每次重试延迟翻倍（1s → 2s → 4s...）
抖动：随机±25%变化防止雷击效应
可配置：通过CLI选项自定义最大重试次数和基础延迟

智能响应缓存

自动缓存：tools/list、resources/list和prompts/list响应被缓存
基于TTL的过期：缓存响应在5分钟后过期
内存高效：自动清理已过期的缓存条目
可配置：使用--no-cache禁用开发/测试

生产就绪可靠性

连接韧性：优雅地处理网络中断
请求跟踪：编号请求便于调试
详细日志：详细的日志输出到stderr（不会干扰MCP通信）
优雅关闭：接收到SIGINT/SIGTERM信号时干净终止

🏗️ 架构

v2.0 相比v1.x 的改进

TypeScript重写：类型安全实现，更好的可维护性
官方SDK集成：使用@modelcontextprotocol/sdk而不是自定义实现
增强认证：支持多种认证方法
更好的错误处理：正确的JSON-RPC错误响应和日志记录
协议协商：自动协议版本协商
流支持：完全支持SSE和流响应

协议支持

主要：MCP 2025-03-26（最新规范）
备用：MCP 2024-11-05（向后兼容）
自动协商：自动检测并使用适当的协议版本

🧪 开发

预备条件

Node.js 18.0.0 或更高版本
TypeScript 5.4.0 或更高版本
带有MCP支持的Leantime实例访问权限

从源码构建

# 克隆仓库
git clone https://github.com/leantime/leantime-mcp.git
cd leantime-mcp

# 安装依赖
npm install

# 构建TypeScript
npm run build

# 本地测试
echo '{"jsonrpc":"2.0","id":1,"method":"ping"}' | node dist/index.js https://your-leantime.com/mcp --token your-token

开发模式

# 监控更改并重新构建
npm run dev

🛡️ 安全注意事项

仅限HTTPS：生产环境中始终使用HTTPS
令牌安全：安全存储令牌，避免将其记录下来
SSL验证：仅在开发中使用--insecure标志
令牌轮换：考虑为长时间运行的过程实施令牌轮换
网络安全：确保代理和Leantime服务器之间的适当网络安全

🐛 错误处理

代理包括全面的错误处理：

网络问题：连接超时，DNS解析失败
认证：无效令牌，过期凭证
协议错误：格式不正确的JSON-RPC消息，协议不匹配
服务器错误：HTTP错误，来自Leantime的无效响应
传输问题：SSE连接问题，流错误

所有错误消息都记录到stderr，以避免干扰MCP通信上的stdout。

🛠️ 故障排除

常见问题及解决方案

"Mcp-Session-Id header required for POST requests"

已在v2.0中修复：代理现在会在初始握手后自动捕获并在所有请求中包含MCP会话ID。

"Invalid JSON-RPC response"错误在Claude Desktop中

已在v2.0中修复：代理现在将Leantime的PHP错误响应转换为Claude Desktop可以理解的正确JSON-RPC错误格式。

连接不断断开/重启

检查您的令牌：确保Leantime API令牌有效且具有适当的权限
网络问题：对于不可靠的连接使用--max-retries 5
SSL问题：使用--insecure进行自签名证书的开发

代理立即退出而没有错误

这是正常行为 - 代理等待从Claude Desktop通过stdin接收JSON-RPC消息。如果您正在手动测试，请发送一个JSON-RPC消息：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | leantime-mcp https://your-leantime.com/mcp --token YOUR_TOKEN

"未找到命令：leantime-mcp"

全局安装：从项目目录运行npm install -g .

使用绝对路径：在您的Claude Desktop配置中直接引用编译脚本：

"command": "node",
"args": ["/absolute/path/to/leantime-mcp/dist/index.js", ...]

调试模式

启用详细日志以排查连接问题：

# 代理将日志输出到stderr，因此您可以看到调试信息，同时MCP通信继续
leantime-mcp https://your-leantime.com/mcp --token YOUR_TOKEN 2>debug.log

查看日志

Claude Desktop日志：检查~/Library/Logs/Claude/mcp-server-leantime.log（macOS）以获取详细的MCP通信日志。

代理日志：所有代理日志都输出到stderr，包括：

带编号ID的请求/响应跟踪
缓存命中/未命中信息
重试尝试和退避时间
会话ID管理
错误详情和转换

📊 日志

代理提供了详细的日志用于调试：

[LeantimeMCP] 初始化Leantime MCP代理...
[LeantimeMCP] 服务器：https://leantime.example.com/mcp
[LeantimeMCP] 认证方法：Bearer
[LeantimeMCP] SSL验证：启用
[LeantimeMCP] 协议版本：2025-03-26
[LeantimeMCP] 准备处理MCP请求...

📄 许可

MIT许可 - 详见LICENSE文件

🤝 贡献

分叉仓库
创建功能分支（git checkout -b feature/amazing-feature）
使用TypeScript进行更改
如适用，添加测试
构建和测试（npm run build && npm test）
提交拉取请求

💬 支持

对于问题和疑问：

在GitHub Issues上创建问题
查看Leantime文档中的MCP设置
在Leantime中验证您的令牌是否具有适当的权限

📋 变更日志

1.6.0（最新）

🎉 **完整的TypeScript重写

精益时间-MCP

项目介绍

Leantime MCP Bridge

✨ 特性

预备条件

🚀 安装

从npm

从源码

📖 使用

🖥️ Claude Desktop配置

基本配置

本地开发使用自签名证书

使用绝对路径

生产环境配置增强安全性

💻 Claude Code配置

配置文件

命令行使用

🎯 Cursor配置

工作区设置（.vscode/settings.json）

全局设置

🤖 OpenAI/ChatGPT 自定义GPT配置

OpenAI API配置

自定义GPT动作配置

🌐 普通MCP客户端配置

标准MCP配置

Docker配置

📱 环境特定示例

开发环境

预发布环境

生产环境

🔧 命令行用法

参数

认证方法

示例

使用Bearer令牌的基本用法

使用API密钥认证

使用自签名证书进行本地开发

指定协议版本

高可靠性设置及自定义重试设置

开发/测试时禁用缓存

🔧 工作原理

🔄 高级功能

带指数退避的重试逻辑

智能响应缓存

生产就绪可靠性

🏗️ 架构

v2.0 相比v1.x 的改进

协议支持

🧪 开发

预备条件

从源码构建

开发模式

🛡️ 安全注意事项

🐛 错误处理

🛠️ 故障排除

常见问题及解决方案

"Mcp-Session-Id header required for POST requests"

"Invalid JSON-RPC response"错误在Claude Desktop中

连接不断断开/重启

代理立即退出而没有错误

"未找到命令：leantime-mcp"

调试模式

查看日志

📊 日志

📄 许可

🤝 贡献

💬 支持

📋 变更日志

1.6.0（最新）

工作区设置（`.vscode/settings.json`）