Leantime MCP Bridge

倾斜时间MCP桥

Leanteme项目管理系统的一个健壮的模型上下文协议（MCP）代理桥。该工具使用TypeScript和官方MCP SDK构建，在MCP客户端和Leanteme服务器之间提供了一个可靠的桥梁。

✨ 特性

• 使用官方MCP SDK构建：用途 @modelcontextprotocol/sdk 用于强健的协议处理
• 多种身份验证方法：承载、API密钥、令牌和X-API-Key头
• 协议版本支持：MCP 2025-03-26（最新），具有向后兼容性
• 高级运输支持：HTTP/HTTPS、服务器发送事件（SSE）和流式响应
• TypeScript实现：类型安全、可维护的代码库

先决条件

• 如果您是自托管的，则需要MCPServer插件https://marketplace.leantime.io/product/mcp-server/
• 通过Leanteme 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桌面配置

添加到您的 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代码配置

对于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 IDE，添加到工作区设置或全局设置中：

工作区设置(.vscode/settings.json)

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

全局设置

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

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

🤖 OpenAI/ChatGPT自定义GPT配置

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

OpenAI API配置

# Python example using OpenAI with MCP
import openai
from mcp_client import MCPClient

# Initialize MCP client
mcp_client = MCPClient(
    command="leantime-mcp",
    args=[
        "https://yourworkspace.leantime.io/mcp",
        "--token",
        "YOUR_TOKEN_HERE"
    ]
)

# Use with 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操作配置

# For Custom GPT Actions
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: List available tools
      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

📱 环境特定示例

开发环境

# Local testing with debug logging
leantime-mcp https://localhost:8080/mcp \
  --token "dev-token-123" \
  --insecure \
  --no-cache \
  --max-retries 1 \
  2>debug.log

模拟环境

# Staging with moderate reliability
leantime-mcp https://staging.leantime.com/mcp \
  --token "staging-token-456" \
  --max-retries 3 \
  --retry-delay 1000

生产环境

# Production with high reliability
leantime-mcp https://leantime.company.com/mcp \
  --token "prod-token-789" \
  --auth-method Bearer \
  --max-retries 5 \
  --retry-delay 2000

🔧 命令行用法

leantime-mcp  --token  [options]

参数

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

身份验证方法

例子

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

🔧 运作原理

1. 协议处理：使用官方MCP SDK进行强大的JSON-RPC消息处理
2. 认证：根据所选方法添加适当的身份验证标头
3. 传输层：支持常规HTTP响应和服务器发送事件（SSE）
4. 错误处理：通过正确的JSON-RPC错误响应进行全面的错误处理
5. 会话管理：跟踪有状态交互的MCP会话ID
6. 重试逻辑：具有抖动的指数级退避可防止雷鸣般的羊群问题
7. 智能缓存：缓存工具/资源/提示列表以减少服务器负载

🔄 高级功能

使用指数回退重试逻辑

• 自动重试：失败的请求会自动重试（默认值：3次尝试）
• 指数退避：每次重试延迟加倍（1秒→ 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支持访问Leanteme实例

从源头构建

# Clone the repository
git clone https://github.com/leantime/leantime-mcp.git
cd leantime-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

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

开发模式

# Watch for changes and rebuild
npm run dev

🛡️ 安全考虑

• 仅限HTTPS：在生产环境中始终使用HTTPS
• 令牌安全：安全地存储令牌并避免记录它们
• SSL验证：仅使用 --insecure 发展中的旗帜
• 代币轮换：考虑对长时间运行的流程实施令牌轮换
• 网络安全：确保代理和Leantime服务器之间的网络安全

🐛 错误处理

该代理包括以下全面的错误处理：

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

所有错误消息都记录到 stderr 避免干扰MCP通信 stdout.

🛠️ 故障排除

常见问题及解决方法

“POST请求需要Mcp会话Id标头”

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

Claude Desktop中的“JSON-RPC响应无效”错误

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

连接不断中断/重新启动

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

代理立即退出，没有错误

这是正常行为——代理通过stdin等待来自Claude Desktop的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", ...]

调试模式

启用详细日志记录以排除连接问题：

# The proxy logs to stderr, so you can see debug info while MCP communication continues
leantime-mcp https://your-leantime.com/mcp --token YOUR_TOKEN 2>debug.log

检查日志

克劳德桌面日志：检查 ~/Library/Logs/Claude/mcp-server-leantime.log （macOS）查看详细的MCP通信日志。

代理日志：所有代理日志都转到 stderr 包括：

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

📊 日志记录

代理为调试提供了详细的日志记录：

[LeantimeMCP] Initializing Leantime MCP Proxy...
[LeantimeMCP] Server: https://leantime.example.com/mcp
[LeantimeMCP] Auth Method: Bearer
[LeantimeMCP] SSL verification: enabled
[LeantimeMCP] Protocol version: 2025-03-26
[LeantimeMCP] Ready to handle MCP requests...

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🤝 贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 使用TypeScript进行更改
4. 如果适用，添加测试
5. 构建和测试(npm run build && npm test)
6. 提交拉取请求

💬 支持

对于问题和疑问：

• 在以下位置创建问题
• 检查 精益时间文件 用于MCP设置
• 验证您的令牌在Leanteme中具有适当的权限

📋 更新日志

1.6.0（最新）

• 🎉 完全重写TypeScript 使用官方MCP SDK
• ✨ 多种身份验证方法 （承载器、ApiKey、令牌、X-API-Key）
• 🚀 增强的协议支持 （MCP 2025-03-26+向后兼容性）
• 🔧 改进了错误处理 以及日志记录
• 📡 更好的传输层 支持SSE和流媒体
• 🛡️ 增强安全 会话管理
• 📦 更小的代码库 （减少80%），可维护性更好
• 🔄 高级重试逻辑 具有指数退避和抖动
• 💾 智能缓存 用于工具列表和模式（5分钟TTL）
• ⚡ 生产准备就绪 连接弹性和错误恢复

1.x.x（遗留）

• 基本MCP代理功能
• HTTP/HTTPS支持
• 仅限承载令牌身份验证
• SSL验证绕过选项