Vietnamese Water Utility API

🚀 MCP API 服務

MCP API 服務是一箇中間服務器，運行於 Model Context Protocol (MCP) 通訊協議，用於連接 clfude AI 與各個內部系統 API，能有效處理指令並反饋結果，極大提升系統交互效率。

🚀 快速開始

MCP API 服務作為中間服務器，運行於 Model Context Protocol (MCP) 通訊協議，主要負責連接 clfude AI 與各個內部系統 API。其工作流程如下：

1. 接收命令：用戶要求執行任務時，clfude 會發送指令。
2. 處理轉換：MCP 將 clfude 的請求轉換為內部系統 API 可接受的格式。
3. 調用 API：執行通往各個內部系統 API 的調用。
4. 回傳結果：將結果格式化後發送給 clfude，供最終用戶查看。

✨ 主要特性

現有功能模塊

• check_connection - 檢查到 API 服務器的連線狀態
• search_employee - 根據姓名或編號搜索員工
• register_breakfast - 登記員工報名參加早餐活動
• manage_conference_rooms - 管理會議室預約

📚 詳細文檔

系統架構

總觀

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 顯示結果供用戶查看。

新增劇本指南

增加新端點

要新增一個新的 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 文件。