Content
# naja-scope
<!-- mcp-name: io.github.najaeda/naja-scope -->
[](https://pypi.org/project/naja-scope/)
[](https://pypi.org/project/naja-scope/)
[](https://github.com/najaeda/naja-scope/actions/workflows/ci.yml)
[](LICENSE)
[](https://glama.ai/mcp/servers/najaeda/naja-scope)
**Let your AI assistant explore SystemVerilog designs — without pasting source code into the chat.**
naja-scope is an [MCP](https://modelcontextprotocol.io) server that gives AI
agents (Claude, and any MCP-compatible assistant) a precise, structured view of
your elaborated SystemVerilog design. Instead of dumping thousands of lines of
RTL into the model's context, the agent asks targeted questions — *what drives
this signal? what's inside this module? where does this net come from?* — and
gets back small, exact answers with file-and-line references.
Built on the [najaeda](https://github.com/najaeda/naja) netlist engine.
> **On a 17-question [CVA6](https://github.com/openhwgroup/cva6) benchmark,
> the same Claude Code agent scored 17/17 with naja-scope versus 10/17 with
> grep/read source tools — in 77 turns instead of 123, processing about 5×
> less input.** [How it was measured ↓](#does-it-actually-help)
```sh
pip install naja-scope
claude mcp add naja-scope -- naja-scope-mcp
```
---
## Why
Large designs don't fit in a chat window. Pasting RTL is slow, expensive, and
the model still can't reliably trace connectivity across hierarchy. naja-scope
turns your design into something an agent can *navigate*:
- 🔎 **Trace connectivity** — find what drives or loads any signal, across
module boundaries.
- 🌲 **Walk the hierarchy** — explore modules, instances, and ports on demand.
- 🎯 **Jump to source** — every answer comes with `file:line` ranges, so the
agent can quote the exact RTL that matters.
- 🧩 **Logic cones** — trace fan-in / fan-out combinational cones up to the
register boundary.
- 💡 **Recover design intent** — enum state names, struct/union fields, and
parameter formulas that normally vanish when a design is elaborated.
Works on **RTL and gate-level netlists** alike: load elaborated SystemVerilog,
or load a post-synthesis structural Verilog netlist together with its Liberty
standard-cell library and navigate the gates the same way (see
[Gate-level designs](#gate-level-designs)). VHDL loading is in
[beta](#vhdl-beta).
All responses are token-bounded: lists paginate, large results truncate with
clear markers. Your context stays small; your answers stay accurate.
---
## Does it actually help?
naja-scope helps most when the answer exists in the elaborated design rather
than in any single source file. In an initial 17-question run on the
`cv32a6_imac_sv32` configuration of
[CVA6](https://github.com/openhwgroup/cva6), the same Claude Code agent was
tested with naja-scope and with source-search tools alone.
| Agent setup | Provider and models | Initial automated score | Turns | Input processed | Output tokens |
|---|---|---:|---:|---:|---:|
| **Agent + naja-scope** | Anthropic Claude Code; `claude-sonnet-4-6` with `claude-haiku-4-5-20251001` helper | **17 / 17** | **77** | **1,058,556** | **19,520** |
| Agent + grep/read source | Anthropic Claude Code; `claude-sonnet-4-6` with `claude-haiku-4-5-20251001` helper | 10 / 17 | 123 | 5,461,719 | 55,962 |
The difference is clearest on structural questions that source search cannot
answer directly:
| CVA6 question | Agent + naja-scope | Agent + grep/read source |
|---|---|---|
| Flattened register groups under `ex_stage_i` | **92**, in 4 turns | No answer at the turn limit |
| Flattened register groups under `commit_stage_i` | **0**, in 3 turns | No answer at the turn limit |
| Elaborated `hpdcache_mux` variants | **20**, in 3 turns | No answer at the turn limit |
Source search remains the right tool for local textual questions. naja-scope
adds the elaborated hierarchy, connectivity, lowered primitives, and generated
or uniquified structures that are otherwise difficult to reconstruct.
See the [benchmark methodology and multi-model runner](benchmarks/README.md)
and [historical result record](benchmarks/historical-cva6-20260628.json) for
configuration, scoring, token accounting, and reproducibility details.
---
## Install
```sh
pip install naja-scope # pulls najaeda and the MCP runtime from PyPI
naja-scope-mcp # stdio MCP server
```
---
## Connect it to Claude Code
```sh
claude mcp add naja-scope -- naja-scope-mcp
```
Or add it to any MCP client's config:
```json
{
"mcpServers": {
"naja-scope": {
"command": "naja-scope-mcp"
}
}
}
```
Then just ask your assistant to load a design and start exploring:
> *"Load my UART design from `rtl/uart.sv` with top `uart_top`, then show me
> everything that drives `tx_o`."*
The agent loads the design once and answers follow-up questions instantly — no
re-reading source, no giant pastes.
---
## Connect it to ChatGPT
ChatGPT connects to MCP servers over an **HTTP endpoint** (custom connectors /
Developer mode), so run naja-scope as an HTTP server instead of stdio:
```sh
naja-scope-mcp --transport streamable-http --host 127.0.0.1 --port 8000
```
This serves MCP at `http://<host>:8000/mcp`. Because ChatGPT reaches the server
over the network, expose that URL where ChatGPT can see it — e.g. a public
tunnel for a local run:
```sh
# example: a tunnel to your local server (ngrok, cloudflared, …)
ngrok http 8000 # -> https://<something>.ngrok.app → add /mcp
```
Then in ChatGPT, open **Settings → Connectors** (enable Developer mode if
needed), **add a custom connector**, and paste the server URL
(`https://<your-host>/mcp`). Once connected, ask it to load a design and explore
exactly as above. (ChatGPT's connector UI evolves; the constant is: it needs an
HTTPS MCP URL, which `--transport streamable-http` provides.)
> ⚠️ The HTTP server has no built-in auth — only expose it over a trusted tunnel,
> and prefer short-lived tunnels for local experiments.
---
## Gate-level designs
Already synthesized? Load the structural Verilog netlist together with the
Liberty library that defines its standard cells, and navigate the gates the same
way as RTL:
> *"Load the Liberty library `pdk/stdcells.lib`, then the gate netlist
> `build/top.v`, and tell me what cells `top` is built from and what drives
> `data_out`."*
Hierarchy, per-cell counts (`get_module_card`), drivers/loads, and logic cones
all work on the netlist; cones stop at the sequential cells. A gate netlist
carries no source line info, so `get_source` applies to RTL only. A runnable
example lives in [`examples/`](examples/) (`stdcells.lib` + `counter2.v` +
`gate_level.py`).
---
## VHDL (beta)
VHDL loading is available in beta with najaeda 0.7.25 or newer. Call
`load_vhdl(file="/path/to/design.vhd", top="my_entity")` to explore its
elaborated hierarchy and connectivity. Load dependencies/packages first,
one file per call; package-only files may return `top: null` until the top
file is loaded. The frontend supports a restricted two-state RTL subset,
and supported constructs may change. `get_intent`/`load_intent` remain
SystemVerilog-only; VHDL source ranges are not guaranteed.
---
## What you can ask
Once a design is loaded, your assistant can:
- **Resolve** any signal or instance by hierarchical path (with glob and
did-you-mean suggestions).
- **Find** objects design-wide by pattern.
- **Show the hierarchy** of any module.
- **Get drivers / loads** of a net — the real endpoints, across hierarchy;
literal drivers preserve four-state `0` / `1` / `X` / `Z` values.
- **Trace logic cones** (fan-in / fan-out) and see the register frontier.
- **Get source** — the exact SystemVerilog lines behind any object.
- **Get a module card** — ports, counts, clock/reset at a glance.
- **Recover design intent** — state-machine names, struct fields, parameter
expressions lost during elaboration.
A runnable end-to-end walkthrough lives in [`examples/`](examples/), including
versions that run against [CVA6](https://github.com/openhwgroup/cva6) (a
production RISC-V core, cloned on demand — see
[`examples/cva6_demo.sh`](examples/cva6_demo.sh)) and
[CORE-V-MCU](https://github.com/openhwgroup/core-v-mcu) (a full multi-vendor
RISC-V SoC — see [`examples/core_v_mcu_demo.sh`](examples/core_v_mcu_demo.sh)).
---
## The Python escape hatch (off by default)
naja-scope also has a `query_python` tool that runs Python directly against the
loaded design, for queries the typed tools above cannot express. **It is not
registered unless you opt in:**
```bash
NAJA_SCOPE_ENABLE_PYTHON=1 naja-scope-mcp
```
It is unsandboxed `eval`/`exec` inside the server process — read-only by
convention, not enforced — so anything that can reach the server can run
arbitrary Python as the server's user. That matters most under `--transport
streamable-http`, where the server listens on a socket. Leave it off unless you
need it and trust every client that can reach the endpoint.
---
## Requirements
- Python 3.10+
- Works anywhere `najaeda` runs (Linux, macOS, Windows)
---
## Development
```sh
# from a checkout
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m pytest -q
```
The full test suite runs against a plain `pip install` of `najaeda` — no native
build required. The CVA6 cross-hierarchy cone regression
(`tests/test_zzz_cone_cva6.py`) is slow and skips automatically unless a CVA6
snapshot is present.
CI tests every supported Python version on Linux x86_64, plus native platform
lanes for Linux x86_64/aarch64, macOS x86_64/arm64, and Windows x86_64. The
macOS x86_64 lane builds `najaeda` from its source distribution because PyPI
does not currently provide an Intel macOS wheel.
---
## Support & contact
- 🐛 **Found a bug or have a feature request?**
[Open an issue on GitHub →](https://github.com/najaeda/naja-scope/issues)
- 📫 **Get in touch:** [contact@keplertech.io](mailto:contact@keplertech.io)
---
## License
Apache-2.0. See [LICENSE](LICENSE).
</content>
</invoke>
## Optional browser schematic
Requires **naja-schematic 0.1.6 or later** (the release containing the
embeddable viewer API):
```bash
pip install "naja-scope[schematic]"
```
Restart the MCP server after installation. Load a design as usual, then use:
- `open_schematic(path="top.u_cpu")`: returns a local browser URL and focuses
the instance. Omit `path` for the top. Anonymous `#id` instances are supported.
- `annotate_schematic(items=[{"path": "top.u_cpu", "message": "Check reset",
"severity": "warning"}])`: replaces the overlay. Use `kind="term"` with a
pin/port path to annotate that terminal; annotations apply to the whole port,
not individual bus bits. Pass `items=[]` to clear. At most 200 annotations,
each with at most 2000 message characters.
- `get_schematic_selection()`: returns the last clicked instance as a regular
naja-scope path, usable with source, hierarchy and module-card queries.
The viewer shares the existing raw naja universe; it does not elaborate again.
The server binds to loopback and returns a token-bearing URL. Open that URL on
**the machine running the MCP server**; it is not a remote or embedded MCP UI.
Treat the URL as access to the loaded design. Design loads/resets refresh open
viewers and clear selection, focus and annotations. The browser server stops
with naja-scope. Existing tools remain usable without the schematic extra.
Connection Info
You Might Also Like
No recommendations available