Party Time MCP Server

Party Time MCP Server

現在時刻について尋ねられると、「It's Party Time」と応答するシンプルな MCP サーバーです。

概要

標準入力から直接読み取り、標準出力に書き込むシンプルな 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 のようなエラーが表示される場合、実行ファイルのビルド方法が正しくありません。escript では実行時に Mix モジュールを使用できません。この問題を修正した最新のコードで実行ファイルを再ビルドしてください。

デバッグ

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 出力に干渉しないよう、すべてのログ出力を無効化
• クリーンな JSON レスポンスのみを stdout に送信するよう変更
• 重複していた起動メッセージを削除
• 解析しやすくするため、各 JSON レスポンスの後に改行を追加

Mix.env() エラーの修正

escript として実行したときに発生する Mix.env() エラーを修正するため、サーバーを更新しました。原因は、escript の実行時には Mix モジュールが利用できないことでした。

変更内容：

• 実行時の Mix.env() 呼び出しをコンパイル時のモジュール属性に置き換え
• サーバーが実行時に Mix に依存せず、テストモードで実行されているかどうかを正しく判定するようになりました

トラブルシューティング

Party Time MCP サーバーで問題が発生した場合は、よくある問題と解決策を以下で確認してください。

Mix.env() エラー

UndefinedFunctionError: function Mix.env/0 is undefined のようなエラーが表示される場合、実行ファイルが正しくビルドされていません。escript の実行時には Mix モジュールを利用できません。最新のコードで実行ファイルを再ビルドしてください。

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"
}