agent-tool

한국어

Servidor de herramientas MCP (Model Context Protocol) para agentes de codificación de IA.

¿Por qué?

Las herramientas integradas en los agentes de codificación de IA (Claude Code, Cursor, Codex, etc.) tienen limitaciones conocidas:

• La indentación con tabulaciones se rompe: los LLM generan espacios, pero tu proyecto usa tabulaciones. La herramienta Edit integrada escribe los espacios tal cual, corrompiendo tu estilo de indentación.

• Corrupción de codificación: editar archivos EUC-KR, Shift-JIS o GB18030 los convierte silenciosamente a UTF-8, rompiendo proyectos heredados.

• Demasiadas herramientas separadas: hacer que el agente encuentre, instale y configure Redis CLI, cliente MySQL, cliente SSH, etc. es tedioso y propenso a errores. agent-tool agrupa 54 herramientas en un solo binario y las expone bajo demanda mediante perfiles compactos.

• Sin soporte de ingeniería inversa: las herramientas integradas no pueden desensamblar binarios, inspeccionar cabeceras PE/ELF, encontrar límites de funciones ni buscar referencias cruzadas. agent-tool incluye análisis estático de binarios (desensamblado, xref, detección de funciones), un depurador DAP y herramientas de memoria estilo CheatEngine, lo que proporciona a tu agente capacidades completas de ingeniería inversa.

• Censura de red: en algunos países, el filtrado web gubernamental rompe las peticiones curl/wget normales. agent-tool usa ECH (Encrypted Client Hello) y DoH (DNS over HTTPS) por defecto para sortear estas restricciones.

agent-tool resuelve estos problemas con herramientas orientadas a agentes que preservan las convenciones del proyecto y mantienen acotado el contexto del modelo.

Related MCP server: DevToolkit MCP Server

Agentes compatibles

Claude Code, Codex CLI, Cursor, Windsurf, Cline, Gemini CLI y cualquier agente compatible con MCP.

Eficiente para LLM por defecto

El perfil core predeterminado expone solo 11 esquemas (incluido toolbox) en lugar de los 54. En una medición a nivel de protocolo, esto redujo la lista serializada de herramientas de aproximadamente 84 KB (full) a 18 KB. Usa toolbox(operation="describe", tool="ssh", compact=true, tool_operation="execute") para cargar solo los campos y la lista de requisitos de una operación, y luego invócala mediante toolbox(operation="call", tool="ssh", arguments={...}). La puerta de enlace no depende de la actualización dinámica de la lista de herramientas, por lo que funciona con clientes con enlace fijo como Codex. Describe devuelve un schema_handle vinculado a la herramienta/versión; enviarlo en una descripción posterior devuelve un breve acuse de recibo sin cambios cuando el esquema sigue vigente. También puedes iniciar con --profile coding|remote|analysis|full.

Las respuestas de texto potencialmente grandes tienen un valor predeterminado de 32K caracteres con un límite máximo de 128K. El truncamiento siempre es visible y las herramientas paginables devuelven next_offset o next_cursor. Las rutas relativas locales se resuelven contra un espacio de trabajo explícito y, luego, contra la raíz del cliente MCP.

Características

Mejoras clave

Sangría inteligente

Los LLM suelen generar espacios, pero muchos proyectos usan tabulaciones. AgentTool convierte automáticamente la sangría para que coincida con el estilo existente del archivo.

• Lee .editorconfig para indent_style e indent_size

• Recurre a la detección basada en el contenido (primeras 100 líneas)

• Protege archivos heredados: no convierte si el contenido real contradice .editorconfig

Preservación de codificación

Las ediciones preservan la codificación original del archivo en lugar de forzar UTF-8.

• Prioridad de detección: BOM → charset de .editorconfig → UTF-16 sin BOM → UTF-8 válido → auto-detección de chardet → codificación de respaldo

• Soportado: UTF-8, UTF-8 BOM, EUC-KR, Shift-JIS, ISO-8859-1, UTF-16 (LE/BE, con o sin BOM), y más

• Sin falsas advertencias en ASCII: el UTF-8 válido se verifica directamente, por lo que los archivos ASCII simples nunca generan una advertencia de baja confianza

• Finales de línea: detecta LF, CRLF, CR y archivos mixtos. edit coincide con un old_string de varias líneas tanto si el archivo usa CRLF como LF, incluidos los archivos que mezclan ambos, y el texto insertado por edit/regexreplace sigue el estilo de nueva línea de la región en la que se inserta, de modo que el resto del archivo queda byte-idéntico.

Listados de directorio seguros para tokens

listdir tiene como valor predeterminado 500 entradas por página y devuelve next_cursor cuando hay más entradas disponibles. Filtra los resultados con directories_only, files_only, name_pattern (por ejemplo A*) o múltiples patrones OR en include. Usa counts_only=true cuando solo necesites los recuentos de archivos/directorios coincidentes.

Liberación de memoria en reposo

Después de 30 minutos sin ninguna llamada a una herramienta, el servidor devuelve su montón al sistema operativo. Un servidor MCP stdio no puede distinguir entre un cliente abandonado y uno inactivo: el proceso que lo creó puede estar vivo, haber terminado con él y seguir manteniendo la tubería abierta, por lo que nunca llega un EOF; y salir basándose en esa suposición rompería una sesión que simplemente se pausó. Liberar la memoria es la mitad segura de ese intercambio: una instancia que una vez leyó un archivo de 50MB vuelve a su línea base de ~20MB en lugar de mantener 200MB durante el resto del tiempo de actividad de la máquina. Las sesiones abiertas de shell y ssh sobreviven, y nada de lo que el cliente pueda observar cambia.

Inicio rápido

1. Descarga el binario para tu sistema operativo desde Releases

2. Ejecuta agent-tool install (o agent-tool install claude para un agente específico)

3. Reinicia tu IDE / agente

4. Listo: las herramientas principales compactas están disponibles de inmediato; toolbox describe y llama a cualquier otra herramienta bajo demanda

O simplemente pídele a tu agente de IA que lo haga por ti:

"Descarga agent-tool desde https://github.com/knewstimek/agent-tool/releases/latest y ejecuta agent-tool install"

Cualquier agente de codificación de IA capaz (Claude Code, Codex, etc.) puede manejar automáticamente todo el flujo de descarga → instalación → reinicio.

Recomendado: dile a tu agente que prefiera agent-tool

Después de la instalación, los agentes tendrán acceso a agent-tool pero aún pueden usar por defecto las herramientas integradas (Read, Edit, etc.). Para asegurar que los agentes prefieran las herramientas de agent-tool que son conscientes de la codificación y inteligentes con la sangría, añade una de las instrucciones siguientes.

Consejo de navegación de código: para proyectos grandes, añade esto a tu CLAUDE.md / AGENTS.md para habilitar la navegación de código basada en AST:

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.

Elige Strict o Soft:

Dónde colocarlo:

Por proyecto — añade a CLAUDE.md de tu proyecto:

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

Global (todos los proyectos) — añade a ~/.claude/CLAUDE.md:

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

Aplicación estricta — deniega las herramientas de archivo integradas a nivel de permisos mediante ~/.claude/settings.json:

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

Esto hace que las herramientas de archivo integradas de Claude Code no estén disponibles, por lo que el agente se ve obligado a usar agent-tool. Recomendado cuando quieres una aplicación estricta sin depender de instrucciones en el prompt.

1. Añade a ~/.codex/config.toml (nivel superior, no dentro de [mcp_servers.*]):

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

2. Crea ~/.codex/model_instructions.md:

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

3. Reinicia Codex.

Por proyecto — añade a AGENTS.md de tu proyecto en su lugar.

Añade a .cursorrules, .windsurfrules o AGENTS.md de tu proyecto:

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

Instalación

Auto-instalación (recomendada)

# 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

Niveles de permiso de instalación:

El nivel de aprobación es independiente del perfil de esquema: la instalación puede aprobar el espacio de nombres completo mientras el servidor aún se inicia con el perfil core eficiente en tokens. toolbox no está aprobado automáticamente por --safe-approve a propósito, porque su puerta de enlace operation=call puede invocar herramientas de red, shell, base de datos y control de procesos. Los usuarios en modo seguro deben revisar cada aprobación de toolbox y evitar otorgarle una regla de permiso permanente a menos que tengan la intención de confiar en todo el espacio de nombres de AgentTool.

Configuración manual

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

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

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

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

Opciones

# 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

Los perfiles son ajustes preestablecidos aditivos: core (11 esquemas), coding (core más herramientas de archivo/compilación/shell más amplias), remote, analysis y full. En tiempo de ejecución, prefiere la puerta de enlace toolbox independiente del cliente: operation=describe devuelve el esquema de una herramienta (compact=true más tool_operation lo limita a una operación), y operation=call la invoca a través del enlace estable de toolbox. Vuelve a enviar un schema_handle devuelto para evitar recibir un esquema sin cambios nuevamente. Cuando los diagnósticos de comandos se compactan, operation=output recupera la salida cruda limitada por su ID informado durante 30 minutos y reporta next_offset cuando se necesita paginación. enable, disable y profile siguen disponibles para clientes que respetan tools/list_changed; los clientes con enlaces fijos siempre pueden seguir usando la puerta de enlace.

Variable de entorno

Establece AGENT_TOOL_FALLBACK_ENCODING y/o AGENT_TOOL_PROFILE para evitar repetir las banderas de CLI:

# 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

Prioridad: bandera de CLI > variable de entorno > predeterminado (UTF-8).

Perfiles de conexión SSH/SFTP locales

SSH y SFTP aceptan tanto connection_profile como un connection_id local a la sesión, por lo que los campos de host, usuario, clave y host de salto no necesitan repetirse. Los perfiles se leen desde el directorio de configuración del usuario del sistema operativo en agent-tool/connections.json; anula la ubicación con AGENT_TOOL_CONNECTION_PROFILE_FILE. Mantén este archivo local y explícitamente ignorado si se coloca dentro de un espacio de trabajo.

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

Una llamada inicial devuelve un connection_id opaco que sigue siendo reutilizable por ambas herramientas durante 30 minutos. trusted:true afecta solo a la visualización: se muestra una advertencia de dirección privada permitida una vez por conexión agrupada en lugar de en cada llamada; el bloqueo SSRF y la protección de metadatos de nube no cambian. SSH también admite quiet, echo_command y result_only; este último devuelve JSON compacto centrado en stdout, stderr y exit_code. SFTP admite quiet, result_only y upload_many (hasta 100 archivos).

Configuración en tiempo de ejecución

Los agentes pueden cambiar la configuración en tiempo de ejecución mediante set_config sin reiniciar:

Compilación

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

Compilación cruzada:

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 .

Solución de problemas

Texto distorsionado (problemas de codificación)

Si el texto coreano, japonés u otro texto no ASCII aparece como caracteres basura:

Opción 1: añade charset a tu .editorconfig:

[*]
charset = euc-kr

Opción 2: establece la variable de entorno (persistente):

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

Opción 3: bandera de CLI (por sesión):

agent-tool --fallback-encoding EUC-KR

Ayuda integrada para agentes

agent-tool incluye una herramienta agent_tool_help que los agentes pueden llamar para obtener orientación de uso. Cuando un agente encuentra advertencias de codificación o texto distorsionado, puede llamar a:

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

Temas disponibles: overview, encoding, indentation, tools, troubleshooting

Seguridad

agent-tool proporciona acceso potente al sistema (SSH, MySQL, Redis, operaciones de archivos, solicitudes HTTP). Cuando se usa con agentes de codificación de IA, ten en cuenta los riesgos de inyección de prompts:

• Protección SSRF: Las IPs de metadatos de la nube (169.254.x.x, fe80::/10) siempre están bloqueadas independientemente de la configuración. El acceso a IPs privadas es configurable por protocolo mediante set_config (allow_http_private, allow_mysql_private, allow_redis_private, allow_ssh_private)

• DLP (Prevención de Pérdida de Datos): Todos los cuerpos de solicitudes HTTP salientes se escanean en busca de patrones de datos sensibles (claves privadas PEM, claves de acceso de AWS, tokens de GitHub/GitLab, tokens de Slack, volcados de archivos .env) y se bloquean antes de la transmisión

• Advertencias de inyección de prompts: Cada conexión a IP privada muestra una advertencia de seguridad visible tanto para el usuario como para el agente de IA, ayudando a detectar ataques de inyección de prompts desde contenido web obtenido

• Protección Zip Slip: Las entradas de archivos con traversal de ruta ../ están bloqueadas (tanto zip como tar)

• Protección Zip Bomb: Límite de archivo individual (1GB), límite total de extracción (5GB)

• Symlinks: Omitidos por defecto. Actívelos mediante set_config allow_symlinks=true (solo tar; los symlinks de zip siempre se omiten). Incluso cuando están habilitados, los symlinks que apuntan fuera del directorio de salida están bloqueados

• Límite de tamaño de archivo: El tamaño máximo de archivo configurable (100MB por defecto) previene OOM en archivos grandes. Ajustable mediante set_config max_file_size_mb=N

• Seguridad de codificación: chardet utiliza una muestra de 64KB (no el archivo completo) para eficiencia de memoria

Para máxima seguridad, revise las llamadas a las herramientas del agente de IA antes de aprobarlas, especialmente los comandos SSH, las solicitudes HTTP a URLs externas y las consultas a bases de datos.

Stack Tecnológico

• Lenguaje: Go

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

• Codificación: saintfish/chardet + golang.org/x/text

• Distribución: Binario único (compilación cruzada)

Licencia

MIT