pyslang-mcp

pyslang-mcp is an alpha-quality, local-first Model Context Protocol server for read-only, compiler-backed analysis of Verilog and SystemVerilog projects using pyslang.

The goal is narrow and explicit: give AI clients structured HDL project context through real parsing and elaboration, not raw text search. This project is a semantic analysis MCP, not a simulator, synthesizer, waveform viewer, or code generator.

[!IMPORTANT] This repo now contains a runnable alpha implementation, but it is not yet a published or broadly hosted MCP product.

✨ Why This Exists

AI coding agents can already search HDL repositories as text. That is useful, but weak. pyslang-mcp exists to answer questions that benefit from a real compiler frontend:

• What design units exist?
• What diagnostics were produced?
• How do modules instantiate each other?
• Where is a symbol declared or referenced?
• How did a filelist, include path, or define actually resolve?

🚦 Status

As of 2026-04-19, the repository contains:

• pyproject.toml packaging metadata
• a FastMCP server under src/pyslang_mcp/
• a stdio entrypoint via python -m pyslang_mcp
• fixture-backed tests for loader, analysis, and MCP call_tool() paths
• an Ubuntu GitHub Actions CI workflow

What is still not done:

• no PyPI release yet
• no MCP Registry publication yet
• no publish automation yet
• no claim of frozen long-term schemas yet
• no promise of full standalone preprocessor fidelity

🧰 Implemented Tools

The current alpha implements these read-only tools:

🔒 Guardrails

• strict project-root scoping; paths outside the declared root are rejected
• stdio transport first
• compact JSON responses instead of giant raw compiler dumps
• hard upper bounds on caller-provided list, hierarchy, file, and excerpt limits
• in-memory caching keyed by normalized project config plus tracked file mtimes
• conservative pyslang_preprocess_files behavior that returns preprocessing metadata and excerpts, not a claimed full preprocessed text stream

🗂️ Current Filelist Support

The implemented .f parser intentionally supports a practical subset:

• raw source file entries
• nested filelists with -f and -F
• include directories with +incdir+..., -I dir, and -Idir
• macro defines with +define+..., -D NAME, and -DNAME

Unsupported directives are reported back in pyslang_parse_filelist output instead of being silently ignored.

🧪 HDL Example Corpus

The repo now includes a generated HDL corpus under examples/hdl with:

• clean reference designs from single modules up to small-IP projects
• intentionally buggy duplicates labeled easy, medium, and hard
• local validation against both pyslang and Verilator

Run the full corpus validator locally:

./.venv/bin/python scripts/validate_hdl_examples.py

CI only runs a small smoke subset so the repository keeps representative HDL coverage without turning the example corpus into the product.

🏃 Quickstart

Local development setup:

cd /path/to/pyslang-mcp
python -m venv .venv
./.venv/bin/pip install -e '.[dev]'

Run

... View full README on GitHub