agentless-mcp

agentless-mcp 是为编码代理提供的无模型结构化机制：一个按需的 tree-sitter 仓库地图，支持任意缩放级别（目录树、代码骨架、行切片），用于缺陷定位的符号与引用查找，以及确定性的补丁解析、语法检查和候选验证。它从不调用语言模型——推理完全由调用方代理完成，而该工具提供的是原本需要临时拼凑的解析、排序、包含与验证能力。它既可作为任何代理都能通过 Bash 调用的 CLI，也可作为基于同一核心的轻量 stdio MCP 服务器。

安装

目前，通过 git 安装：

uv tool install git+https://github.com/dmarlow-personal/agentless-mcp
agentless-mcp warmup

如需 stdio 服务器，请添加 mcp 附加依赖 （uv tool install "agentless-mcp[mcp] @ git+..."）。PyPI 版本将在后续发布； 在此之前，请使用 git URL 作为安装途径。

Related MCP server: agentmako

状态

第 1 至第 6 阶段已完成。CLI 和 stdio MCP 服务器均已上线，共享同一套应用服务：仓库地图、目录树、代码骨架、切片、符号查找、符号展开、扇入分析、位置解析，以及解析图视图——explain（单个符号的分层扇入与扇出）、path（两个符号之间的最短解析路径）和 cycles（模块级导入环）。写入侧——SEARCH/REPLACE 补丁解析、语法检查、工作树隔离应用、候选验证以及等价聚类投票——仅通过 CLI 提供，绝不通过 MCP 暴露。

引用解析是确定性的且不依赖模型：一个名称通过文件自身的导入和自身定义绑定到其候选定义，每条边都携带其背后的离散证据层级（同文件、经导入解析、唯一、仅名称-歧义）。图在每次调用时从当前树在内存中组装——不存储任何相关内容，也没有监视器。

解析默认按需进行；agentless-mcp 会在 $XDG_CACHE_HOME/agentless-mcp/ 下为每个仓库构建一个 SQLite 缓存（绝不会写入被分析的仓库内部），用于保存符号、导入和引用信息，仅针对 sha256 未变化的文件。每次应答都会注明缓存代次及其是否仍属于该仓库自身，而 --no-cache / no_cache: true 可强制进行按需解析。

仓库可以在其根目录通过可选的 .agentless-mcp.json 声明自身默认配置（地图预算、最大文件数、粒度、文档字符串、停用词表补充，以及 test_cmd——该命令仅由 CLI 的 validate 使用，且仅在调用未指定自身命令时生效，并仅在打印之后执行）。该文件属于仓库内容：每个值都经过模式校验并有边界限制，没有键是路径类型的，未知键只会作为响应信封中的警告而非错误出现。

请从 docs/agent-guide.md 开始阅读：这是为调用本工具的代理编写的使用指南。

开发

uv sync --extra mcp
uv run agentless-mcp warmup
uv run pre-commit run --all-files
uv run pytest

uv run pre-commit run --all-files 是质量门禁——它是直接运行 ruff 的严格超集（额外包含 ruff-format、mypy strict、codespell、import-linter 和 deptry）。

Windows 支持

Linux 和 macOS 是受支持的平台：测试套件在这些平台上运行，以下所有保证均在这些平台上得到验证。Windows 仅为文档化的尽力支持——POSIX 专属调用在 Windows 上有对应路径，但没有 Windows CI，且以下内容均未在 Windows 上实际执行过。

覆盖范围：

• 整个读取面。地图、树、骨架、切片、符号查找、扇入和位置解析均为纯解析与路径运算，路径统一通过 pathlib 处理，仓库相对结果统一规范化为正斜杠。

• 标签缓存，包括其单写者纪律。索引锁在 POSIX 上使用 fcntl.flock，在 Windows 上使用 msvcrt.locking，由 util/filelock.py 选择；两者均为非阻塞，因此并发的第二次索引运行会被拒绝而非排队等待。

• 补丁解析、语法检查和等价键。

未覆盖范围，且差异是真实存在的：

• 超时保证较弱。 在 POSIX 上，超时的测试命令会终止其整个进程组（先 SIGTERM，再 SIGKILL），因此其派生的所有子进程都会随之终止。在 Windows 上，子进程以 CREATE_NEW_PROCESS_GROUP 创建，随后仅向领导者发送 terminate()/kill()：孙进程可能在超时后继续存活。如果你的测试命令会启动服务器，请自行做好清理准备。

• 没有 Windows CI。 平台分发逻辑仅在 Linux 上做过单元测试；Windows 系统调用本身未在任何地方实际执行过。

• 任何依赖 git worktree 的功能，其行为与本地 git 一致；但未在 Windows 文件系统上验证过。

安全

该工具对所分析仓库的姿态是只读且路径受限：MCP 面仅暴露只读工具，补丁应用和测试执行均在 CLI 侧进行，并默认在隔离的 git worktree 中运行，仓库内部绝不写入任何缓存或临时状态。

有一个供应链方面的注意事项需要 upfront 说明。语法解析器来自 tree-sitter-language-pack，该包在首次使用时下载预编译的平台捆绑包。这些捆绑包会对照发布清单进行 SHA-256 校验，校验失败即为硬失败——但清单本身（parsers.json）仅依赖 HTTPS 信任，而非密码学签名。我们通过精确的发布版本固定来接受这一风险：tree-sitter 和 tree-sitter-language-pack 作为整体固定版本，仅通过经过审查的版本升级才会变更。下载仅限于显式的预热步骤，且清单 URL 和缓存目录均可覆盖，以支持镜像或离线安装。完整审计请参见 docs/supply-chain-audit.md。

许可证

MIT — 参见 LICENSE。

本包的某些部分衍生自 Agentless（MIT，版权所有 2024 OpenAutoCoder）：行切片原语、位置语法、SEARCH/REPLACE 编辑格式及其解析器，以及候选过滤阶梯和 投票键。NOTICE 列出了每个文件的来源，并复制了上游 许可证。