registree

Un registro de clases anti-alucinaciones para agentes de codificación, servido a través de MCP.

Los agentes de codificación adivinan las firmas de los constructores de memoria — una palabra clave que no existe, un argumento obligatorio omitido — y pagas por la suposición con un TypeError y un viaje de ida y vuelta de depuración. registree elimina la suposición: recorre tu código con ast (nunca importa), construye un registro de cada definición de clase y lo sirve como herramientas MCP para que el agente pueda verificar la firma antes de escribir la llamada.

Dos principios atraviesan todas las herramientas:

• Los nombres se asignan a listas. Un nombre de clase duplicado devuelve todas las definiciones; el servidor nunca elige silenciosamente la primera coincidencia.

• Honestidad sobre confianza. Un constructor abierto (**kwargs, extra=/alias= de Pydantic) informa su contrato como incognoscible, nunca como una lista vacía que pretende ser una respuesta.

Cómo funciona

1. Escaneo — un recorrido AST sobre tu árbol de fuentes extrae cada clase: parámetros del constructor (incluyendo **kwargs y solo posicionales), campos tipados con valores predeterminados, herencia, docstrings. La clasificación es transitiva: un modelo enrutado a través de la clase base de tu propio proyecto sigue siendo reconocido como un modelo Pydantic.

2. Servir — el registro se almacena en caché como JSON y se expone a través de MCP stdio. Se mantiene solo: se genera en el primer uso, se regenera cuando un archivo escaneado es más nuevo que la caché.

3. Responder — el agente lo consulta en el momento de uso, en lugar de adivinar.

Related MCP server: Lore MCP Server

Herramientas MCP

Instalación

No se necesita instalación con uv — los clientes MCP lo lanzan con uvx. Para uso directo desde CLI:

uv tool install registree   # or: pip install registree

Requiere Python 3.12+.

Conéctalo a tu agente

Cualquier cliente MCP, formato de configuración JSON:

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

Omitir --root sirve el directorio en el que el cliente lanza el servidor, que para la mayoría de los clientes MCP es la raíz del proyecto.

• Inicio rápido (cualquier agente): docs/quickstart.md

• Configuración de Claude Code, incluida la integración de hooks: docs/claude-code.md

Compatibilidad con agentes

Las herramientas MCP funcionan con cualquier cliente MCP — Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Zed, modo agente de VS Code Copilot, Gemini CLI y cualquier otra cosa que hable MCP sobre stdio. La salida estructurada de las herramientas se degrada con elegancia para clientes que solo leen contenido de texto.

Los adaptadores de hooks (hook-check, hook-regen) se dirigen al protocolo de hooks de Claude Code, que puede interceptar una edición de archivo pendiente y dar al modelo comentarios de asesoramiento antes de que se aplique la escritura — un punto de control determinista que la capa MCP por sí sola no puede proporcionar. Ver docs/claude-code.md.

Ese protocolo se está extendiendo: el modo agente de VS Code Copilot (Vista previa) lee el mismo formato — mismos eventos, mismo JSON de stdin, incluso .claude/settings.json — y los adaptadores toleran sus nombres de campo en camelCase. Codex CLI y Gemini CLI usan contratos de hooks lo suficientemente cercanos como para que los puertos sean sencillos. Los agentes cuyos sistemas de hooks no pueden interceptar ediciones de archivos antes de su aplicación (Cursor, Windsurf sin comentarios del modelo, Zed sin hooks todavía) aún obtienen el conjunto completo de herramientas MCP — los hooks solo añaden una capa determinista donde la plataforma la soporta.

CLI

El mismo motor está disponible directamente:

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 sale con código distinto de cero solo para nombres duplicados que son olores genuinos — el par aceptado de capas ORM/dominio pasa — por lo que es seguro conectarlo a CI desde el primer día.

La caché del registro

Vive en .registree/registry.json por defecto — añade .registree/ a tu .gitignore. Cada comando que lo toca acepta --registry-path para ponerlo en cualquier otro lugar; las rutas relativas se anclan a la raíz del proyecto.

Desarrollo

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 .

Ejecuta el servidor directamente (habla MCP sobre stdio; sale al recibir EOF):

uv run registree

Licencia

MIT