vunit-mcp

MCP(stdio) 서버로, LLM/에이전트가 VUnit(HDL 단위 테스트) 프로젝트를 처음부터 끝까지 구동할 수 있게 합니다: 테스트 목록, 컴파일, 실행, 보고서 및 테스트별 로그까지 검사합니다.

VUnit에는 독립형 CLI가 없고 VUnit.main()은 sys.exit()를 호출하므로, 서버는 vunit을 프로세스 안에서 실행하지 않습니다 — 사람이 실행하는 방식과 똑같이 프로젝트 자체 run.py를 셸 명령으로 실행합니다. 의도적인 예외가 하나 있습니다: vunit_test_dependencies는 "이 테스트를 구현하려면 어떤 파일이 필요할까?"라는 질문에 답하기 위해 프로세스 내 프로젝트 모델을 구축합니다. vunit-hdl은 이 패키지의 필수 의존성이라서 임포트는 항상 가능합니다. 다만 여전히 지연 임포트되어 해당 도구가 호출될 때만 로드됩니다.

로고

후보 로고는 모두 공식 VUnit 배지(파란색 #0c479d, 흰색 링, 굵은 V)를 기반으로 합니다. SVG 원본은 logos/에 있고, PNG는 400×400 미리보기입니다.

Related MCP server: Lupa MCP Server

설정

uv venv .venv
uv pip install -e .            # installs vunit-mcp + mcp + pydantic + vunit-hdl
# compile/run also need a simulator, in the env that runs run.py
# (default: this same venv):
uv pip install ghdl

구성(환경 변수)

MCP 클라이언트 구성(Claude Code)

{
  "mcpServers": {
    "vunit": {
      "command": "/home/sebbe/git/vunit-mcp/.venv/bin/vunit-mcp",
      "env": {
        "VUNIT_MCP_PROJECT_DIR": "/path/to/your/vunit/project"
      }
    }
  }
}

또는 수동 테스트를 위해 MCP Inspector와 함께:

VUNIT_MCP_PROJECT_DIR=/path/to/project npx @modelcontextprotocol/inspector \
  /home/sebbe/git/vunit-mcp/.venv/bin/python -m vunit_mcp

Skill

이 저장소에는 에이전트 스킬인 skills/vunit-mcp/SKILL.md이 포함되어 있습니다. 이 스킬은 LLM에게 도구를 언제, 어떻게 사용할지 알려줍니다: 어느 요청에 어느 도구가 답하는지, 워크플로 레시피("테스트 X가 왜 실패했나?" → vunit_get_test_log), lib.entity[.proc] 테스트 이름 형식, lib.entity[.proc] 설정 등을 다룹니다. 서버 옆에 설치하면 에이전트가 자동으로 사용합니다.

Claude Code

심볼릭 링크는 저장소 체크아웃을 단일 소스 오브 트루스로 유지합니다(정적 설치를 원하면 cp -r로 복사하세요):

# personal — available in every project
ln -s /path/to/vunit-mcp/skills/vunit-mcp ~/.claude/skills/vunit-mcp

# or project-local — available only in that project
mkdir -p <your-project>/.claude/skills
ln -s /path/to/vunit-mcp/skills/vunit-mcp <your-project>/.claude/skills/vunit-mcp

Maki

Maki는 동일한 ~/.claude/skills/ 디렉터리에서 스킬을 불러옵니다:

ln -s /path/to/vunit-mcp/skills/vunit-mcp ~/.claude/skills/vunit-mcp

도구

내보내기 캐시

vunit_export_json와 vunit_test_dependencies는 호출할 때마다 run.py --export-json을 다시 실행하지 않습니다. 내보낸 모델은 해당 입력의 지문과 함께 <project>/.vunit-mcp-cache/export.json에 기록되며, 지문이 일치하는 동안에는 해당 파일을 서비스합니다. 캐시는 다음 경우에 무효화됩니다:

• 등록된 소스 파일 중 하나라도 mtime 또는 크기가 변하거나 파일이 사라진 경우;

• run.py 자체가 변경된 경우(파일을 추가/제거/이동하는 것을 포함);

• VUNIT_MCP_PYTHON, VUNIT_MCP_SIMULATOR, 또는 VUNIT_MCP_EXTRA_ARGS가 변경된 경우.

VUNIT_MCP_FINGERPRINT_EXCLUDE와 일치하는 파일들(파일 이름이나 프로젝트 상대 경로에 대한 쉼표로 구분된 fnmatch globs, 또는 디렉터리 이름)은 첫 번째 규칙에서 제외됩니다. 해당 mtime/size를 추적하지 않으며, 이런 생성/휘발 파일의 재작성은 캐시를 churn하지 않도록 하기 위한 것입니다. 그래도 파일의 이름과 존재 여부는 추적되므로 어떤 파일을 추가하거나 제거하면 평소와 같이 무효화됩니다.

새 내보내기를 강제로 생성하려면 .vunit-mcp-cache/export.json을 삭제하세요. vunit_test_dependencies가 사용하는 인프로세스(프로세스 내부) 프로젝트 모델은 추가로 메모리에 캐시되며, 내보낸 내용을 키로 사용합니다.

내부 뼈대(scaffold)

일부 VUnit 질문은 프로젝트 자체 run.py CLI로는 대답할 수 없습니다 — 예: "이 테스트를 구현하려면 어떤 파일이 필요할까?". 이러한 경우 vunit-mcp는 캐시된 --export-json 모델로부터 프로세스 내 VUnit 프로젝트("the scaffold")를 구축합니다: 실제 VUnit 인스턴스에 프로젝트의 라이브러리와 소스 파일이 등록된 것입니다. 이 인스턴스는 VUnit의 내부 API를 호출할 때만 사용됩니다(현재는 vunit_test_dependencies가 get_implementation_subset을 호출하고, 향후 추가 내부 질의도 여기에 기반하게 됩니다).

이 스캐폴드는 절대 CLI로 실행되지 않습니다: 내보내기 모델은 사용자의 run.py 특정 사항(사용자 정의 옵션? 테스트 속성, 요구사항 …)을 모두 포함하지 않으므로, 컴파일이나 실행을 필요로 하는 것은 반드시 프로젝트 자체 run.py를 통해야 합니다. 프로세스 내 인스턴스는 project_model.InternalProject에 있고 메모리에 캐시되며, 스크래치 디렉터리로 <project>/.vunit-mcp-cache를 사용합니다 (VUnit이 날려버릴 프로젝트의 vunit_out은 절대 사용하지 않습니다).

로그 크기 정책

도구 출력은 LLM 친화적으로 유지하기 위해 의도적으로 한계가 있습니다 — 원시 로그는 전체가 절대 던져지지 않습니다:

• vunit_get_test_log는 기본적으로 마지막 100줄을 반환하고 이를 명시합니다(예: "3421줄 중 마지막 100줄을 보여줍니다"); 더 필요하면 lines를 늘리세요. 명시적인 "full" 읽기도 ~24 KB(파일의 꼬리 부분)로 제한됩니다.

• vunit_compile은 성공 시 마지막 10줄을, 실패 시 오류 줄 문맥(error/fatal/failure 줄 + 문맥 2줄)을 반환합니다.

• 그 밖의 원시 출력 폴백(fail한 run.py, 파싱 불가한 출력)은 꼬리 부분을 남기면서 4 000자까지 잘라냅니다. 끝부분에 오류와 결과 줄이 있기 때문입니다.

• vunit_run_tests / vunit_get_report는 원시 출력 대신 파싱된 JUnit 요약(개수 + 실패한 테스트 이름)을 반환합니다.

• vunit_export_json은 8 000자 미만일 때만 JSON을 인라인합니다; 그 이상은 개수 + 파일/테스트 이름 목록을 반환합니다.

• vunit_list_files / vunit_export_json은 프로젝트 파일만 나열합니다. VUnit의 내장(inner) 라이브러리 소스(설치된 패키지 파일)는 안정적이고 프로젝트의 일부가 아니므로 개수로만 요약됩니다.

개발

uv pip install -e ".[dev]"
uv run pytest tests/          # pure parsers — no simulator required
uv run ruff check src/ tests/
uv run mypy src/vunit_mcp/