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 클라이언트에서 이는 프로젝트 루트입니다.

• 빠른 시작 (모든 에이전트): docs/quickstart.md

• Claude Code 설정 (훅 통합 포함): docs/claude-code.md

에이전트 호환성

MCP 도구는 모든 MCP 클라이언트에서 작동합니다 — Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Zed, VS Code Copilot 에이전트 모드, Gemini CLI, 그리고 stdio를 통해 MCP를 사용하는 모든 도구. 구조화된 도구 출력은 텍스트 콘텐츠만 읽는 클라이언트에서도 우아하게 저하됩니다.

훅 어댑터(hook-check, hook-regen)는 Claude Code의 훅 프로토콜을 대상으로 하며, 대기 중인 파일 편집을 가로채고 쓰기가 적용되기 전에 모델에 조언 피드백을 전달할 수 있습니다 — MCP 계층만으로는 제공할 수 없는 결정적 체크포인트입니다. docs/claude-code.md를 참조하세요.

이 프로토콜은 확산되고 있습니다: VS Code Copilot 에이전트 모드(미리 보기)는 동일한 형식을 읽습니다 — 동일한 이벤트, 동일한 stdin JSON, 심지어 .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는 진짜 문제가 되는 중복 이름에 대해서만 0이 아닌 종료 코드를 반환합니다 — 허용되는 ORM/도메인 계층 쌍은 통과합니다 — 따라서 첫날부터 CI에 연결해도 안전합니다.

레지스트리 캐시

기본적으로 .registree/registry.json에 위치합니다 — .gitignore에 .registree/를 추가하세요. 이를 다루는 모든 명령은 --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