Rocket Countdown MCP Server

Rocket Countdown MCP Server

一个模型上下文协议 (MCP) 服务器，它实现了一个火箭倒计时计时器。它允许用户启动、停止和重置倒计时，并在倒计时到达零时显示“发射！”。 (Simplified version, potentially more natural sounding): 一个模型上下文协议 (MCP) 服务器，用于实现火箭倒计时功能。用户可以启动、停止和重置倒计时，当倒计时归零时，会显示“发射！”。

WesleyMFrederick

开发者工具
访问服务器

README

火箭倒计时 MCP 服务器

一个模型上下文协议 (MCP) 服务器，实现了火箭倒计时计时器。它允许用户启动、停止和重置倒计时，并在倒计时到达零时显示“发射！”。

功能

  • 从 10 到 1 开始倒计时，然后显示“发射！”

工具

该服务器公开了以下工具：

  1. continueCountdown：通过逐步倒数数字来模拟火箭倒计时。
    • 输入：current_number（整数，0-10）。
    • 操作：将 current_number 输出到 stderr（例如，“10...”），等待 1 秒。
    • 输出：返回带有 next_number_to_count（即 current_number - 1）和 is_final 布尔值的 JSON。如果 current_number 为 0，则将“发射！”输出到 stderr 并返回“倒计时完成！”。
    • 用法：客户端 (LLM) 需要重复调用此工具，将从先前调用收到的 next_number_to_count 作为下一次调用的 current_number 传递，从初始值（例如，10）开始，并持续到响应指示完成或 next_number_to_count 小于 0。

工具定义方法

本项目使用 @modelcontextprotocol/sdk 的 server.tool() 辅助方法以及 zod 库来定义 continueCountdown 工具的输入模式（参见 index.ts）。这提供了一种对开发者友好的方式，可以使用 TypeScript 中的类型安全来定义模式。

重要的是要注意，这种特定于 SDK 的方法是一种抽象。在内部，SDK 会将 zod 模式转换为模型上下文协议规范所需的标准 JSON Schema 格式，然后再将工具定义公开给客户端。原始协议定义结构记录在通用 MCP 文档中（参见 llm_docs/1_mcp_overview.md 中的“工具”概念）。

设置

  1. 确保您已安装 Node.js（建议 v16 或更高版本）
  2. 克隆此存储库
  3. 安装依赖项：
npm install
  1. 在开发模式下启动服务器：
npm start

这将直接使用 ts-node 运行 TypeScript 文件，而无需先编译为 JavaScript。

  1. 为了使用 MCP Inspector 进行测试（需要编译）：
npm run inspect

这将把 TypeScript 文件编译成 JavaScript，然后启动 MCP Inspector，提供一个 Web 界面来与您的 MCP 服务器交互。

故障排除

MCP Inspector 错误

使用 MCP Inspector 时，您可能会遇到以下常见错误：

  1. JSON 解析错误：MCP 协议需要干净的通信通道，stdout 上只有 JSON 消息。如果您看到类似 SyntaxError: Unterminated fractional number in JSON 或 Unexpected token 'B', "BLAST OFF!" is not valid JSON 的错误，那是因为控制台输出干扰了 MCP 消息。

    • 解决方案：此服务器对所有面向用户的输出使用 console.error() 而不是 console.log()，这会将消息定向到 stderr 而不是 stdout，从而使 stdout 对于 MCP 通信保持清洁。这是使用 stdio 传输的 MCP 服务器的关键设计选择。

    • 工作原理：倒计时数字（10、9、8 等）和“发射！”消息被发送到 stderr，而 JSON 格式的 MCP 协议消息被发送到 stdout。这种分离可以防止协议流的损坏。

    • 技术细节：倒计时间隔和服务器启动中的所有 console.log() 语句都已替换为 console.error() 调用，并且添加了未捕获的异常处理程序，以防止任何意外输出到 stdout。

  2. 端口已被占用：运行 MCP Inspector 时，您可能会看到有关端口已被占用的错误：

    Error: listen EADDRINUSE: address already in use :::5173
Error: listen EADDRINUSE: address already in use :::3000
    • 解决方案：查找并终止使用这些端口的进程：
    lsof -i :5173  # 查找使用端口 5173 的进程
lsof -i :3000  # 查找使用端口 3000 的进程
kill -9 PID    # 使用其 PID 杀死该进程

  3. 工具未列出 / "Preprocessing input: undefined" 错误：如果 MCP 服务器连接但未列出其工具（例如，缺少 continueCountdown），并且您在服务器的 MCP 面板状态中看到类似 Debug: Preprocessing input: undefined, type: undefined 的调试消息，则可能是由于模式预处理引起的。

    • 原因：在工具的输入模式定义 (server.tool(...)) 中使用 z.preprocess 有时会导致预处理函数在服务器的启动/注册阶段执行，在任何客户端实际调用该工具之前。在这种情况下，输入值为 undefined，从而导致调试消息并可能干扰工具注册过程。
    • 解决方案：从模式定义中删除 z.preprocess 包装器。将输入转换（例如，Number(val)）和验证逻辑移动到主工具处理函数 (async (args, _extra) => { ... }) 中。这确保了逻辑仅在实际使用数据调用该工具时运行。

高级测试

有关更高级的调试和测试技术，请参见 llm_docs/debugging_mcp_servers.md 文件，该文件提供了：

  • 测试 MCP 服务器的系统方法
  • 诊断 JSON 解析错误的技术
  • MCP 服务器开发的最佳实践
  • 使用 screen 进行后台测试的方法

项目结构

  • index.ts：TypeScript 源代码
  • package.json：项目配置和依赖项
  • tsconfig.json：TypeScript 配置
  • llm_docs/：有关 MCP 的文档
  • .gitignore：指定 Git 应忽略的有意未跟踪的文件

如何连接

此 MCP 服务器使用 stdio 进行通信，因此它可以连接到任何支持 stdio 传输的 MCP 客户端。

在本地存储库中使用 Claude Desktop

Claude Desktop 完全支持 MCP 并且可以连接到此服务器。要与 Claude Desktop 一起使用：

  1. 如果您尚未下载并安装 Claude Desktop
  2. 打开 Claude Desktop
  3. 转到 Claude > 设置
  4. 单击左侧边栏中的开发者
  5. 单击“编辑配置”
  6. 在文本编辑器中编辑 claude_desktop_config.json
  7. 输入以下详细信息：
{
"mcpServers": {
  "rocket-countdown": {
    "command": "/opt/homebrew/bin/npx",
    "args": [
      "-y",
      "absolute/path/to/working/directory"
    ]
  }
}
}

  • 环境问题：如果在 Claude Desktop 中遇到 MCP 服务器的问题，可能是因为该应用程序正在使用 spawn ${command} ${arguments}，这意味着它直接启动一个新进程，而没有您的 shell 环境（其中包含您的路径、nvm 设置等）的上下文。

  • 解决方案：您可以通过使用绝对路径指向 npx 命令来解决此问题。使用 bash 作为中介：

使用 MCP Inspector

对于测试和开发，您可以使用 MCP Inspector，它提供了一个 Web 界面来测试您的 MCP 服务器。

要将 inspector 与此项目一起使用，您可以简单地运行：

npm run inspect

这是最简单的方法，因为它既处理编译 TypeScript 文件又处理启动 inspector。

或者，您可以手动分两步完成。请注意，清理后默认情况下不存在 index.js，因此您必须先构建它：

# 1. 构建 JavaScript 输出（如果尚未存在）
npm run build

# 2. 使用编译后的文件运行 inspector
npx @modelcontextprotocol/inspector node index.js

这将在本地 Web 服务器上启动 MCP Inspector，通常位于 http://localhost:5173，允许您通过用户友好的界面与您的 MCP 服务器交互。

您可能会在控制台中看到如下错误：

Error from MCP server: SyntaxError: Unexpected token 'S', "Starting R"... is not valid JSON
Error from MCP server: SyntaxError: Unexpected token 'R', "Rocket Cou"... is not valid JSON

发生这些错误是因为服务器输出控制台日志，MCP Inspector 尝试将其解析为 JSON。尽管存在这些错误，但 Inspector 仍应正常工作。初始控制台日志不是 MCP 协议的一部分，因此它们会生成这些解析错误，但是一旦服务器完全初始化，通信应正常进行。

注意： inspector 需要编译后的 JavaScript 文件，不能直接使用 TypeScript 源代码。这是因为 inspector 使用 stdio 传输与您的服务器通信，这需要格式正确的 JSON 消息，而 TypeScript 文件中的标准控制台日志会干扰这些消息。

使用示例

通过 MCP 客户端连接到服务器后：

  1. 调用 continueCountdown 工具以开始倒计时
  2. 服务器将输出倒计时中的每个数字
  3. 当倒计时达到 0 时，它将输出“发射！”

在 Claude Desktop 中使用倒计时

使用上述方法之一在 Claude Desktop 中设置服务器后：

  1. 与 Claude 开始新的聊天。
  2. 告诉 Claude 使用连接的 MCP 服务器开始倒计时。例如：“使用火箭倒计时服务器从 10 开始倒计时。”
  3. Claude 应该识别该请求并使用 current_number: 10 调用 continueCountdown 工具。
  4. 系统将提示您批准该工具的使用。单击“批准”。
  5. 服务器将“10...”输出到其日志（可通过 Claude Desktop 设置 -> 开发者 -> 查看日志查看）并将下一个数字 (9) 返回给 Claude。
  6. 然后，Claude 应该使用 current_number: 9 自动再次调用 continueCountdown。
  7. 继续批准 Claude 提示的每个后续工具调用。
  8. 当倒计时达到 0 时，服务器将“发射！”输出到其日志，Claude 应该报告倒计时已完成。

注意： 此工具需要重复调用和批准。倒计时进度（10...、9... 等）和最终的“发射！”消息出现在服务器的日志中，而不是直接出现在聊天窗口中。聊天将主要显示 Claude 请求批准每个步骤。

许可证

MIT

更新日志

2025-03-29 (v1.0.2)

  • 文档清理：
    • 更新了 llm_docs/0_llm_read_first.md 和 llm_docs/3_debugging_mcp_servers.md 以准确反映当前的单个 continueCountdown 工具。
    • 更正了 LLM 文档中的文件路径和测试命令。
    • 在 llm_docs/0_llm_read_first.md 中添加了显式文档同步指南。
    • 确保 LLM 文档符合 LLM-to-LLM 风格指南。
  • 项目清理：
    • 删除了编译后的 JS 文件（index.js、index.js.map），因为该项目通过 npx / ts-node 运行。
    • 添加了带有标准 Node.js 忽略项的 .gitignore 文件。
    • 更新了 README.md 项目结构和 MCP Inspector 说明。
    • 使用项目执行信息和 .gitignore 详细信息更新了 .clinerules。

2025-03-28 (v1.0.1)

  • 修复了 MCP Inspector 中的 JSON 解析错误：
    • 将所有 console.log() 调用替换为 console.error() 以将输出重定向到 stderr
    • 修改了倒计时计时器输出以使用 stderr 而不是 stdout
    • 确保服务器启动消息不会干扰协议消息
  • 增强了错误处理：
    • 添加了全局未捕获异常处理程序以防止进程终止
    • 实施了适当的错误隔离以避免损坏 stdout JSON 协议
  • 改进了文档：
    • 添加了新的 debugging_mcp_servers.md，其中包含全面的调试指南
    • 扩展了故障排除部分，其中包含详细的错误说明
    • 添加了有关 MCP 通信通道的技术细节
    • 包括了处理端口冲突的说明
  • 测试改进：
    • 验证了修复程序可与 MCP Inspector 一起使用
    • 实施并记录了系统测试方法

2025-03-28 (v1.0.0)

  • 通过删除 dist/ 和 src/ 目录，将基本文件移动到根目录来简化项目结构
  • 删除了编译后的 JavaScript 文件，以实现更简洁的开发工作流程
  • 更新了 MCP 服务器，以便使用 ts-node 直接执行 TypeScript
  • 通过专用 npm 脚本改进了 MCP Inspector 集成
  • 修改了启动日志记录，使其基于环境有条件地进行
  • 更新了 Claude Desktop 配置说明以与 ts-node 一起使用
  • 通过更新 package.json 脚本来简化开发工作流程
  • 添加了 MCP Inspector 错误的详细故障排除部分

推荐服务器

Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
MCP Package Docs Server

MCP Package Docs Server

促进大型语言模型高效访问和获取 Go、Python 和 NPM 包的结构化文档，通过多语言支持和性能优化来增强软件开发。

精选
本地
TypeScript
Claude Code MCP

Claude Code MCP

一个实现了 Claude Code 作为模型上下文协议（Model Context Protocol, MCP）服务器的方案，它可以通过标准化的 MCP 接口来使用 Claude 的软件工程能力（代码生成、编辑、审查和文件操作）。

精选
本地
JavaScript
@kazuph/mcp-taskmanager

@kazuph/mcp-taskmanager

用于任务管理的模型上下文协议服务器。它允许 Claude Desktop（或任何 MCP 客户端）在基于队列的系统中管理和执行任务。

精选
本地
JavaScript
mermaid-mcp-server

mermaid-mcp-server

一个模型上下文协议 (MCP) 服务器，用于将 Mermaid 图表转换为 PNG 图像。

精选
JavaScript
Jira-Context-MCP

Jira-Context-MCP

MCP 服务器向 AI 编码助手（如 Cursor）提供 Jira 工单信息。

精选
TypeScript
Linear MCP Server

Linear MCP Server

一个模型上下文协议（Model Context Protocol）服务器，它与 Linear 的问题跟踪系统集成，允许大型语言模型（LLM）通过自然语言交互来创建、更新、搜索和评论 Linear 问题。

精选
JavaScript
Sequential Thinking MCP Server

Sequential Thinking MCP Server

这个服务器通过将复杂问题分解为顺序步骤来促进结构化的问题解决，支持修订，并通过完整的 MCP 集成来实现多条解决方案路径。

精选
Python
Curri MCP Server

Curri MCP Server

通过管理文本笔记、提供笔记创建工具以及使用结构化提示生成摘要，从而实现与 Curri API 的交互。

官方
本地
JavaScript