Vietnamese Water Utility API

🚀 MCP API サービス

MCP APIサービスは、Model Context Protocol (MCP) 通信プロトコルで動作する中間サーバーで、clfude AIと各種内部システムAPIの接続を支援します。このシステムは、以下の機能を実行します。

🚀 クイックスタート

MCP APIサービスを使用することで、clfude AIと内部システムAPIを効果的に接続できます。以下に、基本的な使用手順を説明します。

✨ 主な機能

• 命令の受信：ユーザーがタスクを実行する要求を行うと、clfudeから命令を受け取ります。
• 命令の処理と変換：MCPはclfudeの要求を内部システムAPIが受け入れ可能な形式に変換します。
• APIの呼び出し：各内部システムAPIへの呼び出しを実行します。
• 結果の返送：結果をフォーマットしてclfudeに送信し、最終ユーザーに表示します。

📚 ドキュメント

🔍 システムアーキテクチャ

概要

MCP APIサービスは、Model Context Protocol (MCP) 通信プロトコルで動作する中間サーバーで、clfude AIと各種内部システムAPIの接続を支援します。このシステムは、以下の機能を実行します。

1. clfudeの命令を受信する：ユーザーがタスクを実行する要求を行うと、clfudeから命令を受け取ります。
2. 命令を処理して変換する：MCPはclfudeの要求を内部システムAPIが受け入れ可能な形式に変換します。
3. APIを呼び出す：各内部システムAPIへの呼び出しを実行します。
4. 結果を返送する：結果をフォーマットしてclfudeに送信し、最終ユーザーに表示します。

動作メカニズム

MCPサーバーは、standard input/output (stdio) を介して通信します。

• Standard Input (stdin)：clfudeからの要求を受け取ります（例：社員検索命令）。
• Standard Output (stdout)：結果をclfudeに送信します（例：検索された社員情報）。
• Standard Error (stderr)：エラーメッセージを記録します（例：API接続時のエラー）。

要求処理の流れは以下の通りです。

1. clfudeがstdinを介してJSON形式の要求を送信します。
2. MCPサーバーが要求を処理し、適切なAPIを呼び出します。
3. MCPサーバーが結果をclfudeに送信します（stdoutを介して）。
4. clfudeが結果を表示し、ユーザーに提供します。

🌟 機能（スクリプト）

現行の機能モジュールは以下の通りです。

• check_connection - APIサーバーへの接続状態を確認します。
• search_employee - 名前または番号で社員を検索します。
• register_breakfast - 社員の朝食イベントへの参加登録を行います。
• manage_conference_rooms - 会議室の予約を管理します。

🆕 新しいスクリプトの追加ガイド

新しいエンドポイントの追加

新しいAPIエンドポイントを追加するには、以下の手順を実行します。

1. config.tsファイルを編集する：

   // existingEndpoints配列に新しい.endpointファイルを追加します。
   {
     name: "new_endpoint_name",
     path: "/new_endpoint_path",
     method: "POST",  // GET、POSTなどが可能です。
     description: "新しいエンドポイントの説明"
   }
   

2. 新しいハンドラーファイルを作成する：
   • /src/new_endpoint_handler.ts ファイルを作成します。
   • NewEndpointHandler クラスを実装し、基底ハンドラークラスを継承します。

スクリプトの追加手順

1. コマンドラインで以下のコマンドを実行します。

   npm run add-scenario -- --name new_scenario_name --description "新しいシナリオの説明"
   

2. 指示に従って必要な情報を入力し、新しいスクリプトの設定を完了します。

💡 ベストプラクティス

1. 一貫性

   • 既存の命名規則とコード構造に従います。
   • 確立されたコードテンプレートを使用します。

2. エラー処理

   • すべてのAPI呼び出しでtry/catch文を使用します。
   • 完全なエラー情報を記録します。
   • 明確なエラーメッセージを返します。

3. ログ記録

   • 操作開始前にDEBUGレベルのログを記録します。
   • 操作成功後にINFORMATIONレベルのログを記録します。
   • ログにすべての関連パラメータとコンテキスト情報を含めます。

4. データ検証

   • 必須パラメータの存在を確認します。
   • 入力パラメータのデータ型と形式を検証します。

これらのベストプラクティスの実装方法の詳細については、docs/add-new-scenario.md ファイルを参照してください。