pyslang-mcp

pyslang-mcp

pyslang-mcp は、Verilog および SystemVerilog のプロジェクトに対して、AI エージェントにコンパイラーに基づく読み取り専用のコンテキストを提供する、ローカルの Model Context Protocol サーバーです。

pyslang をラップしているため、MCP クライアントはプレーンテキストではなく、パースおよびエラボレーションされた HDL に対して質問できます。

• このファイルリストには、どのモジュール、インターフェース、パッケージが含まれていますか？
• コンパイラーフロントエンドはどの診断を報告しますか？
• このトップの下には、どのようなインスタンス階層がありますか？
• このシンボルはどこで宣言または参照されていますか？
• インクルードパス、定義、ネストされた .f ファイルは、想定どおりに解決されましたか？

これは、シミュレーター、シンセサイザー、波形ビューアー、リンターの代替、RTL リファクタリングツールではありません。ローカルの HDL チェックアウト向けの、小規模なセマンティック解析サービスです。

この読み取り専用という制約は意図的なものです。サーバーの副作用を防ぎ、IP で保護されたワークスペースでの影響範囲を抑え、ローカル環境や CI 環境でより安全に使用できるようにします。

pyslang-mcp は読み取り専用にすることにしました。実際の RTL コーディングは LLM が担い、pyslang-mcp は、既存のコードをコンパイルおよびエラボレーション結果に基づいて読み取り、チェックし、説明します。つまり、モデルが RTL を作成し、MCP サーバーがコンパイラーフロントエンドから見える内容を検証します。

メモ

このプロジェクトは現在、初期段階にあり、ローカルの stdio 使用向けに PyPI と MCP Registry で公開されています。

ASIC および EDA エンジニアに役立つ理由

多くの AI コーディングツールは、テキストの検索が得意です。しかし、通常 HDL には、それ以上の情報が必要です。

実際のプロジェクトで有用な回答を得るには、多くの場合、ファイルリスト、パッケージ、インクルード、定義、generate ブロック、階層に依存します。pyslang-mcp は、サーバーを読み取り専用に保ち、指定されたプロジェクトルートの範囲内に限定しながら、エージェントにコンパイラーに基づく構造の概要を提供します。

適した用途：

• エージェントに RTL の推論を依頼する前に、パースおよびセマンティック診断をトリアージする
• .f ファイルがどのように展開されるかを確認する
• ブロックまたは小規模な IP 内のデザインユニットを一覧表示する
• コメントや古い grep 結果をたどらずに宣言を見つける
• レビューやデバッグのプロンプト向けに、階層とポート接続のコンテキストを取得する
• EDA ランタイムを渡さずに、ワークフローエージェントへ 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 を指定する必要があります。ソースパス、ファイルリスト、インクルードディレクトリには絶対パスまたは相対パスを指定できますが、すべてそのルート配下に収める必要があります。

最小限のツールペイロード

明示的に指定したファイルを解析します：

{
  "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
1 つの設計単位を調べる	pyslang_describe_design_unit
展開されたインスタンスツリーをたどる	pyslang_get_hierarchy
宣言と参照を検索する	pyslang_find_symbol
1 つの設計単位内でローカルメンバーを検索する	pyslang_find_member
信号に関連する代入を検索する	pyslang_get_assignments
範囲を限定して構造的な接続を追跡する	pyslang_trace_connectivity
1 つのインスタンスのポート接続をダンプする	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. 1 つのインスタンスのポート接続の状況には、pyslang_get_instance_connections を使います。
5. 代入とインスタンスのポート接続を通る、範囲を限定した構造的な経路には、pyslang_trace_connectivity を使います。

接続追跡は、フロントエンドが提示する構造的な情報です。シミュレーション、形式的証明、CDC/RDC サインオフ、タイミングサインオフ、または完全なネットリストレベルのドライバー／ロードデータベースではありません。

ファイルリストのサポート

現在のパーサーは、多くの RTL フローで使われている実用的なサブセットを意図的にサポートしています。

• ソースファイルのエントリー
• -f と -F を使ったネストされたファイルリスト
• +incdir+...、-I dir、-Idir によるインクルードディレクトリ
• +define+...、-D NAME、-DNAME による定義

サポート対象外のファイルリストトークンは、黙って無視せず、ツールの出力で報告されます。

エージェントのプロンプト例

コンパイラーに基づくコンテキストが重要な場合は、このサーバーを使用してください。

• 「+define+DEBUG を指定して compile/project.f を解析し、診断をソースファイル別にグループ化してください。」
• 「このプロジェクト内のすべての設計単位を一覧表示し、トップモジュールと思われるものを特定してください。」
• 「top から深さ 4 までのインスタンス階層を表示してください。」
• 「モジュール axi_dma_top について、ポート、子インスタンス、宣言名を説明してください。」
• 「payload_valid の宣言と参照を検索してください。」
• 「エラボレーターから見える範囲で、legacy_widget がどこかにインスタンス化されているか確認してください。」
• 「このファイルリストから、解決されたファイル、インクルードディレクトリ、定義、サポート対象外のエントリーを表示してください。」

1 行の質問、コメント、名前の検索、または部分的／未完成なソースセットの場合は、通常の rg、エディター検索、またはファイルの直接読み込みのほうが速く、明確です。

ガードレール

• 読み取り専用の MCP ツールです。RTL の編集、フォーマット、シミュレーション、合成は行いません。
• プロジェクトルート内に厳密にスコープを限定します。project_root の外にあるパスは拒否されます。
• 大きな結果セットには切り詰めメタデータを付与した、コンパクトな JSON レスポンスを返します。
• プロセス内キャッシュは、プロジェクト設定と追跡対象ファイルの更新時刻をキーとして使用します。
• pyslang_preprocess_files は要約を目的としています。プリプロセッサのメタデータとソースの抜粋を返しますが、完全な単独プリプロセス済みストリームを保証するものではありません。
• streamable-http は引き続き実験的です。内部の MaaS 経路では、単一サーバーでの使用向けにベアラートークンでラップしていますが、それ自体で完全な本番環境向けホスト型セキュリティ境界となるものではありません。

リモート MaaS の方針

リモート MaaS は、汎用的なホスト型モードとしてではなく、2 つの別々の方向で計画されています。

• プラン A：パブリック OSS MaaS。 公開されているオープンソース HDL リポジトリ向けの利便性重視のデモサービスです。独自仕様または機密の RTL には適していません。
• プラン B：社内 MaaS。 企業が自社ネットワーク内で、社内リポジトリ、認証、ロギング、セキュリティ制御の近くで運用するためのセルフホスト型デプロイパターンです。

単一の社内サーバーを使う場合は、社内 MaaS クイックスタートから始めてください。プラン A／プラン B の詳細な区分については、REMOTE_DEPLOYMENT.mdを参照してください。

Python のセットアップに関する問題を避けられ、RTL のチェックアウトを読み取り専用でマウントできるため、Docker Compose を使った起動を推奨します。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 スキルとの併用

エージェント環境にrtl-analysis、rtl-audit、llm-based-verilog-analysisなど、より広範な RTL スキルがすでにある場合は、そのスキルの下位にある細粒度のコンパイラー証拠レイヤーとしてpyslang-verilog-contextを使用してください。

推奨する設定手順：

1. MCP クライアントでpyslang-mcpサーバーを設定し、エージェントが読み取り専用の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 レビューポリシーは広範なスキルで扱いながら、Verilog／SystemVerilog の構造、診断、階層、シンボル、インクルード、ファイルリストをpyslangに基づいて把握できます。

評価ベンチマーク

このリポジトリには、skills/pyslang-verilog-context/evals以下にpyslang-verilog-contextスキルの評価スイートが、reports/以下に比較レポートが含まれています。現在のベンチマークでは、ローカルの証拠モードを 3 種類比較しています。

• スキルなし／テキスト：ソースとファイルリストのテキストヒューリスティックのみ
• スキルなし／MCP：対象を絞ったpyslang-mcpツール呼び出し
• スキル＋MCP：pyslang-mcpを使ったpyslang-verilog-contextの順次実行

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、タイミング、形式検証、または完全なリンティングのサインオフを行うものではありません。

ドキュメントのみの評価／レポートの更新では、PyPI のリリースは不要です。パッケージコード、公開ツールの動作、スキーマ、ランタイム依存関係、CLI の動作、またはユーザー向けのインストール／ランタイムドキュメントが変更され、その変更が公開済みのユーザーに必要となる場合は、PyPI のリリースが妥当です。

プロジェクトの状況

実装済み：

• FastMCP stdio サーバー
• 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 を参照してください。