# specir-mcp

[English](README.md) | [简体中文](README_zh-CN.md)

`specir-mcp` is a data-neutral framework for turning technical documents into
a structured intermediate representation (SpecIR) and querying it through six
stable MCP tools.

The repository contains no standards PDFs, extracted specification text,
knowledge-base databases, model weights, or vendor-specific protocol tables.
All bundled demo content is fictional.

## Features

- Document, section, table, figure, entity, passage, provenance, and edge IR.
- Extensible domain plugin manifests with dependency-aware loading.
- PDF outline-based section extraction and reusable structure parsers.
- Multi-engine PDF table candidates with deterministic arbitration, geometry,
  non-table rejection, cross-page matching, and auditable review decisions.
- SQLite-backed exact lookup, fetch, explanation, search, and status APIs.
- A six-tool FastMCP surface:
  `specir_resolve`, `specir_fetch`, `specir_explain`, `specir_search`,
  `specir_status`, and `specir_validate`.
- Product-ranked `related_entities` plus evidence-complete `xrefs_raw`.
- Data-neutral typed edges for definitions, listings, field membership, and
  named status mentions.
- Explicit coverage metadata so missing extraction is not confused with absence
  from a source document.

## Quick start

```bash
python -m venv .venv
. .venv/bin/activate
pip install -e ".[test]"

# Generate a small database from the fictional Acme Device Interface fixture.
specir-demo --output data/demo.db

export SPEC_IR_DB="$PWD/data/demo.db"
specir-mcp-server
```

The same server may be launched from a source checkout:

```bash
fastmcp run src/specir/query/server.py
```

Example MCP calls:

```text
specir_resolve(kind="command", id="A1h", spec="acme-device")
specir_fetch(uid="acme-device:2.1", include_xrefs=true,
             xref_profile="test_points")
specir_explain(name="Read Telemetry", kind="command", spec="acme-device")
specir_search(query="telemetry", spec="acme-device")
specir_status()
specir_validate(mode="summary")
```

`test_points` is the default fetch profile: weak or boilerplate edges remain
auditable under `xrefs_raw.suppressed_references` but do not enter the ranked
`related_entities` list. Request `xref_profile="generic"` for an unfiltered
debug view.

When a database contains one document, `spec="auto"` selects it. With multiple
documents, exact lookups return candidates and request an explicit spec.

## Using your own data

Create a database with `specir.query.schema.create_database`, then insert
documents and entities using the schema documented by the Python dataclasses.
Set `SPEC_IR_DB` to that database before starting the server. The framework
never downloads or bundles source documents.

The optional PDF extractor can build coordinate-clipped section records:

```python
from specir.extractors.pdf import build_section_tree

sections = build_section_tree("my-spec", "path/to/your-document.pdf")
```

You are responsible for having permission to process and store the documents
you supply.

## Optional table extraction

Install only the engines you need. PyMuPDF is included in the core package;
the other engines are optional and unavailable engines are skipped safely.

```bash
pip install -e ".[tables]"          # pdfplumber
pip install -e ".[table-camelot]"  # Camelot; may need system libraries
pip install -e ".[table-docling]"  # neural candidate adapter
```

```python
from specir.extractors import arbitrate_candidates, generate_candidates

candidates = generate_candidates(
    "path/to/your-document.pdf",
    pages=[10, 11],
    engines=("pymupdf", "pdfplumber"),
)
results = arbitrate_candidates(candidates)
```

Every candidate retains its engine, strategy, bounding box, cell geometry,
quality metrics, and deterministic ID. Arbitration never treats the first
engine result as authoritative. It reports `TRUSTED_AUTOMATIC`,
`NEEDS_REVIEW`, `CONFLICTING_CANDIDATES`, or `REJECTED_NON_TABLE` and preserves
alternatives as evidence.

`table_continuations.assess_continuation` scores adjacent-page fragments and
keeps disagreements in a review state. `recover_outer_fragment` repairs nested
fragments only when the smallest enclosing candidate passes semantic,
geometric, caption-boundary, and unrelated-table checks. Neural extraction is
configured with explicit `DoclingTableProfile` values; no document names or
vendor rules are built into the framework.

Use `build_review_queue` and `apply_review_decisions` to bind a human decision
to the exact candidate state. Stale decisions, duplicate decisions, and
unknown replacement candidates fail closed.

## Development

```bash
pytest
python -m build
```

The tests create temporary synthetic databases and do not require external
specifications or network access.

## License

Apache License 2.0. See [LICENSE](LICENSE).