This server provides MCP tools to explore and validate Python class definitions and constructor calls in a codebase before an agent writes or refactors code.
get_signature: Get a class's constructor contract (required arguments, accepted keywords, fields, methods, including inherited ones). Duplicated names return every definition; open-ended constructors are reported honestly as unknowable.
verify_snippet: Check a drafted snippet's constructor calls against the registry before writing it, with optional file_path to help disambiguate duplicated names.
search_classes: Find class names by fragment, with case-insensitive and fuzzy fallback, and see definition counts, types, and locations.
list_duplicates: List duplicate class names, split into accepted layered pairs versus genuine smells, and see suggestions/disambiguation guidance.
get_usages: Find every usage of a class — imports, inheritance, instantiations, annotations, references, including via aliases — useful before renames or refactors.
server_info: Check server status, project root, version, registry size, and when the registry was generated.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@registree Verify the UserService constructor signature before I write that call."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An anti-hallucination class registry for coding agents, served over MCP.
Coding agents guess constructor signatures from memory — a keyword that
doesn't exist, a required argument left out — and you pay for the guess in a
TypeError and a debugging round-trip. registree removes the guess: it walks
your codebase with ast (never imports), builds a registry of every class
definition, and serves it as MCP tools so the agent can verify the
signature before writing the call.
Two principles run through every tool:
Names map to lists. A duplicated class name returns every definition; the server never silently picks the first match.
Honesty over confidence. An open-ended constructor (**kwargs,
Pydantic extra=/alias=) reports its contract as unknowable, never as
an empty list pretending to be an answer.
Scan — an AST walk over your source tree extracts every class:
constructor parameters (including **kwargs and positional-only), typed
fields with defaults, inheritance, docstrings. Classification is
transitive: a model routed through your project's own base class is still
recognized as a Pydantic model.
Serve — the registry is cached as JSON and exposed over MCP stdio. It maintains itself: generated on first use, regenerated whenever a scanned file is newer than the cache.
Answer — the agent queries it at the moment of use, instead of guessing.
Related MCP server: codegraph-mcp
tool | use it |
| before writing a constructor or method call — required args, accepted keywords, the class's methods (inherited included), every definition of a duplicated name |
| after drafting code — checks constructor calls against the registry |
| when unsure of the exact class name |
| which names need an explicit import to disambiguate |
| before a rename — every usage, including through import aliases ( |
| server status and registry size |
No install needed with uv — MCP clients launch
it with uvx. For direct CLI use:
uv tool install registree # or: pip install registreeRequires Python 3.12+.
Any MCP client, JSON config form:
{
"mcpServers": {
"registree": {
"command": "uvx",
"args": ["registree", "serve", "--root", "/path/to/your/project"]
}
}
}Omitting --root serves the directory the client launches the server in,
which for most MCP clients is the project root.
Quickstart (any agent): docs/quickstart.md
Claude Code setup, including the hook integration: docs/claude-code.md
The MCP tools work with any MCP client — Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Zed, VS Code Copilot agent mode, Gemini CLI, and anything else that speaks MCP over stdio. Structured tool output degrades gracefully for clients that only read text content.
The hook adapters (hook-check, hook-regen) target Claude Code's hook
protocol, which can intercept a pending file edit — or, opt-in, Python
about to be run through a quoted shell heredoc — and hand the model
advisory feedback before it lands, a deterministic checkpoint the MCP
layer alone can't provide. See docs/claude-code.md.
That protocol is spreading: VS Code Copilot agent mode (Preview) reads the
same format — same events, same stdin JSON, even .claude/settings.json —
and the adapters tolerate its camelCase field names. Codex CLI and Gemini
CLI use close-enough hook contracts that ports are straightforward. Agents
whose hook systems can't intercept file edits pre-application (Cursor,
Windsurf without model feedback, Zed with no hooks yet) still get the full
MCP toolset — the hooks just add a deterministic layer where the platform
supports one.
The same engine is available directly:
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 exits non-zero only for duplicate names that are
genuine smells — the accepted ORM/domain layered pair passes — so it is safe
to wire into CI from day one.
Lives at .registree/registry.json by default — add .registree/ to your
.gitignore. Every command that touches it accepts --registry-path to put
it anywhere else; relative paths are anchored to the project root.
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 .Run the server directly (speaks MCP over stdio; exits on EOF):
uv run registreeConstructor contract AND callable surface for a class — EVERY
definition if the name is duplicated. Call this before writing an
instantiation or a method call: it reports the required arguments, the
accepted keywords, honest null when a constructor is open-ended or
unknowable, and the class's methods (inherited included, each with its
kind and defining class) so a method name can be verified rather than
guessed. When methods_complete is false an ancestor was unresolvable,
so a listed method exists but an unlisted one still might.
Inputs: class_name (required). Returns: note, found, ambiguous, class_name, +1 more
Every place a class name is used — imports, inheritance,
instantiations, annotations, references — including usages through import
aliases (from pkg.db.models import X as XDB). Run this BEFORE a
rename to enumerate what must change.
Inputs: class_name (required), limit, include_tests. Returns: note, total, usages, aliases, +3 more
Duplicate class names, split into accepted layered pairs (ORM model + domain model sharing a name across layers) and genuine smells. Names listed here always need an explicit import to disambiguate.
Inputs: smells_only. Returns: smells, layered, alias_convention, total_duplicate_names
Find classes by name fragment (case-insensitive), falling back to fuzzy matching when nothing contains the fragment. Use this when unsure of the exact class name.
Inputs: query (required), limit. Returns: hits, query, truncated, total_matches
Report server status, the project it serves, and registry size.
Inputs: no named parameters. Returns: name, root, status, version, +2 more
Check a draft snippet's constructor calls against the registry before writing it to a file. Pass the intended file_path when known — imports in the snippet and the target location both help disambiguate duplicated names.
Inputs: code (required), file_path. Returns: ok, note, error, findings
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 6 tools
Each tool targets a clearly distinct concern: server status, class signature lookup, snippet validation, usage enumeration, name search, and duplicate reporting. Even the two validation-adjacent tools differ in scope (single class vs. full snippet), so an agent can reliably pick the right one.
Most tool names follow a clear verb_noun pattern: get_signature, get_usages, search_classes, list_duplicates, verify_snippet. The single outlier is server_info, which lacks a verb and would fit better as get_server_info, but the overall convention is still consistent enough to be predictable.
Six tools is a well-scoped set for a read-only code intelligence registry. Each tool covers a necessary mode of interaction without redundancy or bloat.
The tool surface covers the full workflow: discover classes, resolve duplicates, inspect signatures, validate snippets, and enumerate usages before refactoring. There are no obvious dead ends or missing operations for the stated purpose.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Serves your design system and coding standards to coding agents, so they stop guessing.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
