Super Turtle MCP 服务器端

使用说明（Markdown）

• 项目简介

  • 该仓库实现了基于 MCP 的后端服务器，用于向 LLM 客户端暴露“发送 turtle 笑脸图片的工具”和“bot 控制工具”等能力。服务器通过标准的 MCP JSON-RPC 流程完成请求-响应，并通过文件系统 IPC 与前端代理进程进行任务对接。

• 主要功能点

  • 提供工具查询：列出可用工具及其输入/输出规范，便于 LLM 端在对话中调用。
  • 工具调用处理：接收工具调用请求，将请求写入 IPC 文件，等待后台子系统完成处理并返回结果到 MCP 客户端。
  • 基于文件的后台交互：使用 /tmp 下的 JSON 事件文件进行请求与结果回传，解耦前后端。
  • 安全与观测：通过日志记录与事件上报，帮助追踪工具调用、请求状态和错误信息。

• 安装步骤

  • 确保系统已安装 Bun 的执行环境，用于运行 BSP（示例服务端代码）。
  • 将仓库中的两个 MCP 服务脚本加载到运行环境中（send_turtle_mcp/server.ts 与 bot_control_mcp/server.ts），并确保依赖（@modelcontextprotocol/sdk）可用。
  • 按需配置工作目录与 IPC 目录（默认是 /tmp，运行时通过 SUPERTURTLE_IPC_DIR 环境变量指定）。

• 服务器配置（MCP 客户端使用的配置，示例 JSON，字段含义见注释） { "mcp_servers": { "send-turtle": { "command": "bun", "args": ["run", "super_turtle/claude-telegram-bot/send_turtle_mcp/server.ts"], "env": { "SUPERTURTLE_IPC_DIR": "/tmp" } // 说明：send-turtle 服务器实现了 MCP 的 ListTools 与 CallTool 请求， // 通过 IPC_DIR 写入请求文件并由后台机器人组件处理结果。 }, "bot-control": { "command": "bun", "args": ["run", "super_turtle/claude-telegram-bot/bot_control_mcp/server.ts"], "env": { "SUPERTURTLE_IPC_DIR": "/tmp" } // 说明：bot-control 服务器提供 bot 控制相关的工具查询与执行能力， // 通过 IPC 完成请求-结果的异步交互。 } } }

• 基本使用方法

  • 将 MCP 服务器配置注入客户端环境，确保 command 与 args 指向正确的服务器入口脚本。
  • 启动 MCP 服务器，客户端即可通过 MCP 请求与这些服务器交互，获取相应的工具列表、执行结果和通知。
  • 注意：MCP 服务器通过 STDIO 的 JSON-RPC 传输，日志输出应避免污染 stdout，以确保传输的稳定性。

• 运行与调试提示

  • 运行时如遇到权限、路径或 IPC 目录相关问题，请检查 SUPERTURTLE_IPC_DIR、PATH、以及 Bun 环境配置。
  • 对于开发调试，可参考仓库中的 mcp-config.ts 与示例配置文件进行对齐。

• 关注点

  • MCP 服务器需实现对 MCP 请求的处理、输出正确的 JSON-RPC 响应，以及必要的通知机制。
  • 当前实现通过标准 JSON-RPC/STDIO 传输，并使用文件系统 IPC 进行请求结果对接，具备 MCP 的核心特征。