registree

Анти-галлюцинационный реестр классов для агентов кодирования, предоставляемый через MCP.

Агенты кодирования угадывают сигнатуры конструкторов по памяти — ключевое слово, которого не существует, обязательный аргумент пропущен — и вы платите за догадку TypeError и циклом отладки. registree устраняет догадки: он обходит ваш код с помощью ast (никогда не импортирует), строит реестр каждого определения класса и предоставляет его как инструменты MCP, чтобы агент мог проверить сигнатуру перед написанием вызова.

Два принципа проходят через каждый инструмент:

• Имена сопоставляются со списками. Дублированное имя класса возвращает все определения; сервер никогда молча не выбирает первое совпадение.

• Честность важнее уверенности. Открытый конструктор (**kwargs, Pydantic extra=/alias=) сообщает о своём контракте как непознаваемом, никогда не как пустой список, притворяющийся ответом.

Как это работает

1. Сканирование — обход AST по вашему дереву исходников извлекает каждый класс: параметры конструктора (включая **kwargs и позиционные), типизированные поля с значениями по умолчанию, наследование, docstring'и. Классификация транзитивна: модель, проходящая через собственный базовый класс вашего проекта, всё равно распознаётся как 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-клиентов является корнем проекта.

• Быстрый старт (любой агент): docs/quickstart.md

• Настройка Claude Code, включая интеграцию хуков: docs/claude-code.md

Совместимость с агентами

Инструменты MCP работают с любым MCP-клиентом — Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Zed, режим агента VS Code Copilot, Gemini CLI и всё остальное, что говорит на MCP через stdio. Структурированный вывод инструментов корректно деградирует для клиентов, которые читают только текстовое содержимое.

Адаптеры хуков (hook-check, hook-regen) нацелены на протокол хуков Claude Code, который может перехватывать ожидающее редактирование файла и передавать модели рекомендательный отзыв до применения записи — детерминированная контрольная точка, которую один только слой MCP не может обеспечить. См. docs/claude-code.md.

Этот протокол распространяется: режим агента VS Code Copilot (Preview) читает тот же формат — те же события, тот же JSON из stdin, даже .claude/settings.json — и адаптеры терпимы к его именам полей в camelCase. Codex CLI и Gemini CLI используют достаточно близкие контракты хуков, так что порты просты. Агенты, чьи системы хуков не могут перехватывать редактирование файлов до применения (Cursor, Windsurf без обратной связи модели, 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 завершается с ненулевым кодом только для дублированных имён, которые являются настоящими проблемами — принятая пара 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 .

Запустите сервер напрямую (говорит на MCP через stdio; завершается по EOF):

uv run registree

Лицензия

MIT