agent-tool

agent-tool

한국어

MCP (Model Context Protocol) tool server for AI coding agents.

Why?

Built-in tools in AI coding agents (Claude Code, Cursor, Codex, etc.) have known limitations:

• Tab indentation breaks: LLMs output spaces, but your project uses tabs. The built-in Edit tool writes spaces as-is, corrupting your indentation style.
• Encoding corruption: Editing EUC-KR, Shift-JIS, or GB18030 files silently converts them to UTF-8, breaking legacy projects.
• Too many separate tools: Making the agent find, install, and configure Redis CLI, MySQL client, SSH client, etc. is tedious and error-prone. agent-tool bundles 54 tools into one binary and exposes them on demand through compact profiles.
• No reverse engineering support: Built-in tools can't disassemble binaries, inspect PE/ELF headers, find function boundaries, or search cross-references. agent-tool includes static binary analysis (disassembly, xref, function detection), a DAP debugger, and CheatEngine-style memory tools -- giving your agent full reverse engineering capabilities.
• Network censorship: In some countries, government-level web filtering breaks plain curl/wget requests. agent-tool uses ECH (Encrypted Client Hello) and DoH (DNS over HTTPS) by default to work around these restrictions.

agent-tool solves these with agent-oriented tools that preserve project conventions while keeping model context bounded.

Supported Agents

Claude Code, Codex CLI, Cursor, Windsurf, Cline, Gemini CLI, and any MCP-compatible agent.

LLM-efficient by default

The default core profile exposes only 11 schemas (including toolbox) instead of all 54. In a protocol-level measurement this reduced the serialized tool list from about 84 KB (full) to 18 KB. Use toolbox(operation="describe", tool="ssh", compact=true, tool_operation="execute") to load only one operation's fields and required list, then invoke it through toolbox(operation="call", tool="ssh", arguments={...}). The gateway does not depend on dynamic tool-list refresh, so it works with fixed-binding clients such as Codex. Describe returns a tool/version-bound schema_handle; sending it on a later describe returns a short unchanged acknowledgement when the schema is still current. You can also start with --profile coding|remote|analysis|full.

Potentially large text responses default to 32K characters with a 128K hard ceiling. Truncation is always visible and pageable tools return next_offset or next_cursor. Local relative paths resolve against an explicit workspace, then the MCP client root.

Features

Key Improvements

Smart Indentation

LLMs typically output spaces, but many projects use tabs. AgentTool auto-converts indentation to match the file's existing style.

• Reads .editorconfig for indent_style and indent_size
• Falls back to content-based detection (first 100 lines)
• Protects legacy files: won't convert if actual content contradicts .editorconfig

Encoding Preservation

Edits preserve the original file encoding instead of forcing UTF-8.

• Detection priority: BOM → .editorconfig charset → BOM-less UTF-16 → valid UTF-8 → chardet auto-detection → fallback encoding
• Supported: UTF-8, UTF-8 BOM, EUC-KR, Shift-JIS, ISO-8859-1, UTF-16 (LE/BE, with or without BOM), and more
• No false warnings on ASCII: valid UTF-8 is verified directly, so plain ASCII files never raise a low-confidence warning
• Line endings: Detects LF, CRLF, CR, and mixed files. edit matches a multi-line old_string whether the file uses CRLF or LF, including files that mix both, and text inserted by edit/regexreplace follows the newline style of the region it lands in, so the rest of the file is left byte-identical

Token-safe directory listings

listdir defaults to 500 entries per page and returns next_cursor when more entries are available. Narrow results with directories_only, files_only, name_pattern (for example A*), or multiple OR patterns in include. Use counts_only=true when only matching file/directory counts are needed.

Idle memory release

After 30 minutes with no tool call, the server returns its heap to the OS. A stdio MCP server cannot tell an abandoned client from a quiet one -- the process that spawned it may be alive, finished with it, and still holding the pipe open, so no EOF ever arrives -- and exiting on that guess would break a session that merely paused. Releasing the memory is the safe half of that trade: an instance that once read a 50MB file settles back to its ~20MB baseline instead of holding 200MB for the rest of the machine's uptime. Open shell and ssh sessions survive, and nothing the client can observe changes.

Quick Start

1. Download the binary for your OS from Releases
2. Run agent-tool install (or agent-tool install claude for a specific agent)
3. Restart your IDE / agent
4. Done — the compact core tools are available immediately; toolbox describes and calls every other tool on demand

Or just ask your AI agent to do it for you:

"Download agent-tool from https://github.com/knewstimek/agent-tool/releases/latest and run agent-tool install"

Any capable AI coding agent (Claude Code, Codex, etc.) can handle the full download → install → restart flow automatically.

Recommended: Tell your agent to prefer agent-tool

After installing, agents will have access to agent-tool but may still default to built-in tools (Read, Edit, etc.). To ensure agents prefer agent-tool's encoding-aware, indentation-smart tools, add one of the instructions below.

Code navigation tip: For large projects, add this to your CLAUDE.md / AGENTS.md to enable AST-based code navigation:

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.

Pick Strict or Soft:

Where to put it:

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.

Installation

Auto-install (recommended)

# 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

Install permission levels:

Approval level is independent of schema profile: installation may approve the full namespace while the server still starts with the token-efficient core profile. toolbox is intentionally not auto-approved by --safe-approve, because its operation=call gateway can invoke network, shell, database, and process-control tools. Safe-mode users should review each toolbox approval and avoid granting it a permanent allow rule unless they intend to trust the full AgentTool namespace.

Manual setup

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

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

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

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

Options

# 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

Profiles are additive presets: core (11 schemas), coding (core plus broader file/build/shell tools), remote, analysis, and full. At runtime, prefer the client-independent toolbox gateway: operation=describe returns one tool's schema (compact=true plus tool_operation limits it to one operation), and operation=call invokes it through the stable toolbox binding. Re-send a returned schema_handle to avoid receiving an unchanged schema again. When command diagnostics are compacted, operation=output retrieves the bounded raw output by its reported ID for 30 minutes and reports next_offset when paging is needed. enable, disable, and profile remain available for clients that honor tools/list_changed; fixed-binding clients can always keep using the gateway.

Environment Variable

Set AGENT_TOOL_FALLBACK_ENCODING and/or AGENT_TOOL_PROFILE to avoid repeating CLI flags:

# 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

Priority: CLI flag > environment variable > default (UTF-8).

Local SSH/SFTP connection profiles

SSH and SFTP accept either connection_profile or a session-local connection_id, so host, user, key, and jump-host fields do not need to be repeated. Profiles are read from the OS user config directory at agent-tool/connections.json; override the location with AGENT_TOOL_CONNECTION_PROFILE_FILE. Keep this file local and explicitly ignored if it is placed inside a workspace.

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

An initial call returns an opaque connection_id that remains reusable by both tools for 30 minutes. trusted:true affects only display: an allowed private-address warning is shown once per pooled connection instead of on every call; SSRF blocking and cloud metadata protection are unchanged. SSH also supports quiet, echo_command, and result_only; the last returns compact JSON centered on stdout, stderr, and exit_code. SFTP supports quiet, result_only, and upload_many (up to 100 files).

Runtime Configuration

Agents can change settings at runtime via set_config without restarting:

Build

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

Cross-compile:

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 .

Troubleshooting

Garbled text (encoding issues)

If Korean, Japanese, or other non-ASCII text appears as garbage characters:

Option 1: Add charset to your .editorconfig:

[*]
charset = euc-kr

Option 2: Set environment variable (persistent):

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

Option 3: CLI flag (per-session):

agent-tool --fallback-encoding EUC-KR

Built-in help for agents

agent-tool includes a agent_tool_help tool that agents can call for usage guidance. When an agent encounters encoding warnings or garbled text, it can call:

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

Available topics: overview, encoding, indentation, tools, troubleshooting

Security

agent-tool provides powerful system access (SSH, MySQL, Redis, file operations, HTTP requests). When used with AI coding agents, be aware of prompt injection risks:

• SSRF Protection: Cloud metadata IPs (169.254.x.x, fe80::/10) are always blocked regardless of settings. Private IP access is configurable per protocol via set_config (allow_http_private, allow_mysql_private, allow_redis_private, allow_ssh_private)
• DLP (Data Loss Prevention): All outbound HTTP request bodies are scanned for sensitive data patterns (PEM private keys, AWS access keys, GitHub/GitLab tokens, Slack tokens, .env file dumps) and blocked before transmission
• Prompt Injection Warnings: Every private IP connection shows a security warning visible to both the user and the AI agent, helping detect prompt injection attacks from fetched web content
• Zip Slip protection: Archive entries with ../ path traversal are blocked (both zip and tar)
• Zip Bomb protection: Single file limit (1GB), total extraction limit (5GB)
• Symlinks: Skipped by default. Enable via set_config allow_symlinks=true (tar only; zip symlinks always skipped). Even when enabled, symlinks targeting outside the output directory are blocked
• File size limit: Configurable max file size (default 100MB) prevents OOM on large files. Adjustable via set_config max_file_size_mb=N
• Encoding safety: chardet uses 64KB sample (not full file) for memory efficiency

For maximum security, review the AI agent's tool calls before approving, especially for SSH commands, HTTP requests to external URLs, and database queries.

Tech Stack

• Language: Go
• MCP SDK: github.com/modelcontextprotocol/go-sdk
• Encoding: saintfish/chardet + golang.org/x/text
• Distribution: Single binary (cross-compiled)

License

MIT