convez.ai
AgenteDevOps & InfraestruturaAvançado
knewstimek

Agent Tool

knewstimek/agent-tool

50+ ferramentas MCP em um binário — engenharia reversa, arquivos e infraestrutura

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP completo para agentes de IA com 50+ ferramentas nativas em Go. Oferece manipulação de arquivos com preservação de encoding e indentação, análise binária estática, debugger DAP, SSH/SFTP, inspeção de memória, e suporte a contorno de censura de rede.

Instalação

$npx convez-ai knewstimek/agent-tool

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
26
Forks
7
Acompanhando
0
Saúde
42%
Último commit
há 3 dias
Versão
v1.1.3
Issues abertas
5
Contribuidores
3

Casos de uso

  • Agentes de IA editando código com respeito a indentação e encoding legacy (EUC-KR, Shift-JIS, GB18030)
  • Reverse engineering e análise de binários com disassembly e xref
  • Automação de DevOps com SSH/SFTP, process memory e descoberta de ferramentas do sistema

Veredito

Ferramenta robusta e completa que soluciona lacunas críticas de agentes de IA em ambientes com encoding exótico, projetos legacy e necessidades de reverse engineering. Especialmente valiosa para equipes em regiões com censura de rede e workflows que exigem respeito rigoroso a convenções de projeto.

README

A tradução para o português deste README ainda está na fila.

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 50 tools into a single binary -- one install, everything works.
  • 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 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

ToolDescriptionStatus
EditString replacement with smart indentation and encoding preservation (supports dry_run)✅
ReadEncoding-aware file reading with flexible offset (integer, "N-M" range, [N,M] array). Image files (PNG/JPG/GIF/BMP/WebP/TIFF/ICO) returned as base64 ImageContent✅
WriteEncoding-aware file creation/overwrite✅
GrepEncoding-aware regex content search with output modes (content/files_with_matches/count) and context lines (-B/-A/-C)✅
GlobFile pattern matching with ** recursive support✅
ListDirDirectory listing (flat or tree)✅
DiffCompare two files with unified diff output (encoding-aware)✅
PatchApply unified diff patch to a file (supports dry_run)✅
ChecksumCompute file hash (md5, sha1, sha256)✅
FileInfoFile metadata (size, encoding, line ending, indentation, line count)✅
CompressCreate zip / tar.gz archives✅
DecompressExtract zip / tar.gz archives (Zip Slip/Bomb protection)✅
BackupTimestamped zip backup with exclude patterns. dry_run preview with directory stats, pattern match counts, and largest files✅
ConvertEncodingConvert file encoding (EUC-KR ↔ UTF-8, add/remove BOM, etc.)✅
DeleteSafe single-file deletion (no directories, no symlinks, system path protection, dry_run)✅
RenameAtomic file/directory rename or move (dry_run)✅
SysInfoSystem information — OS, CPU, RAM, disk, uptime, CPU usage measurement✅
FindToolsDiscover 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)✅
ProcListList running processes — PID, name, command line, memory. Sensitive args auto-masked. Filter by name or port✅
ProcKillKill, suspend, or resume processes by PID or port. Tree kill, signal selection (kill/term/hup/int/stop/cont), zombie handling (Linux), dry_run✅
ProcExecExecute commands as new processes. Foreground/background/suspended start (Windows: CREATE_SUSPENDED, Linux: SIGSTOP). Timeout, env vars✅
EnvVarRead environment variables. Sensitive values (passwords, tokens) auto-masked✅
FirewallRead firewall rules — iptables/nftables/firewalld (Linux), netsh (Windows). Read-only✅
SSHExecute commands on remote servers via SSH. Password & key auth (PEM, OpenSSH, PuTTY PPK), session pooling, host key verification (strict/tofu/none), ProxyJump, IPv6✅
SFTPTransfer files and manage remote filesystems over SSH. Upload, download, ls, stat, mkdir, rm, chmod, rename. Reuses SSH session pool. Max 2 GB per transfer✅
BashPersistent 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✅
WebFetchFetch 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✅
WebSearchWeb 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✅
DownloadDownload files from URLs to disk. ECH + DoH by default. SSRF protection. HTTP/SOCKS5 proxy. Atomic write. Max 2 GB✅
HTTPReqExecute HTTP requests with any method (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS). API testing with custom headers, body, proxy. SSRF protection✅
JSONQueryQuery JSON files with dot-notation paths (e.g. dependencies.react, items[*].id). Extract specific values without loading entire file into context✅
YAMLQueryQuery YAML files with dot-notation paths (same syntax as JSONQuery)✅
TOMLQueryQuery TOML files with dot-notation paths (same syntax as JSONQuery). Supports TOML-specific types (datetime, int64)✅
CopyCopy files/directories with atomic write and permission preservation. Recursive directory copy. Windows locked-file fallback (renames running exe/DLL aside). dry_run preview✅
MkdirCreate directories with optional permission mode (octal, e.g. 0755). Recursive by default (mkdir -p). dry_run preview✅
MultiReadRead multiple files in a single call to reduce API round-trips. Encoding-aware, offset/limit support. Max 50 files✅
RegexReplaceRegex find-and-replace across files/directories. Encoding-preserving, capture groups ($1, $2). dry_run preview✅
TLSCheckCheck TLS certificate details — subject, issuer, expiry, SANs, TLS version, cipher suite✅
DNSLookupDNS record lookup (A/AAAA/MX/CNAME/TXT/NS/SOA). DNS over HTTPS (DoH) by default for privacy✅
MySQLExecute SQL queries on MySQL/MariaDB. Table-formatted SELECT results, affected rows for DML. Max 1000 rows✅
RedisExecute Redis commands with formatted output by type. TLS support. Dangerous commands (FLUSHALL, SHUTDOWN, etc.) blocked✅
PortCheckCheck if a TCP port is open on a host. Returns OPEN/CLOSED with response time. Supports hostname, IPv4, IPv6✅
ExternalIPGet your external (public) IP address. Multiple providers with automatic fallback (ipify, ifconfig.me, icanhazip)✅
SLOCCount source lines of code per language. 70+ language detection, per-file/language breakdown, blank line stats, max_depth control✅
DebugInteractive 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✅
AnalyzeStatic binary analysis and reverse engineering. x86/x64/ARM/ARM64 disassembly (PE/ELF/Mach-O, auto VA display, symbol annotation, stop_at_ret). PE/ELF/Mach-O parsing (RWX warnings, resources, imports with IAT VA, exports). xref (PE/ELF/Mach-O, x86/x64/ARM64/ARM32, summary stats). function_at (.pdata or heuristic prologue/epilogue scan). call_graph (PE/ELF/Mach-O, x86/x64/ARM64/ARM32). follow_ptr (pointer chain tracing with circular detection). rtti_dump (MSVC RTTI parsing with class name demangling, pSelf validation). vtable_scan (auto-discover vtables with RTTI in .rdata). struct_layout (memory layout annotation). imphash, Rich header, DWARF debug info, string extraction (with VA), hexdump, hex pattern search (with section names), entropy analysis, overlay detection, binary diff. No global file size limit✅
MemtoolCheatEngine-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)✅
IPCInter-process communication between AI agent sessions over TCP. 1:1 message passing with blocking receive. Protocol: [2-byte type][4-byte length][payload]. Operations: send, receive (blocking with timeout), ping. Works across machines. Max 1MB message, 300s timeout✅
WintoolWindows GUI automation — find/enumerate windows and child controls, capture screenshots (ImageContent PNG via PrintWindow), read clipboard images, read/set text, click, type, send raw messages, show/hide/minimize/maximize, move/resize, close, focus. screenshot/clipboard return ImageContent by default (save_path option for file output). Enables AI agents to "see" and interact with GUI applications. Windows only✅
CodeGraphAST-based code indexing with tree-sitter (WASM). 11 operations: index, find, callers, callees, symbols, methods, inherits, stats, importers, unused (dead code), call_tree (recursive call hierarchy). Supports C/C++, Python, Go, C#, Rust, Java. Respects .gitignore (nested), skips venv/vendor/third_party. No LLM calls, zero token cost✅
SetConfigChange runtime settings (encoding, file size limit, symlinks, workspace, etc.)✅
HelpBuilt-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

  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 — 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.

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.
Then use codegraph for structural queries (find, callers, callees, methods, inherits) instead of grep.

Pick Strict or Soft:

ModeWhen to useInstruction
StrictProjects with non-UTF-8 files or mixed indentationALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools. agent-tool preserves file encoding and respects .editorconfig indentation settings.
SoftGeneral projectsPrefer 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.

Hard enforcement — deny built-in file tools at the permission level via ~/.claude/settings.json:

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

This makes Claude Code's built-in file tools unavailable, so the agent is forced to use agent-tool. Recommended when you want strict enforcement without relying on prompt instructions.

  1. Add to ~/.codex/config.toml (top-level, not inside [mcp_servers.*]):
model_instructions_file = "~/.codex/model_instructions.md"
  1. Create ~/.codex/model_instructions.md:
ALWAYS use agent-tool MCP tools (mcp__agent-tool__*) instead of built-in file tools.
  1. 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:

LevelFlagAuto-approved tools
Full (default)(none)All tools (mcp__agent-tool__* wildcard)
Safe--safe-approve29 local-only tools (read, edit, write, grep, glob, etc.) — no SSH, HTTP, DB, bash, process control
None--no-auto-approveNo 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:

ParameterDescriptionDefault
fallback_encodingFallback encoding when auto-detection failsUTF-8
encoding_warningsShow encoding detection warningstrue
max_file_size_mbMax file size for read/edit/grep (MB)50
allow_symlinksAllow symlink extraction from tar archivesfalse
workspaceDefault workspace/project root for tools like glob when no explicit path is given(cwd)
allow_http_privateAllow webfetch/download/httpreq to access private IPsfalse
allow_mysql_privateAllow mysql tool to access private IPstrue
allow_redis_privateAllow redis tool to access private IPstrue
allow_ssh_privateAllow ssh/sftp tools to access private IPstrue
enable_dohEnable DNS over HTTPS globally (webfetch/download/httpreq/dnslookup)true
enable_echEnable 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.

Tech Stack

License

MIT

Ver o original no GitHub

Bom para

Relacionados