Party Time MCP Server

Party Time MCP 服务

一个简单的 MCP 服务，在被询问当前时间时会回复“It's Party Time”。

概述

这是一个简单的 MCP 服务实现，会直接从标准输入读取数据并写入标准输出。它注册了一个名为 get-time 的工具，每次调用该工具时都会回复“It's Party Time”。

该服务直接实现 MCP 协议，处理 JSON-RPC 消息并做出相应响应。

macOS 安装说明

1. 构建可执行文件

首先，构建可执行文件：

mix deps.get
mix escript.build

这会在项目目录中创建一个名为 party_time_mcp 的可执行文件。

确保它具有执行权限：

chmod +x ./party_time_mcp

2. 配置 Claude Desktop

1. 打开 Claude Desktop 配置文件：

open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. 将以下内容添加到配置中（如果文件尚不存在，请创建该文件并写入以下内容）：

{
  "mcpServers": {
    "partytime": {
      "command": "/path/to/your/party_time_mcp",
      "args": []
    }
  }
}

将 /path/to/your/party_time_mcp 替换为可执行文件的实际路径。

3. 保存文件并重启 Claude Desktop

3. 测试服务

1. 打开 Claude Desktop
2. 询问 Claude：“现在几点了？”
3. Claude 应该会检测到你的工具并回复“It's Party Time”

故障排除

• Claude Desktop 找不到工具：确保配置中的路径正确，并且文件具有执行权限
• 权限问题：如果可执行文件没有正确的权限，你可能需要运行 chmod +x ./party_time_mcp
• 配置文件问题：确保 JSON 有效且格式正确
• 重启 Claude Desktop：更改配置后，请确保已重启 Claude Desktop
• JSON 解析错误：如果你看到“Unexpected end of JSON input”或“Unexpected non-whitespace character after JSON”等错误：
  • 这很可能是因为服务在输出 JSON 响应的同时，还向标准输出写入了额外文本
  • 确保使用最新版本的服务，该版本已修复此问题，会将日志发送到标准错误，而不是标准输出
  • 现在，服务会确保仅向标准输出发送格式规范、干净的 JSON
  • 如果仍然看到这些错误，请查看 Claude Desktop 日志以了解详情
• Mix.env() 错误：如果你看到类似 function Mix.env/0 is undefined 的错误，说明可执行文件构建不正确。Mix 模块在 escript 运行时不可用。请使用已修复此问题的最新代码重新构建可执行文件。

调试

如果遇到 JSON 错误，可以手动运行服务以查看其输出：

./party_time_mcp

然后在另一个终端中，可以向其发送测试 JSON-RPC 消息：

echo '{"jsonrpc":"2.0","id":"test-1","method":"tools/list"}' | ./party_time_mcp

你也可以测试其他消息类型：

# Initialize request
echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"0.1.0"}}}' | ./party_time_mcp

# Notifications/initialized message
echo '{"jsonrpc":"2.0","method":"notifications/initialized"}' | ./party_time_mcp

# Tools/call request
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get-time","arguments":{}}}' | ./party_time_mcp

服务架构

Party Time MCP 服务旨在符合 Machine Conversation Protocol（MCP）。它处理以下消息类型：

• initialize：返回服务能力、服务信息和协议版本。处理完成后还会发送 server/initialized 通知。
• notifications/initialized：处理客户端初始化通知（无需响应）。
• tools/list：返回可用工具列表。
• tools/call：执行指定工具并返回结果。

该服务还针对无效请求和未知方法提供了完善的错误处理。

MCP 协议合规性

该服务按照 Model Context Protocol 规范实现了 MCP 协议。所有消息均遵循 JSON-RPC 2.0 格式，并实现了所需的消息类型：

1. 初始化：服务通过 initialize 消息返回其功能，并发送 server/initialized 通知。
2. 工具发现：服务通过 tools/list 返回可用工具列表。
3. 工具执行：服务处理针对 get-time 工具的 tools/call 请求。
4. 错误处理：对于无效请求、未知方法和其他错误情况，服务会返回相应的错误响应。

测试

该服务包含全面的测试，以确保其正常运行：

1. 服务测试：测试服务处理各种 JSON-RPC 消息的能力，包括：

   • initialize 消息处理和响应验证
   • notifications/initialized 消息处理
   • tools/list 请求处理
   • 针对“get-time”工具执行 tools/call 请求

2. Hermes 客户端测试：测试服务与 Hermes 客户端的兼容性，包括：

   • 处理 initialize 请求和 server/initialized 通知
   • 处理 notifications/initialized 消息
   • 正确响应 tools/list 请求
   • 正确执行 tools/call 请求

3. JSON 格式测试：确保所有 JSON 响应均按照 JSON-RPC 2.0 规范正确格式化。

运行测试：

mix test

重新构建（如有需要）

如果需要进行更改并重新构建：

mix deps.get
mix escript.build

最近修复

通知处理

服务已更新，可正确处理来自 Claude Desktop 的 notifications/initialized 消息。客户端会发送此消息，以确认已收到 server/initialized 通知。

所做更改：

• 添加了对 notifications/initialized 消息的支持
• 服务现在可以正确处理此通知而不会产生错误

JSON 解析错误

服务已更新，以修复 Claude Desktop 中的 JSON 解析错误。问题在于服务将日志消息与 JSON 响应一起输出到 stdout，导致 Claude Desktop 中的 JSON 解析器无法正确解析。

所做更改：

• 禁用了所有日志记录，避免干扰 JSON 输出
• 现在仅向 stdout 发送干净的 JSON 响应
• 移除了重复的启动消息
• 在每个 JSON 响应后添加了换行符，以便更好地解析

Mix.env() 错误修复

服务已更新，以修复作为 escript 运行时出现的 Mix.env() 错误。问题在于 Mix 模块在 escript 运行时不可用。

所做更改：

• 将运行时的 Mix.env() 调用替换为编译时模块属性
• 服务现在可以正确判断自身是否处于测试模式，而无需在运行时依赖 Mix

故障排除

如果 Party Time MCP 服务出现问题，以下是一些常见问题及解决方案：

Mix.env() 错误

如果看到类似 UndefinedFunctionError: function Mix.env/0 is undefined 的错误，说明可执行文件构建不正确。Mix 模块在 escript 运行时不可用。请使用最新代码重新构建可执行文件：

mix escript.build

权限问题

如果运行可执行文件时出现权限被拒绝错误，请将其设为可执行文件：

chmod +x ./party_time_mcp

配置文件问题

如果服务无法找到或读取配置文件，请检查文件是否存在且权限是否正确。

JSON 错误

如果出现 JSON 解析错误，请确保传递给服务的输入是有效的 JSON-RPC 2.0 格式。服务要求消息采用以下格式：

{
  "jsonrpc": "2.0",
  "id": "some-id",
  "method": "method-name",
  "params": {}
}

对于通知（无需响应的消息），应省略 id 字段：

{
  "jsonrpc": "2.0",
  "method": "notification-name"
}