Ahma MCP

🚀 Ahma MCP

1つのJSONファイルでコマンドラインツールからエージェントを作成し、真のマルチスレッドツール使用エージェント型AIワークフローで作業をより迅速に完了させます。

ahma_mcp は、コマンドラインツールをAIが利用できるように迅速に適応させます。AIは、バックグラウンドプロセスが開始されたことをすぐに確認し、計画や分析を続行でき、各操作が完了すると自動的にツールの結果を受け取ります。複数の同時ツール呼び出しは並列に実行されます。個々のツールやサブコマンドは、必要に応じて synchronous: true とタグ付けすることで、従来のブロッキングMCPツール呼び出しになります。一般的に、AIは非同期ツールの完了を await する必要はありませんが、必要な場合はできます。

Ahma（フィンランド語でヤマアラシを意味する）は、粘り強く敏捷なツールで、一般的な同期ツールよりも短時間で複雑なタスクを迅速に処理し、ワークフローを高速化します。

🚀 クイックスタート

VS CodeのMCPサポートを使って ahma_mcp を試す最速の方法は次の通りです。

# 1) リポジトリをクローンし、リリースバイナリをビルドする
git clone https://github.com/paulirotta/ahma_mcp.git
cd ahma_mcp
cargo build --release

# 2) `tools/`, `.vscode/`, `.gihub/chatmodes/` をVS Codeプロジェクトにコピーし、パス、ツール、ツール使用のAIガイダンスを好みに合わせて編集する

次に、内容をVS CodeのMCP構成ファイルにコピーし（OSごとの場所は以下を参照）、VS Codeを再起動すると準備完了です。

✨ 主な機能

基本的な機能

Ahma MCPは、ツールの使用を高速化し、以下の機能を提供します。

• 汎用CLI適応性：MTDF JSON構成を介して、あらゆるコマンドラインツールと動作します。
• 非同期優先アーキテクチャ：操作はデフォルトで非同期に実行され、結果が自動的にAIにプッシュされるため、AIのブロッキング時間が減少し、並行ワークフローが可能になります。
• マルチツールサポート：単一のサーバーが複数のCLIツールを同時に処理し、ツールごとに1つのMTDF JSONファイルが必要です。
• テスト駆動開発：cargo nextest を使用した包括的なテストカバレッジで、70を超えるテストが信頼性を保証します。
• コードカバレッジ統合：詳細なテストカバレッジ分析とレポートのための組み込み cargo llvm-cov サポート（同期操作）。
• クリーンなツール命名：「デフォルト」サブコマンドパターンにより、冗長な接尾辞のない直感的なツール名が提供されます。
• モジュール型ツールアーキテクチャ：オプションのツールは個別のJSONファイルに分けられ、保守性と組織性が向上します。
• 集中型ガイダンスシステム：tool_guidance.json の再利用可能なガイダンスブロックにより、guidance_key 参照を介してツール間で一貫したAI命令が保証されます。
• MtdfValidator：組み込みのスキーマ検証により、MTDF構成の正確性が保証され、一般的なエラーが防止されます。
• AI最適化ガイダンス：ツールの説明には、生産的な並行作業を促す明示的な提案が含まれています。

高度な機能

操作管理と監視

Ahma MCPは、高度な操作追跡と管理機能を提供します。

• リアルタイム操作監視：status ツールですべての実行中の操作のステータスを追跡します。
• インテリジェントウェイト機能：await ツールを使用して、操作を設定可能なタイムアウト（1 - 1800秒、デフォルト240秒）で監視します。
• 段階的タイムアウト警告：タイムアウト期間の50％、75％、90％で警告を受け取り、長時間実行される操作を追跡します。
• 自動エラー修復：操作がタイムアウトしたときに具体的な提案を取得します。
  • 古いロックファイル（Cargo.lock、package-lock.json、yarn.lock、composer.lockなど）の検出
  • ネットワーク接続チェックとオフラインモードの提案
  • ディスク空間とリソース使用状況の監視推奨事項
  • プロセスの競合検出と解決手順
• 部分結果回復：タイムアウトが発生した場合、完了した操作は結果を返し、失敗した操作は詳細なエラーコンテキストを提供します。

円滑な開発ワークフロー

シームレスな開発体験のために強化されています。

• シグナル対応シャットダウン：ファイルの変更や cargo watch の再起動中にSIGTERM/SIGINTシグナルを適切に処理します。
• 操作完了猶予期間：シャットダウン前に進行中の操作が自然に完了するための10秒のウィンドウを提供します。
• 開発に配慮した再起動：開発中のファイル変更は操作を突然終了させず、操作が完了して結果を返すまで待ちます。
• 進捗フィードバック：シャットダウンシーケンス中に操作のステータスを示す視覚的な進捗インジケーター（🔄⏳⚠️）を表示します。

📦 インストール

前提条件

• Rust 1.70以上：rustup.rs からインストールします。
• VS Code：MCPサポート付き（GitHub Copilot拡張機能を推奨）
• Git：リポジトリをクローンするために必要です。

インストール手順

1. リポジトリをクローンしてビルドする：

   git clone https://github.com/paulirotta/ahma_mcp.git
   cd ahma_mcp
   cargo build --release
   

2. インストールを確認する：

   ./target/release/ahma_mcp --help
   

ツール構成

Ahma MCPは、tools/ ディレクトリ内の MTDF（MCP Tool Definition Format）JSONファイルを使用して、CLIツールの統合を定義します。

内部ツール（ahma_mcpで実装されている）：

• await.json - 操作の調整、1つまたは複数のツールが完了するまで一時停止します。
• status.json - 進行中および最近完了した操作の情報を提供します。

コマンドラインツールの外部ツール定義 は .ahma/tools/ に含まれています。必要なものをコピーして編集するか、独自のものを追加します。

Rustエコシステム：

• cargo.json - 再帰的なサブコマンドを持つRustパッケージマネージャー（13個のサブコマンド）
• cargo_audit.json - Cargo.lockのセキュリティ脆弱性を監査する（2個のサブコマンド）
• cargo_bench.json - Rustプロジェクトのベンチマークを実行する（1個のサブコマンド）
• cargo_clippy.json - Rustの拡張リンティングとコード品質チェック（1個のサブコマンド）
• cargo_edit.json - Cargo.tomlファイルを編集するツール（4個のサブコマンド）
• cargo_fmt.json - スタイルガイドラインに従ってRustコードを整形する（1個のサブコマンド）
• cargo_llvm_cov.json - RustプロジェクトのLLVMソースベースのコードカバレッジ（8個のサブコマンド、同期）
• cargo_nextest.json - Rustの次世代テストランナー（1個のサブコマンド）

バージョン管理とCI/CD：

• git.json - Gitバージョン管理システム（10個のサブコマンド）
• gh.json - GitHub CLI、cache delete や run cancel などの入れ子操作をサポート（10個のサブコマンド）

一般的な開発：

• python3.json - Pythonインタープリターとモジュール実行（7個のサブコマンド）
• gradlew.json - Android/JavaプロジェクトのGradleラッパー（47個のサブコマンド）
• shell_async.json - シェルコマンドを非同期に実行する（1個のサブコマンド）
• long_running_async.json - 非同期動作をテストするためのスリープユーティリティ（1個のサブコマンド）

ファイル操作：

• cat.json - ファイルの内容を表示する（単一コマンド）

各MTDFファイルは、guidance_key フィールドを使用して .ahma/tool_guidance.json のガイダンスブロックを参照でき、ガイダンスの重複を排除し、一貫性を保証します。詳細なスキーマ情報と検証については、 を参照してください。

インストールのテスト

すべてが正常に動作することを確認するために、包括的なテストスイートを実行します。

# nextestですべてのテストを実行する（高速なテストランナー）
cargo nextest run

# カバレッジ分析付きでテストを実行する
cargo llvm-cov nextest --html --open

# 代替: 標準のcargo test
cargo test

以下のような出力が表示されるはずです。

✓ Finished running 76 tests across 45 binaries (2.34s)

💻 使用例

基本的な使用法

VS CodeでのMCP統合の基本的な使用法は次の通りです。

Step 1: VS CodeでMCPを有効にする

VS Codeの設定（Ctrl/Cmd+, → 「settings.json」を検索）に以下を追加します。

{
    "chat.mcp.enabled": true
}

Step 2: MCPサーバーを構成する

グローバルMCP構成ファイルを作成または編集します。

場所：

• macOS：~/Library/Application Support/Code/User/mcp.json
• Linux：~/.config/Code/User/mcp.json
• Windows：%APPDATA%\Code\User\mcp.json

{
    "servers": {
        "ahma_mcp": {
            "type": "stdio",
            "cwd": "${workspaceFolder}",
            "command": "target/release/ahma_mcp",
            "args": [
                "--server",
                "--tools-dir",
                "tools"
            ]
        }
    },
    "inputs": []
}

Step 3: VS Codeを再起動する

mcp.json ファイルを保存した後、VS Codeを再起動してMCPサーバーを有効にします。

Step 4: 接続を確認する

1. VS Codeを開き、GitHub Copilotとチャットを開始します。
2. 利用可能なMCPサーバーに「ahma_mcp」が表示されるはずです。
3. AIに ahma_mcp ツールを使用するように依頼します。例：「Use ahma_mcp to show the git status」

利用可能なツール

接続後、約44の動的に生成されたMCPツールにアクセスできます。

Git操作：

• mcp_ahma_mcp_git_status - ワーキングツリーのステータスを確認する
• mcp_ahma_mcp_git_add - 変更をステージングする
• mcp_ahma_mcp_git_commit - コミットを作成する
• mcp_ahma_mcp_git_push - 変更をアップロードする
• mcp_ahma_mcp_git_pull - 変更をダウンロードする
• その他17以上のgitサブコマンド

Cargo操作：

• mcp_ahma_mcp_cargo_build - プロジェクトをビルドする
• mcp_ahma_mcp_cargo_test - テストを実行する
• mcp_ahma_mcp_cargo_run - バイナリを実行する
• mcp_ahma_mcp_cargo_check - ビルドせずにチェックする
• mcp_ahma_mcp_cargo_doc - ドキュメントをビルドする
• mcp_ahma_mcp_cargo_add - 依存関係を追加する
• mcp_ahma_mcp_cargo_remove - 依存関係を削除する
• mcp_ahma_mcp_cargo_update - 依存関係を更新する
• mcp_ahma_mcp_cargo_fetch - 依存関係をフェッチする
• mcp_ahma_mcp_cargo_install - バイナリをインストールする
• mcp_ahma_mcp_cargo_search - クレートを検索する
• mcp_ahma_mcp_cargo_tree - 依存関係ツリーを表示する
• mcp_ahma_mcp_cargo_version - Cargoのバージョンを表示する
• mcp_ahma_mcp_cargo_rustc - カスタムrustcを使用する
• mcp_ahma_mcp_cargo_metadata - パッケージのメタデータを表示する
• mcp_ahma_mcp_cargo_audit_audit - 依存関係の脆弱性を監査する
• mcp_ahma_mcp_cargo_bench_bench - ベンチマークを実行する
• mcp_ahma_mcp_cargo_clippy_clippy - clippyでコードをリントする
• mcp_ahma_mcp_cargo_edit_add - cargo-editで依存関係を追加する
• mcp_ahma_mcp_cargo_edit_remove - cargo-editで依存関係を削除する
• mcp_ahma_mcp_cargo_edit_upgrade - cargo-editで依存関係をアップグレードする
• mcp_ahma_mcp_cargo_edit_bump_version - cargo-editでパッケージのバージョンを上げる
• mcp_ahma_mcp_cargo_fmt_fmt - rustfmtでコードを整形する
• mcp_ahma_mcp_cargo_nextest_run - nextestでテストを実行する
• mcp_ahma_mcp_cargo_llvm_cov_test - LLVMカバレッジ付きでテストを実行する（同期）
• mcp_ahma_mcp_cargo_llvm_cov_run - LLVMカバレッジ付きでバイナリを実行する（同期）
• mcp_ahma_mcp_cargo_llvm_cov_report - カバレッジレポートを生成する（同期）
• mcp_ahma_mcp_cargo_llvm_cov_show_env - カバレッジ環境を表示する（同期）
• mcp_ahma_mcp_cargo_llvm_cov_clean - カバレッジデータをクリーンアップする（同期）
• mcp_ahma_mcp_cargo_llvm_cov_nextest - LLVMカバレッジ付きでnextestを実行する（同期）
• インストールされている場合のオプション：clippy, nextest, fmt, audit, upgrade, bump_version, bench

ファイル操作（コアセット）：

• mcp_ahma_mcp_cat_run - ファイルの内容を表示する
• mcp_ahma_mcp_grep_run - テキストパターンを検索する
• mcp_ahma_mcp_sed_run - テキストストリームを編集する
• mcp_ahma_mcp_echo_run - テキストを出力する

必要に応じて追加できるオプション：リストツール（ls.json）を再導入することができます。テストではこの存在を前提としなくなりました。

操作管理：

• mcp_ahma_mcp_status - すべての操作のステータス（アクティブ、完了、失敗）を確認する
• mcp_ahma_mcp_wait - 操作が完了するまで待機する（設定可能なタイムアウト：1 - 1800秒、デフォルト240秒）

高度な使用法

カスタムツール構成の作成

独自のCLIツールを追加したい場合は、tools/ ディレクトリにMTDF（MCP Tool Definition Format）JSONファイルを作成します。

クイックスタートテンプレート

{
    "name": "your_tool",
    "description": "Brief description of the tool",
    "command": "your_command",
    "enabled": true,
    "subcommand": [
        {
            "name": "subcommand_name",
            "guidance_key": "sync_behavior",
            "synchronous": true,
            "description": "What this subcommand does",
            "options": [
                {
                    "name": "option_name",
                    "type": "string",
                    "description": "Option description"
                }
            ]
        }
    ]
}

ガイダンスシステム

集中型ガイダンスシステムを使用して、一貫したAI命令を維持します。

• ガイダンスブロックを参照する：長時間実行される操作には "guidance_key": "async_behavior" を使用します。
• ガイダンスブロックを参照する：高速な操作には "guidance_key": "sync_behavior" を使用します。
• ガイダンスブロックを参照する：await/statusツールには "guidance_key": "coordination_tool" を使用します。
• カスタムガイダンス：tool_guidance.json で再利用可能なブロックを定義します。

ドキュメントと例

• 完全なMTDF仕様：
• 実際の例： の実際のツール構成を参照してください（例：cargo.json, python3.json, gh.json）
• スキーマ検証：組み込みのMtdfValidatorは、役立つエラーメッセージと提案を提供します。
• IDEサポート：JSONスキーマにより、開発環境での自動補完が可能になります。

📚 ドキュメント

概要

Ahma MCPは、コマンドラインツールをMCP対応エージェントに変換し、コマンドが実行中でもAIが計画と推論を続けることを可能にします。Model Context Protocol (MCP) を実装し、MCP Tool Definition Format (MTDF) - ゼロコンパイルツール統合を可能にするJSONツール定義を使用します（例については tools/ を参照）。

デフォルトでは、ツール呼び出しは非同期です。操作が完了するとAIにプッシュ/コールバックが送信されるため、AIは結果を待つためにブロックされません。迅速に返すツールは、ツールのJSON構成で "synchronous": true とマークすることができます。

MTDF: MCP Tool Definition Format

MTDFは、ahma_mcpのJSONベースのツール構成形式で、コードの変更なしに動的なツールロードを可能にします。

• 動的ツール登録：tools/ ディレクトリにJSONファイルを作成することで、新しいツールを追加できます。
• ゼロコンパイル統合：CLIツールを追加するためにRustコードを変更する必要はありません。
• 再帰的サブコマンドサポート：入れ子になったサブコマンドを持つ複雑なCLIツールをモデル化できます（例：cargo nextest run, gh cache delete）。
• クリーンなツール命名：「デフォルト」サブコマンドパターンにより、冗長な接尾辞のない直感的なツール名が提供されます（例：cargo_fmt の代わりに cargo_fmt_default）。
• モジュール型アーキテクチャ：オプションのツールは個別のJSONファイルに分けられ、保守性が向上します。
• 集中型ガイダンスシステム：tool_guidance.json を介して再利用可能なAIガイダンスブロックが提供されます。
• スキーマ検証：組み込みのMtdfValidatorにより、構成の正確性が保証されます。
• 同期/非同期制御：サブコマンドごとに細かい実行モード制御が可能です。
• JSONスキーマエクスポート：検証とIDEサポートのために、自動生成されたスキーマが にあります。

例: Claude Sonnet 4 は決して止まらず、ツールの使用と思考を同時に行う

今、MCPサーバーを使用してテストを再度実行しましょう。

Ran cargo_test ahma_mcp (MCP Server)

テストが実行中の間、製品要件文書の更新を続けましょう。

Read product-requirements.md

製品要件にJSONスキーマ要件を追加しましょう。

product-requirements.md+21-6

今、テスト結果を確認しましょう。

Ran status ahma_mcp (MCP Server)

問題がわかりました...

例: Gemini 2.5 Pro

adapter_coverage_improvement_test.rs のコンパイルエラーを修正しました。今、テストを再実行して、さらなる問題を確認します。

Ran cargo_nextest ahma_mcp (MCP Server)

adapter_coverage_improvement_test.rs のコンパイル問題を解決し、テストスイートを再開しました。今、結果を待ちます。

Ran await ahma_mcp (MCP Server)

adapter_coverage_improvement_test.rs の修正が成功しました。

例: ツールのファイルアクセスは制限されている "format": "path" とマークされたJSONツールフィールドの文字列は、プロジェクトディレクトリとそのサブディレクトリに制限されます。これにより、セキュリティと偶発的な影響範囲が削減されます。

Error: MPC -32602: Path validation failed for parameter 'output-dir'. The path '/users/someone' is outside the allowed workspace.

互換性

テストされたツール呼び出しAIは動作しますが、Grok Code Fast 1 はMCPツール呼び出しよりもターミナルを好みます。

STDIO MCPサポート付きのIDEは動作するはずですが、ほとんどのテストはVS Codeで行われています。

HTTPベースのMCPクライアントはまだサポートされていません。

問題報告とプルリクエストを歓迎します。

🔧 技術詳細

パフォーマンス：事前ウォームアップされたシェルプール

Ahma MCPは、事前ウォームアップされたシェルプールを使用して、コマンドの起動遅延を最小限に抑えます。詳細については shell_pool.rs を参照してください。

📄 ライセンス

Apache License 2.0 または MIT License のいずれかのライセンスの下でライセンスされています。