MCP Http Proxy

🚀 MCP代理使用文檔

該MCP代理腳本為用戶提供了一個統一的接口，用於與MCP（礦工控制協議）進行交互。它藉助HTTP提供多個端點，支持通過GET和POST請求發送命令，並能即時接收響應，極大地簡化了與MCP服務的交互流程。

✨ 主要特性

1. 啟動子進程：代理啟動後會自動開啟一個子進程運行MCP服務。
2. 多端點支持：提供了多個HTTP端點來處理不同的請求類型。
3. 參數驗證：對所有用戶輸入進行嚴格的安全檢查，防止潛在的攻擊。
4. 錯誤處理：遇到問題時能優雅地處理並返回友好的錯誤信息。

📦 安裝指南

啟動代理

# 在終端中運行代理腳本
node mcp-proxy.js

💻 使用示例

發送命令

方式一：使用POST /rpc/raw/command（適合程序matic調用）

將完整的JSON - RPC請求放在請求體中發送。

示例 curl 請求 (Linux/macOS):

curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  http://localhost:3005/rpc/raw/command

示例 curl 請求 (Windows 命令提示符):

curl -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}" http://localhost:3005/rpc/raw/command

PowerShell 示例：

$rpcBody = @{
    jsonrpc = "2.0"
    method = "tools/call"
    id = 2
    params = @{
        name = "your_tool_name"
        arguments = @{
            param1 = "value1"
            count = 10
        }
    }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri http://localhost:3005/rpc/raw/command -Method Post -ContentType 'application/json' -Body $rpcBody

方式二：使用GET /tool/:toolName（適合簡單的GET請求）

通過URL的查詢參數傳遞參數。

示例 curl 請求：

# 假設有一個名為'worker_get'的工具，接受'name'參數
curl "http://localhost:3005/tool/worker_get?name=my-worker"

即時事件推送

SSE流

通過GET /sse端點可以建立Server - Sent Events流，即時接收服務器推送的消息。

示例 curl 請求：

curl http://localhost:3005/sse

調試界面

訪問http://localhost:3005/debug可以看到更全面的調試信息，包括：

• 當前活動的SSE連接數量
• 最近的代理日誌
• 請求歷史記錄
• 原始消息交換記錄

🔧 技術細節

錯誤處理

代理在遇到錯誤時會盡量優雅地處理並提供友好的反饋：

1. HTTP錯誤：返回標準的HTTP狀態碼（例如404表示未知工具或端點，400表示無效參數）。
2. 參數驗證：/tool/:toolName端點會對查詢參數進行嚴格的模式匹配檢查，任何格式錯誤都會被攔截並返回詳細的錯誤信息。
3. MCP錯誤：如果底層MCP進程返回錯誤（例如工具執行失敗），代理會捕獲這些錯誤信息並通過HTTP響應返回給客戶端，並在SSE流中推送事件通知。

停止代理

要停止代理，可以按下Ctrl + C或發送SIGINT信號。代理會在退出前執行以下清理操作：

1. 終止子進程：調用MCPWorker.mcpProcess.kill()結束正在運行的MCP服務。
2. 關閉連接：斷開所有活動的SSE客戶端連接，確保資源被正確釋放。

附加功能

MCP管理端點（可選）

如果啟用了mcp - manager.js，代理還會提供一些額外的管理端點：

• /mcp/install：安裝新的MCP實例
• /mcp/start：啟動指定的MCP服務
• /mcp/stop：停止運行中的MCP服務
• /mcp/list：列出所有可用的MCP實例

這些功能允許用戶動態地管理多個MCP服務，提高了系統的靈活性和可擴展性。

📚 詳細文檔

安全注意事項

1. 輸入驗證：代理對所有用戶輸入都進行了嚴格的驗證，防止注入攻擊。
2. 訪問控制：默認情況下，所有端點都是公開的。建議在生產環境中配置基本認證或使用更高級的身份驗證機制來保護敏感功能。
3. 日誌記錄：建議啟用詳細的日誌記錄功能，以便於審計和故障排除。

日誌和監控

代理提供了內置的日誌系統，支持記錄所有的請求、響應以及內部狀態變化。通過分析日誌，可以有效監控系統的運行狀況，及時發現潛在問題。

總結

該MCP代理提供了一個強大而靈活的接口，簡化了與MCP服務的交互。無論是簡單的命令執行還是複雜的任務調度，代理都能很好地滿足需求。通過合理配置和使用其提供的各種功能，用戶可以高效地管理和控制自己的礦工資源。