agent-tool

韩语

面向 AI 编程智能体的 MCP（Model Context Protocol）工具服务器。

为什么？

• Tab 缩进损坏：LLM 输出空格，但你的项目使用 Tab。内置的 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 个 schema（包括 toolbox），而不是全部 54 个。在协议级别的测量中，这使序列化后的工具列表从约 84 KB（full）减少到 18 KB。使用 toolbox(operation="describe", tool="ssh", compact=true, tool_operation="execute") 只加载一个操作的字段和必填列表，然后通过 toolbox(operation="call", tool="ssh", arguments={...}) 调用它。网关不依赖动态工具列表刷新，因此可以与 Codex 等固定绑定客户端配合使用。Describe 会返回一个绑定工具/版本的 schema_handle；在后续 describe 调用中发送它，如果 schema 仍然是最新的，就会返回一个简短的不变确认。你也可以使用 --profile coding|remote|analysis|full 启动。

可能较大的文本响应默认为 32K 字符，硬性上限为 128K。截断始终可见，可分页的工具会返回 next_offset 或 next_cursor。

本地相对路径会先基于显式工作区解析，然后再基于 MCP 客户端根目录解析。

功能

主要改进

智能缩进

LLM 通常输出空格，但许多项目使用制表符。AgentTool 会自动转换缩进，以匹配文件现有的风格。

• 读取 .editorconfig 中的 indent_style 和 indent_size

• 回退到基于内容的检测（前 100 行）

• 保护旧文件：如果实际内容与 .editorconfig 矛盾，则不进行转换

编码保留

编辑操作会保留原始文件编码，而不是强制使用 UTF-8。

• 检测优先级：BOM → .editorconfig 字符集 → 无 BOM 的 UTF-16 → 有效 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 以及混合行尾的文件。无论文件使用 CRLF 还是 LF（包括两者混用的文件），edit 都能匹配多行 old_string；edit/regexreplace 插入的文本会跟随所落区域的换行风格，因此文件其余部分保持逐字节不变。

节省 Token 的目录列表

listdir 默认每页返回 500 个条目，当有更多条目可用时返回 next_cursor。 使用 directories_only、files_only、name_pattern（例如 A*）或 include 中的多个 OR 模式来缩小结果范围。 当只需要匹配的文件/目录计数时，使用 counts_only=true。

空闲内存释放

在 30 分钟没有工具调用后，服务器会将堆内存归还给操作系统。stdio MCP 服务器无法区分被遗弃的客户端与暂时安静的客户端——生成它的进程可能仍然存活、已经不再需要它，却依然持有管道使其保持打开，因此永远不会出现 EOF——而如果仅凭这种猜测退出，就会中断一个只是暂停的会话。释放内存是这一权衡中更安全的选择：曾经读取过 50MB 文件的实例会回落到约 ~20MB 的基线，而不是在机器剩余运行时间内一直占用 200MB。已打开的 shell 和 ssh 会话不受影响，客户端可观察到的任何内容都不会改变。

快速开始

1. 从 Releases 下载适用于你的操作系统的二进制文件

2. 运行 agent-tool install（或针对特定代理运行 agent-tool install claude）

3. 重启你的 IDE / 代理

4. 完成——精简的核心工具立即可用；toolbox 会按需描述并调用其他所有工具

或者直接让你的 AI 代理替你做这件事：

"从 https://github.com/knewstimek/agent-tool/releases/latest 下载 agent-tool 并运行 agent-tool install"

任何有能力的 AI 编程代理（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

安装权限级别：

批准级别与 schema 配置档无关：安装过程可以批准整个命名空间，而服务器仍以节省 token 的 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 个 schema）、coding（core 加上更广泛的文件/构建/shell 工具）、remote、analysis 和 full。在运行时，优先使用与客户端无关的 toolbox 网关：operation=describe 返回某个工具的 schema（compact=true 加上 tool_operation 可将其限制为单个操作），operation=call 则通过稳定的 toolbox 绑定调用它。重新发送返回的 schema_handle，可避免再次收到未变化的 schema。当命令诊断被压缩时，operation=output 可在 30 分钟内通过其报告的 ID 获取受限的原始输出，并在需要分页时报告 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，因此主机、用户、密钥和跳板机字段无需重复填写。配置档从操作系统用户配置目录下的 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；后者返回以 stdout、stderr 和 exit_code 为核心的紧凑 JSON。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：在 .editorconfig 中添加 charset：

[*]
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 请求）。与 AI 编程代理一起使用时，请注意提示注入风险：

• 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 连接都会显示一条安全警告，用户和 AI 代理均可见，有助于检测来自抓取的网页内容的提示注入攻击

• Zip Slip 防护：包含 ../ 路径穿越的归档条目将被阻止（zip 和 tar 均适用）

• Zip 炸弹防护：单文件限制（1GB），总解压限制（5GB）

• 符号链接：默认跳过。通过 set_config allow_symlinks=true 启用（仅限 tar；zip 符号链接始终跳过）。即使启用，指向输出目录外部的符号链接也会被阻止

• 文件大小限制：可配置最大文件大小（默认 100MB），防止大文件导致 OOM。可通过 set_config max_file_size_mb=N 调整

• 编码安全性：chardet 使用 64KB 采样（而非整个文件）以提高内存效率

为获得最大安全性，请在批准前审查 AI 代理的工具调用，尤其是 SSH 命令、对外部 URL 的 HTTP 请求以及数据库查询。

技术栈

• 语言：Go

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

• 编码：saintfish/chardet + golang.org/x/text

• 分发：单个二进制文件（交叉编译）

许可证

MIT