Super Turtle MCP 服务器实现

使用说明

• 项目简介
  • 该仓库实现了基于 MCP 的后端服务器，用于向 LLM 客户端提供资源数据、工具执行能力以及可渲染的 Prompt 模板等上下文服务。核心通过 JSON-RPC 与客户端通信，服务器端负责会话管理、能力声明及跨传输协议的支持。仓库内包含两个核心 MCP 服务器示例：
    • send-turtle：将 Emoji Kitchen 的 turtle 图片请求转化为 Telegram 发送任务，通过 IPC 文件实现请求-应答模式，供 Telegram 机器人组件消费执行。
    • bot-control：提供对机器人控制相关的工具接口（如获取使用情况、切换模型、会话管理等），同样通过 IPC 机制与 Bot 控制流程衔接。
• 主要功能点
  • MCP 服务端实现：使用 Model Context Protocol 的 Server 与 StdioServerTransport，暴露工具列表和工具调用接口。
  • 工具调用与结果返回：支持 ListTools 与 CallTool 请求，工具调用结果通过 IPC 文件回传给客户端。
  • 资源与数据访问：通过工具描述和输入参数，提供对外部系统的调用能力。
  • 会话与状态管理：服务器端记录请求与结果，便于后续追踪和调试。
  • 多服务器支持：仓库中包含两个 MCP 服务器示例，便于在同一应用中对外暴露多种能力。
  • 流式/ STDIO 传输：默认以 STDIO 作为 MCP 客户端的传输通道，便于在本地或容器中直接运行。
• 安装与运行
  • MCP 服务器需要 Node/Bun 运行环境，项目中使用 bun + npm 脚本进行构建与启动。
  • 直接运行示例服务器（ send-turtle / bot-control ）通常需要在同一环境下按 MCP 标准先安装依赖、再通过 Bun 启动对应的服务端脚本。
• MCP 服务器配置（给 MCP 客户端使用的配置示例）
  • 服务器配置以 JSON 形式提供，描述服务器名称、启动命令以及参数等信息，供 MCP 客户端建立连接。
  • 下面给出仓库内配置的准确示例（请将路径替换为你部署时的实际路径）： { "mcp_servers": { "send-turtle": { "command": "bun", "args": ["run", "/path/to/your/repo/super_turtle/claude-telegram-bot/send_turtle_mcp/server.ts"], "cwd": "/path/to/your/repo" }, "bot-control": { "command": "bun", "args": ["run", "/path/to/your/repo/super_turtle/claude-telegram-bot/bot_control_mcp/server.ts"], "cwd": "/path/to/your/repo" } } } 说明：
  • command：启动 MCP 服务器的可执行程序，一般为 bun。
  • args：运行服务器脚本及必要参数，路径请指向仓库中的 server.ts。
  • cwd：运行工作目录，确保服务器脚本及相对导入能够正确解析。
  • 对接客户端时，客户端仅需要读取上述配置中的 server 名称、command、args 等字段，便能启动对应 MCP 服务器。
• 基本使用方法
  • 在目标环境中按照以下步骤部署：
    1. 安装运行环境：确保系统已安装 Bun（或 Node 相应环境），并具备 Bun 的执行能力。
    2. 安装依赖并构建：在相关 MCP 服务器目录下执行 bun install（若需要）。
    3. 启动 MCP 服务器：通过命令 bun run send_turtle_mcp/server.ts 或 bun run bot_control_mcp/server.ts 启动对应的 MCP 服务器。
    4. 配置 MCP 客户端：将上述 JSON 配置写入客户端（Claude/Codex）所读取的位置，确保客户端能够找到并启动 MCP 服务器。
  • 运行时注意事项
    • 服务器通过 STDIO 传输 JSON-RPC，请确保生产环境中没有其它输出污染 STDOUT，以避免 MCP 传输异常。
    • 服务器在运行时会通过 IPC 文件夹（/tmp 等）与其他系统组件通信，确保该目录具有写权限。
    • 如需在容器化部署，需确保工作目录和 IPC 路径在容器内可访问且持久化。