🛡️ Sentinel DV v2.3.0 - Verification Intelligence for AI Agents

<!-- mcp-name: io.github.kiranreddi/sentinel-dv -->

<div align="center">

A security-first MCP server for verification intelligence (SystemVerilog/UVM/cocotb)

Features • Architecture • Quick Start • Documentation

</div>

---

🌟 What is Sentinel DV?

Sentinel DV is an open-source Model Context Protocol (MCP) server that provides large language models and AI agents with safe, structured, read-only access to verification artifacts—enabling deterministic triage, root-cause analysis, and verification insight without exposing raw logs or granting control of simulators.

Verification Ecosystems Supported

• 🔧 UVM (Universal Verification Methodology) - Enterprise verification framework
• 🐍 cocotb - Python-based verification with coroutines
• 📊 SystemVerilog - Assertions, coverage, and native testbenches
• 🌊 Waveform summaries - *.wave.json and *.vcd via built-in parsers (no raw FSDB/WLF streaming)

All through a unified, schema-driven interface with built-in security, redaction, and deterministic outputs.

---

🏗️ Architecture

Sentinel DV follows a strict separation of concerns with security-first principles:

sentinel_dv/
├── server.py              # MCP server entrypoint
├── config.py              # Security limits, feature flags, governance
├── registry.py            # Tool registration and versioning
├── schemas/               # Typed contracts for all data
│   ├── common.py         # EvidenceRef, RunRef, base types
│   ├── tests.py          # TestCase, TestTopology, UvmTopology
│   ├── failures.py       # FailureEvent, FailureSignature
│   ├── assertions.py     # AssertionInfo, AssertionFailure
│   ├── coverage.py       # CoverageSummary, CoverageMetric
│   ├── regressions.py    # RegressionSummary, RunDiff
│   └── versioning.py     # Schema version management
├── tools/                 # MCP tools (discovery + detail)
│   ├── runs.py           # runs.list, runs.diff
│   ├── tests.py          # tests.list, tests.get, tests.topology
│   ├── failures.py       # failures.list
│   ├── assertions.py     # assertions.list/get/failures
│   ├── coverage.py       # coverage.list/summary
│   ├── regressions.py    # regressions.summary
│   └── wave.py           # wave.summary, wave.signals
├── indexing/              # Artifact indexing and querying
│   ├── indexer.py        # Build normalized index from artifacts
│   ├── store.py          # DuckDB storage interface
│   └── query.py          # Filter/sort/pagination
├── adapters/              # Parse verification artifacts
│   ├── uvm_log.py        # UVM log parsing
│   ├── cocotb.py         # cocotb result parsing
│   ├── assertion_reports.py # Assertion report/log parsing
│   ├── coverage_reports.py  # Coverage summary parsing
│   ├── protocol_tags.py     # Protocol taxonomy hints (AXI/APB/AHB/...)
│   ├── waveform_summary.py  # Precomputed *.wave.json
│   └── vcd_summary.py       # VCD → bounded summary (Verilator, etc.)
├── normalization/         # Security and determinism
│   ├── signatures.py     # Stable failure signature hashing
│   ├── taxonomy.py       # Failure categorization
│   └── redaction.py      # Automatic secret/PII redaction
└── utils/                 # Common utilities
    ├── hashing.py
    ├── time.py
    └── bounded_text.py

Design Principles:

• Read-only by default - No simulator control, no artifact modification
• Schema-first - Every response conforms to typed contracts
• Deterministic - Same input → same output (no LLM-generated fields)
• Evidence-based - All facts traceable to source artifacts
• Bounded and safe - Automatic redaction, size limits, path sandboxing

---

✨ Features

🔒 Security First

• Read-only by design - No simulation triggers or artifact writes
• Automatic redaction - Credentials, tokens, emails, IP addresses, paths
• Path sandboxing - Only configured artifact roots accessible
• Bounded outputs - Max response sizes, max evidence excerpts
• Provenance tracking - Every fact includes optional source references

📊 Rich Verification Data

• Test results - Status, duration, seed, simulator info, DUT config
• UVM topology - Env/agent/driver/monitor/scoreboard hierarchy
• Failure analysis - Categorized events (assertion/scoreboard/protocol/timeout)
• Assertion intelligence - SVA definitions, runtime failures, intent mapping
• Coverage metrics - Functional/code/assertion/toggle/FSM coverage
• Regression analytics - Pass rates, failure signatures, run diffs
• Interface bindings - Protocol mapping (AXI/AHB/APB/PCIe/USB)

⚡ Performance & Scale

• Efficient indexing - DuckDB for fast filtering and aggregation
• Smart pagination - Bounded result sets with stable sorting
• Normalized storage - Deduplicated, hashed artifacts
• Selective projection - Request only needed fields

🔌 Simulator Agnostic

• Works with any simulator (Synopsys VCS, Cadence Xcelium, Mentor Questa, Verilator)
• Adapter pattern - Ingest tool-specific formats, output unified schemas
• Pre-computed summaries - No runtime dependency on EDA tools

📋 Schema-Driven Contracts

• Versioned schemas - SemVer with compatibility guarantees
• JSON Schema validation - Deterministic, testable
• Stable tool APIs - Backwards-compatible evolution
• Self-documenting - Schemas define the interface

---

🚀 Quick Start

PyPI: Use sentinel-dv>=2.3.0 for commercial simulator fixtures (VCS, Questa, Cadence), multi-project demos, 28 MCP tools (v2.0 submission/SVA/replay + v2.1 DV intelligence), assertion/coverage intelligence, and waveform indexing.

Install from MCP Registry

Install via uv (uvx) or your MCP client’s registry UI using server name io.github.kiranreddi/sentinel-dv.

Claude Desktop / MCP client (stdio):

{
  "mcpServers": {
    "sentinel-dv": {
      "command": "uvx",
      "args": [
        "--from",
        "sentinel-dv@2.3.0",
        "sentinel-dv-server",
        "--config",
        "/absolute/path/to/config.yaml"
      ]
    }
  }
}

Alternatively set SENTINEL_DV_CONFIG to your config path and omit --config.

Before querying: build the artifact index (required once per config):

uvx --from sentinel-dv@2.3.0 sentinel-dv-index --config /absolute/path/to/config.yaml --index-all

Installation

# Clone the repository
git clone https://github.com/kiranreddi/sentinel-dv.git
cd sentinel-dv

# Install with development dependencies
pip install -e ".[dev]"

# Or production install (requires >=2.3.0 for all 28 MCP tools)
pip install "sentinel-dv>=2.3.0"

Configuration

Required: copy config.example.yaml to config.yaml (or set SENTINEL_DV_CONFIG / pass --config). The server does not start without a config file and does not auto-use demo/.

Create a config.yaml:

# Artifact roots (read-only)
artifact_roots:
  - /path/to/verification/regressions
  - /path/to/uvm/logs

# Index storage
index:
  type: duckdb
  path: ./sentinel_dv.db

# Adapters (enable/disable)
adapters:
  uvm: true
  cocotb: true
  assertions: true
  coverage: true
  waveform_summary: true   # *.wave.json and *.vcd under artifact_roots

# Security & limits
security:
  max_response_bytes: 2097152  # 2MB
  max_page_size: 200
  max_evidence_refs: 10
  max_excerpt_length: 1024

# Redaction
redaction:
  enabled: true
  patterns:
    - AKIA.*           # AWS keys
    - ghp_.*           # GitHub tokens
    - Bearer\s+\S+     # Bearer tokens
  redact_emails: true
  redact_paths: true

Running the Server

# Start the MCP server
python -m sentinel_dv.server --config config.yaml

# Index artifacts (one-time or scheduled)
python -m sentinel_dv.indexing.indexer --config config.yaml --index-all

# Run with Claude Desktop
# Add to Claude config:
{
  "mcpServers": {
    "sentinel-dv": {
      "command": "python",
      "args": ["-m", "sentinel_dv.server", "--config", "/path/to/config.yaml"]
    }
  }
}

Example Queries

With Claude or any MCP client:

"Why did test axi_burst_test fail in the latest regression?"
→ Uses: tests.list, failures.list, tests.topology

"What assertions failed in the AXI agent?"
→ Uses: assertions.failures, assertions.get

"Compare coverage between runs R123 and R124"
→ Uses: runs.diff, coverage.summary

"Show me the failure signatures from the past week"
→ Uses: regressions.summary

---

📖 Documentation

Core Concepts

• Architecture Overview - Design principles and structure
• Schema Reference - Complete type definitions
• Tool Contracts - Request/response specifications
• Security Model - Redaction, bounding, sandboxing

Examples

• Examples overview — VCS, Questa, Cadence, Verilator, cocotb, and UVM artifact fixtures
• MCP tool gallery — SVG “screenshots” for all 28 tools
• Verilator + VCD — Build, index, query wave.* with time windows
• VCS, Questa, and Cadence — Exported artifact fixtures and all-tool verification
• cocotb + waveforms — Index demo/ tree
• demo/ — Runnable artifacts (multi-project UVM, cocotb, Verilator, VCS, Questa, Cadence)

Guides

• Waveform summaries - JSON + VCD indexing
• Getting Started - Setup and first queries
• Adapter Development - Parse new artifact formats
• Simulator Support - Vendor-specific notes
• Deployment Guide - Production best practices

Reference

• Documentation Site
• Configuration Reference
• Examples - Demo artifacts and clients

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Code of Conduct
• Development setup
• Testing guidelines
• Pull request process

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=sentinel_dv --cov-report=html

# Lint and format
ruff check .
black .
mypy sentinel_dv/

---

📊 Project Status

• ✅ Core schemas - Stable v1.0
• ✅ MCP tools - 28 tools (discovery, analysis, regression, waveforms, v2.0 workflow, v2.1 DV intelligence, v2.3 run/test aggregation)
• ✅ Adapters - UVM, cocotb, assertions, coverage
• ✅ Indexing - DuckDB with efficient querying
• ✅ Security - Redaction, sandboxing, bounding
• ✅ Test coverage - 70%+ with unit and integration tests
• ✅ Documentation - Full guides and API reference
• ✅ Waveform summaries - *.wave.json + *.vcd (VcdSummaryParser); Verilator demo
• ✅ Simulator examples - VCS, Questa, and Cadence exported artifact fixtures with all-tool verification
• 🚧 Plugin ecosystem - Coming soon

---

🎯 Positioning

What Sentinel DV is

• A read-only MCP server for verification ecosystems
• A schema-first context provider for agents and LLMs
• A deterministic translation layer from noisy artifacts to typed data
• A composable infrastructure component for debug workflows

What Sentinel DV is not

• ❌ It does not start simulations or submit jobs
• ❌ It does not modify RTL/testbench code
• ❌ It does not require any specific simulator
• ❌ It is not an "AI that guesses"; it returns grounded, typed facts

---

🙏 Acknowledgments

Inspired by:

• Sentinel CI - Universal CI/CD intelligence
• Model Context Protocol - Anthropic's agent-context standard
• The verification community using UVM, cocotb, and SystemVerilog

---

📄 License

Apache License 2.0 - see LICENSE for details.

---

🔗 Links

• 🌐 Documentation
• 💬 Discussions
• 🐛 Issue Tracker
• 📣 Changelog

---

<div align="center">

Built with ❤️ for the verification community

⬆ back to top

</div>