vhdl-rag-mcp

조직의 VHDL 코드, VHDL 관련 문서, 그리고 일반 소스 코드(C/C++, Python, ...)에 대한 고품질 의미론적 검색을 코딩 에이전트에 제공하는 MCP(Model Context Protocol) 서버입니다. 모든 것은 상호 참조되며, 정확한 소스 출처가 함께 제공됩니다.

stdio를 통해 uvx vhdl-rag-mcp로 실행됩니다. 외부 서비스가 필요하지 않습니다. Qdrant는 임베디드로 실행되고, 임베딩 모델은 로컬에서 실행됩니다(ONNX via FastEmbed).

기능

• 세 가지 인덱스 도메인, 하나의 서버. VHDL 소스, 문서(Markdown/reST/text), 일반 코드(C/C++, Python, ...)는 각각 세 개의 Qdrant 컬렉션에 저장되며, 각 청크에는 밀집(jina v2) 및 희소(BM25) 벡터가 하나씩 포함됩니다.

• 하이브리드 검색. 모든 쿼리는 Qdrant 고유의 하이브리드(밀집 + 희소, RRF 융합) 쿼리로 실행됩니다. 의미적 유사성 및 정확한 식별자 일치가 한 번의 호출로 이루어집니다. rst_n을 물으면 그 결과를 얻을 수 있습니다.

• VHDL 인식 청킹. VHDL 파일은 vhdl_ls 언어 서버(documentSymbol, 정확한 줄 범위 포함)를 사용하여 구성 단위(entity, architecture, process, package, function, component)별로 청킹됩니다. 구문 오류가 있는 파일은 구조 기반 줄 스캐너로 대체되고, 마지막으로 전체 파일 단위로 처리되므로 어떤 VHDL도 유실되지 않습니다.

• 구조 인식 청킹. 문서는 헤딩 섹션별로 청킹됩니다. 일반 코드는 tree-sitter(문법이 있는 모든 언어)로 최상위 함수/클래스 단위로 청킹되며, 포함되지 않은 최상위 코드는 파일 범위 갭 청크로 채워집니다.

• 교차 참조. 모든 청크 페이로드에는 해당 청크가 정의하거나 참조하는 식별자(symbols)가 저장됩니다. 검색 도구는 symbols 필터를 지원하여 지정된 식별자를 참조하는 청크만 반환하며, 이를 통해 문서 ↔ VHDL ↔ 테스트 코드를 연결합니다(예: fifo_write를 다루는 모든 VHDL 프로세스와 C 함수 찾기).

• 우선순위 인식 랭킹. 저장소는 카테고리(golden > approved > project > legacy) 또는 명시적 priority 0–100을 가지며, 융합 점수에 제한된 가중치를 적용합니다. 이를 통해 참조 저장소가 관련성 동점에서 우위를 차지할 수는 있으나, 실제 유사도를 묻어두지는 않습니다.

• 정확한 소스 출처. 모든 결과에는 저장소, 파일, 줄 범위, 커밋이 명시됩니다. get_source는 동기화된 작업 트리에서 현재 파일(또는 줄 범위)의 정확한 내용을 반환합니다.

• 점진적·자기 유지형 인덱스. 저장소는 Git(clone/fetch/diff)에서 동기화됩니다. 변경된 파일만 다시 청킹 및 임베딩됩니다. 백그라운드 작업은 sync_interval초마다 동기화를 실행하며, 도구를 통해 언제든지 강제 동기화 또는 전체 재구축을 실행할 수 있습니다.

• 명활한 오류 처리(Graceful degradation). 오류는 저장소별로 차단되어 상태에 기록됩니다. 하나의 저장소가 고장나도 다른 저장소나 서버 실행에는 영향이 없습니다.

• 프로토콜 전용 표준 출력. 모든 로깅은 stderr와 회전 로그 파일로 전송되므로, 어떤 MCP 호스트에서도 안전하게 실행할 수 있습니다.

Related MCP server: PAMPA

설치

요구 사항:

• uv (uvx용), Python ≥ 3.12

• Git (개인 저장소용 인증/SSH 설정 포함)

• vhdl_ls 바이너리(VHDL 저장소에서만 필요): https://vhdl-lang.org/에서 릴리스를 설치하여 vhdl_ls가 PATH에 있거나 vhdl_ls_path가 사용하는 바이너리를 지정하세요. 바이너리와 함께 배포되는 vhdl_libraries 디렉터리는 자동 감지됩니다.

$ uvx vhdl-rag-mcp --help
# (the server speaks MCP over stdio; --help is not a flag — see "Usage")

첫 시작 시 서버는 데이터 디렉토리를 생성하고, 임베딩 모델을 다운로드하며(jina v2 base-code + base-en, 각각 수십 MB, 최초 1회), 설정된 모든 저장소를 초기 동기화합니다.

설정

구성 파일: ~/.config/vhdl-rag/config.toml (파일이 없으면 처음 실행 때 주석 템플릿이 생성됩니다).

data_dir = "~/.local/share/vhdl-rag"   # all state lives here
sync_interval = 300                    # seconds between periodic syncs
vhdl_ls_path = "vhdl_ls"               # binary on PATH or full path
log_level = "INFO"

[embeddings]
vhdl_model = "jinaai/jina-embeddings-v2-base-code"  # per-collection dense models
docs_model = "jinaai/jina-embeddings-v2-base-en"
code_model = "jinaai/jina-embeddings-v2-base-code"
sparse_model = "Qdrant/bm25"           # one shared sparse model

[qdrant]
mode = "local"                         # embedded (default) — or "server" with url
# url = "http://qdrant:6333"

[[repositories]]
name = "company-standards"             # unique, [A-Za-z0-9._-]
url = "git@github.com:company/vhdl-standards.git"
ref = "main"                           # branch (tracked on every sync),
                                       # tag, or commit SHA (pinned)
category = "golden"                    # golden | approved | project | legacy
priority = 100                         # optional 0-100 (defaults by category:
                                       # golden=100, approved=90, project=70, legacy=20)
# domains = ["vhdl", "docs", "code"]   # which domains to index (default: all)
# exclude = ["sim", "build/*", "*.log"]# glob path excludes ('*' crosses '/');
                                       # wildcard-free patterns exclude the subtree

참고:

• ref: 동기화 때마다 브랜칠 이름을 fetch하고 저장합니다. 태그 혹 commit SHA는 사용자는 저장소를 고정합니다(정확히 40자리 16진수 SHA면 네트워크 fetch를 완전히 건너니다).

• 저장보별 도메인/제외 (정도 설정: 각 저장소가 어떤 도메인에 속하는 제어합니다. 예: domains = ["vhdl"]은 순수 IP 저장소를, exclude = ["sim"]은 시뮬레이션 전용 파일을 무시합니다.

• 임베딩 모델 변경은 밀집 벡터의 차원을 바꿉니다. 서버는 인덱스를 주지 않고 뚜렷한 경고 메시지와 함께 명확히 실패합니다(단, 컬렉션 또는 data_dir을 삭제하고 재인덱싱하면 해제됩니다).

사용법

서버 실행

$ uvx vhdl-rag-mcp

호스트가 연결을 닫기 전까지 stdio를 통해 MCP를 제공합니다. 백그라운드 작업이 sync_interval초마다 모든 저장소를 동기화합니다. 단일 인스턴스 잠금(data_dir/서버.lock)으로 두 서버가 같은 데이터 디렉토리를 동시에 사용하지 못하게 합니다.

MCP 클라이언트 등록

Claude Code:

$ claude mcp add vhdl-rag-mcp -- uvx vhdl-rag-mcp

Maki(TOML 설정 — 정확한 테이블 이름은 사용 중인 Maki 버전의 문서를 확인하세요):

[mcp_servers.vhdl_rag_mcp]
command = "uvx"
args = ["vhdl-rag-mcp"]

도구

모든 검색 도구는 선택적 repo(repository)(이름) 및 category(golden/approved/project/legacy) 필터, 그리고 symbols: list[str]를 지원합니다. 하나라도 주어진 식별자를 참조하는 청크로 제합됩니다. 결과는 소스 출처와 함께 마크다운 점수, 참조 식별자를 담은 마크다운으로 렌더링되고, 도메인별로 코드 블록이 구분됩니다.

예시 어시트 흐름:

1. search_knowledge("asynchronous reset conventions") → 리셋에 대한 문서 섹션과 실제 리셋을 구현한 VHDL 프로세스.

2. search_vhdl("reset", symbols=["rst_n"]) → rst_n을 참조한 모든 VHDL 청크.

3. get_source("company-standards", "rtl/reset_ctrl.vhd", 12, 40) → 복사하기에 딱 좋은 정확한 로우 범위 내용.

운영

• 데이터 디렉터리(data_dir):. Qdrant 컬렉션, 저장소별 Git 워킹 트루트(<name>/) 상태(state/repositories.json), 로그 파일(logs/vvdh-rag-mcp.log) 및 잠금 파일을 포함합니다. 이 텍터를 삭제하면 인덱스가 초기화됩니다.

• 상태 및 재시도: 저장소의 indexed_commit은 해당 저장소의 인덱스 업데이트가 완전히 성공한 경우에만 진행됩니다. 동기화 실패 시 이전 커밋이 유지되어 다음 동기화에서 동일한 diff를 다시 시도합니다. last_sync_error는 repository_status에서 확인할 수 있습니다.

• 설정에서 저장소 제거: 다음 시작 시 서버가 상태 파일 사용해서 해당 저장소의 모든 청크와 저장소 상태를 자動으로 삭제합니다.

• 로그: stderr 및 프로에서 logs/vhdl-rag-mcp.log(롤링, 3×5 MB)로 기록됩니다. log_level = "DEBUG" 설정하면 LSP/git/임베딩 상세 로그를 볼 수 있습니다.

개발

$ uv sync
$ uv run ruff format -q . && uv run ruff check .   # format + lint
$ uv run mypy src                                   # strict types
$ uv run pytest -q                                  # offline test suite

테스트 스윗트는 완전히 오프라인으로 동작합니다. 로컬 file:// git 리모트, 가짜 LSP 서버, 임베딩 프로바이더를 사용합니다. 실제 배이너리 테스트 하나는 VHDL_LS_TEST_BIN 환결 변수에 게이트되어 있습니...

Layout:

src/vhdl_rag_mcp/
  config.py        typed config (pydantic) + default template
  state.py         atomic repository sync state
  git_manager.py   async clone/fetch/checkout + incremental SyncPlan
  routing.py       extension -> domain classification (+domains/excludes)
  lsp/client.py    vhdl_ls LSP client (handshake, quiet-wait, symbols)
  embeddings/      FastEmbed dense/sparse providers (per-collection + shared)
  vector_store.py  Qdrant wrapper: hybrid RRF query, payload filters
  indexing/        vhdl (LSP-primary), docs (sections), code (tree-sitter),
                   pipeline (incremental sync driver)
  retrieval.py     search service: fusion, priority bonus, source access
  server.py        FastMCP tools + startup + periodic sync + lock