Sentinel DV

Sentinel DV

[PyPI] [MCP Registry] [CI] [Documentation] [License]

Sentinel DV v2.3.1 is a read-only Model Context Protocol server for design verification evidence. It indexes exported SystemVerilog, UVM, cocotb, assertion, coverage, regression, and waveform artifacts into DuckDB and exposes 28 bounded, schema-driven tools to AI agents.

Documentation | Quick start | Video walkthrough | All tools | Agent skills

What it provides

• Run and test intelligence: discovery, summaries, history, topology, diffs, replay-command generation, and live-status snapshots.
• Failure analysis: normalized categories, stable signatures, bounded evidence, assertion failures, and failure clustering.
• Coverage closure: functional, code, toggle, and FSM metrics; trends; gaps; vacuity; SVA status; and protocol-aware constraint candidates.
• Waveform context: precomputed *.wave.json and bounded VCD summaries. Native FSDB/WLF streaming is intentionally out of scope.
• Agent workflows: regression triage, single-test failure debugging, and coverage closure skills for Codex, Claude Code, and GitHub Copilot.

Sentinel DV does not execute simulations, modify RTL or testbench files, or stream unrestricted raw artifacts. runs.submit and tests.replay return dry-run commands for engineer review.

Quick start

Python 3.10 or newer is required. This example indexes the checked-in demo corpus:

For a persistent environment, install sentinel-dv>=2.3.1. The commands below use uvx to run the same release without a persistent install.

git clone https://github.com/kiranreddi/sentinel-dv.gitcd sentinel-dvcp demo/config.example.yaml demo/config.yaml
uvx --from [email protected] \  sentinel-dv-index --config "$PWD/demo/config.yaml" --index-all

Connect one agent:

Codex

codex mcp add sentinel-dv \  --env SENTINEL_DV_CONFIG="$PWD/demo/config.yaml" \  -- uvx --from [email protected] sentinel-dv-server

Claude Code

claude mcp add \  --env SENTINEL_DV_CONFIG="$PWD/demo/config.yaml" \  --transport stdio --scope local sentinel-dv \  -- uvx --from [email protected] sentinel-dv-server

GitHub Copilot CLI

copilot mcp add sentinel-dv \  --env SENTINEL_DV_CONFIG="$PWD/demo/config.yaml" \  -- uvx --from [email protected] sentinel-dv-server

Use an absolute SENTINEL_DV_CONFIG path. Verify the connection in the client's MCP status view, then call runs.list.

See Agent setup for configuration-file examples, project scope, skill discovery, and troubleshooting.

Production configuration

Copy config.example.yaml and define allowed artifact roots:

artifact_roots:  - /absolute/path/to/regression/artifacts
index:  type: duckdb  path: ./sentinel_dv.db
adapters:  uvm: true  cocotb: true  assertions: true  coverage: true  waveform_summary: true
security:  max_response_bytes: 2097152  max_page_size: 200  max_evidence_refs: 10
redaction:  enabled: true  redact_emails: true  redact_paths: true

Build the index before starting the server:

sentinel-dv-index --config /absolute/path/to/config.yaml --index-allsentinel-dv-server --config /absolute/path/to/config.yaml

Relative paths inside the YAML are resolved from the config file's directory. Production startup never silently falls back to demo data.

MCP tools

The 28 tools are grouped by engineering purpose:

Every registered tool carries read-only MCP annotations and a versioned output schema. The MCP tools reference documents exact inputs and outputs.

Agent skills

The canonical skills live under skills/:

• sentinel-dv-regression-triage
• sentinel-dv-failure-debugging
• sentinel-dv-coverage-closure

Deterministic mirrors support project discovery:

The repository also contains Codex and Claude plugin manifests. .mcp.json defines the bundled stdio server command; provide SENTINEL_DV_CONFIG or a config.yaml in the server working directory.

After editing a canonical skill:

.venv/bin/python scripts/sync_agent_skills.py.venv/bin/python scripts/sync_agent_skills.py --check

Supported artifact sources

• UVM logs and topology hints
• cocotb and generic JUnit XML
• assertion definition and failure JSON
• SVA run-status JSON
• supported JSON, XML, text, and HTML coverage summaries
• *.wave.json and VCD
• live simulation status JSON
• exported VCS, Xcelium, Questa, and Verilator results

Adapter output is normalized into versioned schemas so clients do not need vendor-specific parsing logic.

Security model

• Tools are read-only and operate on an index plus configured artifact roots.
• Path resolution is sandboxed to allowed roots.
• Evidence counts, excerpts, pages, wave signals, bins, and total response size are bounded.
• Configurable redaction protects common secrets, email addresses, IP addresses, and local paths.
• Tool output is deterministic; the MCP server does not generate causal conclusions.

Read Security and Production deployment before using production artifacts.

Verification

Create a development environment:

python3 -m venv .venv.venv/bin/pip install -e ".[dev,docs]"

Run endpoint and workflow checks:

.venv/bin/python scripts/verify_all_mcp_tools.py.venv/bin/python scripts/verify_skill_workflows.py

Run the full quality suite:

.venv/bin/pytest.venv/bin/ruff check ..venv/bin/black --check ..venv/bin/mypy sentinel_dv.venv/bin/mkdocs build --strict

The all-tools verifier invokes every registered MCP endpoint. The skill verifier indexes 52 checked-in demo artifacts and executes the published regression triage, failure debugging, and coverage closure sequences.

Project layout

sentinel_dv/  adapters/        artifact parsers  indexing/        DuckDB indexing and queries  normalization/   signatures, taxonomy, redaction, coverage guidance  schemas/         versioned response contracts  tools/core.py    tool implementations  server.py        FastMCP registration and stdio entry point
skills/            canonical agent skillsdemo/              license-free exported verification fixturesdocs/              MkDocs documentationscripts/           verification, gallery, release, and skill-sync toolingtests/             unit and integration coverage

Contributing

See CONTRIBUTING.md. Sentinel DV is licensed under Apache-2.0.