ariklapid/pyslang-mcp
GitHub: ariklapid/pyslang-mcp
一个基于编译器前端的只读 MCP 服务器，为 Verilog/SystemVerilog 提供精确的结构化语义分析与上下文查询。
Stars: 0 | Forks: 0
# pyslang-mcp
[](https://github.com/asicdesign-ai/pyslang-mcp/actions/workflows/ci.yml)
`pyslang-mcp` 是一个专注于只读、本地优先的模型上下文协议（MCP）服务器
用于通过 [`pyslang`](https://pypi.org/project/pyslang/) 对 Verilog 和 SystemVerilog 项目进行只读、编译器支持的解析分析
目标是提供精确明确的结构化 HDL 项目上下文：
通过真实的解析与编译展开，而非原始文本搜索，向 AI 客户端提供语义分析支持。
本项目是语义分析 MCP，不是仿真器、综合器、波形查看器或代码生成器。
## ✨ 存在的意义
AI 编码代理已经可以像搜索文本一样搜索 HDL 仓库，这很有用但能力有限。
`pyslang-mcp` 的存在是为了回答那些需要真实编译器前端才能解决的问题：
- 存在哪些设计单元？
- 产生了哪些诊断信息？
- 模块之间如何实例化？
- 符号在哪里声明或引用？
- 文件列表、包含路径或宏定义是如何实际解析的？
## 🚦 状态
截至 2026-04-19，仓库包含：
- `pyproject.toml` 打包元数据
- 位于 `src/pyslang_mcp/` 的 `FastMCP` 服务器
- 通过 `python -m pyslang_mcp` 提供的 `stdio` 入口点
- 基于 fixture 的加载器、分析与 MCP `call_tool()` 路径测试
- Ubuntu GitHub Actions CI 工作流
尚未完成的工作：
- 尚未发布到 PyPI
- 尚未发布到 MCP Registry
- 尚未实现发布自动化
- 尚未承诺长期冻结的 Schema
- 尚未承诺完整的前处理器一致性
## 🧰 已实现的工具
当前 Alpha 版本实现了以下只读工具：
| 领域 | 工具 |
|---|---|
| 解析 / 加载 | `pyslang_parse_files`, `pyslang_parse_filelist` |
| 诊断 | `pyslang_get_diagnostics` |
| 语义清单 | `pyslang_list_design_units`, `pyslang_describe_design_unit` |
| 结构 | `pyslang_get_hierarchy`, `pyslang_get_project_summary` |
| 查找 | `pyslang_find_symbol` |
| 语法 / 预处理摘要 | `pyslang_dump_syntax_tree_summary`, `pyslang_preprocess_files` |
## 🔒 保护机制
- 严格的项目根目录作用域；拒绝根目录外的路径
- 优先使用 `stdio` 传输
- 使用紧凑的 JSON 响应，而非庞大的原始编译器输出
- 以标准化项目配置和跟踪的文件 mtime 为键的内存缓存
- 保守的 `pyslang_preprocess_files` 行为，返回预处理元数据和摘录，而非声称完整预处理文本流
## 🗂️ 当前文件列表支持
实现的 `.f` 解析器有意支持实用子集：
- 原始源文件条目
- 使用 `-f` 和 `-F` 的嵌套文件列表
- 使用 `+incdir+...` 和 `-I` 的包含目录
- 使用 `+define+...` 的宏定义
不支持的指令会回显到 `pyslang_parse_filelist` 输出中，而不是被静默忽略。
## 🧪 HDL 示例语料库
仓库现在包含位于
[`examples/hdl`](./examples/hdl/) 的生成 HDL 示例语料库，包含：
- 从单个模块到小 IP 项目的干净参考设计
- 故意包含错误的副本，标记为 `easy`、`medium` 和 `hard`
- 基于 `pyslang` 和 Verilator 的本地验证
在本地运行完整语料库验证：
```
./.venv/bin/python scripts/validate_hdl_examples.py
```
CI 仅运行小型烟雾测试子集，以便仓库保持代表性的 HDL 覆盖率，而不会将示例语料库变成产品。
## 🏃 快速开始
本地开发设置：
```
cd /path/to/pyslang-mcp
python -m venv .venv
./.venv/bin/pip install -e '.[dev]'
```
在仓库根目录运行可编辑安装。如果从其他位置启动新终端，请先 `cd` 到克隆的目录，以便 `pip` 能解析本地的 `pyproject.toml`。
通过 `stdio` 运行服务器：
```
./.venv/bin/python -m pyslang_mcp
```
或显式选择传输方式：
```
./.venv/bin/python -m pyslang_mcp --transport stdio
```
## 🧭 本地客户端设置
当前预期的连接模型是本地 `stdio`。
这意味着：
- MCP 服务器进程在与包含 HDL 签出的同一台机器、VM 或开发容器上运行
- MCP 客户端启动 `pyslang-mcp` 作为子进程
- 工具调用使用存在于同一文件系统上的 `project_root` 路径
这与许多本地 MCP 集成使用的基本模式相同，即使供应商也为其他产品提供托管连接器。
### 本地操作概览
```
flowchart LR
User["🧑 User / Agent"]
Client["🧠 MCP Client
Claude / Cursor / IDE"] Server["🧩 pyslang-mcp
local stdio process"] Loader["📁 project_loader.py"] Core["🧪 analysis.py + pyslang"] Repo["📚 Verilog / SystemVerilog repo"] JSON["📦 Stable JSON responses"] User --> Client Client <-->|stdio MCP| Server Server --> Loader Loader --> Repo Loader --> Core Core --> Repo Core --> JSON JSON --> Server Server --> Client ``` ### 通用 `stdio` 客户端配置 通用本地客户端配置： ``` { "mcpServers": { "pyslang-mcp": { "command": "/path/to/python", "args": [ "-m", "pyslang_mcp", "--transport", "stdio" ] } } } ``` 对于使用仓库虚拟环境的本地签出，通常意味着： ``` { "mcpServers": { "pyslang-mcp": { "command": "/absolute/path/to/pyslang-mcp/.venv/bin/python", "args": [ "-m", "pyslang_mcp", "--transport", "stdio" ] } } } ``` ### 客户端示例 #### Claude Desktop 添加指向仓库虚拟环境的本地 MCP 服务器条目： ``` { "mcpServers": { "pyslang-mcp": { "command": "/absolute/path/to/pyslang-mcp/.venv/bin/python", "args": ["-m", "pyslang_mcp", "--transport", "stdio"] } } } ``` #### Cursor 在 Cursor 的 MCP 配置中使用相同的命令/参数模式： ``` { "mcpServers": { "pyslang-mcp": { "command": "/absolute/path/to/pyslang-mcp/.venv/bin/python", "args": ["-m", "pyslang_mcp", "--transport", "stdio"] } } } ``` #### 通用 IDE / 代理运行器 任何支持本地子进程服务器的 MCP 客户端都可以使用： ``` { "mcpServers": { "pyslang-mcp": { "command": "/absolute/path/to/pyslang-mcp/.venv/bin/python", "args": ["-m", "pyslang_mcp", "--transport", "stdio"] } } } ``` ### 本地安装选项 开发签出： ``` git clone https://github.com/asicdesign-ai/pyslang-mcp.git cd pyslang-mcp python -m venv .venv ./.venv/bin/pip install -e '.[dev]' ``` 然后将 MCP 客户端指向： - `command`：`/absolute/path/to/pyslang-mcp/.venv/bin/python` - `args`：`["-m", "pyslang_mcp", "--transport", "stdio"]` 未来的打包安装目标： ``` pip install pyslang-mcp ``` 然后将 MCP 客户端指向： - `command`：`pyslang-mcp` - `args`：`[]` 或： - `command`：`python` - `args`：`["-m", "pyslang_mcp"]` ### 工具输入规则 - 始终提供 `project_root` - 仅提供 `files` 或 `filelist` 之一 - 路径可以是相对于 `project_root` 的相对路径或绝对路径，但必须位于 `project_root` 内部 - `include_dirs`、`defines` 和 `top_modules` 为可选参数 `pyslang_parse_files` 示例负载： ``` { "project_root": "/path/to/rtl-project", "files": [ "rtl/pkg.sv", "rtl/top.sv" ], "include_dirs": [ "include" ], "defines": { "WIDTH": "32" }, "top_modules": [ "top" ] } ``` `pyslang_parse_filelist` 示例负载： ``` { "project_root": "/path/to/rtl-project", "filelist": "compile/project.f" } ``` `pyslang_find_symbol` 示例负载： ``` { "project_root": "/path/to/rtl-project", "filelist": "compile/project.f", "query": "payload", "match_mode": "exact", "include_references": true } ``` ### 示例提示 当编译器支持的答案优于文本搜索，或问题跨越多个文件时，应使用此 MCP。这些正是 `pyslang_mcp` 值得其编译展开成本的场景。 #### 唯一性、缺失性与基数 grep 告诉你“找到 N 个匹配项”；MCP 告诉你“展开器确认 X”。 编译器支持的断言是 grep 无法做出的： - “`ecc_error` 是否实际被消耗，还是死代码？我需要编译器确认每个加载都是未连接的 sink，而不仅仅是文本匹配。” - “模块 `legacy_widget` 是否在展开器可见的范围内被实例化，即使 grep 仅在注释中找到其名称？” - “信号 `fsm_discard` 有多少个不同的声明与该确切名称匹配？” #### 跨模块与层次查询 grep 会迭代并丢失上下文；MCP 仅展开一次即可遍历展开树： - “从 `top` 开始，遍历实例层次结构并显示 `sync_fifo_mem` 的每个实例及其层次路径和端口连接。” - “描述模块 `kuku_top`：端口、子实例和声明的名称。” - “列出展开设计中所有顶层实例并报告其深度。” #### 项目健康与诊断 - “使用 `+define+DEBUG` 解析 `compile/project.f` 并每个错误和警告的文件/行位置。” - “按文件分组当前诊断，以便我可以确定哪些模块最糟糕。” - “pyslang 是否能干净地编译此项目？我需要解析加语义诊断，而非文本匹配。” #### 结构清单 - “按种类（模块 / 接口 / 包）列出项目中的每个设计单元。” - “给出项目形状：文件数、顶层实例数、诊断数、跟踪路径数。不进行深度分析。” #### 文件列表与预处理合理性 - “在 `compile/project.f` 上运行 `pyslang_parse_filelist` 并确认解析的文件集合、包含路径、宏定义和不支持的指令是否与你的仿真器一致。” #### 符号队列分析 - “对于模块 `kuku_top`，列出每个声明的名称，以便我可以检查 `ecc_err` 是否属于一组 未连接的标量。” - “类型 `data_t` 定义在哪里？哪些变量或端口声明了它？” #### 何时不应使用此 MCP 诚实面对——MCP 付出了展开成本，简单的文本工具更高效。 **纯 `grep` / `读取` 更优：** - 单文件问题且位置已知（“这一行 42 做了什么？”，“字符串 `foo_bar` 出现在哪里？”）。 - 注释或文档字符串查找（“这个函数上方的注释是什么？”）。 - 不完整的文件集合——解析错误可能导致下游结果静默降级（`describe_*` 可能返回空端口列表）。如果提供的文件集合不完整，grep 加读取能给出更干净的答案。 **直接使用 `pyslang` 更优：** - 需要自定义访问者的专门分析：“统计使用负沿复位的 `always_ff` 块”，“构建任务调用图”，或“运行此自定义规则”。十个 pyslang 代码胜过组合工具调用。 - 自定义作用域中的表达式求值、参数扫描、增量展开。 **完全不在职责范围内：** - 重命名 / 重构 / 格式化 / 自动修复——MCP 严格只读。 - 测试平台生成、综合、仿真、波形分析。 ### 推荐工作流程 1. 先使用 `pyslang_parse_filelist` 或 `pyslang_parse_files` 确认项目根目录、文件展开、包含目录和宏定义是否符合预期。 2. 运行 `pyslang_get_diagnostics` 尽早发现解析或语义问题。 3. 使用 `pyslang_list_design_units` 和 `pyslang_describe_design_unit` 理解模块与包。 4. 使用 `pyslang_get_hierarchy` 检查实例化结构。 5. 使用 `pyslang_find_symbol` 查找声明与引用。 6. 仅在需要语法或预处理上下文时使用 `pyslang_dump_syntax_tree_summary` 和 `pyslang_preprocess_files`；它们有意保持紧凑。 ### 客户端应期待的响应 - 响应为 JSON 字典 - 大型结果列表包含截断元数据 - 可恢复的输入问题会返回带有结构化错误负载的 MCP 工具错误 - `pyslang_describe_design_unit` 对常规查找未命中返回 `found` / `ambiguous`，而非抛出异常 - `pyslang_preprocess_files` 侧重摘要，不声称能生成 完整的独立预处理输出流 - 如果路径逃离声明的根目录，工具将返回错误而非读取 ## 🏗️ 架构 实现有意将分析核心与轻量级 MCP 包装层分离。 ``` flowchart TD Main["__main__.py
CLI entrypoint"] Server["server.py
FastMCP tool layer"] Loader["project_loader.py
root checks + filelist parsing"] Analysis["analysis.py
pyslang compilation + queries"] Cache["cache.py
config hash + mtime invalidation"] Ser["serializers.py
stable JSON + truncation"] Types["types.py
shared internal types"] Pyslang["pyslang"] Main --> Server Server --> Loader Server --> Analysis Server --> Cache Analysis --> Cache Analysis --> Ser Loader --> Types Analysis --> Types Cache --> Types Analysis --> Pyslang ``` ### 典型工具调用流程 ``` sequenceDiagram participant C as MCP Client participant S as server.py participant L as project_loader.py participant A as analysis.py participant P as pyslang C->>S: pyslang_get_hierarchy(project_root, filelist) S->>L: normalize root + expand filelist L-->>S: ProjectConfig S->>A: build or reuse cached analysis A->>P: parse + elaborate project P-->>A: compilation + symbols A-->>S: hierarchy JSON S-->>C: MCP tool response ``` ## 🌐 远程部署方向 如果目标是将 `pyslang-mcp` 感觉像 GitHub 或 Google Sheets 这类知名的可连接 MCP，应将托管访问视为独立部署产品，而非当前本地 `stdio` 模式的扩展。 当前状态： - 已实现本地优先的 `stdio` 服务器 - 托管多用户部署尚未实现 推荐的托管方向： - 添加安全的 HTTP MCP 传输 - 要求经过身份验证的工作区 - 隔离每个用户或仓库的工作区 - 仅分析工作区内存在的文件 - 保持相同的只读工具语义 ### 托管方向示意图 ``` flowchart LR Client["🌍 Remote MCP Client"] Edge["🛡️ HTTPS + Auth"] Control["🧭 Control Plane
users / orgs / workspaces"] Exec["⚙️ MCP Execution Plane"] Workspace["📦 Isolated Workspace"] Repo["🔐 Repo snapshot / upload"] Client --> Edge Edge --> Control Edge --> Exec Control --> Workspace Repo --> Workspace Workspace --> Exec ``` 参见 [`REMOTE_DEPLOYMENT.md`](./REMOTE_DEPLOYMENT.md) 了解托管 架构、安全模型和发布计划。 ## 🧪 开发命令 ``` ./.venv/bin/ruff format src tests ./.venv/bin/ruff check src tests ./.venv/bin/pyright ./.venv/bin/pytest --cov=src/pyslang_mcp --cov-report=term-missing:skip-covered -q ``` ## ⚠️ 已知限制 - `pyslang_preprocess_files` 侧重摘要且有意保守 - `pyslang_find_symbol` 当前每次查询都重新遍历展开的设计；适用于当前场景，但尚未为大型语料库建立索引 - 文件列表解析器是有用的子集，而非完整的仿真器兼容性 - 工具输出设计为稳定且紧凑，但仍是 Alpha 版本 - 打包和注册表发布仍在进行中 ## 🗺️ 路线图 - `M0`：研究阶段与 `pyslang` API 验证 - `M1`：仓库脚手架与本地可运行服务器 - `M2`：解析、文件列表、预处理、诊断 - `M3`：设计单元清单、层次结构、符号查找 - `M4`：加固、缓存、Schema 冻结、文档 - `M5`：PyPI 发布、注册表发布、公告 仓库目前已完成 `M3` 的本地实现，但发布和注册表发布工作仍在进行中。 ## 📚 参考资料 - `pyslang`：
- Python MCP SDK：
- MCP Registry：
## 📄 许可证
本仓库根据 Apache 2.0 条款授权，位于
[`LICENSE`](./LICENSE)。
Claude / Cursor / IDE"] Server["🧩 pyslang-mcp
local stdio process"] Loader["📁 project_loader.py"] Core["🧪 analysis.py + pyslang"] Repo["📚 Verilog / SystemVerilog repo"] JSON["📦 Stable JSON responses"] User --> Client Client <-->|stdio MCP| Server Server --> Loader Loader --> Repo Loader --> Core Core --> Repo Core --> JSON JSON --> Server Server --> Client ``` ### 通用 `stdio` 客户端配置 通用本地客户端配置： ``` { "mcpServers": { "pyslang-mcp": { "command": "/path/to/python", "args": [ "-m", "pyslang_mcp", "--transport", "stdio" ] } } } ``` 对于使用仓库虚拟环境的本地签出，通常意味着： ``` { "mcpServers": { "pyslang-mcp": { "command": "/absolute/path/to/pyslang-mcp/.venv/bin/python", "args": [ "-m", "pyslang_mcp", "--transport", "stdio" ] } } } ``` ### 客户端示例 #### Claude Desktop 添加指向仓库虚拟环境的本地 MCP 服务器条目： ``` { "mcpServers": { "pyslang-mcp": { "command": "/absolute/path/to/pyslang-mcp/.venv/bin/python", "args": ["-m", "pyslang_mcp", "--transport", "stdio"] } } } ``` #### Cursor 在 Cursor 的 MCP 配置中使用相同的命令/参数模式： ``` { "mcpServers": { "pyslang-mcp": { "command": "/absolute/path/to/pyslang-mcp/.venv/bin/python", "args": ["-m", "pyslang_mcp", "--transport", "stdio"] } } } ``` #### 通用 IDE / 代理运行器 任何支持本地子进程服务器的 MCP 客户端都可以使用： ``` { "mcpServers": { "pyslang-mcp": { "command": "/absolute/path/to/pyslang-mcp/.venv/bin/python", "args": ["-m", "pyslang_mcp", "--transport", "stdio"] } } } ``` ### 本地安装选项 开发签出： ``` git clone https://github.com/asicdesign-ai/pyslang-mcp.git cd pyslang-mcp python -m venv .venv ./.venv/bin/pip install -e '.[dev]' ``` 然后将 MCP 客户端指向： - `command`：`/absolute/path/to/pyslang-mcp/.venv/bin/python` - `args`：`["-m", "pyslang_mcp", "--transport", "stdio"]` 未来的打包安装目标： ``` pip install pyslang-mcp ``` 然后将 MCP 客户端指向： - `command`：`pyslang-mcp` - `args`：`[]` 或： - `command`：`python` - `args`：`["-m", "pyslang_mcp"]` ### 工具输入规则 - 始终提供 `project_root` - 仅提供 `files` 或 `filelist` 之一 - 路径可以是相对于 `project_root` 的相对路径或绝对路径，但必须位于 `project_root` 内部 - `include_dirs`、`defines` 和 `top_modules` 为可选参数 `pyslang_parse_files` 示例负载： ``` { "project_root": "/path/to/rtl-project", "files": [ "rtl/pkg.sv", "rtl/top.sv" ], "include_dirs": [ "include" ], "defines": { "WIDTH": "32" }, "top_modules": [ "top" ] } ``` `pyslang_parse_filelist` 示例负载： ``` { "project_root": "/path/to/rtl-project", "filelist": "compile/project.f" } ``` `pyslang_find_symbol` 示例负载： ``` { "project_root": "/path/to/rtl-project", "filelist": "compile/project.f", "query": "payload", "match_mode": "exact", "include_references": true } ``` ### 示例提示 当编译器支持的答案优于文本搜索，或问题跨越多个文件时，应使用此 MCP。这些正是 `pyslang_mcp` 值得其编译展开成本的场景。 #### 唯一性、缺失性与基数 grep 告诉你“找到 N 个匹配项”；MCP 告诉你“展开器确认 X”。 编译器支持的断言是 grep 无法做出的： - “`ecc_error` 是否实际被消耗，还是死代码？我需要编译器确认每个加载都是未连接的 sink，而不仅仅是文本匹配。” - “模块 `legacy_widget` 是否在展开器可见的范围内被实例化，即使 grep 仅在注释中找到其名称？” - “信号 `fsm_discard` 有多少个不同的声明与该确切名称匹配？” #### 跨模块与层次查询 grep 会迭代并丢失上下文；MCP 仅展开一次即可遍历展开树： - “从 `top` 开始，遍历实例层次结构并显示 `sync_fifo_mem` 的每个实例及其层次路径和端口连接。” - “描述模块 `kuku_top`：端口、子实例和声明的名称。” - “列出展开设计中所有顶层实例并报告其深度。” #### 项目健康与诊断 - “使用 `+define+DEBUG` 解析 `compile/project.f` 并每个错误和警告的文件/行位置。” - “按文件分组当前诊断，以便我可以确定哪些模块最糟糕。” - “pyslang 是否能干净地编译此项目？我需要解析加语义诊断，而非文本匹配。” #### 结构清单 - “按种类（模块 / 接口 / 包）列出项目中的每个设计单元。” - “给出项目形状：文件数、顶层实例数、诊断数、跟踪路径数。不进行深度分析。” #### 文件列表与预处理合理性 - “在 `compile/project.f` 上运行 `pyslang_parse_filelist` 并确认解析的文件集合、包含路径、宏定义和不支持的指令是否与你的仿真器一致。” #### 符号队列分析 - “对于模块 `kuku_top`，列出每个声明的名称，以便我可以检查 `ecc_err` 是否属于一组 未连接的标量。” - “类型 `data_t` 定义在哪里？哪些变量或端口声明了它？” #### 何时不应使用此 MCP 诚实面对——MCP 付出了展开成本，简单的文本工具更高效。 **纯 `grep` / `读取` 更优：** - 单文件问题且位置已知（“这一行 42 做了什么？”，“字符串 `foo_bar` 出现在哪里？”）。 - 注释或文档字符串查找（“这个函数上方的注释是什么？”）。 - 不完整的文件集合——解析错误可能导致下游结果静默降级（`describe_*` 可能返回空端口列表）。如果提供的文件集合不完整，grep 加读取能给出更干净的答案。 **直接使用 `pyslang` 更优：** - 需要自定义访问者的专门分析：“统计使用负沿复位的 `always_ff` 块”，“构建任务调用图”，或“运行此自定义规则”。十个 pyslang 代码胜过组合工具调用。 - 自定义作用域中的表达式求值、参数扫描、增量展开。 **完全不在职责范围内：** - 重命名 / 重构 / 格式化 / 自动修复——MCP 严格只读。 - 测试平台生成、综合、仿真、波形分析。 ### 推荐工作流程 1. 先使用 `pyslang_parse_filelist` 或 `pyslang_parse_files` 确认项目根目录、文件展开、包含目录和宏定义是否符合预期。 2. 运行 `pyslang_get_diagnostics` 尽早发现解析或语义问题。 3. 使用 `pyslang_list_design_units` 和 `pyslang_describe_design_unit` 理解模块与包。 4. 使用 `pyslang_get_hierarchy` 检查实例化结构。 5. 使用 `pyslang_find_symbol` 查找声明与引用。 6. 仅在需要语法或预处理上下文时使用 `pyslang_dump_syntax_tree_summary` 和 `pyslang_preprocess_files`；它们有意保持紧凑。 ### 客户端应期待的响应 - 响应为 JSON 字典 - 大型结果列表包含截断元数据 - 可恢复的输入问题会返回带有结构化错误负载的 MCP 工具错误 - `pyslang_describe_design_unit` 对常规查找未命中返回 `found` / `ambiguous`，而非抛出异常 - `pyslang_preprocess_files` 侧重摘要，不声称能生成 完整的独立预处理输出流 - 如果路径逃离声明的根目录，工具将返回错误而非读取 ## 🏗️ 架构 实现有意将分析核心与轻量级 MCP 包装层分离。 ``` flowchart TD Main["__main__.py
CLI entrypoint"] Server["server.py
FastMCP tool layer"] Loader["project_loader.py
root checks + filelist parsing"] Analysis["analysis.py
pyslang compilation + queries"] Cache["cache.py
config hash + mtime invalidation"] Ser["serializers.py
stable JSON + truncation"] Types["types.py
shared internal types"] Pyslang["pyslang"] Main --> Server Server --> Loader Server --> Analysis Server --> Cache Analysis --> Cache Analysis --> Ser Loader --> Types Analysis --> Types Cache --> Types Analysis --> Pyslang ``` ### 典型工具调用流程 ``` sequenceDiagram participant C as MCP Client participant S as server.py participant L as project_loader.py participant A as analysis.py participant P as pyslang C->>S: pyslang_get_hierarchy(project_root, filelist) S->>L: normalize root + expand filelist L-->>S: ProjectConfig S->>A: build or reuse cached analysis A->>P: parse + elaborate project P-->>A: compilation + symbols A-->>S: hierarchy JSON S-->>C: MCP tool response ``` ## 🌐 远程部署方向 如果目标是将 `pyslang-mcp` 感觉像 GitHub 或 Google Sheets 这类知名的可连接 MCP，应将托管访问视为独立部署产品，而非当前本地 `stdio` 模式的扩展。 当前状态： - 已实现本地优先的 `stdio` 服务器 - 托管多用户部署尚未实现 推荐的托管方向： - 添加安全的 HTTP MCP 传输 - 要求经过身份验证的工作区 - 隔离每个用户或仓库的工作区 - 仅分析工作区内存在的文件 - 保持相同的只读工具语义 ### 托管方向示意图 ``` flowchart LR Client["🌍 Remote MCP Client"] Edge["🛡️ HTTPS + Auth"] Control["🧭 Control Plane
users / orgs / workspaces"] Exec["⚙️ MCP Execution Plane"] Workspace["📦 Isolated Workspace"] Repo["🔐 Repo snapshot / upload"] Client --> Edge Edge --> Control Edge --> Exec Control --> Workspace Repo --> Workspace Workspace --> Exec ``` 参见 [`REMOTE_DEPLOYMENT.md`](./REMOTE_DEPLOYMENT.md) 了解托管 架构、安全模型和发布计划。 ## 🧪 开发命令 ``` ./.venv/bin/ruff format src tests ./.venv/bin/ruff check src tests ./.venv/bin/pyright ./.venv/bin/pytest --cov=src/pyslang_mcp --cov-report=term-missing:skip-covered -q ``` ## ⚠️ 已知限制 - `pyslang_preprocess_files` 侧重摘要且有意保守 - `pyslang_find_symbol` 当前每次查询都重新遍历展开的设计；适用于当前场景，但尚未为大型语料库建立索引 - 文件列表解析器是有用的子集，而非完整的仿真器兼容性 - 工具输出设计为稳定且紧凑，但仍是 Alpha 版本 - 打包和注册表发布仍在进行中 ## 🗺️ 路线图 - `M0`：研究阶段与 `pyslang` API 验证 - `M1`：仓库脚手架与本地可运行服务器 - `M2`：解析、文件列表、预处理、诊断 - `M3`：设计单元清单、层次结构、符号查找 - `M4`：加固、缓存、Schema 冻结、文档 - `M5`：PyPI 发布、注册表发布、公告 仓库目前已完成 `M3` 的本地实现，但发布和注册表发布工作仍在进行中。 ## 📚 参考资料 - `pyslang`：
标签：FastMCP, HDL, MCP, Model Context Protocol, PySLANG, Python 3.11, Python 3.12, SEO: AI 编程工具, SEO: HDL 分析, SEO: 编译器后端, SOC Prime, SystemVerilog, Verilog, 代码分析, 代码导航, 代码理解, 凭证管理, 协议服务器, 只读分析, 层次结构, 工程工具, 开发工具, 开源, 本地优先, 标准工具协议, 渗透测试平台, 结构化信息, 编译器, 设计单元, 诊断报告, 语法分析, 逆向工具