sentinel-dv

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

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

<div align="center">

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/sentinel-dv.svg)](https://pypi.org/project/sentinel-dv/)
[![MCP Registry](https://img.shields.io/badge/MCP-io.github.kiranreddi%2Fsentinel--dv-purple)](https://registry.modelcontextprotocol.io/?search=io.github.kiranreddi/sentinel-dv)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
[![CI](https://github.com/kiranreddi/sentinel-dv/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kiranreddi/sentinel-dv/actions/workflows/ci.yml)
[![Documentation](https://github.com/kiranreddi/sentinel-dv/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/kiranreddi/sentinel-dv/actions/workflows/docs.yml)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
[![Coverage](https://img.shields.io/badge/coverage-70%25+-brightgreen.svg)](tests/)

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

[Features](#-features) • [Architecture](#-architecture) • [Quick Start](#-quick-start) • [Documentation](#-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](https://docs.astral.sh/uv/) (`uvx`) or your MCP client’s registry UI using server name `io.github.kiranreddi/sentinel-dv`.

**Claude Desktop / MCP client (stdio):**

```json
{
  "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):

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

### Installation

```bash
# 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`:

```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

```bash
# 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](docs/architecture/overview.md) - Design principles and structure
- [Schema Reference](docs/architecture/schemas.md) - Complete type definitions
- [Tool Contracts](docs/tools/overview.md) - Request/response specifications
- [Security Model](docs/architecture/security.md) - Redaction, bounding, sandboxing