specir-mcp

English | 简体中文

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.

Related MCP server: literature-agent-mcp

Quick start

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:

fastmcp run src/specir/query/server.py

Example MCP calls:

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:

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.

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

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

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.