Jarvis MCP

🚀 JARVIS MCP 項目文檔

JARVIS MCP 是一個基於 MCP Go 框架 實現的系統，採用 Model - Code - Proxy（模型 - 代碼 - 代理）模式。它能在本地系統上運行，提供執行命令、文件操作等實用功能。

🚀 快速開始

JARVIS MCP 可通過源碼或二進制文件進行安裝，安裝完成後即可快速體驗其功能。

示例用法

# 執行系統命令：顯示幫助信息
curl -X POST http://localhost:8090/api/v1/tool/execute_command --data '{"command":"help","arg":"/"}'

# 讀取文件內容
curl -X POST http://localhost:8090/api/v1/tool/read_file --data '{"file":"/path/to/file.txt"}'

# 寫入新文件
curl -X POST http://localhost:8090/api/v1/tool/write_file --data '{"file":"newfile.txt","content":"Hello, World!"}'

✨ 主要特性

• 功能豐富：支持執行系統命令、文件讀寫等操作。
• 模塊化設計：通過模塊劃分，將系統命令執行和文件操作分離，便於維護和擴展。
• 安全可靠：具備完善的安全機制，如權限控制、輸入驗證、日誌記錄等。
• 易於擴展：可方便地添加新工具，並通過配置文件或環境變量管理運行時參數。

📦 安裝指南

從源碼安裝

1. 克隆倉庫：

   git clone https://github.com/yourusername/jarvis-mcp.git
   cd jarvis-mcp
   

2. 構建項目：

   go mod tidy
   ./build.sh
   

3. 運行程序：

   ./out/jarvis-mcp --port=8090
   

二進制文件安裝

從 發佈頁面 下載對應平臺的二進制文件，然後解壓並運行。

💻 使用示例

基礎用法

# 執行系統命令
curl -X POST http://localhost:8090/api/v1/tool/execute_command \
     --data '{"command":"ls", "arg":"-a"}'

# 讀取文件內容
curl -X POST http://localhost:8090/api/v1/tool/read_file \
     --data '{"file":"./test.txt"}'

📚 詳細文檔

工具說明

執行命令工具

package shell

import (
    "context"
    "errors"

    "github.com/mark3labs/mcp-go/mcp"
    "github.com/mark3labs/mcp-go/server"
)

func GetExecuteCommandTool() (tool mcp.Tool, handler server.ToolHandlerFunc) {
    return mcp.NewTool("execute_command",
        mcp.WithDescription("Execute system commands in a controlled manner"),
        mcp.WithString("command",
            mcp.Required(),
            mcp.Description("The command to execute")),
        mcp.WithString("arg",
            mcp.Optional(),
            mcp.Description("Optional argument for the command")),
    ), ExecuteCommandHandler
}

func ExecuteCommandHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    cmd := request.Params.Arguments["command"].(string)
    arg, ok := request.Params.Arguments["arg"].(string)
    if !ok {
        arg = ""
    }

    output, err := execute.Command(cmd, arg)
    if err != nil {
        return nil, errors.New("failed to execute command")
    }

    return mcp.NewToolResultText(output), nil
}

文件操作工具

package files

import (
    "context"
    "errors"

    "github.com/mark3labs/mcp-go/mcp"
    "github.com/mark3labs/mcp-go/server"
)

func GetReadFileTool() (tool mcp.Tool, handler server.ToolHandlerFunc) {
    return mcp.NewTool("read_file",
        mcp.WithDescription("Read content from a file"),
        mcp.WithString("file",
            mcp.Required(),
            mcp.Description("The path to the file")),
    ), ReadFileHandler
}

func ReadFileHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    filePath := request.Params.Arguments["file"].(string)
    content, err := readFile(filePath)
    if err != nil {
        return nil, errors.New("failed to read file")
    }

    return mcp.NewToolResultText(content), nil
}

項目架構

模塊劃分

• shell：處理系統命令的執行。
• files：負責文件操作，如讀取、寫入等。

核心組件

• 工具註冊：所有工具通過 mcp 框架進行註冊和管理。
• 上下文處理：使用 Go 的 context 來傳遞請求相關信息。

安全注意事項

⚠️ 重要提示

為確保系統安全穩定運行，請嚴格遵循以下安全注意事項：

1. 權限控制：
   • 僅允許經過身份驗證的用戶執行敏感命令或文件操作。
   • 設置適當的文件訪問權限，避免未經授權的讀寫操作。
2. 輸入驗證：
   • 對用戶提供的命令和文件路徑進行嚴格的輸入驗證，防止注入攻擊。
   • 確保所有外部輸入都經過消毒處理。
3. 日誌記錄：
   • 記錄所有執行的操作日誌，包括命令內容和文件操作的詳細信息。
   • 配置日誌級別和輸出格式，便於後續審計和問題排查。
4. 異常處理：
   • 對所有可能失敗的操作進行錯誤捕捉，並提供有意義的錯誤信息。
   • 實現回滾機制，防止部分操作成功而其他操作失敗導致的數據不一致。
5. 資源清理：
   • 及時釋放不再使用的系統資源，如文件句柄和網絡連接。
   • 定期清理臨時生成的文件，避免磁盤空間耗盡。

擴展與集成

添加新工具

要添加新的工具（例如 create_directory），可以按照以下步驟進行：

1. 創建新的 Go 文件（如 directory.go）並定義工具接口。
2. 在 main 函數中註冊該工具：

   tool, handler := GetCreateDirectoryTool()
   server.AddTool(tool, handler)
   

配置管理

通過配置文件或環境變量來管理運行時參數，例如設置默認的文件存儲路徑或命令超時時間。

錯誤處理與調試

常見錯誤場景

1. 權限不足：

   {
       "error": "permission denied"
   }
   

2. 文件不存在：

   {
       "error": "file not found"
   }
   

3. 命令語法錯誤：

   {
       "error": "invalid command syntax"
   }
   

調試步驟

💡 使用建議

當遇到問題時，可按以下步驟進行調試：

1. 檢查日誌輸出，獲取詳細錯誤信息。
2. 確保服務有足夠的權限執行相關操作。
3. 驗證輸入參數是否符合預期格式。

最佳實踐

• 最小權限原則：限制每個工具的功能範圍，僅授予必要的權限。
• 日誌審計：定期審查操作日誌，識別異常行為和潛在的安全漏洞。
• 性能優化：監控服務的運行狀態，優化關鍵路徑以提升響應速度。

項目維護

1. 版本控制：
   • 使用 Git 進行代碼管理，定期提交變更記錄。
   • 遵循語義化版本控制策略，確保兼容性和可追溯性。
2. 依賴管理：
   • 定期更新 Go 依賴庫，保持項目的安全性與穩定性。
   • 監控依賴項的變更，評估其對項目的影響。
3. 測試覆蓋：
   • 編寫單元測試和集成測試用例，確保各功能模塊正常工作。
   • 使用自動化測試工具，加速開發流程並提高代碼質量。

附錄

環境變量配置

# 設置服務運行的端口
export PORT=8090

# 配置日誌輸出目錄
export LOG_PATH=./logs

日誌格式示例

{
    "timestamp": "2024-03-15T12:34:56Z",
    "level": "INFO",
    "message": "Command 'ls -a' executed successfully"
}

通過遵循上述結構和最佳實踐，您可以有效地構建一個安全、可靠且易於維護的命令行工具和服務框架。