registree

一个为编码智能体提供的防幻觉类注册表，通过 MCP 提供服务。

编码智能体会凭记忆猜测构造函数签名——一个不存在的关键字、一个漏掉的必填参数——而你要为一个 TypeError 和一次调试往返承担猜测的代价。registree 消除了猜测：它用 ast 遍历你的代码库（从不 import），构建一个包含所有类定义的注册表，并将其作为 MCP 工具提供，让智能体可以在编写调用之前验证签名。

每个工具都贯穿两条原则：

• 名称映射到列表。 重复的类名会返回所有定义；服务器永远不会静默选取第一个匹配项。

• 诚实优于自信。 开放式构造函数（**kwargs、Pydantic 的 extra=/alias=）会将其契约报告为不可知，而绝不会以伪装成答案的空列表来呈现。

工作原理

1. 扫描 — 对源码树进行 AST 遍历，提取每个类：构造函数参数（包括 **kwargs 和仅限位置参数）、带默认值的类型化字段、继承、文档字符串。分类具有传递性：即使模型经由你自己项目的基类传递，仍然会被识别为 Pydantic 模型。

2. 服务 — 注册表缓存为 JSON，并通过 MCP stdio 暴露。它能够自我维护：首次使用生成后，只要有任何被扫描的文件比缓存更新，就会重新生成。

3. 回答 — 智能体在使用时查询注册表，而不是凭记忆猜测。

Related MCP server: Lore MCP Server

MCP 工具

安装

使用 uv 无需安装——MCP 客户端会通过 uvx 启动它。如需直接使用 CLI：

uv tool install registree   # or: pip install registree

要求 Python 3.12+。

接入你的智能体

任意 MCP 客户端，JSON 配置格式：

{
  "mcpServers": {
    "registree": {
      "command": "uvx",
      "args": ["registree", "serve", "--root", "/path/to/your/project"]
    }
  }
}

省略 --root 时，会将客户端启动服务器所在目录作为服务目录 ，对大多数 MCP 客户端来说就是项目根目录。

• 快速开始（任何 Agent）：docs/quickstart.md

• Claude Code 配置，包括钩子集成：docs/claude-code.md

智能体兼容性

MCP 工具适用于任何 MCP 客户端——Claude Code、Claude Desktop、Cursor、Windsurf、Cline、Zed、VS Code Copilot agent mode、Gemini CLI，以及其他任何通过 stdio 说 MCP 的客户端。结构化工具输出对于只读取文本内容的客户端来说会优雅地降级。

Hook 适配器（hook-check、hook-regen）面向 Claude Code 的 hook 协议，能够拦截尚未写入的文件编辑，并在写入落地之前向模型提供参考性反馈——这是 MCP 层单独无法提供的确定性检查点。请参阅 docs/claude-code.md。

这种协议正在普及：VS Code Copilot agent mode（Preview）读取相同的格式——相同的事件、相同的 stdin JSON，甚至相同的 .claude/settings.json——而适配器可以兼容其驼峰式命名字段。Codex CLI 和 Gemini CLI 的 hook 契约已经足够接近，因此移植会非常直接。对于那些 hook 系统无法在文件编辑应用前拦截的智能体（Cursor、没有模型反馈的 Windsurf、目前还没有 hook 的 Zed），仍然可以使用完整的 MCP 工具集——钩子只是在该平台支持的基础上额外增加了一层确定性检查。

CLI

同样的引擎也可以直接使用：

registree gen                 # build the registry
registree conflicts           # duplicate names: accepted layering vs smells
registree usages SomeClass    # every usage, alias-aware — run before renames
registree hook-check          # Claude Code PreToolUse adapter (advisory)
registree hook-regen          # Claude Code PostToolUse adapter (debounced)

registree conflicts 只对真正有意义 duplicate 的名称返回非零退出码——公认的 ORM/领域分层组合会通过——所以从第一天起就可以安全接入 CI。

注册表缓存

默认位于 .registree/registry.json —— 将 .registree/ 添加到你的 .gitignore。凡是访问该文件的命令都接受 --registry-path 参数，可以将其放在其他任何位置；相对路径会以项目根目录为基准。

开发

uv sync            # creates .venv, installs deps + dev tools
uv run pytest      # includes a real stdio JSON-RPC handshake test
uv run mypy src tests
uv run ruff check .
uv run black --check .

直接运行服务器（通过 stdio 说 MCP，按 EOF 退出）：

uv run registree

许可证

MIT