agent-tool

한국어

MCP (Model Context Protocol) Tool-Server für KI-Codierungsagenten.

Warum?

Integrierte Tools in KI-Codierungsagenten (Claude Code, Cursor, Codex usw.) haben bekannte Einschränkungen:

• Tab-Einrückung bricht: LLMs geben Leerzeichen aus, aber Ihr Projekt verwendet Tabs. Das integrierte Edit-Tool schreibt Leerzeichen unverändert und beschädigt so Ihren Einrückungsstil.

• Kodierungsbeschädigung: Das Bearbeiten von EUC-KR-, Shift-JIS- oder GB18030-Dateien konvertiert diese stillschweigend in UTF-8 und bricht damit Legacy-Projekte.

• Zu viele separate Tools: Den Agenten dazu zu bringen, Redis CLI, MySQL-Client, SSH-Client usw. zu finden, zu installieren und zu konfigurieren, ist mühsam und fehleranfällig. agent-tool bündelt 54 Tools in einer einzigen Binärdatei und stellt sie bei Bedarf über kompakte Profile bereit.

• Keine Reverse-Engineering-Unterstützung: Integrierte Tools können keine Binärdateien disassemblieren, PE/ELF-Header untersuchen, Funktionsgrenzen finden oder Querverweise durchsuchen. agent-tool enthält statische Binäranalyse (Disassemblierung, Xref, Funktionserkennung), einen DAP-Debugger und CheatEngine-artige Speichertools – das gibt Ihrem Agenten vollständige Reverse-Engineering-Fähigkeiten.

• Netzzensur: In einigen Ländern unterbricht staatliche Webfilterung einfache curl/wget-Anfragen. agent-tool verwendet standardmäßig ECH (Encrypted Client Hello) und DoH (DNS over HTTPS), um diese Einschränkungen zu umgehen.

agent-tool löst diese Probleme mit agentenorientierten Tools, die Projektkonventionen bewahren und gleichzeitig den Modellkontext begrenzt halten.

Related MCP server: DevToolkit MCP Server

Unterstützte Agenten

Claude Code, Codex CLI, Cursor, Windsurf, Cline, Gemini CLI und jeder MCP-kompatible Agent.

Standardmäßig LLM-effizient

Das Standardprofil core stellt nur 11 Schemas (einschließlich toolbox) bereit, statt aller 54. In einer Messung auf Protokollebene reduzierte dies die serialisierte Tool-Liste von etwa 84 KB (full) auf 18 KB. Verwenden Sie toolbox(operation="describe", tool="ssh", compact=true, tool_operation="execute"), um nur die Felder und die Pflichtliste einer einzigen Operation zu laden, und rufen Sie sie dann über toolbox(operation="call", tool="ssh", arguments={...}) auf. Das Gateway hängt nicht von einer dynamischen Aktualisierung der Tool-Liste ab und funktioniert daher mit Clients mit fester Bindung wie Codex. Describe gibt einen tool-/versionsgebundenen schema_handle zurück; wenn Sie ihn bei einem späteren Describe senden, erhalten Sie eine kurze unveränderte Bestätigung, solange das Schema noch aktuell ist. Sie können auch mit --profile coding|remote|analysis|full starten.

Potentiell große Textantworten sind standardmäßig auf 32K Zeichen begrenzt, mit einer harten Obergrenze von 128K. Kürzungen sind immer sichtbar, und paginierbare Tools geben next_offset oder next_cursor zurück. Lokale relative Pfade werden zuerst gegen einen expliziten Workspace aufgelöst, dann gegen die MCP-Client-Root.

Funktionen

Wichtigste Verbesserungen

Intelligente Einrückung

LLMs geben typischerweise Leerzeichen aus, aber viele Projekte verwenden Tabs. AgentTool konvertiert die Einrückung automatisch, sodass sie zum vorhandenen Stil der Datei passt.

• Liest .editorconfig für indent_style und indent_size

• Fällt auf inhaltsbasierte Erkennung zurück (erste 100 Zeilen)

• Schützt Altdateien: Konvertiert nicht, wenn der tatsächliche Inhalt .editorconfig widerspricht

Erhaltung der Kodierung

Bearbeitungen erhalten die ursprüngliche Dateikodierung, anstatt UTF-8 zu erzwingen.

• Erkennungspriorität: BOM → .editorconfig-Zeichensatz → UTF-16 ohne BOM → gültiges UTF-8 → chardet-Autoerkennung → Fallback-Kodierung

• Unterstützt: UTF-8, UTF-8-BOM, EUC-KR, Shift-JIS, ISO-8859-1, UTF-16 (LE/BE, mit oder ohne BOM) und mehr

• Keine falschen Warnungen bei ASCII: Gültiges UTF-8 wird direkt verifiziert, sodass reine ASCII-Dateien niemals eine Warnung mit geringer Konfidenz auslösen

• Zeilenenden: Erkennt LF, CRLF, CR und gemischte Dateien. edit gleicht einen mehrzeiligen old_string ab, unabhängig davon, ob die Datei CRLF oder LF verwendet, einschließlich Dateien, die beide mischen, und von edit/regexreplace eingefügter Text folgt dem Zeilenumbruchstil der Region, in der er landet, sodass der Rest der Datei byte-identisch bleibt

Token-sichere Verzeichnisauflistungen

listdir verwendet standardmäßig 500 Einträge pro Seite und gibt next_cursor zurück, wenn weitere Einträge verfügbar sind. Eingrenzen der Ergebnisse mit directories_only, files_only, name_pattern (zum Beispiel A*) oder mehreren ODER-Mustern in include. Verwenden Sie counts_only=true, wenn nur übereinstimmende Datei-/Verzeichnisanzahlen benötigt werden.

Speicherfreigabe im Leerlauf

Nach 30 Minuten ohne Tool-Aufruf gibt der Server seinen Heap an das Betriebssystem zurück. Ein stdio-MCP-Server kann einen verlassenen Client nicht von einem ruhigen unterscheiden – der Prozess, der ihn gestartet hat, kann noch am Leben sein, mit ihm fertig sein und die Pipe weiterhin offen halten, sodass nie ein EOF eintrifft – und ein Beenden aufgrund dieser Vermutung würde eine Sitzung unterbrechen, die nur pausiert hat. Die Speicherfreigabe ist die sichere Hälfte dieses Kompromisses: Eine Instanz, die einmal eine 50-MB-Datei gelesen hat, kehrt zu ihrer ~20-MB-Basislinie zurück, anstatt 200 MB für die restliche Betriebszeit der Maschine zu halten. Offene Shell- und SSH-Sitzungen überleben, und nichts, was der Client beobachten kann, ändert sich.

Schnellstart

1. Laden Sie die Binärdatei für Ihr Betriebssystem von Releases herunter

2. Führen Sie agent-tool install aus (oder agent-tool install claude für einen bestimmten Agenten)

3. Starten Sie Ihre IDE / Ihren Agenten neu

4. Fertig – die kompakten Kern-Tools sind sofort verfügbar; toolbox beschreibt und ruft jedes andere Tool bei Bedarf auf

Oder bitten Sie einfach Ihren KI-Agenten, es für Sie zu erledigen:

„Laden Sie agent-tool von https://github.com/knewstimek/agent-tool/releases/latest herunter und führen Sie agent-tool install aus"

Jeder leistungsfähige KI-Codierungsagent (Claude Code, Codex usw.) kann den vollständigen Download-→-Installations-→-Neustart-Ablauf automatisch bewältigen.

Empfohlen: Sagen Sie Ihrem Agenten, dass er agent-tool bevorzugen soll

Nach der Installation haben Agenten Zugriff auf agent-tool, verwenden aber möglicherweise weiterhin standardmäßig integrierte Tools (Read, Edit usw.). Um sicherzustellen, dass Agenten die kodierungsbewussten, einrückungsintelligenten Tools von agent-tool bevorzugen, fügen Sie eine der folgenden Anweisungen hinzu.

Tipp zur Codenavigation: Fügen Sie für große Projekte Folgendes zu Ihrer CLAUDE.md / AGENTS.md hinzu, um AST-basierte Codenavigation zu aktivieren:

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.

Wählen Sie Strict oder Soft:

Wo Sie es platzieren:

Pro Projekt — fügen Sie Folgendes zur CLAUDE.md Ihres Projekts hinzu:

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

Global (alle Projekte) — fügen Sie Folgendes zu ~/.claude/CLAUDE.md hinzu:

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

Harte Durchsetzung — verweigern Sie integrierte Datei-Tools auf Berechtigungsebene über ~/.claude/settings.json:

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

Dadurch werden die integrierten Datei-Tools von Claude Code nicht verfügbar, sodass der Agent gezwungen ist, agent-tool zu verwenden. Empfohlen, wenn Sie eine strikte Durchsetzung ohne Verlass auf Eingabeaufforderungsanweisungen wünschen.

1. Fügen Sie zu ~/.codex/config.toml hinzu (auf oberster Ebene, nicht innerhalb von [mcp_servers.*]):

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

2. Erstellen Sie ~/.codex/model_instructions.md:

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

3. Starten Sie Codex neu.

Pro Projekt — fügen Sie stattdessen zur AGENTS.md Ihres Projekts hinzu.

Fügen Sie zu .cursorrules, .windsurfrules oder AGENTS.md Ihres Projekts hinzu:

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

Installation

Automatische Installation (empfohlen)

# 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

Berechtigungsstufen für die Installation:

Die Genehmigungsstufe ist unabhängig vom Schema-Profil: Die Installation kann den vollständigen Namespace genehmigen, während der Server weiterhin mit dem token-effizienten core-Profil startet. toolbox wird absichtlich nicht durch --safe-approve automatisch genehmigt, da sein operation=call-Gateway Netzwerk-, Shell-, Datenbank- und Prozesssteuerungs-Tools aufrufen kann. Benutzer im Sicherheitsmodus sollten jede toolbox-Genehmigung überprüfen und vermeiden, ihr eine dauerhafte Erlaubnisregel zu erteilen, es sei denn, sie beabsichtigen, dem vollständigen AgentTool-Namespace zu vertrauen.

Manuelle Einrichtung

Claude Code / Cursor / Cline (settings.json oder mcp.json):

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

Codex CLI (~/.codex/config.toml):

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

Optionen

# 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

Profile sind additive Voreinstellungen: core (11 Schemas), coding (core plus breitere Datei-/Build-/Shell-Tools), remote, analysis und full. Zur Laufzeit bevorzugen Sie das clientunabhängige toolbox-Gateway: operation=describe gibt das Schema eines Tools zurück (compact=true plus tool_operation begrenzt es auf eine Operation), und operation=call ruft es über die stabile toolbox-Bindung auf. Senden Sie einen zurückgegebenen schema_handle erneut, um zu vermeiden, ein unverändertes Schema erneut zu erhalten. Wenn Befehlsdiagnosen komprimiert werden, ruft operation=output die begrenzte Rohausgabe anhand ihrer gemeldeten ID 30 Minuten lang ab und meldet next_offset, wenn Paginierung erforderlich ist. enable, disable und profile bleiben für Clients verfügbar, die tools/list_changed unterstützen; Clients mit festen Bindungen können das Gateway weiterhin verwenden.

Umgebungsvariable

Setzen Sie AGENT_TOOL_FALLBACK_ENCODING und/oder AGENT_TOOL_PROFILE, um sich wiederholende CLI-Flags zu vermeiden:

# 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

Priorität: CLI-Flag > Umgebungsvariable > Standard (UTF-8).

Lokale SSH/SFTP-Verbindungsprofile

SSH und SFTP akzeptieren entweder connection_profile oder eine sitzungslokale connection_id, sodass Host-, Benutzer-, Schlüssel- und Sprunghost-Felder nicht wiederholt werden müssen. Profile werden aus dem Benutzerkonfigurationsverzeichnis des Betriebssystems unter agent-tool/connections.json gelesen; überschreiben Sie den Speicherort mit AGENT_TOOL_CONNECTION_PROFILE_FILE. Halten Sie diese Datei lokal und ignorieren Sie sie explizit, wenn sie in einem Arbeitsbereich platziert wird.

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

Ein erster Aufruf gibt eine undurchsichtige connection_id zurück, die von beiden Tools 30 Minuten lang wiederverwendbar bleibt. trusted:true betrifft nur die Anzeige: Eine zulässige Warnung für private Adressen wird einmal pro gepoolter Verbindung angezeigt, anstatt bei jedem Aufruf; SSRF-Blockierung und Cloud-Metadatenschutz bleiben unverändert. SSH unterstützt außerdem quiet, echo_command und result_only; letzteres gibt kompaktes JSON zurück, das auf stdout, stderr und exit_code fokussiert ist. SFTP unterstützt quiet, result_only und upload_many (bis zu 100 Dateien).

Laufzeitkonfiguration

Agenten können Einstellungen zur Laufzeit über set_config ändern, ohne neu zu starten:

Build

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

Cross-Kompilierung:

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 .

Fehlerbehebung

Verstümmelter Text (Kodierungsprobleme)

Wenn koreanischer, japanischer oder anderer Nicht-ASCII-Text als Zeichensalat erscheint:

Option 1: Fügen Sie charset zu Ihrer .editorconfig hinzu:

[*]
charset = euc-kr

Option 2: Umgebungsvariable setzen (dauerhaft):

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

Option 3: CLI-Flag (pro Sitzung):

agent-tool --fallback-encoding EUC-KR

Integrierte Hilfe für Agenten

agent-tool enthält ein agent_tool_help-Tool, das Agenten für Nutzungshinweise aufrufen können. Wenn ein Agent auf Kodierungswarnungen oder verstümmelten Text stößt, kann er Folgendes aufrufen:

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

Verfügbare Themen: overview, encoding, indentation, tools, troubleshooting

Sicherheit

agent-tool bietet leistungsstarken Systemzugriff (SSH, MySQL, Redis, Dateioperationen, HTTP-Anfragen). Bei der Verwendung mit KI-Codierungsagenten sollten Sie sich der Risiken von Prompt-Injection bewusst sein:

• SSRF-Schutz: Cloud-Metadaten-IPs (169.254.x.x, fe80::/10) werden unabhängig von den Einstellungen immer blockiert. Der Zugriff auf private IPs ist pro Protokoll über set_config konfigurierbar (allow_http_private, allow_mysql_private, allow_redis_private, allow_ssh_private)

• DLP (Data Loss Prevention / Verhinderung von Datenverlust): Alle ausgehenden HTTP-Anfragekörper werden auf sensible Datenmuster gescannt (PEM-Private-Keys, AWS-Zugriffsschlüssel, GitHub/GitLab-Tokens, Slack-Tokens, .env-Datei-Dumps) und vor der Übertragung blockiert

• Warnungen vor Prompt-Injection: Jede Verbindung zu einer privaten IP zeigt eine Sicherheitswarnung, die sowohl für den Benutzer als auch für den KI-Agenten sichtbar ist, und hilft so, Prompt-Injection-Angriffe über abgerufene Webinhalte zu erkennen

• Zip-Slip-Schutz: Archiveinträge mit ../-Pfad-Traversal werden blockiert (sowohl zip als auch tar)

• Zip-Bomben-Schutz: Einzeldateilimit (1 GB), Gesamtextraktionslimit (5 GB)

• Symlinks: Standardmäßig übersprungen. Aktivierung über set_config allow_symlinks=true (nur tar; zip-Symlinks werden immer übersprungen). Selbst wenn aktiviert, werden Symlinks, die aus dem Ausgabeverzeichnis herausführen, blockiert

• Dateigrößenlimit: Konfigurierbare maximale Dateigröße (Standard 100 MB) verhindert OOM bei großen Dateien. Einstellbar über set_config max_file_size_mb=N

• Kodierungssicherheit: chardet verwendet eine 64-KB-Stichprobe (nicht die gesamte Datei) für Speichereffizienz

Für maximale Sicherheit sollten Sie die Tool-Aufrufe des KI-Agenten vor der Freigabe überprüfen, insbesondere bei SSH-Befehlen, HTTP-Anfragen an externe URLs und Datenbankabfragen.

Technologie-Stack

• Sprache: Go

• MCP SDK: github.com/modelcontextprotocol/go-sdk

• Kodierung: saintfish/chardet + golang.org/x/text

• Verteilung: Einzelne Binärdatei (cross-kompiliert)

Lizenz

MIT