PUNT MCP 服务器

关键词

PUNTLLM 集成实时协作工具化接口会话上下文

使用说明（简要且直观，便于开发者快速上手）：

  • 项目简介

    • 该仓库实现了一个 MCP 服务器，用于通过 MCP 标准向 LLM 客户端提供上下文服务，包括对资源、工具、以及提示模板的管理与执行能力，支持会话管理与实时更新。
    • 服务器使用 JSON-RPC 风格的请求/响应，并通过标准传输通道（当前为 stdio）与客户端对接，便于在本地开发环境中与 Claude、Claude Code 等 AI 客户端配合使用。

  • 主要功能点

    • MCP 核心能力
      • 资源管理与数据访问（面向 LLM 的上下文资源）
      • 工具注册与执行（LLM 调用外部功能）
      • 提示模板的定义与渲染
    • 实时通信与多传输
      • 目前实现通过 Stdio 传输实现 MCP 通信（未来可扩展为 SSE/WebSocket）
    • 与 Punt 应用后端的整合
      • 通过 MCP 服务器调用 Punt 的 REST API 客户端实现（mcp/src/api-client.ts），实现 Tickets、Projects、Sprints、Labels、Columns、Members 等操作的封装
    • 安全性与会话
      • 提供会话管理、权限检查与事件驱动的实时通知

  • 安装步骤（简化版）

    • 获取代码与依赖
      • 确保已安装 Node.js，推荐版本与 Punt 项目一致（文档推荐 Node.js 20+）。
      • 安装依赖：进入 punt/mcp 目录，执行相应的包管理器安装命令（如 pnpm install）。
    • 环境配置
      • 根目录下创建并配置 .env（必要时可通过 .env.example 复制），确保 MCP 的 API Key、数据库等依赖正确设置。
    • 启动 MCP 服务器
      • 使用 MCP 客户端的配置启动命令时，请参考以下服务器配置示例（不涉及代码示例，只给出配置模板）。
    • 运行方式
      • 服务器当前实现通过 stdio 传输与客户端连接，请确保客户端配置中使用 stdio 传输并将 MCP_API_KEY 设置到环境变量中。
    • 服务器与 Punt 的集成
      • MCP 服务端将通过 Punt 的 REST API（mcp/src/api-client.ts 中实现的请求封装）访问 Punt 的数据以提供服务。

  • 服务器配置（JSON，供 MCP 客户端使用） 说明：该配置用于 Claude/Claude Code 等 MCP 客户端连接 Punt 的 MCP 服务器。MCP 客户端需要在启动时读取该配置，以建立与 MCP 服务器的连接。 JSON 示例（仅描述，不放在代码块内）： { "serverName": "punt", "type": "stdio", "command": "pnpm", "args": ["--dir", "mcp", "exec", "tsx", "src/index.ts"], "cwd": "/path/to/your/project/root", "env": { "MCP_API_KEY": "your-api-key-here" } } 说明：

    • serverName：MCP 服务器的名称，推荐与 Punt 的实际名称保持一致，便于客户端识别
    • type：传输类型，当前实现使用 stdio
    • command/args：启动 MCP 服务器的命令及参数，按仓库提供的运行方式配置
    • cwd：运行工作目录，指向 Punt 项目的根目录
    • env.MCP_API_KEY：用于客户端认证的 API Key（按实际获取方式设置）

  • 基本使用方法

    • 客户端连接后，即可通过 MCP 提供的工具（如 list_projects、get_project、create_ticket 等）进行对 Punt 的操作
    • 使用 SSE/WebSocket 等后续传输方式时，可订阅服务器端的事件流，获取实时更新
    • 若要扩展功能，只需在 mcp/src/tools 目录下新增工具，或调整现有工具的注册即可

  • 运行与测试要点

    • 确保 Punt 后端数据库可用，MCP 服务器在启动时能正确访问 Punt 的 REST API
    • MCP 服务器通过标准输出和输入进行通信，确保客户端正确读取 JSON-RPC 风格的请求与响应
    • 如需将服务器暴露为对外服务，需在当前实现基础上增加对网络传输的支持（如 WebSocket），当前实现以 stdio 为核心传输

  • 重要注意

    • MCP 服务器代码与 Punt 应用紧密耦合，需保持 Punt 的 API 稳定性以确保 MCP 服务端功能可用
    • 该实现当前定位为服务器端，客户端仅通过配置读取与连接，不包含 MCP 客户端实现的代码

  • 参考与扩展

    • 服务器注册的工具覆盖：Tickets、Projects、Sprints、Members、Labels、Columns
    • 服务器侧对外暴露的操作界面以文本格式返回结果，便于 LLM 解析并展示

服务器信息

访问项目