agent-tool

한국어

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

なぜ？

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

• タブインデントの破壊：LLMはスペースを出力しますが、プロジェクトはタブを使用しています。組み込みのEditツールはスペースをそのまま書き込むため、インデントスタイルが壊れます。

• エンコーディングの破損：EUC-KR、Shift-JIS、GB18030ファイルを編集すると、黙ってUTF-8に変換され、レガシープロジェクトが壊れます。

• ツールが多すぎる：エージェントにRedis CLI、MySQLクライアント、SSHクライアントなどを探してインストール・設定させるのは面倒でエラーが発生しやすいです。agent-toolは54のツールを1つのバイナリにバンドルし、コンパクトなプロファイルを通じてオンデマンドで公開します。

• リバースエンジニアリング非対応：組み込みツールはバイナリの逆アセンブル、PE/ELFヘッダーの検査、関数境界の特定、クロスリファレンスの検索ができません。agent-toolには静的バイナリ解析（逆アセンブル、xref、関数検出）、DAPデバッガー、CheatEngineスタイルのメモリツールが含まれており、エージェントに完全なリバースエンジニアリング機能を提供します。

• ネットワーク検閲：一部の国では、政府レベルのWebフィルタリングにより、素のcurl/wgetリクエストが機能しません。agent-toolはデフォルトでECH（Encrypted Client Hello）とDoH（DNS over HTTPS）を使用して、これらの制限を回避します。

agent-toolは、プロジェクトの規約を維持しながらモデルコンテキストを制限内に保つ、エージェント指向のツールでこれらの問題を解決します。

Related MCP server: DevToolkit MCP Server

対応エージェント

Claude Code、Codex CLI、Cursor、Windsurf、Cline、Gemini CLI、およびMCP互換の任意のエージェント。

デフォルトでLLM効率的

デフォルトのcoreプロファイルは、全54個ではなく11個のスキーマ（toolboxを含む）のみを公開します。プロトコルレベルの測定では、シリアライズされたツールリストが約84KB（full）から18KBに削減されました。toolbox(operation="describe", tool="ssh", compact=true, tool_operation="execute")を使用して1つのオペレーションのフィールドと必須リストのみを読み込み、その後toolbox(operation="call", tool="ssh", arguments={...})を通じて呼び出します。ゲートウェイは動的なツールリストの更新に依存しないため、Codexなどの固定バインディングのクライアントでも動作します。describeはツール/バージョンに紐づくschema_handleを返します。後続のdescribeでそれを送信すると、スキーマがまだ最新である場合、短い変更なしの確認応答が返ります。--profile coding|remote|analysis|fullで起動することもできます。

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

機能

主な改善点

スマートなインデント

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

• .editorconfig から indent_style と indent_size を読み取ります

• コンテンツベースの検出（最初の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 はデフォルトで1ページあたり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. お使いのOS用のバイナリを Releases からダウンロードします

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 を選択:

配置場所:

プロジェクトごと — プロジェクトの CLAUDE.md に追加:

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

グローバル（全プロジェクト）— ~/.claude/CLAUDE.md に追加:

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

ハードな強制 — ~/.claude/settings.json で権限レベルで組み込みファイルツールを拒否:

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

これにより、Claude Codeの組み込みファイルツールが使用できなくなり、エージェントは agent-tool を使用せざるを得なくなります。プロンプトの指示に頼らずに厳格な強制を行いたい場合に推奨されます。

1. ~/.codex/config.toml に追加（トップレベル、[mcp_servers.*] 内ではない）:

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

2. ~/.codex/model_instructions.md を作成:

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

3. Codex を再起動します。

プロジェクトごと — 代わりにプロジェクトの AGENTS.md に追加します。

プロジェクトの .cursorrules、.windsurfrules、または AGENTS.md に追加:

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 によって自動承認されないよう意図的に設計されています。セーフモードのユーザーは、各 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 coding

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

プロファイルは加算的なプリセットです: 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 を尊重するクライアントのために引き続き利用可能です。固定バインディングのクライアントは常にゲートウェイを使用し続けることができます。

環境変数

CLIフラグを繰り返さないように、AGENT_TOOL_FALLBACK_ENCODING および/または AGENT_TOOL_PROFILE を設定します:

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

最初の呼び出しは、両方のツールで30分間再利用可能な不透明な connection_id を返します。trusted:true は表示のみに影響します: 許可されたプライベートアドレスの警告は、呼び出しごとではなく、プールされた接続ごとに1回表示されます。SSRFブロッキングとクラウドメタデータ保護は変更されません。SSHは quiet、echo_command、result_only もサポートしています。最後のものは、stdout、stderr、exit_code を中心としたコンパクトなJSONを返します。SFTPは quiet、result_only、upload_many（最大100ファイル）をサポートしています。

ランタイム設定

エージェントは再起動せずに 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 .

トラブルシューティング

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

韓国語、日本語、その他の非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接続のたびに、ユーザーとAIエージェントの両方にセキュリティ警告が表示され、取得したWebコンテンツからのプロンプトインジェクション攻撃の検出に役立ちます。

• 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

• 配布: シングルバイナリ（クロスコンパイル）

ライセンス

MIT