Jarvis MCP

🚀 JARVIS MCP プロジェクトドキュメント

JARVIS MCP は MCP Go フレームワーク をベースにしたシステムで、Model-Code-Proxy（モデル-コード-プロキシ）モードを採用しています。このシステムは、コマンドの実行やファイル操作などの機能を提供し、ローカルシステム上で動作します。

🚀 クイックスタート

インストールとビルド

ソースコードからのインストール

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":"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!"}'

✨ 主な機能

コマンド実行ツール

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)
   

設定管理

設定ファイルまたは環境変数を使用して、ランタイムパラメータを管理します。例えば、デフォルトのファイル保存パスやコマンドのタイムアウト時間を設定できます。

📁 プロジェクト構造

javis-mcp/
├── api/                  # インターフェース定義とルート処理
│   └── routes.go         # 各ツールのインターフェースエンドポイントを定義
├── build.sh              # ビルドスクリプト
├── cmd/                  # 実行可能ファイルのエントリポイント
│   └── main.go           # プロジェクトのメイン関数、サービスの初期化と起動を担当
├── files/                # ファイル操作モジュール
│   ├── file.go           # ファイルの読み書きロジック
│   └── directory.go      # ディレクトリの作成と削除機能
├── shell/                # システムコマンド実行モジュール
│   └── command.go        # コマンド実行ロジック
└── go.mod                # 依存関係管理ファイル

💻 使用例

システムコマンドの実行

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

🐞 エラー処理とデバッグ

一般的なエラーシナリオ

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

上記の構造とベストプラクティスに従うことで、安全で信頼性が高く、保守しやすいコマンドラインツールとサービスフレームワークを効果的に構築できます。