primarysource 0.1.0__py3-none-any.whl

primarysource/nist/server/mcp.py

@@ -0,0 +1,19 @@
+"""MCP server for the local NIST publications: the shared server (primarysource.pdfcorpus.server) with the
+nist spec. `primarysource mcp --collection nist` serves `mcp`."""
+
+from __future__ import annotations
+
+from primarysource.nist.spec import SPEC
+from primarysource.pdfcorpus.server import CorpusServer
+
+SERVER = CorpusServer(SPEC)
+mcp = SERVER.mcp
+
+
+def main() -> None:
+    """Serve over stdio (`primarysource mcp --collection nist` is the usual way)."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

primarysource/nist/server/tools.py

@@ -0,0 +1,35 @@
+"""The five nist tools: the shared ones (primarysource.pdfcorpus.tools)."""
+
+from __future__ import annotations
+
+from primarysource.pdfcorpus.tools import (
+    GRAMMAR,
+    OUTLINE_ROWS,
+    READ_TOKENS,
+    ToolError,
+    cite,
+    info,
+    outline,
+    parse_lines,
+    read,
+    resolve,
+    resolve_doc,
+    resolve_section,
+    search,
+)
+
+__all__ = [
+    "GRAMMAR",
+    "OUTLINE_ROWS",
+    "READ_TOKENS",
+    "ToolError",
+    "cite",
+    "info",
+    "outline",
+    "parse_lines",
+    "read",
+    "resolve",
+    "resolve_doc",
+    "resolve_section",
+    "search",
+]

primarysource/nist/spec.py

@@ -0,0 +1,38 @@
+"""The nist collection's settings for the shared skeleton (primarysource.pdfcorpus)."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from pathlib import Path
+
+from primarysource.nist.paths import corpus_dir
+from primarysource.pdfcorpus.spec import CorpusSpec
+
+
+def publication_name(key: str) -> str:
+    """A reference with its issuer stripped: "nist sp 800-53 low" -> "800-53 low", "nist csf" -> "csf"."""
+    name = re.sub(r"^nist ", "", key)
+    return re.sub(r"^(special publication|sp|csrc) ", "", name)
+
+
+def _read_defaults(root: Path) -> Mapping[str, str]:
+    from primarysource.nist.ingest.status import read_defaults
+
+    return read_defaults(root)
+
+
+SPEC = CorpusSpec(
+    name="nist",
+    server_name="nistlib",
+    env_var="NISTLIB_CORPUS",
+    fetch_command="primarysource nist fetch",
+    index_command="primarysource nist index",
+    default_dir=corpus_dir,
+    instructions=(
+        "NIST publications (SP 800-73 PIV, SP 800-78, SP 800-76, FIPS 201) from a locally fetched corpus. search('<words>') -> read('<doc_id>§<section>') -> cite('<doc_id>§<section>'). Search hits start with that ref; a read's 'next:' line is a ref to pass back to read. Documents are addressed by doc_id or by number. Check info(doc) for status before quoting. A missing corpus or search index is an error whose 'action:' line is the command to run (`primarysource nist fetch`, `primarysource nist index`)."
+    ),
+    cite_example='NIST SP 800-73pt2-5 §3.2.4',
+    read_defaults=_read_defaults,
+    alias=publication_name,
+)

primarysource/pdfcorpus/__init__.py

@@ -0,0 +1,16 @@
+"""The shared skeleton of a fetched-document collection: user-fetched PDFs, extracted text, a section index,
+a search index in the core FTS5 index (`fts`), five tools (search, read, outline, info, cite) and an MCP server.
+
+nistlib and usblib were one skeleton copied twice (primarysource PLAN.md §1). This is the one copy. A collection
+supplies a `CorpusSpec` (its names, where its corpus lives, its fetch command, and optional hooks such as NIST's
+default-revision aliases) and gets the loader, the tools and the server from here. Fetching and splitting stay in
+the collection for now (ROADMAP `us.base_segmenter`).
+"""
+
+from __future__ import annotations
+
+from primarysource.pdfcorpus.corpus import Corpus, CorpusError, load_corpus
+from primarysource.pdfcorpus.models import Document, Section
+from primarysource.pdfcorpus.spec import CorpusSpec
+
+__all__ = ["Corpus", "CorpusError", "CorpusSpec", "Document", "Section", "load_corpus"]

primarysource/pdfcorpus/corpus.py

@@ -0,0 +1,159 @@
+"""Load and validate a collection's ``corpus/index.json`` against ``primarysource.pdfcorpus.models``."""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from primarysource.errors import LibError
+from primarysource.pdfcorpus.models import Document, Section
+
+if TYPE_CHECKING:
+    from primarysource.pdfcorpus.spec import CorpusSpec
+
+SCHEMA_VERSION = 1
+
+_DOC_FIELDS = tuple(f.name for f in dataclasses.fields(Document))
+_SECTION_FIELDS = tuple(f.name for f in dataclasses.fields(Section))
+
+
+class CorpusError(LibError):
+    """The corpus or its search index is missing, stale or malformed. `action` is the fetch or index command."""
+
+
+@dataclasses.dataclass(frozen=True)
+class Corpus:
+    """A loaded corpus. `defaults` and `alias` resolve a bare publication name to a document (see `CorpusSpec`).
+
+    `fetch_command` and `index_command` are the `action:` of an error that a fetch or an index rebuild fixes;
+    `prefix` is put before a tool name in a `hint:` (`nist_` gives `nist_outline(...)`). `digest` is the sha256 of
+    the `index.json` this was loaded from, which the search index records to tell whether it is stale.
+    """
+
+    root: Path
+    documents: tuple[Document, ...]
+    defaults: Mapping[str, str] = dataclasses.field(default_factory=dict)
+    alias: Callable[[str], str] | None = None
+    fetch_command: str = ""
+    index_command: str = ""
+    prefix: str = ""
+    digest: str = ""
+
+    def tool(self, name: str) -> str:
+        """The served name of one of this collection's tools, for a `hint:` line."""
+        return self.prefix + name
+
+    def text_lines(self, doc: Document) -> list[str]:
+        """Lines of the document's extracted text (index 0 is line 1)."""
+        path = (self.root / doc.text_file).resolve()
+        if not path.is_relative_to(self.root.resolve()):
+            raise CorpusError(
+                f"{doc.doc_id}: text_file {doc.text_file!r} escapes the corpus directory", action=self.fetch_command
+            )
+        try:
+            # Split on newline only, as the ingest side does. splitlines() also breaks on form feeds,
+            # which pdftotext puts at every page break, and that shifts every line number. Read with
+            # newline="" for the same reason: universal newlines would also break on a lone "\r" that
+            # pdftotext left inside a line (sp800-38g line 449). Only the "\r" of a CRLF is dropped.
+            with path.open(encoding="utf-8", newline="") as handle:
+                lines = [line.removesuffix("\r") for line in handle.read().split("\n")]
+            if lines and lines[-1] == "":
+                lines.pop()
+            return lines
+        except FileNotFoundError:
+            raise CorpusError(
+                f"{doc.doc_id}: text file {doc.text_file!r} is missing", action=self.fetch_command
+            ) from None
+
+
+def _check_fields(where: str, obj: object, expected: tuple[str, ...]) -> Mapping[str, Any]:
+    if not isinstance(obj, dict):
+        raise CorpusError(f"{where}: expected an object, got {type(obj).__name__}")
+    missing = [f for f in expected if f not in obj]
+    extra = [f for f in obj if f not in expected]
+    if missing:
+        raise CorpusError(f"{where}: missing field(s) {', '.join(missing)}")
+    if extra:
+        raise CorpusError(f"{where}: unknown field(s) {', '.join(extra)}")
+    return obj
+
+
+def _parse_section(where: str, raw: object) -> Section:
+    d = _check_fields(where, raw, _SECTION_FIELDS)
+    for name in ("id", "heading"):
+        if not isinstance(d[name], str) or not d[name]:
+            raise CorpusError(f"{where}.{name}: expected a non-empty string")
+    for name in ("start_line", "end_line"):
+        v = d[name]
+        if isinstance(v, bool) or not isinstance(v, int) or v < 1:
+            raise CorpusError(f"{where}.{name}: expected a positive integer")
+    if d["start_line"] > d["end_line"]:
+        raise CorpusError(f"{where}: start_line {d['start_line']} is after end_line {d['end_line']}")
+    return Section(d["id"], d["heading"], d["start_line"], d["end_line"])
+
+
+def _parse_document(where: str, raw: object) -> Document:
+    d = _check_fields(where, raw, _DOC_FIELDS)
+    for name in _DOC_FIELDS:
+        if name == "sections":
+            continue
+        if not isinstance(d[name], str) or not d[name]:
+            raise CorpusError(f"{where}.{name}: expected a non-empty string")
+    secs = d["sections"]
+    if not isinstance(secs, list):
+        raise CorpusError(f"{where}.sections: expected a list")
+    sections = tuple(_parse_section(f"{where}.sections[{i}]", s) for i, s in enumerate(secs))
+    ids = [s.id for s in sections]
+    dup = sorted({i for i in ids if ids.count(i) > 1})
+    if dup:
+        raise CorpusError(f"{where}.sections: duplicate section id(s) {', '.join(dup)}")
+    values = {n: d[n] for n in _DOC_FIELDS if n != "sections"}
+    return Document(sections=sections, **values)
+
+
+def load_corpus(spec: CorpusSpec, root: Path | None = None) -> Corpus:
+    """Read and validate the index; raise ``CorpusError`` whose `action` is the fetch command."""
+    root = spec.corpus_dir() if root is None else root
+    fetch = spec.fetch_command
+    index = root / "index.json"
+    if not index.is_file():
+        raise CorpusError(f"no corpus index at {index}: the corpus is not fetched yet", action=fetch)
+    raw = index.read_bytes()
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as e:
+        raise CorpusError(f"{index} is not valid JSON ({e})", action=fetch) from None
+    if not isinstance(data, dict):
+        raise CorpusError(f"{index}: expected a JSON object at the top level", action=fetch)
+    if data.get("schema") != SCHEMA_VERSION:
+        raise CorpusError(
+            f"{index}: schema is {data.get('schema')!r}, this server reads schema {SCHEMA_VERSION}",
+            "update primarysource if the corpus is newer than it",
+            fetch,
+        )
+    docs = data.get("documents")
+    if not isinstance(docs, list):
+        raise CorpusError(f"{index}: 'documents' must be a list", action=fetch)
+    try:
+        documents = tuple(_parse_document(f"documents[{i}]", d) for i, d in enumerate(docs))
+    except CorpusError as e:
+        raise CorpusError(f"{index}: {e.message}", action=fetch) from None
+    ids = [d.doc_id for d in documents]
+    dup = sorted({i for i in ids if ids.count(i) > 1})
+    if dup:
+        raise CorpusError(f"{index}: duplicate doc_id(s) {', '.join(dup)}", action=fetch)
+    defaults = spec.read_defaults(root) if spec.read_defaults is not None else {}
+    return Corpus(
+        root=root,
+        documents=documents,
+        defaults=defaults,
+        alias=spec.alias,
+        fetch_command=fetch,
+        index_command=spec.index_command or fetch,
+        prefix=f"{spec.name}_",
+        digest=hashlib.sha256(raw).hexdigest(),
+    )

primarysource/pdfcorpus/fts.py

@@ -0,0 +1,175 @@
+"""The search index of a fetched-document collection: its sections in the core FTS5 index (`primarysource.index`).
+
+`build` writes `<corpus>/sections.sqlite` from `index.json` and the extracted text, atomically, when the corpus is
+fetched or when `primarysource <collection> index` is run. `open_index` opens it read-only (`mode=ro`) for search,
+so the server never re-reads or re-tokenises the text to answer a query.
+
+A section's indexed body is the text it owns: the lines in its range that no narrower section claims, so a parent
+section is not credited with its children's text (the rule the old in-memory scan had).
+
+**Staleness.** The index records the sha256 of the `index.json` it was built from, as a sentinel row in the core
+`documents` table (`SOURCE_ID`, title = the digest, no sections, so it is never a search hit). It is written in the
+same atomic rebuild as the sections. An index whose digest differs from the loaded corpus is refused with a
+`CorpusError` whose `action` is the index command, as is a missing one. (The core index has no metadata table;
+when it grows one, the digest moves there.)
+"""
+
+from __future__ import annotations
+
+import argparse
+import sqlite3
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from primarysource import index
+from primarysource.errors import LibError
+from primarysource.model import Document as IndexedDocument
+from primarysource.model import Section as IndexedSection
+from primarysource.model import Unit
+from primarysource.pdfcorpus.corpus import Corpus, CorpusError, load_corpus
+from primarysource.pdfcorpus.models import Document
+
+if TYPE_CHECKING:
+    from primarysource.pdfcorpus.spec import CorpusSpec
+
+INDEX_FILE = "sections.sqlite"
+SOURCE_ID = "#source"
+
+# The old scan scored a heading word 3 above a body word, plus 5 per distinct word: heading hits weigh more. As
+# BM25 column weights: the section heading counts four times the body, the document's number and title once.
+RANKING = index.Ranking(doc_title=1.0, title=4.0, body=1.0)
+
+
+def index_path(root: Path) -> Path:
+    return root / INDEX_FILE
+
+
+def owned_lines(document: Document, line_count: int) -> dict[str, list[int]]:
+    """Section id -> the 1-based line numbers it owns: a line belongs to the narrowest section containing it."""
+    owner: dict[int, str] = {}
+    for section in sorted(document.sections, key=lambda s: s.end_line - s.start_line, reverse=True):
+        for number in range(section.start_line, min(section.end_line, line_count) + 1):
+            owner[number] = section.id
+    owned: dict[str, list[int]] = {section.id: [] for section in document.sections}
+    for number in sorted(owner):
+        owned[owner[number]].append(number)
+    return owned
+
+
+def indexed_document(corpus: Corpus, document: Document) -> IndexedDocument:
+    """One corpus document as the core index stores it: one unit per section, the text the section owns."""
+    lines = corpus.text_lines(document)
+    owned = owned_lines(document, len(lines))
+    return IndexedDocument(
+        id=document.doc_id,
+        title=f"{document.number} {document.title}",
+        unit=Unit.BLOCK,
+        sections=tuple(
+            IndexedSection(
+                id=section.id,
+                title=section.heading,
+                units=("\n".join(lines[n - 1] for n in owned[section.id]),),
+                depth=section.id.count(".") + 1,
+            )
+            for section in document.sections
+        ),
+    )
+
+
+def build(corpus: Corpus) -> int:
+    """Rebuild `<corpus>/sections.sqlite` from the loaded corpus; returns the number of sections indexed."""
+    documents = [indexed_document(corpus, document) for document in corpus.documents]
+    documents.append(IndexedDocument(id=SOURCE_ID, title=corpus.digest, unit=Unit.BLOCK))
+    return index.rebuild(index_path(corpus.root), documents, rebuild_command=corpus.index_command)
+
+
+def open_index(corpus: Corpus) -> sqlite3.Connection:
+    """A read-only connection to the corpus's search index, or a `CorpusError` naming the index command."""
+    path = index_path(corpus.root)
+    action = corpus.index_command
+    if not path.is_file():
+        raise CorpusError(f"no search index at {path}: the corpus has not been indexed", action=action)
+    try:
+        conn = index.open_read(path, rebuild_command=action)
+    except LibError as error:
+        raise CorpusError(error.message, action=action) from None
+    try:
+        row = conn.execute("SELECT title FROM documents WHERE doc_id = ?", (SOURCE_ID,)).fetchone()
+    except sqlite3.DatabaseError as error:
+        conn.close()
+        raise CorpusError(f"{path} is not a readable search index: {error}", action=action) from None
+    if row is None or row[0] != corpus.digest:
+        conn.close()
+        stale = f"the search index at {path} is stale: index.json changed since it was built"
+        raise CorpusError(stale, action=action)
+    return conn
+
+
+def _match_in(
+    conn: sqlite3.Connection, expression: str, doc_id: str, ranking: index.Ranking, fetch: int
+) -> list[index.Hit]:
+    order = ranking.bm25()
+    rows = conn.execute(
+        "SELECT s.doc_id, s.section_id, s.doc_title, s.title, "  # noqa: S608 - only formatted floats are interpolated
+        f"snippet(sections_fts, 2, '', '', ' … ', 24), {order} "
+        "FROM sections_fts JOIN sections AS s ON s.id = sections_fts.rowid "
+        f"WHERE sections_fts MATCH ? AND s.doc_id = ? ORDER BY {order}, s.id LIMIT ?",
+        (expression, doc_id, fetch),
+    ).fetchall()
+    return [index.Hit(row[0], row[1], row[2], row[3], row[4] or row[3], -row[5]) for row in rows]
+
+
+def search(
+    conn: sqlite3.Connection, query: str, *, doc_id: str | None = None, limit: int = 8, start: int = 0
+) -> index.SearchResult:
+    """`index.search` with this collection's ranking, optionally within one document.
+
+    The core search has no document filter yet, so a restricted search runs the same strict-then-relaxed query
+    here with `s.doc_id = ?` added: the decision to relax is then taken within the document, not across the corpus.
+    """
+    if doc_id is None:
+        return index.search(conn, query, ranking=RANKING, limit=limit, start=start)
+    fetch = start + limit + 1
+    strict = index.fts_query(query)
+    hits = _match_in(conn, strict, doc_id, RANKING, fetch)
+    relaxed = False
+    if not hits:
+        loose = index.fts_query(query, any_term=True)
+        if loose != strict:
+            hits = _match_in(conn, loose, doc_id, RANKING, fetch)
+            relaxed = bool(hits)
+    page = tuple(hits[start : start + limit])
+    more = len(hits) > start + limit
+    return index.SearchResult(page, relaxed, start + len(page) if more else None)
+
+
+def main(spec: CorpusSpec, argv: Sequence[str]) -> int:
+    """`primarysource <collection> index [--corpus DIR]`: rebuild the search index from the fetched corpus."""
+    parser = argparse.ArgumentParser(
+        prog=spec.index_command or f"primarysource {spec.name} index",
+        description="Rebuild the search index from the fetched corpus (index.json and the extracted text).",
+    )
+    parser.add_argument("--corpus", type=Path, default=None, help=f"corpus directory (default: ${spec.env_var})")
+    args = parser.parse_args(list(argv))
+    try:
+        corpus = load_corpus(spec, args.corpus)
+        written = build(corpus)
+    except LibError as error:
+        print(error.as_text(), file=sys.stderr)
+        return 2
+    print(f"indexed {written} section(s) of {len(corpus.documents)} document(s) into {index_path(corpus.root)}")
+    return 0
+
+
+def build_after_fetch(spec: CorpusSpec, root: Path) -> bool:
+    """Called by a fetch once `index.json` is written: rebuild the search index, report, and say if it worked."""
+    try:
+        corpus = load_corpus(spec, root)
+        written = build(corpus)
+    except LibError as error:
+        print(f"search index not rebuilt:\n{error.as_text()}", file=sys.stderr)
+        return False
+    print(f"indexed {written} section(s) into {index_path(root)}")
+    return True

primarysource/pdfcorpus/index.py

@@ -0,0 +1,70 @@
+"""The corpus index: ``index.json``, ``{"schema": 1, "documents": [...]}``, written atomically."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import asdict
+from pathlib import Path
+
+from primarysource.pdfcorpus.models import Document, Section
+
+SCHEMA = 1
+
+
+def sha256_file(path: Path) -> str:
+    """Hex sha256 of a file, read in chunks."""
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def document_from_dict(raw: dict[str, object]) -> Document:
+    sections = raw["sections"]
+    if not isinstance(sections, list):
+        raise ValueError("sections must be a list")
+    return Document(
+        doc_id=str(raw["doc_id"]),
+        number=str(raw["number"]),
+        title=str(raw["title"]),
+        date=str(raw["date"]),
+        status=str(raw["status"]),
+        url=str(raw["url"]),
+        sha256=str(raw["sha256"]),
+        text_file=str(raw["text_file"]),
+        sections=tuple(
+            Section(
+                id=str(s["id"]),
+                heading=str(s["heading"]),
+                start_line=int(s["start_line"]),
+                end_line=int(s["end_line"]),
+            )
+            for s in sections
+        ),
+    )
+
+
+def write_index(path: Path, documents: list[Document]) -> None:
+    """Write ``{"schema": 1, "documents": [...]}`` atomically."""
+    payload = {"schema": SCHEMA, "documents": [asdict(d) for d in documents]}
+    temp = path.with_name(path.name + ".tmp")
+    temp.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    os.replace(temp, path)
+
+
+def read_index(path: Path) -> list[Document]:
+    """Read an index; a missing, unreadable or foreign-schema file yields no documents."""
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+        if raw.get("schema") != SCHEMA:
+            return []
+        return [document_from_dict(item) for item in raw["documents"]]
+    except (OSError, ValueError, KeyError, TypeError, AttributeError):
+        return []

primarysource/pdfcorpus/models.py

@@ -0,0 +1,30 @@
+"""Data contract shared by the ingest pipeline and the MCP server. Change it only with both sides."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Section:
+    """One numbered section of a document, located by line range in its extracted text."""
+
+    id: str  # dotted section number, e.g. "3.2.4"
+    heading: str
+    start_line: int  # 1-based, inclusive
+    end_line: int  # 1-based, inclusive
+
+
+@dataclass(frozen=True, slots=True)
+class Document:
+    """One publication in the corpus index."""
+
+    doc_id: str  # file-safe slug, e.g. "sp800-73pt2-5"
+    number: str  # as cited, e.g. "NIST SP 800-73pt2-5" or "USB-IF CCID Rev 1.1"
+    title: str
+    date: str  # "YYYY-MM"
+    status: str  # e.g. "final", "withdrawn"
+    url: str  # where the user fetched the PDF
+    sha256: str  # of the PDF as fetched
+    text_file: str  # path relative to data/corpus/
+    sections: tuple[Section, ...]

primarysource/pdfcorpus/server.py

@@ -0,0 +1,96 @@
+"""The MCP server for a fetched-document collection: search, read, outline, info, cite.
+
+Reads local files only. The corpus is loaded on the first call and kept until its `index.json` changes on disk
+(a fetch or an OSCAL merge rewrites it), so a running server picks up a new corpus without a restart; `reset()`
+drops it outright. Search reads the FTS5 index (`primarysource.pdfcorpus.fts`) read-only.
+
+Tools are registered through `scaffold.add_tools` under their bare names (`search`, `read`, ...): `primarysource mcp`
+serves them as `<collection>_<tool>` (`nist_search`), and `primarysource mcp --bare-names` or this module's own
+stdio server keeps the bare names the old `nistlib`/`usblib` servers had. Every `LibError` reaches the client as an
+`isError` result with `error:`, `hint:` and `action:` lines (PLAN.md §5.10).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from mcp.server.mcpserver import MCPServer
+from mcp.types import ToolAnnotations
+
+from primarysource.pdfcorpus import tools
+from primarysource.pdfcorpus.corpus import Corpus, load_corpus
+from primarysource.pdfcorpus.spec import CorpusSpec
+from primarysource.scaffold import add_tools
+
+READ_ONLY = ToolAnnotations(read_only_hint=True, idempotent_hint=True, destructive_hint=False, open_world_hint=False)
+
+
+class CorpusServer:
+    """One collection's MCP server. `mcp` is the `MCPServer`; the tool functions are attributes, callable directly
+    (they raise `LibError`; through `mcp` it becomes an `isError` result)."""
+
+    def __init__(self, spec: CorpusSpec) -> None:
+        self.spec = spec
+        self._corpus: Corpus | None = None
+        self._stamp: tuple[int, int] | None = None
+        self.mcp = MCPServer(spec.server_name, instructions=spec.instructions)
+
+        def search(query: str, doc: str | None = None, limit: int = 8, start: int = 0) -> str:
+            return tools.search(self._load(), query, doc, limit, start)
+
+        def read(
+            doc: str, section: str | None = None, lines: str | None = None, max_tokens: int = tools.READ_TOKENS
+        ) -> str:
+            return tools.read(self._load(), doc, section, lines, max_tokens)
+
+        def outline(doc: str, start: int = 0, limit: int = tools.OUTLINE_ROWS) -> str:
+            return tools.outline(self._load(), doc, start, limit)
+
+        def info(doc: str) -> str:
+            return tools.info(self._load(), doc)
+
+        def cite(doc: str, section: str | None = None) -> str:
+            return tools.cite(self._load(), doc, section)
+
+        search.__doc__ = _SEARCH
+        read.__doc__ = _READ
+        outline.__doc__ = _OUTLINE
+        info.__doc__ = _INFO
+        cite.__doc__ = _CITE.format(example=spec.cite_example)
+        self.search, self.read, self.outline, self.info, self.cite = search, read, outline, info, cite
+        functions: tuple[Callable[..., str], ...] = (search, read, outline, info, cite)
+        add_tools(self.mcp, functions, annotations=READ_ONLY)
+
+    def reset(self) -> None:
+        self._corpus = None
+        self._stamp = None
+
+    def _load(self) -> Corpus:
+        stamp = None
+        try:
+            stat = (self.spec.corpus_dir() / "index.json").stat()
+            stamp = (stat.st_mtime_ns, stat.st_size)
+        except OSError:
+            pass
+        if self._corpus is None or stamp != self._stamp or self._corpus.root != self.spec.corpus_dir():
+            self._corpus = load_corpus(self.spec)
+            self._stamp = stamp
+        return self._corpus
+
+
+_SEARCH = """Find sections by keywords (BM25 over the local FTS5 index; a heading match weighs more), best first.
+
+Each hit starts with a ref '<doc_id>§<section>' to pass to read() and cite(), then the heading, line range and a
+snippet. doc restricts the search to one document (doc_id or number). Every word is required first; if no section
+has them all, sections with some of them are returned and a 'relaxed:' line says so. A 'next: start=N' line means
+call again with start=N for more."""
+_READ = """Read numbered lines of one section or a line range, cut at whole lines within max_tokens.
+
+doc is a doc_id or number with section='3.2.4' (ids from outline) or lines='120-160', or a ref on its own:
+'<doc_id>§3.2.4' or '<doc_id>:120-160'. A 'next:' line holds a ref; pass it back as doc to continue."""
+_OUTLINE = """List a document's section tree: ids, headings and line ranges. A 'next: start=N' line means call
+again with start=N for the rest."""
+_INFO = """Document metadata: number, title, date, status, url, sha256.
+A 'warning:' line appears when the status is not 'final'."""
+_CITE = """Citation string such as '{example}' plus the document URL.
+doc may be a ref ('<doc_id>§<section>'). Headings come verbatim from the index."""