agent-tool

agent-tool

한국어

面向 AI 编码 Agent 的 MCP（Model Context Protocol）工具服务。

为什么？

AI 编码 Agent（Claude Code、Cursor、Codex 等）中的内置工具存在一些已知限制：

• 制表符缩进会出错：大模型会输出空格，但你的项目使用制表符。内置的 Edit 工具会原样写入空格，破坏项目的缩进风格。
• 编码损坏：编辑 EUC-KR、Shift-JIS 或 GB18030 文件时，文件会在不提示的情况下转换为 UTF-8，导致旧项目出错。
• 独立工具过多：让 Agent 查找、安装和配置 Redis CLI、MySQL 客户端、SSH 客户端等工具，既繁琐又容易出错。agent-tool 将 40 种工具打包到一个二进制文件中，并通过精简配置按需提供这些工具。
• 缺少逆向工程支持：内置工具无法反汇编二进制文件、检查 PE/ELF 标头、查找函数边界或搜索交叉引用。agent-tool 提供静态二进制分析（反汇编、使用 PDB/DWARF 类型反编译为 C、交叉引用、函数检测）、DAP 调试器和 CheatEngine 风格的内存工具，让你的 Agent 具备完整的逆向工程能力。
• 网络审查：在某些国家，政府级网络过滤会导致普通的 curl/wget 请求失效。agent-tool 默认使用 ECH（加密客户端问候）和 DoH（基于 HTTPS 的 DNS）来绕过这些限制。

agent-tool 通过面向 Agent 的工具解决这些问题：既能保留项目约定，又能控制模型上下文的大小。

支持的 Agent

Claude Code、Codex CLI、Cursor、Windsurf、Cline、Gemini CLI，以及任何兼容 MCP 的 Agent。

默认高效利用大模型上下文

默认的 core 配置仅提供 11 个架构（包括 toolbox），而非全部 40 个。在协议层面的测量中，这将序列化后的工具列表从约 74 KB（full）缩减至 15 KB。若要尽可能减少稳定状态下的上下文占用，请从 --profile core-lite 开始；其 5 个架构约为 6.4 KB，仅提供 read、write、edit、grep 和 toolbox。使用 toolbox(operation="describe", tool="ssh", compact=true, tool_operation="execute") 可仅加载某个操作的字段和必填列表，然后通过 toolbox(operation="call", tool="ssh", arguments={...}) 调用该操作。网关不依赖动态工具列表刷新，因此可与 Codex 等使用固定绑定的客户端配合使用。Describe 会返回与工具及版本绑定的 schema_handle；如果架构仍为最新版本，后续 describe 携带此句柄时会返回简短的“未更改”确认。常用的精简操作包括 SSH 执行、MySQL 查询、文件复制、Windows 截图/剪贴板图像以及静态分析操作。你也可以从 --profile core-lite|coding|remote|analysis|full 开始。

可能较大的文本响应默认限制为 32K 个字符，硬性上限为 128K。截断情况始终会明确显示，支持分页的工具会返回 next_offset 或 next_cursor。本地相对路径会先相对于显式指定的工作区解析，然后再相对于 MCP 客户端根目录解析。

功能

主要改进

智能缩进

大模型通常输出空格，但许多项目使用制表符。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 插入的文本会遵循插入位置所在区域的换行符风格，因此文件其余部分的字节保持不变

防止目录列表占用过多令牌

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 时，运行 agent-tool install claude）
3. 重启 IDE / Agent
4. 完成——精简的核心工具立即可用；toolbox 可按需介绍并调用所有其他工具

或者直接让你的 AI Agent 帮你完成：

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

任何功能完善的 AI 编码 Agent（Claude Code、Codex 等）都能自动完成下载 → 安装 → 重启的完整流程。

推荐：告知 Agent 优先使用 agent-tool

安装后，Agent 可以使用 agent-tool，但可能仍会默认使用内置工具（Read、Edit 等）。若要确保 Agent 优先使用 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.

选择 严格或宽松：

添加位置：

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

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

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

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

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

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 core-lite

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

配置是预设方案：core-lite（读取/写入/编辑/grep/toolbox）、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， 因此无需重复填写主机、用户、密钥和跳转主机字段。配置文件从 OS 用户配置目录下的 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；将其设为 trusted:false，即可在每次调用时显示私有地址警告，而不是每个连接池连接只显示一次。这只影响显示；SSRF 拦截和云元数据保护保持不变。SSH 还支持 quiet、echo_command 和 result_only；最后一个选项会返回以 stdout、stderr 和 exit_code 为核心的精简 JSON。SFTP 支持 quiet、result_only 和 upload_many（最多 100 个文件）。

对于 Windows PowerShell，请使用 powershell_script 而不是 command 传入脚本文本。 SSH 会通过一条简短 PowerShell 命令的标准输入上传唯一的 UTF-8 临时 .ps1 文件， 使用简短的 PowerShell 启动器执行其内容，并在成功或失败后将其删除。使用 -EncodedCommand（或 -enc、-ec、-e）的独立 powershell[.exe] / pwsh[.exe] 命令会在达到 8,000 个 UTF-16 代码单元时自动暂存。安全配置文件、交互、线程单元和执行策略选项会保留；不支持的选项或 shell 后缀需要明确传入 powershell_script。脚本大小上限为 4 MiB。 不要求使用 SFTP，包括连接旧版 Windows SSH 服务器时。

{"operation":"execute","connection_profile":"dev","powershell_script":"Write-Output 'hello'","result_only":true}

准备和前台执行共用 timeout_sec。 后台脚本使用相同的上传和清理流程，然后提供 job_id，用于查询状态、查看尾部输出或取消。 远程启动器会尝试在 finally 中清理；确认执行完成后，也会通过 SSH 进行有时限的清理。取消或连接中断并不能证明远程执行已终止，因此工具会将删除工作留给远程启动器；如果无法确认执行完成或清理情况，则会报告 cleanup_warning。此警告与脚本的退出代码和捕获的输出分开。

本地 SSH 私钥转换

ssh_key 可转换私钥文件，过程中不会通过网络发送其内容，也不会在响应中返回密钥材料。输入格式会自动检测为 PPK、PEM、PKCS#8 或 OpenSSH。输出格式可以是 ppk、pem、pkcs8 或 openssh。

{
  "operation": "convert",
  "input_path": "server.pem",
  "output_path": "server.ppk",
  "output_format": "ppk",
  "input_passphrase": "",
  "output_passphrase": "",
  "overwrite": false
}

PPK 输出使用第 3 版。带密码短语保护的 PPK 输出使用 Argon2id、 AES-256-CBC 和 HMAC-SHA-256；受保护的 OpenSSH 输出使用 OpenSSH 的现代 加密格式。传统 PEM 和 PKCS#8 输出不会加密；如需加密输出，请使用 openssh 或 ppk。新文件的权限模式为 0600；除非设置 overwrite=true，否则不会替换现有文件。

运行时配置

Agent 可以通过 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 .

发布

受保护的 GitHub 工作流会运行测试、构建所有声明的资产、创建 MCPB 和校验和，并验证上传的字节。从干净且已推送的 master 分支开始，触发仅构建的试运行：

.\scripts\release.ps1

试运行成功后，发布 main.go 中声明的版本：

.\scripts\release.ps1 -Publish

该工作流要求在 docs/releases/vVERSION.md 中提供已跟踪的说明。发布操作会创建附注标签和 GitHub Release，然后使用已发布 MCPB 的哈希更新 server.json。当 RepoPlane 将此仓库用作工作区时，也可以通过仓库本地的 catalog/ 清单发现相同的试运行、发布和状态操作。

故障排除

文本乱码（编码问题）

如果韩文、日文或其他非 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 的内置帮助

agent-tool 包含一个 agent_tool_help 工具，Agent 可调用它获取使用指南。当 Agent 遇到编码警告或文本乱码时，可以调用：

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

可用主题：overview、encoding、indentation、tools、troubleshooting

安全

agent-tool 提供强大的系统访问能力（SSH、MySQL、Redis、文件操作、HTTP 请求）。 与 AI 编码 Agent 搭配使用时，请注意提示词注入风险：

• SSRF 防护：无论设置如何，云元数据 IP（169.254.x.x、fe80::/10）始终会被屏蔽。可通过 set_config 按协议配置私有 IP 访问权限（allow_http_private、allow_mysql_private、allow_redis_private、allow_ssh_private）
• DLP（数据丢失防护）：所有出站 HTTP 请求正文都会扫描敏感数据模式（PEM 私钥、AWS 访问密钥、GitHub/GitLab 令牌、Slack 令牌、.env 文件转储），并会在传输前拦截
• 提示词注入警告：允许的私有 IP 连接会显示简短警告；受信任的本地 SSH/SFTP 配置文件则会在每个连接池连接上显示一次
• 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 样本（而非整个文件）以提高内存效率

为确保最高安全性，请在批准 AI Agent 的工具调用前进行审核，尤其是 SSH 命令、发往外部 URL 的 HTTP 请求和数据库查询。

技术栈

• 语言：Go
• MCP SDK：github.com/modelcontextprotocol/go-sdk
• 编码：saintfish/chardet + golang.org/x/text
• 分发：单个二进制文件（交叉编译）
• 反编译器：Gosleigh，内嵌 Ghidra x86/x64 语言规范
• PDB：gopdb（PDB 7.0 读取器和 MSVC 符号反混淆器）

许可证

MIT

反编译器（Gosleigh）及其内嵌的 Ghidra 语言规范采用 Apache License 2.0 许可；Gosleigh 是 Ghidra 反编译器的重新实现，由美国国家安全局开发（https://github.com/NationalSecurityAgency/ghidra）。