pyslang-mcp

pyslang-mcp

pyslang-mcp is a local Model Context Protocol server that gives AI agentscompiler-backed, read-only context for Verilog and SystemVerilog projects.

It wraps pyslang so an MCP client can askquestions against parsed and elaborated HDL instead of plain text:

• What modules, interfaces, and packages are in this filelist?
• What diagnostics does the compiler frontend report?
• What is the instance hierarchy below this top?
• Where is this symbol declared or referenced?
• Did my include paths, defines, and nested .f files resolve as expected?

This is not a simulator, synthesizer, waveform viewer, linter replacement, orRTL refactoring tool. It is a small semantic analysis service for local HDLcheckouts.

[!NOTE]The project is currently early-stage and published onPyPI and theMCP Registry forlocal stdio use.

Why ASIC And EDA Engineers Might Care

Most AI coding tools are good at searching text. HDL usually needs more thanthat.

In real projects, useful answers often depend on filelists, packages, includes,defines, generate blocks, and hierarchy. pyslang-mcp gives an agent a compactcompiler-backed view of that structure, while keeping the server read-only andscoped to a project root you provide.

Good fits:

• triaging parse and semantic diagnostics before asking an agent to reasonabout RTL
• checking what a .f file expands to
• listing design units in a block or small IP
• finding a declaration without chasing comments and stale grep hits
• getting hierarchy and port-connection context for review/debug prompts
• giving workflow agents HDL context without handing them an EDA runtime

Quickstart

Install the package:

pip install pyslang-mcp

Run the local stdio server:

pyslang-mcp

For contributor setup, clone the repo and install it in editable mode:

git clone https://github.com/ariklapid/pyslang-mcp.git
cd pyslang-mcp
python -m venv .venv
./.venv/bin/pip install -e '.[dev]'

Run the checkout stdio server:

./.venv/bin/python -m pyslang_mcp

The installed console script works too:

./.venv/bin/pyslang-mcp

Run tests:

./.venv/bin/pytest

MCP Client Config

Use local stdio. The MCP client should launch the server on the same machine,VM, or dev container that can see your RTL checkout.

{
  "mcpServers": {
    "pyslang-mcp": {
      "command": "pyslang-mcp",
      "args": []
    }
  }
}

For editable checkout installs, point the command at the checkout virtualenvironment instead:

{
  "mcpServers": {
    "pyslang-mcp": {
      "command": "/absolute/path/to/pyslang-mcp/.venv/bin/python",
      "args": ["-m", "pyslang_mcp"]
    }
  }
}

Tool calls must provide a project_root. Source paths, filelists, and includedirectories may be absolute or relative, but they must stay under that root.

Minimal Tool Payloads

Analyze explicit files:

{
  "project_root": "/path/to/rtl-project",
  "files": ["rtl/pkg.sv", "rtl/top.sv"],
  "include_dirs": ["include"],
  "defines": {
    "WIDTH": "32"
  },
  "top_modules": ["top"]
}

Analyze a filelist:

{
  "project_root": "/path/to/rtl-project",
  "filelist": "compile/project.f"
}

Find a symbol:

{
  "project_root": "/path/to/rtl-project",
  "filelist": "compile/project.f",
  "query": "payload",
  "match_mode": "exact",
  "include_references": true
}

Tools

Typical flow:

1. Start with pyslang_parse_filelist or pyslang_parse_files.
2. Run pyslang_get_diagnostics.
3. Use pyslang_list_design_units to see what the compiler frontend found.
4. Use pyslang_describe_design_unit, pyslang_get_hierarchy, orpyslang_find_symbol for the actual review/debug question.

Filelist Support

The current parser intentionally supports a practical subset used by many RTLflows:

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

Unsupported filelist tokens are reported in the tool output instead of beingsilently ignored.

Example Agent Prompts

Use this server when compiler-backed context matters:

• "Parse compile/project.f with +define+DEBUG and group diagnostics bysource file."
• "List every design unit in this project and identify the likely top modules."
• "From top, show the instance hierarchy down to depth 4."
• "Describe module axi_dma_top: ports, child instances, and declared names."
• "Find the declaration and references for payload_valid."
• "Confirm whether legacy_widget is instantiated anywhere the elaboratorsees it."
• "Show the resolved files, include dirs, defines, and unsupported entries fromthis filelist."

For single-line questions, comments, naming searches, or partial/incompletesource sets, regular rg, editor search, or direct file reading is usuallyfaster and clearer.

Guardrails

• Read-only MCP tools. No RTL edits, formatting, simulation, or synthesis.
• Strict project-root scoping. Paths outside project_root are rejected.
• Compact JSON responses with truncation metadata for large result sets.
• Process-local cache keyed by project config and tracked file mtimes.
• pyslang_preprocess_files is summary-oriented. It returns preprocessingmetadata and source excerpts, not a guaranteed full standalone preprocessedstream.
• streamable-http remains experimental. The internal MaaS path wraps it witha bearer token for single-server use, but it is not a complete productionhosted security boundary by itself.

Remote MaaS Direction

Remote MaaS is planned as two separate tracks, not as one generic hosted mode:

• Plan A: public OSS MaaS. A convenience/demo service for publicopen-source HDL repositories. This is not suitable for proprietary orconfidential RTL.
• Plan B: internal MaaS. A self-hosted deployment pattern for companies torun inside their own network, close to internal repositories, auth, logging,and security controls.

Start with the internal MaaS quickstartfor a single internal server. See REMOTE_DEPLOYMENT.mdfor the full Plan A / Plan B split.

Docker Compose is the recommended bring-up path because it avoids Python setupissues and mounts the RTL checkout read-only. Docker is not required; thequickstart also includes a native Python path for corporate servers wherecontainers are not available.

HDL Example Corpus

The repo includes generated HDL examples underexamples/hdl:

• clean reference projects from single modules to small IP-style examples
• intentionally buggy variants labeled easy, medium, and hard
• local validation hooks for both pyslang and verilator --lint-only

Run the full corpus validator:

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

Run the CI smoke subset:

./.venv/bin/python scripts/validate_hdl_examples.py --smoke-only

Using With Broader RTL Skills

If your agent environment already has a broad RTL skill such asrtl-analysis, rtl-audit, or llm-based-verilog-analysis, usepyslang-verilog-context as the fine-grained compiler-evidence layer beneaththat broader skill.

Recommended setup:

1. Configure the pyslang-mcp server in your MCP client so the agent can callthe read-only pyslang_* tools.
2. Install or copy the pyslang-verilog-context skill fromskills/pyslang-verilog-context.
3. Add a delegation note like this to your broader RTL skill:

For Verilog/SystemVerilog tasks, use $pyslang-verilog-context before making
claims about diagnostics, design units, ports, hierarchy, declarations,
references, includes, defines, or filelist behavior. Treat its output as
compiler frontend evidence only. Do not present it as simulation, synthesis,
timing, CDC/RDC, formal, or full lint signoff.

The intended flow is:

user RTL request
  -> broad RTL analysis/audit skill
  -> pyslang-verilog-context
  -> pyslang-mcp compiler-backed evidence
  -> final answer with evidence and limitations

This keeps high-level RTL review policy in the broad skill while groundingVerilog/SystemVerilog structure, diagnostics, hierarchy, symbols, includes, andfilelists in pyslang.

Evaluation Benchmarks

The repo includes a pyslang-verilog-context skill eval suite underskills/pyslang-verilog-context/evalsand comparison reports under reports/. The current benchmarkcompares three local evidence modes:

• text/no skill: source and filelist text heuristics only
• MCP/no skill: targeted pyslang-mcp tool calls
• skill + MCP: pyslang-verilog-context sequencing with pyslang-mcp

Latest local result from 2026-05-23:

The benchmark mixes deterministic repo-local HDL fixtures with real public RTLsource files. The local fixtures exercise targeted behaviors such as filelists,hierarchy, symbols, diagnostics, clean-frontend functional bugs, and RTL codingand bug-audit discipline. The real public RTL cases use source files fromlowrisc-ibex,pulp-common-cells, verilog-axis, pulp-axi,pulp-register-interface, and picorv32. They exercise frontend diagnosticstatus, design-unit inventory, and first-unit port counts on real source files.See docs/evaluation-benchmarks.md for theprompt/task shapes and MCP functions used.

Verification commands used for the reported run:

./.venv/bin/python skills/pyslang-verilog-context/scripts/validate_eval_fixtures.py
./.venv/bin/python -m pytest
./.venv/bin/python skills/pyslang-verilog-context/scripts/run_comparison_evals.py
./.venv/bin/python scripts/run_mcp_comparison.py --output-dir reports/mcp_comparison_comprehensive_20260523
./.venv/bin/python reports/real_examples_75/run_real75_comparison.py
./.venv/bin/python -m py_compile reports/real_examples_75/run_real75_comparison.py

These are deterministic scalar harnesses, not blind autonomous LLM-judge runs.pyslang-mcp evidence remains frontend/compiler context only, not simulation,synthesis, CDC/RDC, timing, formal, or full lint signoff.

Documentation-only eval/report updates do not require a PyPI release. A PyPIrelease is warranted when package code, public tool behavior, schemas, runtimedependencies, CLI behavior, or user-facing install/runtime docs change in a waypublished users need.

Project Status

Implemented:

• FastMCP stdio server
• CLI entrypoint via python -m pyslang_mcp and pyslang-mcp
• project loader with root checks and .f parsing
• pyslang-backed diagnostics, design-unit listing, hierarchy, symbol lookup,syntax summaries, and project summaries
• bounded in-memory cache
• fixture-backed tests and Ubuntu CI for Python 3.11 and 3.12
• package smoke CI from a built wheel
• manual PyPI Trusted Publishing release workflow with release-gate tests
• PyPI package: pyslang-mcp
• MCP Registry entry:io.github.ariklapid/pyslang-mcp
• internal MaaS bring-up artifacts: Dockerfile, Docker Compose config, nativePython fallback instructions, systemd template, bearer-token HTTP option, anda single-server quickstart

Not done yet:

• schema freeze for a more mature API-stable release
• broad platform validation beyond the current Linux-focused CI path
• production MaaS hardening for broad team use: SSO, multi-workspace routing,Kubernetes deployment, source-safe metrics, and reverse-proxy examples

Development

Useful commands:

./.venv/bin/ruff check .
./.venv/bin/pyright
./.venv/bin/pytest

Architecture and contribution docs:

• docs/architecture.md
• docs/internal-maas-quickstart.md
• REMOTE_DEPLOYMENT.md
• docs/mcp-registry.md
• CONTRIBUTING.md

License

Apache-2.0. See LICENSE.