pyslang-mcp

pyslang-mcp

pyslang-mcp 是一个本地 Model Context Protocol 服务，为 AI Agent 提供基于编译器的只读上下文，用于 Verilog 和 SystemVerilog 项目。

它封装了 pyslang，使 MCP 客户端能够针对经过解析和展开的 HDL 提问，而不只是查看纯文本：

• 这个文件列表中有哪些模块、接口和包？
• 编译器前端报告了哪些诊断信息？
• 这个顶层模块下的实例层次结构是什么？
• 在哪里声明或引用了这个符号？
• 我的 include 路径、宏定义和嵌套 .f 文件是否按预期解析？

它不是仿真器、综合器、波形查看器、代码检查工具的替代品，也不是 RTL 重构工具。它是一个面向本地 HDL 代码库的小型语义分析服务。

只读边界是有意为之。它能让服务端不会产生副作用，缩小受 IP 保护工作区中的影响范围，并使其在本地和 CI 环境中更安全。

我们决定让 pyslang-mcp 保持只读。LLM 负责实际的 RTL 编码，而 pyslang-mcp 则充当编译／展开支持的读取器、检查器和讲解器，用于分析现有代码。换句话说，模型负责起草 RTL，MCP 服务负责验证编译器前端所看到的内容。

说明

项目目前处于早期阶段，已发布到 PyPI 和 MCP Registry，供本地 stdio 使用。

ASIC 和 EDA 工程师为何可能关注

大多数 AI 编码工具都擅长搜索文本，而 HDL 通常需要更多信息。

在实际项目中，想要获得有用的答案，通常需要了解文件列表、包、include、宏定义、生成块和层次结构。pyslang-mcp 为 Agent 提供这种结构的精简编译器视图，同时保持服务只读，并将范围限定在你提供的项目根目录内。

适用场景：

• 在让 Agent 分析 RTL 之前，对解析和语义诊断进行分类
• 检查 .f 文件展开后的内容
• 列出某个模块或小型 IP 中的设计单元
• 查找声明，无需在注释和过时的 grep 结果中逐一排查
• 为审查／调试提示词提供层次结构和端口连接上下文
• 在不提供 EDA 运行时的情况下，为工作流 Agent 提供 HDL 上下文

快速入门

安装软件包：

pip install pyslang-mcp

运行本地 stdio 服务：

pyslang-mcp

配置贡献者环境：克隆仓库并以可编辑模式安装：

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

运行检出目录中的 stdio 服务：

./.venv/bin/python -m pyslang_mcp

也可以使用已安装的控制台脚本：

./.venv/bin/pyslang-mcp

运行测试：

./.venv/bin/pytest

MCP 客户端配置

使用本地 stdio。MCP 客户端应在能够访问 RTL 代码库的同一台机器、VM 或开发容器上启动服务。

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

对于以可编辑模式安装的检出目录，请改为将命令指向该检出目录的虚拟环境：

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

工具调用必须提供 project_root。源文件路径、文件列表和 include 目录可以是绝对路径或相对路径，但必须位于该根目录下。

最简工具负载

分析指定文件：

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

分析文件列表：

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

查找符号：

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

工具

需求	工具
加载指定文件	pyslang_parse_files
加载 .f 文件列表	pyslang_parse_filelist
获取解析和语义诊断	pyslang_get_diagnostics
列出模块、接口和包	pyslang_list_design_units
检查一个设计单元	pyslang_describe_design_unit
遍历展开后的实例树	pyslang_get_hierarchy
查找声明和引用	pyslang_find_symbol
在一个设计单元中查找局部成员	pyslang_find_member
查找涉及某个信号的赋值	pyslang_get_assignments
跟踪有界结构连通性	pyslang_trace_connectivity
转储某个实例的端口连接	pyslang_get_instance_connections
按代码分组诊断	pyslang_summarize_diagnostics_by_code
汇总语法节点形状	pyslang_dump_syntax_tree_summary
检查预处理元数据和摘录	pyslang_preprocess_files
获取精简的项目概览	pyslang_get_project_summary

典型流程：

1. 从 pyslang_parse_filelist 或 pyslang_parse_files 开始。
2. 运行 pyslang_get_diagnostics。
3. 使用 pyslang_list_design_units 查看编译器前端发现的内容。
4. 针对具体的审查或调试问题，使用 pyslang_describe_design_unit、pyslang_get_hierarchy 或 pyslang_find_symbol。

Verilog/SystemVerilog 分析与调试流程

1. 使用 pyslang_summarize_diagnostics_by_code，将重复的前端警告与未解决的依赖错误区分开来。
2. 使用 pyslang_find_member 查找 response__vld 等局部名称。
3. 使用 pyslang_get_assignments 检查可见的连续或过程驱动项和负载。
4. 使用 pyslang_get_instance_connections 查看某个实例的端口绑定上下文。
5. 使用 pyslang_trace_connectivity 跟踪赋值和实例端口绑定中的有界结构路径。

连通性跟踪提供的是结构性的前端证据。它不是仿真、形式化证明、CDC/RDC 签核、时序签核，也不是完整的网表级驱动项/负载数据库。

文件列表支持

当前解析器有意支持许多 RTL 工作流中常用的实用子集：

• 源文件条目
• 使用 -f 和 -F 嵌套文件列表
• 使用 +incdir+...、-I dir 和 -Idir 指定包含目录
• 使用 +define+...、-D NAME 和 -DNAME 定义宏

不支持的文件列表令牌会在工具输出中报告，而不会被静默忽略。

Agent 提示词示例

在需要编译器支持的上下文时使用此服务：

• “使用 +define+DEBUG 解析 compile/project.f，并按源文件对诊断分组。”
• “列出此项目中的所有设计单元，并指出可能的顶层模块。”
• “从 top 开始，显示深度为 4 的实例层次结构。”
• “描述模块 axi_dma_top：端口、子实例和已声明名称。”
• “查找 payload_valid 的声明和引用。”
• “确认展开器能看到的任何位置是否实例化了 legacy_widget。”
• “显示此文件列表中的已解析文件、包含目录、宏定义和不支持的条目。”

对于单行问题、注释、名称搜索或不完整的源文件集，常规 rg、编辑器搜索或直接读取文件通常更快、更清晰。

使用限制

• 只读 MCP 工具。不支持编辑 RTL、格式化、仿真或综合。
• 严格限定项目根目录范围。拒绝 project_root 之外的路径。
• 返回精简的 JSON；大型结果集会附带截断元数据。
• 进程内缓存以项目配置和受跟踪文件的修改时间为键。
• pyslang_preprocess_files 侧重摘要。它返回预处理元数据和源代码摘录，不保证提供完整、独立的预处理流。
• streamable-http 仍处于实验阶段。内部 MaaS 路径通过承载令牌封装它，以供单服务使用，但其本身并非完整的生产环境托管安全边界。

远程 MaaS 方向

远程 MaaS 计划分为两个独立方向，而不是一种通用的托管模式：

• 方案 A：公共开源 MaaS。 为公共开源 HDL 仓库提供的便捷演示服务。不适用于专有或机密 RTL。
• 方案 B：内部 MaaS。 一种可自托管的部署模式，供公司在自己的网络内运行，并靠近内部仓库、身份验证、日志记录和安全控制。

单台内部服务器请从内部 MaaS 快速入门开始。完整的方案 A / 方案 B 划分请参阅 REMOTE_DEPLOYMENT.md。

推荐使用 Docker Compose 进行启动，因为它能避免 Python 环境配置问题，并以只读方式挂载 RTL 检出目录。Docker 并非必需；快速入门也包含原生 Python 部署方式，适用于无法使用容器的企业服务器。

HDL 示例集

仓库在 examples/hdl 下包含生成的 HDL 示例：

• 从单个模块到小型 IP 风格示例的无错误参考项目
• 标有 easy、medium 和 hard 的故意引入错误的变体
• 用于 pyslang 和 verilator --lint-only 的本地验证钩子

运行完整的示例集验证器：

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

运行 CI 冒烟测试子集：

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

与更全面的 RTL 技能搭配使用

如果你的 Agent 环境已具备 rtl-analysis、rtl-audit 或 llm-based-verilog-analysis 等全面的 RTL 技能，请将 pyslang-verilog-context 用作该技能之下的细粒度编译器证据层。

推荐配置：

1. 在 MCP 客户端中配置 pyslang-mcp 服务，让 Agent 能调用只读的 pyslang_* 工具。
2. 从 skills/pyslang-verilog-context 安装或复制 pyslang-verilog-context 技能。
3. 在更全面的 RTL 技能中添加类似这样的委派说明：

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.

预期的工作流程如下：

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

这样既能将高层 RTL 审查策略保留在全面的技能中，又能通过 pyslang 为 Verilog/SystemVerilog 结构、诊断信息、层次结构、符号、包含文件和文件列表提供依据。

评估基准

仓库在 skills/pyslang-verilog-context/evals 下包含 pyslang-verilog-context 技能评估套件，并在 reports/ 下提供对比报告。目前的基准比较三种本地证据模式：

• 纯文本／无技能：仅使用源码和文件列表文本启发式
• MCP／无技能：针对性调用 pyslang-mcp 工具
• 技能 + MCP：按 pyslang-verilog-context 的流程调用 pyslang-mcp

2026-06-14 的最新本地结果：

基准	纯文本／无技能	MCP／无技能	技能 + MCP
100 个 HDL 分析用例	60/100	95/100	100/100

该基准结合了确定性的仓库本地 HDL 固定测试用例与真实的公共 RTL 源文件。本地固定测试用例用于测试文件列表、层次结构、符号、诊断信息、前端无错误但存在功能问题的代码，以及 RTL 编码和错误审查规范等针对性行为。真实公共 RTL 用例使用来自 lowrisc-ibex、pulp-common-cells、verilog-axis、pulp-axi、pulp-register-interface 和 picorv32 的源文件。它们用于测试真实源文件的前端诊断状态、设计单元清单和第一个单元的端口数量。提示词／任务形式以及使用的 MCP 函数请参阅 docs/evaluation-benchmarks.md。

本次报告运行所用的验证命令：

./.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_20260614
./.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

这些是确定性的标量测试框架，并非不加监督的自主 LLM 裁判测试。pyslang-mcp 提供的证据仅限于前端／编译器上下文，不涵盖仿真、综合、CDC/RDC、时序、形式验证或完整的 lint 签核。

仅更新文档、评估或报告时无需发布 PyPI 版本。若包代码、公开工具行为、架构、运行时依赖、CLI 行为或面向用户的安装／运行时文档发生变化，且发布用户需要这些变更，则应发布 PyPI 版本。

项目状态

已实现：

• FastMCP 标准输入/输出服务
• 通过 python -m pyslang_mcp 和 pyslang-mcp 启动 CLI
• 带根目录检查和 .f 解析功能的项目加载器
• 基于 pyslang 的诊断和诊断分组、设计单元与成员查找、赋值和实例连接分析、有限范围的结构连通性分析、层级分析、语法摘要和项目摘要
• 有限容量的内存缓存
• 基于测试夹具的测试，以及针对 Python 3.11 和 3.12 的 Ubuntu CI
• 基于构建 wheel 的软件包冒烟测试 CI
• 带发布门禁测试的手动 PyPI Trusted Publishing 发布工作流
• PyPI 软件包：pyslang-mcp
• MCP Registry 条目： io.github.ariklapid/pyslang-mcp
• 内部 MaaS 启动所需的文件：Dockerfile、Docker Compose 配置、原生 Python 回退说明、systemd 模板、Bearer 令牌 HTTP 选项，以及单服务快速入门指南

尚未完成：

• 面向更成熟、API 稳定版本的架构冻结
• 超出当前以 Linux 为主的 CI 路径的平台广泛验证
• 面向团队广泛使用的生产级 MaaS 加固：SSO、多工作区路由、Kubernetes 部署、保障源代码安全的指标，以及反向代理示例

开发

常用命令：

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

架构和贡献文档：

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

许可证

Apache-2.0。请参阅 LICENSE。