# reqif-mcp

**An MCP server for requirements engineering.** Load ReqIF / `.reqifz` baselines (the [OMG open standard](https://www.omg.org/spec/ReqIF/) exported by IBM DOORS, Polarion, Codebeamer, Jama…) and let any MCP client — Claude Desktop, Claude Code, Cursor — query requirements, follow trace links, detect orphans, and diff baselines in natural language.

Requirements management is where automotive, aerospace, rail and defense engineering actually lives, yet the MCP ecosystem has servers for Slack and GitHub and almost nothing for it. This fills that gap.

## What it does

Ask your MCP client things like:

- *"Which ASIL-D requirements have no verifying test case?"*
- *"Trace REQ-AEB-001 downstream — what tests cover it, directly or transitively?"*
- *"Diff baseline v3 against v4: what changed, was added, was removed?"*
- *"Show me the outline of the AEB specification."*

## Tools exposed

| Tool | Purpose |
|---|---|
| `load_reqif` | Parse and index a `.reqif` / `.reqifz` file |
| `search_requirements` | Paginated search over ids, titles, text, attribute values, with optional attribute filter |
| `attribute_values` | Distinct values of an attribute with counts — the fastest way to discover how a baseline is structured |
| `get_requirement` | One requirement: all attributes + incoming/outgoing links |
| `trace_requirement` | Transitive trace links, up/down/both, bounded depth |
| `find_orphans` | Requirements with no trace links — paginated, filterable (e.g. exclude headings via `Object Classification = Requirement`) |
| `diff_baselines` | Added / removed / modified requirements between two baselines, with changed attribute names |
| `document_outline` | The specification tree (chapters, ordering) |
| `document_stats` / `list_documents` | Counts by type, loaded documents |

## Install & run

```bash
pip install reqif-mcp        # or: pip install -e . from a clone
reqif-mcp path/to/baseline.reqifz
```

Register in Claude Desktop / Claude Code (`.mcp.json`) — no arguments needed;
load files at runtime with the `load_reqif` tool:

```json
{
  "mcpServers": {
    "reqif": { "command": "reqif-mcp" }
  }
}
```

Then, in your MCP client: *"Load /path/to/baseline.reqifz and show me the document stats."*

CLI arguments are an optional shortcut for small files
(`reqif-mcp fixtures/small.reqif`); large baselines are better loaded at
runtime so the stdio connection comes up instantly. Unloadable startup paths
log a warning instead of killing the server.

## Architecture

```
.reqif / .reqifz ──▶ parser.py (lxml, namespace-agnostic) ──▶ model.py (dataclasses)
                                                                    │
MCP client ◀── server.py (FastMCP, stdio) ◀── store.py (in-memory DuckDB: SQL over
                                               requirements / attributes / relations)
```

Design choices:

- **Namespace-agnostic parsing.** Real-world ReqIF exports disagree on namespace prefixes and even URI revisions; matching on `local-name()` makes the parser tool-vendor tolerant.
- **Enum values resolved to labels.** `ATTRIBUTE-VALUE-ENUMERATION` refs are resolved through `DATATYPE-DEFINITION-ENUMERATION`, so a status reads `Approved`, not `ev-4f2a…`.
- **Type-level default values applied.** An `ATTRIBUTE-DEFINITION` with a `DEFAULT-VALUE` is materialized on every spec-object of that type that doesn't override it — otherwise baseline diffs silently miss defaulted attributes.
- **DuckDB as the query engine.** Orphan detection, transitive tracing and baseline diffs are set operations — SQL expresses them cleanly, and it scales to large baselines without an external service.
- **Hardened XML parsing.** Entity resolution and network access disabled (XXE-safe).
- **XHTML flattened to text.** MCP tools serve search and trace; formatting is noise for that job.

## Development

```bash
pip install -e ".[dev]"
pytest
```

Tests run against a synthetic ADAS emergency-braking fixture (`tests/fixtures/`) — no proprietary data anywhere in this repo.

## Known limitations

Deliberate scope cuts for v0.1 — the parser extracts all spec-object attributes dynamically (no fixed schema), but:

- Attributes carried by `SPEC-RELATION`s and `SPECIFICATION`s themselves are not extracted (only id, type, source/target).
- `RELATION-GROUP`s, `ALTERNATIVE-ID`s and vendor `TOOL-EXTENSIONS` blocks are ignored.
- Datatype constraints (min/max, string length) are not enforced; every value is a string.
- XHTML values are flattened to plain text; embedded objects and formatting are dropped.

## Roadmap

- [ ] Semantic search over requirement text (embeddings)
- [ ] MCP resources (expose specifications as browsable resources)
- [ ] Coverage report tool: requirement type A → verifying type B matrix
- [ ] Write-back: export a filtered subset as valid ReqIF

## License

MIT