Metadata-Version: 2.4
Name: naja-scope
Version: 0.1.25
Summary: Agent-facing MCP query layer over najaeda: navigate elaborated SystemVerilog and VHDL designs without loading source into context.
Author-email: Kepler Technologies <contact@keplertech.io>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/keplertech/naja-scope
Project-URL: Repository, https://github.com/keplertech/naja-scope
Project-URL: Issues, https://github.com/keplertech/naja-scope/issues
Keywords: mcp,systemverilog,vhdl,eda,netlist,rtl,najaeda,llm,agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: najaeda>=0.7.35
Requires-Dist: mcp<2,>=1.28
Provides-Extra: schematic
Requires-Dist: naja-schematic<0.3,>=0.2.0; extra == "schematic"
Dynamic: license-file

# naja-scope

<!-- mcp-name: io.github.keplertech/naja-scope -->

[![PyPI version](https://img.shields.io/pypi/v/naja-scope.svg)](https://pypi.org/project/naja-scope/)
[![Python versions](https://img.shields.io/pypi/pyversions/naja-scope.svg)](https://pypi.org/project/naja-scope/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/keplertech/naja-scope/blob/main/LICENSE)
[![Install in VS Code](https://raw.githubusercontent.com/keplertech/naja-scope/main/docs/images/badges/install-vscode.svg)](https://insiders.vscode.dev/redirect/mcp/install?name=naja-scope&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22naja-scope%22%5D%7D)
[![Install in Cursor](https://raw.githubusercontent.com/keplertech/naja-scope/main/docs/images/badges/install-cursor.svg)](https://cursor.com/en/install-mcp?name=naja-scope&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJuYWphLXNjb3BlIl19)

**Let your AI assistant explore SystemVerilog and VHDL 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 or VHDL 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](https://github.com/keplertech/naja-scope#does-it-actually-help)

```sh
claude mcp add naja-scope -- uvx naja-scope
```

No separate install step: [`uvx`](https://docs.astral.sh/uv/) fetches naja-scope
and najaeda from PyPI on first launch. The buttons above do the same for VS Code
and Cursor. Prefer pip? See [Install](#install).

See it in action: [demo recording](https://github.com/keplertech/naja-scope#naja-scope).

---

## 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.

Requires **najaeda 0.7.35 or newer**. See the
[0.1.25 release notes](https://github.com/keplertech/naja-scope/blob/main/docs/releases/0.1.25.md)
for test results and snapshot migration requirements.

Works on **RTL and gate-level netlists** alike — load elaborated SystemVerilog
or VHDL ([beta](#vhdl-beta)), or a post-synthesis structural Verilog netlist
plus its Liberty standard-cell library (see
[Gate-level designs](#gate-level-designs)).

`get_module_card` reports direct-child register bits and inferred RAM/ROM
summaries: width, depth, capacity in bits, read/write port counts, and
initialization status. Native memory interfaces also report `address_bits`
and `reset_mode` (`none`, `async_low`, `async_high`, `sync_low`, or
`sync_high`). It lists up to 12 memories, with `memories_truncated`
when more exist; initialized memories include a 64-character `init_preview`
and `init_truncated`. Address zero occupies the least-significant word.

`get_stats` aggregates these counts below the selected instance using
`flat_register_bits`, `flat_memory_instances`, `flat_rom_instances`,
`flat_ram_instances`, and `flat_memory_bits`. Register bits count modeled
flip-flop/latch states, including multibit Liberty banks; RAM capacity is
separate. Sequential cells without a state model are counted in
`register_bits_unknown_instances` (`flat_` in statistics), so known bit
counts remain explicit lower bounds when that count is nonzero. Memories
are recognized from native naja primitives; opaque memory macros are not
assigned an inferred capacity.

`get_content_hash()` returns a versioned SHA-256 of the top model and its
descendants; pass `module="uart_tx"` to hash one elaborated model. Use it to
compare loaded content across snapshot reloads or netlist edits. Compare only
within the same `format_version`, and track `naja_git_hash` separately when
primitive semantics matter. Names and IDs participate; source metadata and
primitive definitions are excluded. This is not functional equivalence.
Hashing is explicit because large hierarchies can take time.

Tools send compact JSON text alongside the same structured result.
`get_stats()` returns summary counts with an empty `models` list; pass
`limit=5` for model details, or use its `next_cursor` to start paging
(cursor-only pages default to 25 models; maximum 200).
`find`, `get_drivers`, and `get_loads` default to 20 entries, with explicit
limits up to 200. Continue `find` with `next_cursor`; for endpoints, check
`truncated` and increase `limit` or query an individual bus bit.
Explicit large limits and deep hierarchy queries can still exceed client
output caps. Record the naja-scope version when comparing benchmark token
counts across these changes.

---

## 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](https://github.com/keplertech/naja-scope/tree/main/benchmarks)
and [historical result record](https://github.com/keplertech/naja-scope/blob/main/benchmarks/historical-cva6-20260628.json)
for configuration, scoring, token accounting, and reproducibility details.

---

## Install

```sh
pip install naja-scope
```

That's it — `najaeda` and the MCP runtime come along automatically.

---

## Connect it to Claude Code

```sh
claude mcp add naja-scope -- uvx naja-scope      # with uv, no install step
claude mcp add naja-scope -- naja-scope-mcp      # after pip install naja-scope
```

Or add it to any MCP client's config:

```json
{
  "mcpServers": {
    "naja-scope": {
      "command": "uvx",
      "args": ["naja-scope"]
    }
  }
}
```

(With a pip install, use `"command": "naja-scope-mcp"` and no `args`.)

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`. Expose that URL where ChatGPT can
reach it (e.g. an `ngrok`/`cloudflared` tunnel for a local run), then in ChatGPT
open **Settings → Connectors**, **add a custom connector**, and paste the URL
(`https://<your-host>/mcp`). The HTTP server has no built-in auth — only expose
it over a trusted tunnel.

---

## 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, drivers/loads, and logic cones all work on the
netlist; cones stop at the sequential cells. `get_source` shows an object's
line in the netlist, and for Yosys output `yosys_source_attributes=True` adds
`origins` that `get_source(path, origin=0)` reads back in the RTL.

---

## SystemVerilog time units

For mixed RTL where only some modules declare a time unit, pass
`default_timescale="1ns/1ps"` to `load_systemverilog`. It supplies a fallback
for modules without a time unit and preserves explicit declarations. The
setting survives snapshots and `load_intent` re-elaboration.

## VHDL (beta)

VHDL loading is available in beta. Call
`load_vhdl(file=["pkg.vhd", "child.vhd", "top.vhd"], top="my_entity")` to
explore its elaborated hierarchy and connectivity; the files may be listed in
any order. A single path per call also works (load packages first);
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_source` reads VHDL entity, port,
signal, instance and process origins, including after snapshot reloads.

Designs that name their library, as in `library neorv32;`, need
`library="neorv32"` on the load.

Pass `intent=True` to `load_vhdl`, or call `load_intent` afterwards, to query
`get_intent` for enum literals and their encodings, including FSM states held
in record fields, record fields, generics, and symbolic ranges such as
`WIDTH-1 downto 0`. Package members use `pkg::NAME`, and an instance's parameter
list leaves them out. Query the signal rather than its inferred flop, and note
that record fields report widths, not bit positions. Validated on the
[NEORV32](https://github.com/stnolting/neorv32) SoC.

---

## 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 source 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.

---

## Requirements

- Python 3.10+
- Works anywhere `najaeda` runs (Linux, macOS, Windows)

---

## Support & contact

- 🐛 **Found a bug or have a feature request?**
  [Open an issue on GitHub →](https://github.com/keplertech/naja-scope/issues)
- 📫 **Get in touch:** [contact@keplertech.io](mailto:contact@keplertech.io)

---

## License

Apache-2.0. See [LICENSE](https://github.com/keplertech/naja-scope/blob/main/LICENSE).

## Optional browser schematic

Requires **naja-schematic 0.2.0 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.
