What can you do with this server?

The agent-tool server is an MCP (Model Context Protocol) tool server for AI coding agents, providing encoding-aware file operations, system management, remote access, and web capabilities. File Operations * Read, write, edit, delete, rename, diff, and patch files with encoding preservation (UTF-8, EUC-KR, Shift-JIS, etc.) and smart indentation conversion (tabs/spaces via .editorconfig or auto-detection) * Get file metadata (size, encoding, line endings, indentation), checksums (MD5/SHA1/SHA256), and convert between encodings File Discovery & Search * Glob (recursive pattern matching), grep (encoding-aware regex search), directory tree listing, and JSON dot-notation queries Archive & Backup * Compress/decompress .zip and .tar.gz archives with Zip Slip/Bomb protection; timestamped directory backups with exclude patterns and dry_run support Process & System Management * List, execute, kill, suspend, and resume processes by PID or port; get OS/CPU/RAM/disk/uptime info; read environment variables (sensitive values masked); view firewall rules; discover installed dev tools (Go, Node, Python, Java, Rust, .NET, Docker, etc.) Remote & Network * Execute commands on remote servers via SSH (key/password auth, ProxyJump, session pooling, IPv6) and transfer files via SFTP (upload/download/ls/mkdir/rm/chmod, async up to 2 GB) * Fetch web content as text/Markdown (SSRF protection), search via Brave/Naver APIs, download files, make arbitrary HTTP requests, check TCP port status, and retrieve your external IP Shell & Configuration * Persistent bash/PowerShell sessions with working directory and environment retention * Runtime configuration (fallback encoding, file size limits, symlink allowances, workspace path) without restarting * Built-in help guide for agents covering encoding, indentation, and troubleshooting

Which integrations are available for this server?

Locates C and C++ compilers and build systems to facilitate code compilation and development tasks. Automatically respects project-specific indentation and encoding standards by reading settings from .editorconfig files during file editing. Supports the discovery of development tools, compilers, and runtimes installed through the Homebrew package manager. Enables retrieval of Linux-specific system metrics, process management, and firewall rules from iptables, nftables, and firewalld. Provides system information and environment-aware tool discovery for development workflows on macOS. Generates unified diff outputs and comprehensive help documentation in Markdown format for high readability by AI agents. Discovers .NET SDKs and runtimes to support application development and environmental assessment. Identifies Node.js runtimes and associated development tools managed via the Node Version Manager (nvm). Searches for and identifies installed Python environments and development tools across the host system. Detects Rust toolchains, compilers, and development utilities to assist AI agents in managing Rust projects.

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 46 tools into a single binary — one install, everything works.
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 by providing drop-in replacement tools that respect your project's conventions.

Supported Agents

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

Features

Tool	Description	Status
Edit	String replacement with smart indentation and encoding preservation (supports dry_run)	✅
Read	Encoding-aware file reading with line range support	✅
Write	Encoding-aware file creation/overwrite	✅
Grep	Encoding-aware regex content search	✅
Glob	File pattern matching with `**` recursive support	✅
ListDir	Directory listing (flat or tree)	✅
Diff	Compare two files with unified diff output (encoding-aware)	✅
Patch	Apply unified diff patch to a file (supports dry_run)	✅
Checksum	Compute file hash (md5, sha1, sha256)	✅
FileInfo	File metadata (size, encoding, line ending, indentation, line count)	✅
Compress	Create zip / tar.gz archives	✅
Decompress	Extract zip / tar.gz archives (Zip Slip/Bomb protection)	✅
Backup	Timestamped zip backup with exclude patterns. dry_run preview with directory stats, pattern match counts, and largest files	✅
ConvertEncoding	Convert file encoding (EUC-KR ↔ UTF-8, add/remove BOM, etc.)	✅
Delete	Safe single-file deletion (no directories, no symlinks, system path protection, dry_run)	✅
Rename	Atomic file/directory rename or move (dry_run)	✅
SysInfo	System information — OS, CPU, RAM, disk, uptime, CPU usage measurement	✅
FindTools	Discover installed dev tools — compilers, runtimes, build systems (Go, .NET, Node, Python, Java, Rust, C/C++, etc.). Searches PATH, env vars, and known locations (~/bin, snap, scoop, Homebrew, SDKMAN, nvm, fnm, pyenv)	✅
ProcList	List running processes — PID, name, command line, memory. Sensitive args auto-masked. Filter by name or port	✅
ProcKill	Kill, suspend, or resume processes by PID or port. Tree kill, signal selection (kill/term/hup/int/stop/cont), zombie handling (Linux), dry_run	✅
ProcExec	Execute commands as new processes. Foreground/background/suspended start (Windows: CREATE_SUSPENDED, Linux: SIGSTOP). Timeout, env vars	✅
EnvVar	Read environment variables. Sensitive values (passwords, tokens) auto-masked	✅
Firewall	Read firewall rules — iptables/nftables/firewalld (Linux), netsh (Windows). Read-only	✅
SSH	Execute commands on remote servers via SSH. Password & key auth (PEM, OpenSSH, PuTTY PPK), session pooling, host key verification (strict/tofu/none), ProxyJump, IPv6	✅
SFTP	Transfer files and manage remote filesystems over SSH. Upload, download, ls, stat, mkdir, rm, chmod, rename. Reuses SSH session pool. Max 2 GB per transfer	✅
Bash	Persistent shell sessions with working directory and environment variable retention. Session pooling (max 5, idle timeout 30 min). Unix: bash/sh, Windows: PowerShell/git-bash/cmd (auto-detected, best available). PowerShell sessions include UTF-8 encoding and PATH enhancement	✅
WebFetch	Fetch web content as text/Markdown. ECH (Encrypted Client Hello) + DoH (DNS over HTTPS) by default. HTML→Markdown auto-conversion. SSRF protection. HTTP/SOCKS5 proxy. Chrome User-Agent. Note: Returns full page content (default 100K chars) which consumes context window tokens — use `max_length` to limit, or prefer your agent's built-in web tools for simple searches	✅
WebSearch	Web search via Brave Search or Naver API. Requires API key env vars (`BRAVE_SEARCH_API_KEY` or `NAVER_CLIENT_ID`/`NAVER_CLIENT_SECRET`). Auto-selects engine, Brave preferred	✅
Download	Download files from URLs to disk. ECH + DoH by default. SSRF protection. HTTP/SOCKS5 proxy. Atomic write. Max 2 GB	✅
HTTPReq	Execute HTTP requests with any method (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS). API testing with custom headers, body, proxy. SSRF protection	✅
JSONQuery	Query JSON files with dot-notation paths (e.g. `dependencies.react`, `items[*].id`). Extract specific values without loading entire file into context	✅
YAMLQuery	Query YAML files with dot-notation paths (same syntax as JSONQuery)	✅
TOMLQuery	Query TOML files with dot-notation paths (same syntax as JSONQuery). Supports TOML-specific types (datetime, int64)	✅
Copy	Copy files/directories with atomic write and permission preservation. Recursive directory copy. Windows locked-file fallback (renames running exe/DLL aside). dry_run preview	✅
Mkdir	Create directories with optional permission mode (octal, e.g. 0755). Recursive by default (mkdir -p). dry_run preview	✅
MultiRead	Read multiple files in a single call to reduce API round-trips. Encoding-aware, offset/limit support. Max 50 files	✅
RegexReplace	Regex find-and-replace across files/directories. Encoding-preserving, capture groups ($1, $2). dry_run preview	✅
TLSCheck	Check TLS certificate details — subject, issuer, expiry, SANs, TLS version, cipher suite	✅
DNSLookup	DNS record lookup (A/AAAA/MX/CNAME/TXT/NS/SOA). DNS over HTTPS (DoH) by default for privacy	✅
MySQL	Execute SQL queries on MySQL/MariaDB. Table-formatted SELECT results, affected rows for DML. Max 1000 rows	✅
Redis	Execute Redis commands with formatted output by type. TLS support. Dangerous commands (FLUSHALL, SHUTDOWN, etc.) blocked	✅
PortCheck	Check if a TCP port is open on a host. Returns OPEN/CLOSED with response time. Supports hostname, IPv4, IPv6	✅
ExternalIP	Get your external (public) IP address. Multiple providers with automatic fallback (ipify, ifconfig.me, icanhazip)	✅
SLOC	Count source lines of code per language. 70+ language detection, per-file/language breakdown, blank line stats, max_depth control	✅
Debug	Interactive debugger via DAP (Debug Adapter Protocol). Full DAP coverage: breakpoints (source/function/data/instruction/exception), stepping (forward/backward), variable inspection and modification, expression evaluation, disassembly, memory read/write, stack traces, modules, goto, completions. Tested with dlv (Go), debugpy (Python), codelldb (C/C++/Rust). Works with any DAP-compatible adapter. Stdio and TCP modes. Note: vsdbg (Microsoft) requires VS Code licensing and is not usable standalone — use codelldb or netcoredbg as open-source alternatives	✅
Analyze	Static binary analysis — x86/x64/ARM/ARM64 disassembly, PE/ELF/Mach-O parsing (RWX warnings, resources, imports, exports), imphash, Rich header, DWARF debug info, string extraction, hexdump, hex pattern search, entropy analysis, overlay detection, binary diff	✅
Memtool	CheatEngine-style process memory tool — search/filter/read/write memory values, live disassembly (x86/x64/ARM/ARM64), undo, struct pattern search, pointer scan, memory diff. Disk-backed snapshots for large scans. Session management with idle timeout. Windows (ReadProcessMemory) and Linux (/proc/pid/mem)	✅
SetConfig	Change runtime settings (encoding, file size limit, symlinks, workspace, etc.)	✅
Help	Built-in usage guide for agents (encoding, indentation, troubleshooting)	✅

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: .editorconfig charset → chardet auto-detection → fallback encoding
Supported: UTF-8, UTF-8 BOM, EUC-KR, Shift-JIS, ISO-8859-1, UTF-16, and more
Line endings: Preserves \r\n / \n as-is

Quick Start

Download the binary for your OS from Releases
Run agent-tool install (or agent-tool install claude for a specific agent)
Restart your IDE / agent
Done — all tools are available immediately with no permission popups

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.

Pick Strict or Soft:

Mode	When to use	Instruction
Strict	Projects with non-UTF-8 files or mixed indentation	`ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools. agent-tool preserves file encoding and respects .editorconfig indentation settings.`
Soft	General projects	`Prefer agent-tool MCP tools (mcp__agent-tool__*) over built-in file tools when available.`

Where to put it:

Per-project — add to your project's CLAUDE.md:

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

Global (all projects) — add to ~/.claude/CLAUDE.md:

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

Add to ~/.codex/config.toml (top-level, not inside [mcp_servers.*]):

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

Create ~/.codex/model_instructions.md:

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

Restart Codex.

Per-project — add to your project's AGENTS.md instead.

Add to your project's .cursorrules, .windsurfrules, or AGENTS.md:

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:

Level	Flag	Auto-approved tools
Full (default)	(none)	All tools (`mcp__agent-tool__*` wildcard)
Safe	`--safe-approve`	29 local-only tools (read, edit, write, grep, glob, etc.) — no SSH, HTTP, DB, bash, process control
None	`--no-auto-approve`	No tools — every call requires manual approval

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

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

Environment Variable

Set AGENT_TOOL_FALLBACK_ENCODING to avoid repeating the CLI flag every session:

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

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

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

Runtime Configuration

Agents can change settings at runtime via set_config without restarting:

Parameter	Description	Default
`fallback_encoding`	Fallback encoding when auto-detection fails	`UTF-8`
`encoding_warnings`	Show encoding detection warnings	`true`
`max_file_size_mb`	Max file size for read/edit/grep (MB)	`50`
`allow_symlinks`	Allow symlink extraction from tar archives	`false`
`workspace`	Default workspace/project root for tools like glob when no explicit path is given	(cwd)
`allow_http_private`	Allow webfetch/download/httpreq to access private IPs	`false`
`allow_mysql_private`	Allow mysql tool to access private IPs	`true`
`allow_redis_private`	Allow redis tool to access private IPs	`true`
`allow_ssh_private`	Allow ssh/sftp tools to access private IPs	`true`
`enable_doh`	Enable DNS over HTTPS globally (webfetch/download/httpreq/dnslookup)	`true`
`enable_ech`	Enable Encrypted Client Hello globally (webfetch/download/httpreq)	`true`

Build

go build -o agent-tool .

Cross-compile:

GOOS=linux GOARCH=amd64 go build -o agent-tool .
GOOS=darwin GOARCH=arm64 go build -o agent-tool .
GOOS=windows GOARCH=amd64 go build -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 50MB) 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.