agent-tool

agent-tool

한국어

AI コーディングエージェント向けの MCP（Model Context Protocol）ツールサーバーです。

なぜ必要なのか？

AI コーディングエージェント（Claude Code、Cursor、Codex など）の組み込みツールには、よく知られた制限があります。

• タブによるインデントが崩れます：LLM はスペースを出力しますが、プロジェクトではタブを使っている場合があります。組み込みの編集ツールはスペースをそのまま書き込むため、インデントスタイルが崩れます。
• 文字コードが破損します：EUC-KR、Shift-JIS、GB18030 のファイルを編集すると、気付かないうちに UTF-8 に変換され、レガシープロジェクトに問題が生じます。
• 個別のツールが多すぎます：エージェントに Redis CLI、MySQL クライアント、SSH クライアントなどを探してインストールし、設定させるのは面倒で、エラーも起きやすくなります。agent-tool は 40 個のツールを 1 つのバイナリにまとめ、コンパクトなプロファイルを通じて必要に応じて公開します。
• リバースエンジニアリングに対応していません：組み込みツールでは、バイナリの逆アセンブル、PE/ELF ヘッダーの検査、関数境界の検出、クロスリファレンスの検索ができません。agent-tool には、静的バイナリ解析（逆アセンブル、PDB/DWARF 型情報を使った C への逆コンパイル、xref、関数検出）、DAP デバッガー、CheatEngine 風のメモリツールが含まれており、エージェントに包括的なリバースエンジニアリング機能を提供します。
• ネットワーク検閲：一部の国では、政府レベルのウェブフィルタリングによって、通常の curl／wget リクエストが妨げられます。agent-tool はデフォルトで ECH（Encrypted Client Hello）と DoH（DNS over HTTPS）を使用して、こうした制限を回避します。

agent-tool は、モデルのコンテキストを一定範囲内に保ちながら、プロジェクトの規約を維持するエージェント向けツールによって、これらの問題を解決します。

対応エージェント

Claude Code、Codex CLI、Cursor、Windsurf、Cline、Gemini CLI、および MCP 互換のあらゆるエージェントに対応しています。

デフォルトで LLM に最適化

デフォルトの core プロファイルでは、40 個すべてではなく、toolbox を含む 11 個のスキーマのみが公開されます。プロトコルレベルでの測定では、シリアライズされたツール一覧は約 74 KB（full）から 15 KB に削減されました。定常時のコンテキストを最小限にするには、--profile core-lite から始めてください。5 個のスキーマは約 6.4 KB で、read、write、edit、grep、toolbox のみを公開します。toolbox(operation="describe", tool="ssh", compact=true, tool_operation="execute") を使うと、1 つの操作のフィールドと必須リストのみを読み込んでから、toolbox(operation="call", tool="ssh", arguments={...}) で呼び出せます。このゲートウェイは動的なツール一覧の更新に依存しないため、Codex のような固定バインディングのクライアントでも動作します。describe はツールとバージョンに紐付いた schema_handle を返します。後続の describe でこれを送信すると、スキーマが最新のままであれば、変更がないことを示す短い確認応答が返されます。よく使われるコンパクトな操作には、SSH の実行、MySQL クエリ、ファイルコピー、Windows のスクリーンショット／クリップボード画像、静的解析操作などがあります。--profile core-lite|coding|remote|analysis|full から開始することもできます。

サイズが大きくなる可能性のあるテキスト応答は、デフォルトで 32K 文字、上限は 128K 文字です。切り捨ては常に明示され、ページングに対応したツールは next_offset または next_cursor を返します。ローカルの相対パスは、明示的に指定されたワークスペースを基準に解決され、次に MCP クライアントのルートを基準に解決されます。

機能

主な改善点

スマートインデント

LLM は通常スペースを出力しますが、多くのプロジェクトではタブが使われています。AgentTool は、ファイルの既存のスタイルに合わせてインデントを自動変換します。

• indent_style と indent_size を .editorconfig から読み取ります
• 内容に基づいて検出します（先頭 100 行）
• 既存ファイルを保護します。実際の内容が .editorconfig と矛盾する場合は変換しません

エンコーディングの保持

編集時に UTF-8 を強制せず、元のファイルのエンコーディングを保持します。

• 検出の優先順位：BOM → .editorconfig の charset → BOM なし UTF-16 → 有効な UTF-8 → chardet による自動検出 → フォールバックエンコーディング
• 対応形式：UTF-8、UTF-8 BOM、EUC-KR、Shift-JIS、ISO-8859-1、UTF-16（LE/BE、BOM の有無を問わず）など
• ASCII で誤った警告は発生しません：有効な UTF-8 を直接検証するため、通常の ASCII ファイルで信頼度の低い警告が発生することはありません
• 改行コード：LF、CRLF、CR、および混在するファイルを検出します。edit は、ファイルで CRLF と LF のどちらが使われている場合も、両方が混在している場合も、複数行の old_string に一致します。また、edit／regexreplace で挿入されたテキストは挿入先の領域の改行スタイルに従うため、ファイルの残りの部分はバイト単位で同一のままです

トークンに配慮したディレクトリ一覧

listdir はデフォルトでページあたり 500 件を返し、さらに項目がある場合は next_cursor を返します。 directories_only、files_only、name_pattern（例：A*）、または include で複数の OR パターンを指定して、結果を絞り込めます。 一致するファイル／ディレクトリの件数のみが必要な場合は、counts_only=true を使用してください。

アイドル時のメモリ解放

ツール呼び出しが 30 分間ない場合、サーバーはヒープを OS に返します。stdio MCP サーバーでは、放棄されたクライアントと、単に静かなクライアントを見分けられません。起動元のプロセスは生きていて、処理を終えた後もパイプを開いたままにしている可能性があり、その場合 EOF は届きません。その推測に基づいて終了すると、単に一時停止していただけのセッションを壊してしまいます。メモリを解放することで、この取引の安全な部分を実現します。かつて 50MB のファイルを読み込んだインスタンスも、マシンの稼働中ずっと 200MB を保持するのではなく、約 20MB のベースラインに戻ります。開いているシェルや SSH のセッションは維持され、クライアントから見える動作に変化はありません。

クイックスタート

1. Releases から OS 用のバイナリをダウンロードします
2. agent-tool install を実行します（特定のエージェントを指定する場合は agent-tool install claude）
3. IDE／エージェントを再起動します
4. 完了です。コンパクトなコアツールがすぐに使えるようになります。toolbox を使うと、その他すべてのツールについて説明を確認し、必要に応じて呼び出せます

または、AI エージェントに実行を依頼してください。

「https://github.com/knewstimek/agent-tool/releases/latest から agent-tool をダウンロードして、agent-tool install を実行してください」

対応可能な AI コーディングエージェント（Claude Code、Codex など）なら、ダウンロードからインストール、再起動までの一連の作業を自動で実行できます。

推奨：エージェントに agent-tool を優先するよう指示する

インストール後、エージェントは agent-tool を利用できるようになりますが、組み込みツール（Read、Edit など）を引き続きデフォルトで使う場合があります。エンコーディングに対応し、インデントを適切に扱う agent-tool のツールをエージェントが優先するように、以下の指示のいずれかを追加してください。

コードナビゲーションのヒント：大規模なプロジェクトでは、AST ベースのコードナビゲーションを有効にするため、これを CLAUDE.md / AGENTS.md に追加してください。

At the start of a session, run codegraph(op="index", path="<project_root>") to build a code index.
For several repositories sharing one graph, use codegraph(op="index", path="<db_root>", roots=["<source_root_1>", "<source_root_2>"]). Source-root provenance prevents unrelated projects with the same symbol names from contaminating candidates while explicit/transitive includes can still cross roots.
Then use codegraph for structural queries (find, callers, callees, methods, inherits) instead of grep.

Strict または Soft を選択してください。

追加場所：

ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.

ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.

{
  "permissions": {
    "deny": ["Read", "Edit", "MultiEdit", "Write", "Glob", "Grep"]
  }
}

model_instructions_file = "~/.codex/model_instructions.md"

ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.

ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.

インストール

自動インストール（推奨）

# Register with all detected agents (full auto-approve — all tools)
agent-tool install

# Safe mode — only auto-approve local file tools (no SSH, HTTP, DB, shell)
agent-tool install --safe-approve

# No auto-approve — manual approval required for every tool call
agent-tool install --no-auto-approve

# Register with a specific agent
agent-tool install claude
agent-tool install claude --safe-approve

# Uninstall (removes agent-tool entry only, preserves other settings)
agent-tool uninstall          # from all agents
agent-tool uninstall claude   # from specific agent

インストール時の権限レベル：

承認レベルはスキーマプロファイルとは独立しています。インストール時に名前空間全体を承認しても、サーバーはトークン効率の高い core プロファイルで起動できます。 toolbox は、operation=call ゲートウェイからネットワーク、シェル、データベース、プロセス制御の各ツールを呼び出せるため、--safe-approve では意図的に自動承認されません。Safe モードを使用する場合は、toolbox の承認内容を毎回確認し、AgentTool 名前空間全体を信頼する意図がない限り、恒久的な許可ルールを付与しないでください。

手動セットアップ

Claude Code / Cursor / Cline（settings.json または mcp.json）：

{
  "mcpServers": {
    "agent-tool": {
      "command": "/path/to/agent-tool"
    }
  }
}

Codex CLI（~/.codex/config.toml）：

[mcp_servers.agent-tool]
command = "/path/to/agent-tool"

オプション

# Select the initial schema profile (default: core)
agent-tool --profile core-lite

# Set fallback encoding for projects with non-UTF-8 files
agent-tool --fallback-encoding EUC-KR

プロファイルはプリセットです。core-lite（read/write/edit/grep/toolbox）、core（11個のスキーマ）、coding（core に幅広いファイル／ビルド／シェルツールを追加）、remote、analysis、full があります。実行時は、クライアントに依存しない toolbox ゲートウェイを優先してください。operation=describe は1つのツールのスキーマを返し（compact=true と tool_operation を指定すると、対象を1つの操作に絞れます）、operation=call は安定した toolbox バインディングを通じてツールを呼び出します。返された schema_handle を再送すると、変更されていないスキーマが再び返されるのを避けられます。コマンドの診断情報がコンパクト化された場合、operation=output を使うと、報告された ID に対応するサイズ制限付きの生出力を30分間取得できます。ページングが必要な場合は next_offset が示されます。enable、disable、profile は tools/list_changed に対応するクライアントで引き続き使用できます。固定バインディングのクライアントでは、常にゲートウェイを使用できます。

環境変数

AGENT_TOOL_FALLBACK_ENCODING および／または AGENT_TOOL_PROFILE を設定すると、CLI フラグを繰り返し指定せずに済みます。

# Windows (no admin required)
setx AGENT_TOOL_FALLBACK_ENCODING EUC-KR
setx AGENT_TOOL_PROFILE coding

# Linux / macOS (add to ~/.bashrc or ~/.zshrc)
export AGENT_TOOL_FALLBACK_ENCODING=EUC-KR
export AGENT_TOOL_PROFILE=coding

優先順位：CLI フラグ ＞ 環境変数 ＞ デフォルト（UTF-8）。

ローカル SSH／SFTP 接続プロファイル

SSH と SFTP では、connection_profile またはセッションローカルの connection_id を使用できるため、ホスト、ユーザー、キー、ジャンプホストの各フィールドを繰り返し指定する必要はありません。プロファイルは OS のユーザー設定ディレクトリにある agent-tool/connections.json から読み込まれます。AGENT_TOOL_CONNECTION_PROFILE_FILE で場所を変更できます。このファイルをワークスペース内に置く場合は、ローカルに保管し、明示的に無視対象にしてください。

{
  "connections": {
    "dev": {
      "host": "192.0.2.10",
      "user": "builder",
      "key_file": "/local/path/to/id_ed25519",
      "host_key_check": "strict",
      "trusted": true
    }
  }
}

最初の呼び出しでは、不透明な connection_id が返されます。この ID は両方のツールで30分間再利用できます。ローカルプロファイルの trusted はデフォルトで true です。プールされた接続ごとに一度だけではなく、呼び出しのたびにプライベートアドレスの警告を表示するには、trusted:false に設定してください。これは表示にのみ影響し、SSRF ブロックとクラウドメタデータ保護に変更はありません。SSH は quiet、echo_command、result_only もサポートしています。最後の項目を指定すると、stdout、stderr、exit_code を中心としたコンパクトな JSON が返されます。SFTP は quiet、result_only、upload_many（最大100ファイル）をサポートしています。

Windows PowerShell では、command の代わりに powershell_script にスクリプトテキストを渡してください。SSH は、一意の UTF-8 一時 .ps1 ファイルを短い PowerShell コマンドの標準入力経由でアップロードし、短い PowerShell ランチャーでその内容を実行して、成功時も失敗時も削除します。-EncodedCommand（または -enc、-ec、-e）を使う単独の powershell[.exe]／pwsh[.exe] コマンドは、UTF-16 コード単位で8,000文字を超える場合に自動的にステージングされます。安全なプロファイル、対話型、アパートメント、実行ポリシーの各オプションは保持されます。サポートされていないオプションやシェルのサフィックスを使用する場合は、powershell_script に明示的に入力する必要があります。スクリプトの上限は4 MiBです。レガシーな Windows SSH サーバーを含め、SFTP は必要ありません。

{"operation":"execute","connection_profile":"dev","powershell_script":"Write-Output 'hello'","result_only":true}

準備とフォアグラウンド実行では、同じ timeout_sec を使用します。バックグラウンドスクリプトも同じアップロードおよびクリーンアップの手順を使用し、その後、ステータス確認、末尾の取得、キャンセルに使う job_id を公開します。リモートランチャーは finally でのクリーンアップを試みます。完了が確認された場合は、SSH による時間制限付きのクリーンアップも実行されます。キャンセルや接続の切断だけではリモートでの終了が確認できないため、ツールは削除をリモートランチャーに任せ、完了またはクリーンアップを確認できなかった場合は cleanup_warning を報告します。この警告は、スクリプトの終了コードや取得された出力とは別のものです。

ローカル SSH 秘密鍵の変換

ssh_key は、内容をネットワーク経由で送信したり、鍵の情報を応答に含めたりせずに、秘密鍵ファイルを変換します。入力形式は PPK、PEM、PKCS#8、OpenSSH として自動判別されます。出力形式は ppk、pem、pkcs8、openssh のいずれかです。

{
  "operation": "convert",
  "input_path": "server.pem",
  "output_path": "server.ppk",
  "output_format": "ppk",
  "input_passphrase": "",
  "output_passphrase": "",
  "overwrite": false
}

PPK の出力ではバージョン3を使用します。パスフレーズで保護された PPK 出力では Argon2id、AES-256-CBC、HMAC-SHA-256 を使用します。保護された OpenSSH 出力では、OpenSSH の最新の暗号化形式を使用します。従来形式の PEM および PKCS#8 出力は、意図的に暗号化されません。出力の暗号化が必要な場合は、openssh または ppk を使用してください。新しいファイルのモードは0600です。overwrite=true を指定しない限り、既存のファイルは置き換えられません。

ランタイム設定

エージェントは再起動せずに set_config で設定を変更できます。

ビルド

go build -trimpath -ldflags="-s -w" -o agent-tool .

クロスコンパイル：

GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o agent-tool .
GOOS=darwin GOARCH=arm64 go build -trimpath -ldflags="-s -w" -o agent-tool .
GOOS=windows GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o agent-tool.exe .

リリース

保護された GitHub ワークフローでは、テストを実行し、宣言されたすべてのアセットをビルドして、MCPB とチェックサムを作成し、アップロードされたバイト列を検証します。クリーンでプッシュ済みの master ブランチから、ビルドのみのドライランを実行します。

.\scripts\release.ps1

ドライランが成功したら、main.go で宣言されたバージョンを公開します。

.\scripts\release.ps1 -Publish

このワークフローには、docs/releases/vVERSION.md に追跡対象のリリースノートが必要です。公開すると、注釈付きタグと GitHub Release が作成され、その後 server.json がリリース済み MCPB のハッシュで更新されます。RepoPlane がこのリポジトリをワークスペースとして使用する場合、同じドライラン、公開、ステータス確認の操作を、リポジトリ内の catalog/ マニフェストから実行できます。

トラブルシューティング

文字化け（エンコーディングの問題）

韓国語、日本語、その他の非 ASCII テキストが文字化けして表示される場合：

オプション 1：.editorconfig に charset を追加します。

[*]
charset = euc-kr

オプション 2：環境変数を設定します（永続的）。

setx AGENT_TOOL_FALLBACK_ENCODING EUC-KR   # Windows
export AGENT_TOOL_FALLBACK_ENCODING=EUC-KR  # Linux

オプション 3：CLI フラグを使用します（セッションごと）。

agent-tool --fallback-encoding EUC-KR

エージェント向けの組み込みヘルプ

agent-tool には、エージェントが使用方法の案内を受けるために呼び出せる agent_tool_help ツールが含まれています。エージェントがエンコーディングの警告や文字化けに遭遇した場合、次のように呼び出せます。

{ "tool": "agent_tool_help", "arguments": { "topic": "encoding" } }

利用可能なトピック：overview、encoding、indentation、tools、troubleshooting

セキュリティ

agent-tool は、SSH、MySQL、Redis、ファイル操作、HTTP リクエストなど、強力なシステムアクセス機能を提供します。 AI コーディングエージェントと併用する場合は、プロンプトインジェクションのリスクに注意してください。

• SSRF 保護：クラウドメタデータの IP アドレス（169.254.x.x、fe80::/10）は、設定にかかわらず常にブロックされます。プライベート IP アドレスへのアクセスは、set_config を使用してプロトコルごとに設定できます（allow_http_private、allow_mysql_private、allow_redis_private、allow_ssh_private）
• DLP（データ漏えい防止）：すべての送信 HTTP リクエスト本文を、機密データのパターン（PEM 秘密鍵、AWS アクセスキー、GitHub/GitLab トークン、Slack トークン、.env ファイルのダンプ）についてスキャンし、送信前にブロックします
• プロンプトインジェクションの警告：許可されたプライベート IP アドレスへの接続時には簡潔な警告が表示されます。信頼済みのローカル SSH/SFTP プロファイルでは、プールされた接続ごとに一度だけ表示されます
• Zip Slip 保護：../ によるパストラバーサルを含むアーカイブエントリはブロックされます（zip と tar の両方）
• Zip Bomb 保護：単一ファイルの上限は 1GB、展開サイズの合計上限は 5GB です
• シンボリックリンク：デフォルトではスキップされます。set_config allow_symlinks=true で有効にできます（tar のみ。zip のシンボリックリンクは常にスキップされます）。有効にした場合でも、出力ディレクトリの外を参照するシンボリックリンクはブロックされます
• ファイルサイズの上限：設定可能な最大ファイルサイズ（デフォルトは 100MB）により、大きなファイルによる OOM を防ぎます。set_config max_file_size_mb=N で変更できます
• エンコーディングの安全性：メモリ効率を高めるため、chardet はファイル全体ではなく 64KB のサンプルを使用します

セキュリティを最大限に高めるには、AI エージェントのツール呼び出しを承認前に確認してください。特に、SSH コマンド、外部 URL への HTTP リクエスト、データベースクエリに注意してください。

技術スタック

• 言語：Go
• MCP SDK：github.com/modelcontextprotocol/go-sdk
• エンコーディング：saintfish/chardet + golang.org/x/text
• 配布：単一バイナリ（クロスコンパイル）
• 逆コンパイラー：Gosleigh（Ghidra の x86/x64 言語仕様を内蔵）
• PDB：gopdb（PDB 7.0 リーダーおよび MSVC デマングラー）

ライセンス

MIT

逆コンパイラー（Gosleigh）と、内蔵されている Ghidra の言語仕様は、Apache License 2.0 の下でライセンスされています。Gosleigh は、米国国家安全保障局が開発した Ghidra 逆コンパイラーの再実装です（https://github.com/NationalSecurityAgency/ghidra）。