verilog-mcp-server: Instructions file for Codex

AGENTS.md

Agent guidance for the Verilog MCP Server project.

Project Overview

Verilog/SystemVerilog RTL semantic analysis MCP server. Uses tree-sitter for syntax-level parsing of HDL source files and pyslang (slang compiler frontend) for semantic-level elaboration. Exposes tools via MCP protocol for module search, signal tracing, hierarchy tree construction, FSM detection, clock domain analysis, and visualization.

Build & Development Commands

# Install in editable mode
pip install -e .

# Run the MCP server (stdio transport, called by MCP clients)
verilog-mcp-server

# Start with index building
verilog-mcp-server --build -p /path/to/rtl/project

# Specify filelist + top module
verilog-mcp-server --build -f project.f --top soc

# Force full rebuild
verilog-mcp-server --rebuild -p /path/to/rtl/project

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_module_extractor.py -v

# Build standalone executable (CentOS 8.4)
bash scripts/build-centos8.sh

CentOS 8 构建详细指南

前提条件

1. 操作系统: CentOS 8.4 (glibc 2.28)
2. Python 环境: miniconda3 Python 3.10+ (推荐 3.12)
3. 依赖包: tree-sitter-language-pack, pyslang, mcp, pyyaml, pyinstaller
4. yosys (可选): 如果需要 yosys 功能，确保 yosys 在 PATH 中

构建步骤

1. 环境准备

# 检查 Python 版本
python3 --version

# 检查 pip
python3 -m pip --version

# 如果使用 miniconda3，确保 Python 环境正常
conda install python=3.12 --force-reinstall

2. 运行构建脚本

# 进入项目目录
cd /wa/project/verilog_mcp_server

# 运行构建脚本
bash scripts/build-centos8.sh

# 如果需要 yosys，确保在 PATH 中
export PATH=$PATH:/path/to/yosys/bin
bash scripts/build-centos8.sh

# 跳过 yosys 构建
YOSYS_ENABLED=0 bash scripts/build-centos8.sh

3. 构建产物

构建完成后，产物位于：

dist/verilog-mcp-server-linux-x86_64.tar.gz

解压后得到单个可执行文件：

tar -xzf dist/verilog-mcp-server-linux-x86_64.tar.gz
./verilog-mcp-server --version

常见问题解决

1. Python 环境问题

问题: ImportError: undefined symbol: XML_SetReparseDeferralEnabled 解决:

# 重新安装 Python
conda install python=3.12 --force-reinstall

# 或者创建新的 conda 环境
conda create -n build python=3.10
conda activate build