agent-tool

한국어

MCP-сервер (Model Context Protocol) с инструментами для ИИ-агентов, пишущих код.

Зачем?

Встроенные инструменты ИИ-агентов для написания кода (Claude Code, Cursor, Codex и др.) имеют известные ограничения:

• Ломаются отступы из табов: LLM выводят пробелы, а в вашем проекте используются табы. Встроенный инструмент Edit записывает пробелы как есть, нарушая ваш стиль отступов.

• Порча кодировки: При редактировании файлов в EUC-KR, Shift-JIS или GB18030 они молча конвертируются в UTF-8, ломая легаси-проекты.

• Слишком много отдельных инструментов: Заставлять агента искать, устанавливать и настраивать Redis CLI, MySQL-клиент, SSH-клиент и т.д. — утомительно и чревато ошибками. agent-tool объединяет 54 инструмента в один бинарник и предоставляет их по требованию через компактные профили.

• Нет поддержки реверс-инжиниринга: Встроенные инструменты не умеют дизассемблировать бинарники, анализировать PE/ELF-заголовки, находить границы функций или искать перекрёстные ссылки. agent-tool включает статический анализ бинарников (дизассемблирование, xref, определение функций), DAP-отладчик и инструменты работы с памятью в стиле CheatEngine — это даёт вашему агенту полные возможности реверс-инжиниринга.

• Цензура в сети: В некоторых странах государственная фильтрация веб-трафика ломает обычные запросы curl/wget. agent-tool по умолчанию использует ECH (Encrypted Client Hello) и DoH (DNS over HTTPS), чтобы обходить эти ограничения.

agent-tool решает эти проблемы с помощью инструментов, ориентированных на агентов, которые сохраняют конвенции проекта и при этом держат контекст модели в разумных пределах.

Related MCP server: DevToolkit MCP Server

Поддерживаемые агенты

Claude Code, Codex CLI, Cursor, Windsurf, Cline, Gemini CLI и любой MCP-совместимый агент.

Эффективность для LLM по умолчанию

Профиль core по умолчанию открывает только 11 схем (включая toolbox) вместо всех 54. При измерении на уровне протокола это сократило сериализованный список инструментов примерно с 84 КБ (full) до 18 КБ. Используйте toolbox(operation="describe", tool="ssh", compact=true, tool_operation="execute"), чтобы загрузить поля и список обязательных аргументов только одной операции, а затем вызывайте её через toolbox(operation="call", tool="ssh", arguments={...}). Шлюз не зависит от динамического обновления списка инструментов, поэтому работает с клиентами с фиксированной привязкой, такими как Codex. Describe возвращает привязанный к инструменту/версии schema_handle; при повторном вызове describe с ним возвращается короткое подтверждение без изменений, если схема всё ещё актуальна. Также можно запустить с флагом --profile coding|remote|analysis|full.

Потенциально большие текстовые ответы по умолчанию ограничены 32К символами с жёстким потолком 128К. Усечение всегда заметно, а инструменты с постраничной выдачей возвращают next_offset или next_cursor. Локальные относительные пути разрешаются относительно явно заданного workspace, затем корня MCP-клиента.

Возможности

Ключевые улучшения

Умные отступы

LLM обычно выводят пробелы, но во многих проектах используются табуляции. AgentTool автоматически преобразует отступы в соответствии с существующим стилем файла.

• Читает .editorconfig для indent_style и indent_size

• В качестве запасного варианта использует определение по содержимому (первые 100 строк)

• Защищает устаревшие файлы: не выполняет преобразование, если фактическое содержимое противоречит .editorconfig

Сохранение кодировки

Правки сохраняют исходную кодировку файла, а не принудительно используют UTF-8.

• Приоритет определения: BOM → charset из .editorconfig → UTF-16 без BOM → корректный UTF-8 → автоопределение chardet → запасная кодировка

• Поддерживаемые: UTF-8, UTF-8 BOM, EUC-KR, Shift-JIS, ISO-8859-1, UTF-16 (LE/BE, с BOM и без), и другие

• Без ложных предупреждений об ASCII: корректный UTF-8 проверяется напрямую, поэтому обычные ASCII-файлы никогда не вызывают предупреждение о низкой достоверности

• Переводы строк: определяет LF, CRLF, CR и смешанные файлы. edit сопоставляет многострочный old_string независимо от того, использует ли файл CRLF или LF, включая файлы со смешанными переводами строк, а текст, вставленный через edit/regexreplace, следует стилю перевода строк той области, в которую попадает, поэтому остальная часть файла остаётся побайтово идентичной

Экономные по токенам списки каталогов

listdir по умолчанию возвращает 500 записей на страницу и возвращает next_cursor, когда доступны дополнительные записи. Сузьте результаты с помощью directories_only, files_only, name_pattern (например, A*) или нескольких OR-шаблонов в include. Используйте counts_only=true, когда нужны только количества соответствующих файлов/каталогов.

Освобождение памяти в простое

После 30 минут без вызова инструментов сервер возвращает свою кучу (heap) операционной системе. stdio MCP-сервер не может отличить покинутого клиента от просто молчащего — процесс, который его запустил, может быть жив, уже закончил работу с ним и всё ещё удерживает pipe открытым, поэтому EOF никогда не наступает, — а завершение на основе такой догадки разорвало бы сессию, которая лишь приостановлена. Освобождение памяти — безопасная половина этой сделки: экземпляр, однажды прочитавший файл на 50MB, возвращается к своему базовому уровню ~20MB вместо того, чтобы удерживать 200MB всё время работы машины. Открытые shell и ssh сессии сохраняются, и ничто из того, что клиент может наблюдать, не меняется.

Быстрый старт

1. Скачайте бинарный файл для вашей ОС из Releases

2. Выполните agent-tool install (или agent-tool install claude для конкретного агента)

3. Перезапустите вашу IDE / агента

4. Готово — компактные основные инструменты доступны сразу; toolbox описывает и вызывает все остальные инструменты по требованию

Или просто попросите вашего ИИ-агента сделать это за вас:

"Скачайте agent-tool с https://github.com/knewstimek/agent-tool/releases/latest и выполните agent-tool install"

Любой способный ИИ-агент для написания кода (Claude Code, Codex и т. д.) может автоматически выполнить весь процесс загрузка → установка → перезапуск.

Рекомендуется: укажите агенту предпочитать agent-tool

После установки агенты получат доступ к agent-tool, но по-прежнему могут по умолчанию использовать встроенные инструменты (Read, Edit и т. д.). Чтобы агенты предпочитали учитывающие кодировку и интеллектуально работающие с отступами инструменты agent-tool, добавьте одну из приведённых ниже инструкций.

Совет по навигации по коду: для крупных проектов добавьте это в CLAUDE.md / AGENTS.md, чтобы включить навигацию по коду на основе 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.

Выберите Strict или Soft:

Куда добавить:

Для конкретного проекта — добавьте в CLAUDE.md вашего проекта:

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

Глобально (все проекты) — добавьте в ~/.claude/CLAUDE.md:

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

Жёсткое принуждение — запретите встроенные файловые инструменты на уровне разрешений через ~/.claude/settings.json:

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

Это делает встроенные файловые инструменты Claude Code недоступными, поэтому агент вынужден использовать agent-tool. Рекомендуется, когда нужно строгое принуждение без опоры на инструкции в промпте.

1. Добавьте в ~/.codex/config.toml (на верхнем уровне, не внутри [mcp_servers.*]):

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

2. Создайте ~/.codex/model_instructions.md:

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

3. Перезапустите Codex.

Для конкретного проекта — вместо этого добавьте в AGENTS.md вашего проекта.

Добавьте в .cursorrules, .windsurfrules или AGENTS.md вашего проекта:

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

Установка

Автоустановка (рекомендуется)

# 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

Уровни разрешений при установке:

Уровень одобрения не зависит от профиля схемы: установка может одобрить всё пространство имён, пока сервер всё ещё запускается с экономным по токенам профилем core. toolbox намеренно не одобряется автоматически через --safe-approve, поскольку его шлюз operation=call может вызывать сетевые инструменты, shell-инструменты, инструменты баз данных и управления процессами. Пользователям безопасного режима следует проверять каждое одобрение toolbox и избегать предоставления ему постоянного правила разрешения, если они не намерены доверять всему пространству имён AgentTool.

Ручная настройка

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

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

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

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

Параметры

# 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

Профили — это аддитивные пресеты: core (11 схем), coding (core плюс более широкие файловые/сборочные/shell инструменты), remote, analysis и full. Во время выполнения предпочитайте независимый от клиента шлюз toolbox: operation=describe возвращает схему одного инструмента (compact=true вместе с tool_operation ограничивает её одной операцией), а operation=call вызывает его через стабильную привязку toolbox. Повторно отправьте полученный schema_handle, чтобы не получать снова неизменённую схему. Когда диагностика команд сжимается, operation=output получает ограниченный необработанный вывод по указанному ID в течение 30 минут и сообщает next_offset, когда требуется постраничный переход. enable, disable и profile остаются доступны для клиентов, поддерживающих tools/list_changed; клиенты с фиксированной привязкой могут всегда продолжать использовать шлюз.

Переменная окружения

Задайте AGENT_TOOL_FALLBACK_ENCODING и/или AGENT_TOOL_PROFILE, чтобы не повторять флаги 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

Приоритет: флаг CLI > переменная окружения > значение по умолчанию (UTF-8).

Локальные профили подключений SSH/SFTP

SSH и SFTP принимают либо connection_profile, либо локальный для сессии connection_id, поэтому поля host, user, key и jump-host не нужно повторять. Профили читаются из каталога конфигурации пользователя ОС по пути agent-tool/connections.json; переопределите расположение с помощью AGENT_TOOL_CONNECTION_PROFILE_FILE. Храните этот файл локально и явно игнорируйте его, если он помещён внутри рабочей области.

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

Первый вызов возвращает непрозрачный connection_id, который остаётся пригодным для повторного использования обоими инструментами в течение 30 минут. trusted:true влияет только на отображение: предупреждение о разрешённом частном адресе показывается один раз для объединённого подключения, а не при каждом вызове; блокировка SSRF и защита метаданных облака не меняются. SSH также поддерживает quiet, echo_command и result_only; последний возвращает компактный JSON с фокусом на stdout, stderr и exit_code. SFTP поддерживает quiet, result_only и upload_many (до 100 файлов).

Конфигурация во время выполнения

Агенты могут изменять настройки во время выполнения через set_config без перезапуска:

Сборка

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

Кросс-компиляция:

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 .

Устранение неполадок

Нечитаемый текст (проблемы с кодировкой)

Если корейский, японский или другой не-ASCII текст отображается в виде нечитаемых символов:

Вариант 1: добавьте charset в ваш .editorconfig:

[*]
charset = euc-kr

Вариант 2: задайте переменную окружения (постоянно):

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

Вариант 3: флаг CLI (на сессию):

agent-tool --fallback-encoding EUC-KR

Встроенная справка для агентов

agent-tool включает инструмент agent_tool_help, который агенты могут вызывать для получения руководства по использованию. Когда агент сталкивается с предупреждениями о кодировке или нечитаемым текстом, он может вызвать:

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

Доступные темы: overview, encoding, indentation, tools, troubleshooting

Безопасность

agent-tool предоставляет мощный доступ к системе (SSH, MySQL, Redis, файловые операции, HTTP-запросы). При использовании с ИИ-агентами для написания кода помните о рисках промпт-инъекций:

• Защита от SSRF: IP-адреса метаданных облака (169.254.x.x, fe80::/10) всегда блокируются независимо от настроек. Доступ к приватным IP-адресам настраивается отдельно для каждого протокола через set_config (allow_http_private, allow_mysql_private, allow_redis_private, allow_ssh_private)

• DLP (предотвращение утечек данных): Все исходящие тела HTTP-запросов сканируются на предмет паттернов конфиденциальных данных (приватные ключи PEM, ключи доступа AWS, токены GitHub/GitLab, токены Slack, дампы .env-файлов) и блокируются до передачи

• Предупреждения о промпт-инъекциях: Каждое подключение к приватному IP-адресу показывает предупреждение о безопасности, видимое и пользователю, и ИИ-агенту, помогая обнаруживать атаки промпт-инъекций из загруженного веб-контента

• Защита от Zip Slip: Записи архивов с обходом пути ../ блокируются (как zip, так и tar)

• Защита от Zip Bomb: Лимит одного файла (1GB), общий лимит извлечения (5GB)

• Символические ссылки: По умолчанию пропускаются. Включаются через set_config allow_symlinks=true (только для tar; символические ссылки в zip пропускаются всегда). Даже при включении символические ссылки, ведущие за пределы выходного каталога, блокируются

• Лимит размера файла: Настраиваемый максимальный размер файла (по умолчанию 100MB) предотвращает нехватку памяти (OOM) на больших файлах. Регулируется через set_config max_file_size_mb=N

• Безопасность кодировок: chardet использует выборку размером 64KB (не весь файл) для эффективного использования памяти

Для максимальной безопасности проверяйте вызовы инструментов ИИ-агента перед одобрением, особенно команды SSH, HTTP-запросы к внешним URL и запросы к базам данных.

Технологический стек

• Язык: Go

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

• Кодировки: saintfish/chardet + golang.org/x/text

• Распространение: один бинарный файл (кросс-компилируемый)

Лицензия

MIT