primarysource 0.1.0__py3-none-any.whl

primarysource/cavp/parse.py

@@ -0,0 +1,269 @@
+"""Parse CAVP `.rsp` response files and ACVP vector-set JSON into `VectorSet`s, within fixed bounds.
+
+Bytes in, a `VectorSet` out: nothing is written to disk and no archive is unpacked (a zip member is read into
+memory, capped at `MAX_SOURCE_BYTES`).
+
+An `.rsp` file is a header of `#` comments, then `[...]` lines that open a group, then blocks of `Key = Value`
+lines separated by blank lines. Rules this parser applies, because real files need them:
+
+- consecutive `[...]` lines form one group (label joined with `,`); a `[...]` line after cases opens the next;
+- a repeated key inside a block starts a new block, so a file with no blank lines still splits;
+- RSA `SigVer` files put the modulus `n` in a block of its own, ahead of the cases that use it. A block whose
+  keys are disjoint from the group's most common block shape is *context*: it is merged into every following
+  case of the group and is not a case itself;
+- a case's id is its `COUNT` when every case of the group has a unique one, else its 1-based position.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import re
+import zipfile
+from collections import Counter
+from typing import Any
+
+from primarysource.cavp.model import (
+    KINDS,
+    MAX_CASES,
+    MAX_FIELDS_PER_CASE,
+    MAX_GROUPS,
+    MAX_HEADER_LINES,
+    MAX_LINE_BYTES,
+    MAX_SOURCE_BYTES,
+    SET_ID,
+    Case,
+    Group,
+    VectorSet,
+    sha256_bytes,
+)
+from primarysource.errors import LibError
+
+_MODE = re.compile(r'#\s*"([^"]+)"\s+information', re.IGNORECASE)
+
+
+def read_member(archive: bytes, member: str) -> bytes:
+    """One file out of a zip held in memory, refused when it is larger than the cap (declared or actual)."""
+    try:
+        zf = zipfile.ZipFile(io.BytesIO(archive))
+        info = zf.getinfo(member)
+    except zipfile.BadZipFile:
+        raise LibError("the artifact is not a zip file", "check the url and the pinned sha256") from None
+    except KeyError:
+        names = ", ".join(n for n in zf.namelist() if not n.endswith("/"))[:400]
+        raise LibError(f"zip has no member {member!r} (members: {names})", "fix `member` in vectors.toml") from None
+    if info.file_size > MAX_SOURCE_BYTES:
+        raise LibError(f"{member}: {info.file_size} bytes is over the {MAX_SOURCE_BYTES} byte cap", "")
+    with zf.open(info) as stream:
+        data = stream.read(MAX_SOURCE_BYTES + 1)
+    if len(data) > MAX_SOURCE_BYTES:
+        raise LibError(f"{member}: larger than the {MAX_SOURCE_BYTES} byte cap", "")
+    return data
+
+
+def _decode(data: bytes, what: str) -> str:
+    if len(data) > MAX_SOURCE_BYTES:
+        raise LibError(f"{what}: {len(data)} bytes is over the {MAX_SOURCE_BYTES} byte cap", "")
+    try:
+        return data.decode("utf-8-sig")
+    except UnicodeDecodeError as exc:
+        raise LibError(f"{what} is not UTF-8 ({exc})", "") from None
+
+
+def _group_params(labels: list[str]) -> dict[str, Any]:
+    """`[L = 1024, N = 160, SHA-1]` -> {"L": "1024", "N": "160", "tokens": ["SHA-1"]}."""
+    params: dict[str, Any] = {}
+    tokens: list[str] = []
+    for label in labels:
+        for piece in label.split(","):
+            key, eq, value = piece.partition("=")
+            if eq:
+                params[key.strip()] = value.strip()
+            elif piece.strip():
+                tokens.append(piece.strip())
+    if tokens:
+        params["tokens"] = tokens
+    return params
+
+
+def _cases(blocks: list[dict[str, str]]) -> tuple[Case, ...]:
+    if not blocks:
+        return ()
+    dominant = Counter(frozenset(b) for b in blocks).most_common(1)[0][0]
+    context: dict[str, str] = {}
+    rows: list[dict[str, str]] = []
+    for block in blocks:
+        if dominant.isdisjoint(block):
+            context = block
+        else:
+            rows.append({**context, **block})
+    counts = [row.get("COUNT") for row in rows]
+    use_count = bool(rows) and all(c is not None for c in counts) and len(set(counts)) == len(counts)
+    return tuple(Case(str(row["COUNT"]) if use_count else str(i), row) for i, row in enumerate(rows, 1))
+
+
+def parse_rsp(
+    data: bytes,
+    *,
+    set_id: str,
+    algorithm: str,
+    source_url: str,
+    sha256: str,
+    member_sha256: str,
+    mode: str = "",
+) -> VectorSet:
+    """Parse one `.rsp`. `mode` defaults to the quoted name in the file's header (`# "SigVer" information`)."""
+    text = _decode(data, set_id)
+    header: list[str] = []
+    groups: list[tuple[list[str], list[dict[str, str]]]] = []
+    labels: list[str] | None = None
+    blocks: list[dict[str, str]] = []
+    block: dict[str, str] = {}
+
+    def close_block() -> None:
+        nonlocal block
+        if block:
+            blocks.append(block)
+            block = {}
+
+    def close_group() -> None:
+        nonlocal labels, blocks
+        close_block()
+        if labels is not None or blocks:
+            groups.append((labels if labels is not None else ["all"], blocks))
+        labels, blocks = None, []
+
+    for number, raw in enumerate(text.replace("\r\n", "\n").replace("\r", "\n").split("\n"), 1):
+        if len(raw) > MAX_LINE_BYTES:
+            raise LibError(f"{set_id} line {number}: over {MAX_LINE_BYTES} characters", "")
+        line = raw.strip()
+        if not line:
+            close_block()
+        elif line.startswith("#"):
+            if not groups and labels is None and not blocks and len(header) < MAX_HEADER_LINES:
+                header.append(line)
+        elif line.startswith("[") and line.endswith("]"):
+            close_block()
+            if labels is None or blocks:
+                close_group()
+                labels = []
+            labels.append(line[1:-1].strip())
+            if len(groups) >= MAX_GROUPS:
+                raise LibError(f"{set_id}: more than {MAX_GROUPS} groups", "")
+        else:
+            key, eq, value = line.partition("=")
+            if not eq or not key.strip():
+                raise LibError(f"{set_id} line {number}: not 'Key = Value' or '[group]': {line[:60]!r}", "")
+            key = key.strip()
+            if key in block:
+                close_block()
+            block[key] = value.strip()
+            if len(block) > MAX_FIELDS_PER_CASE:
+                raise LibError(f"{set_id} line {number}: more than {MAX_FIELDS_PER_CASE} fields in one case", "")
+    close_group()
+
+    seen: Counter[str] = Counter()
+    out: list[Group] = []
+    total = 0
+    for group_labels, group_blocks in groups:
+        label = ",".join(group_labels)
+        seen[label] += 1
+        if seen[label] > 1:
+            label = f"{label}~{seen[label]}"
+        cases = _cases(group_blocks)
+        total += len(cases)
+        if total > MAX_CASES:
+            raise LibError(f"{set_id}: more than {MAX_CASES} cases", "")
+        out.append(Group(label, _group_params(group_labels), cases))
+    if not out:
+        raise LibError(f"{set_id}: no groups or cases found", "is this a CAVP .rsp file?")
+    found = _MODE.search("\n".join(header))
+    return VectorSet(
+        id=set_id,
+        kind="cavp",
+        algorithm=algorithm,
+        mode=mode or (found.group(1) if found else ""),
+        source_url=source_url,
+        sha256=sha256,
+        member_sha256=member_sha256,
+        header=tuple(header),
+        groups=tuple(out),
+    )
+
+
+def _acvp_document(data: bytes, what: str) -> dict[str, Any]:
+    try:
+        doc = json.loads(_decode(data, what))
+    except (ValueError, RecursionError) as exc:
+        raise LibError(f"{what} is not valid JSON ({exc})", "") from None
+    if isinstance(doc, list):  # a server response: [{"acvVersion": ...}, {the vector set}]
+        doc = next((d for d in doc if isinstance(d, dict) and "testGroups" in d), None)
+    if not isinstance(doc, dict) or not isinstance(doc.get("testGroups"), list):
+        raise LibError(f"{what}: no testGroups", "is this an ACVP prompt.json or expectedResults.json?")
+    return doc
+
+
+def parse_acvp(
+    prompt: bytes,
+    expected: bytes | None,
+    *,
+    set_id: str,
+    source_url: str,
+    sha256: str,
+    member_sha256: str,
+) -> VectorSet:
+    """One ACVP vector set: `prompt.json` (the inputs), joined by (tgId, tcId) with `expectedResults.json`."""
+    doc = _acvp_document(prompt, f"{set_id} prompt")
+    answers: dict[tuple[str, str], dict[str, Any]] = {}
+    if expected is not None:
+        for g in _acvp_document(expected, f"{set_id} expectedResults")["testGroups"]:
+            for t in g.get("tests", []):
+                answers[(str(g.get("tgId")), str(t.get("tcId")))] = {k: v for k, v in t.items() if k != "tcId"}
+    groups: list[Group] = []
+    total = 0
+    used = 0
+    for g in doc["testGroups"]:
+        tg = str(g.get("tgId"))
+        tests = g.get("tests")
+        if not isinstance(tests, list):
+            raise LibError(f"{set_id} group {tg}: no tests list", "")
+        cases = []
+        for t in tests:
+            tc = str(t.get("tcId"))
+            fields = {k: v for k, v in t.items() if k != "tcId"}
+            if len(fields) > MAX_FIELDS_PER_CASE:
+                raise LibError(f"{set_id} case {tg}/{tc}: more than {MAX_FIELDS_PER_CASE} fields", "")
+            answer = answers.get((tg, tc), {})
+            used += bool(answer)
+            cases.append(Case(tc, fields, answer))
+        total += len(cases)
+        if total > MAX_CASES or len(groups) >= MAX_GROUPS:
+            raise LibError(f"{set_id}: over {MAX_CASES} cases or {MAX_GROUPS} groups", "")
+        groups.append(Group(tg, {k: v for k, v in g.items() if k not in ("tests", "tgId")}, tuple(cases)))
+    if expected is not None and used != len(answers):
+        raise LibError(
+            f"{set_id}: expectedResults has {len(answers) - used} cases that prompt does not",
+            "pair the files of one vector set",
+        )
+    return VectorSet(
+        id=set_id,
+        kind="acvp",
+        algorithm=str(doc.get("algorithm", "")),
+        mode=str(doc.get("mode", "")),
+        source_url=source_url,
+        sha256=sha256,
+        member_sha256=member_sha256,
+        header=(),
+        groups=tuple(groups),
+        revision=str(doc.get("revision", "")),
+    )
+
+
+def check_set_id(set_id: str, kind: str) -> None:
+    if kind not in KINDS or not SET_ID.fullmatch(set_id) or not set_id.startswith(kind + "/"):
+        raise LibError(
+            f"bad set id {set_id!r} for kind {kind!r}", "ids look like cavp/ecdsa/SigVer.rsp or acvp/ECDSA-SigVer-1.0"
+        )
+
+
+__all__ = ["check_set_id", "parse_acvp", "parse_rsp", "read_member", "sha256_bytes"]

primarysource/cavp/paths.py

@@ -0,0 +1,17 @@
+"""Where the cavp collection keeps imported vector sets: `$PRIMARYSOURCE_HOME/cavp`, else the per-user
+`primarysource/cavp` (`primarysource.home.collection_home`). Never the working directory, never the package."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from primarysource.cavp.model import Store
+from primarysource.home import collection_home
+
+
+def store_dir() -> Path:
+    return collection_home("cavp")
+
+
+def open_store() -> Store:
+    return Store(store_dir())

primarysource/cavp/server.py

@@ -0,0 +1,67 @@
+"""MCP server for the cavp collection: `primarysource mcp --collection cavp`.
+
+Tools are prefixed `cavp_`, answer in text with the fixed footer, and turn a `LibError` into a tool error naming
+the remedy. Read-only, local files only.
+"""
+
+from __future__ import annotations
+
+from mcp.server.mcpserver import MCPServer
+from mcp.types import ToolAnnotations
+
+from primarysource import __version__
+from primarysource.cavp import tools
+from primarysource.cavp.paths import open_store
+from primarysource.scaffold import add_tools
+
+READ_ONLY = ToolAnnotations(read_only_hint=True, idempotent_hint=True, destructive_hint=False, open_world_hint=False)
+INSTRUCTIONS = (
+    "NIST cryptographic test vectors (CAVP .rsp, ACVP JSON) the user imported, each pinned by sha256. "
+    "cavp_sets() lists them as refs; cavp_groups('nist:cavp/ecdsa/SigVer.rsp') lists a set's groups; "
+    "cavp_read('nist:cavp/ecdsa/SigVer.rsp#[P-256,SHA-256]/3') reads one case in full; cavp_find looks a case up "
+    "by a field value (a message, a key, a signature). ACVP refs use the tgId and tcId: "
+    "'nist:acvp/ECDSA-SigVer-1.0#1/3'. The cite: footer line is the citation. If nothing is imported the error "
+    "says how."
+)
+
+
+def cavp_sets(query: str | None = None, limit: int = 50) -> str:
+    """List imported vector sets, one ref per line with algorithm, mode and counts. query filters by id,
+    algorithm or mode."""
+    return tools.sets(open_store(), query, limit)
+
+
+def cavp_groups(set_ref: str, start: int = 0, max_tokens: int = 2000) -> str:
+    """List a set's groups as refs with their case counts and parameters. set_ref: 'nist:cavp/ecdsa/SigVer.rsp'.
+    A 'next: start=N' footer line means call again with start=N (a 0-based offset)."""
+    return tools.groups(open_store(), set_ref, start, max_tokens)
+
+
+def cavp_read(ref: str, max_tokens: int = 2000) -> str:
+    """Read by ref: a set ('nist:cavp/ecdsa/SigVer.rsp'), a group ('...#[P-256,SHA-256]', values shortened) or one
+    case in full ('...#[P-256,SHA-256]/3'). A 'next: <ref>' footer line is the ref that reads the next page: pass
+    it back as ref."""
+    return tools.read(open_store(), ref, max_tokens)
+
+
+def cavp_find(
+    set_ref: str,
+    field: str,
+    value: str,
+    group: str | None = None,
+    start: int = 0,
+    max_tokens: int = 2000,
+) -> str:
+    """Find cases in a set whose field equals value (hex compared without case or 0x), e.g. field='Msg'.
+    Returns refs. field may be 'expected.<name>' for an ACVP answer. A 'next: start=N' footer line means call
+    again with start=N (a 0-based offset)."""
+    return tools.find(open_store(), set_ref, field, value, group, start, max_tokens)
+
+
+def cavp_cite(ref: str) -> str:
+    """The citation for a ref: algorithm, mode, source URL, pinned sha256, and NIST's credit line."""
+    return tools.cite(open_store(), ref)
+
+
+cavp_server = MCPServer("primarysource-cavp", version=__version__, instructions=INSTRUCTIONS)
+add_tools(cavp_server, (cavp_sets, cavp_groups, cavp_read, cavp_find, cavp_cite), annotations=READ_ONLY)

primarysource/cavp/tools.py

@@ -0,0 +1,169 @@
+"""The vector tools as plain functions over a `Store`, returning text with the core's fixed footer.
+
+Each result is a body (one line per item, or one case in full), then footer lines: `cite:` names the set, its
+source file and pinned sha256, `span:` is the hash of the exact text returned (case reads). When the token budget
+cuts a page, `next:` is exactly what to pass back: for `read`, the ref that reads on (`<set or group ref>¶<n>`,
+the nth line of that listing); for `groups` and `find`, `start=<n>`, a 0-based line offset.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from primarysource import cursor
+from primarysource.budget import page
+from primarysource.cavp.model import (
+    CREDIT,
+    Case,
+    Group,
+    Store,
+    VectorSet,
+    find_case,
+    find_group,
+    format_ref,
+    norm_value,
+    parse_ref,
+)
+from primarysource.errors import LibError
+from primarysource.model import span_hash
+from primarysource.render import next_start, render
+
+SHOWN = 60  # characters of a field value in a listing; a case read is never shortened
+
+
+def _value(v: Any) -> str:
+    return v if isinstance(v, str) else json.dumps(v, separators=(",", ":"))
+
+
+def _short(v: Any) -> str:
+    s = _value(v)
+    return s if len(s) <= SHOWN else f"{s[:SHOWN]}...({len(s)} chars)"
+
+
+def _cite(s: VectorSet, where: str = "") -> str:
+    kind = "ACVP" if s.kind == "acvp" else "CAVP"
+    head = f"NIST {kind} {s.algorithm} {s.mode}".strip()
+    rev = f" rev {s.revision}" if s.revision else ""
+    return f"{head}{rev}{where}; {s.source_url}; sha256:{s.sha256}"
+
+
+def _listed(lines: list[str], start: int, max_tokens: int, cite: str) -> str:
+    """A list cut at the token budget from the 0-based line `start`; `next: start=<n>` continues."""
+    if start < 0 or max_tokens < 1:
+        raise LibError(f"start is a 0-based offset and max_tokens positive (got {start}, {max_tokens})", "")
+    got = page(lines, start + 1, max_tokens)
+    body = "\n".join(got.units) if got.units else f"nothing at start={start} ({got.total} lines)"
+    resume = None if got.next_start is None else got.next_start - 1
+    return render(body, {"cite": cite, "next": next_start(resume)})
+
+
+def _read_page(lines: list[str], scope: str, line: int | None, max_tokens: int, cite: str) -> str:
+    """A read cut at the token budget from line `line` (1-based); `next:` is the ref that reads on."""
+    if max_tokens < 1:
+        raise LibError("max_tokens must be positive", "")
+    got = page(lines, cursor.first_unit(line, len(lines), "lines", f"{scope}¶{line}"), max_tokens)
+    return render("\n".join(got.units), {"cite": cite, "next": cursor.read_next(scope, got)})
+
+
+def sets(store: Store, query: str | None = None, limit: int = 50) -> str:
+    """One line per imported set. `query` keeps the sets whose id, algorithm or mode contains it."""
+    entries = store.require()
+    needle = (query or "").lower()
+    hits = [e for e in entries if needle in f"{e.id} {e.algorithm} {e.mode}".lower()]
+    if not hits:
+        return f"no vector set matches {query!r} ({len(entries)} imported)\n"
+    lines = [
+        f"{format_ref(e.id)}: {e.algorithm} {e.mode}{' rev ' + e.revision if e.revision else ''}, "
+        f"{e.groups} groups, {e.cases} cases"
+        for e in hits[: max(1, limit)]
+    ]
+    if len(hits) > limit:
+        lines.append(f"... {len(hits) - limit} more; narrow the query")
+    return "\n".join(lines) + "\n"
+
+
+def _group_line(s: VectorSet, g: Group) -> str:
+    extras = " ".join(f"{k}={_short(v)}" for k, v in g.params.items())
+    return f"{format_ref(s.id, g.label)}: {len(g.cases)} cases {extras}".rstrip()
+
+
+def _case_body(s: VectorSet, g: Group, c: Case) -> str:
+    lines = [format_ref(s.id, g.label, c.id)]
+    lines += [f"{k} = {_value(v)}" for k, v in c.fields.items()]
+    lines += [f"expected.{k} = {_value(v)}" for k, v in c.expected.items()]
+    return "\n".join(lines)
+
+
+def groups(store: Store, set_ref: str, start: int = 0, max_tokens: int = 2000) -> str:
+    """The groups of a set, one line each, as refs."""
+    ref = parse_ref(set_ref)
+    s = store.load(ref.set_id)
+    return _listed([_group_line(s, g) for g in s.groups], start, max_tokens, _cite(s))
+
+
+def read(store: Store, ref_text: str, max_tokens: int = 2000) -> str:
+    """A set (its header and groups), a group (its cases, values shortened) or one case in full. `<ref>¶n` reads a
+    set or a group from line n of its listing."""
+    text, line = cursor.split_para(ref_text)
+    ref = parse_ref(text)
+    s = store.load(ref.set_id)
+    if ref.group is None:
+        header = [f"# {h.lstrip('# ')}" for h in s.header[:5]]
+        lines = header + [_group_line(s, g) for g in s.groups]
+        return _read_page(lines, format_ref(s.id), line, max_tokens, _cite(s))
+    g = find_group(s, ref.group)
+    if ref.case is None:
+        lines = [
+            f"{format_ref(s.id, g.label, c.id)}: "
+            + " ".join(
+                f"{k}={_short(v)}"
+                for k, v in {**c.fields, **{f"expected.{k}": v for k, v in c.expected.items()}}.items()
+            )
+            for c in g.cases
+        ]
+        return _read_page(lines, format_ref(s.id, g.label), line, max_tokens, _cite(s, f", group {g.label}"))
+    if line is not None:
+        raise LibError(f"{ref_text}: a case is read whole", f"read {format_ref(s.id, g.label, ref.case)}")
+    c = find_case(g, ref.case)
+    body = _case_body(s, g, c)
+    return render(body, {"cite": _cite(s, f", group {g.label}, case {c.id}"), "span": span_hash(body)})
+
+
+def find(
+    store: Store,
+    set_ref: str,
+    field: str,
+    value: str,
+    group: str | None = None,
+    start: int = 0,
+    max_tokens: int = 2000,
+) -> str:
+    """The cases of a set whose `field` equals `value` (compared as hex: case and `0x` ignored), as refs with the
+    case's other short fields. `field` may be `expected.<name>` for an ACVP answer. Zero matches is said, not an
+    error."""
+    s = store.load(parse_ref(set_ref).set_id)
+    chosen = [find_group(s, group)] if group else list(s.groups)
+    want = norm_value(value)
+    lines: list[str] = []
+    for g in chosen:
+        for c in g.cases:
+            held = c.expected.get(field[9:]) if field.startswith("expected.") else c.fields.get(field)
+            if held is not None and norm_value(_value(held)) == want:
+                lines.append(f"{format_ref(s.id, g.label, c.id)}: {_short(held)}")
+    if not lines:
+        return f"no case in {format_ref(s.id)} has {field} = {_short(value)}\n"
+    return _listed(lines, start, max_tokens, _cite(s))
+
+
+def cite(store: Store, ref_text: str) -> str:
+    """The citation for a ref, with its source, pinned digest and NIST's credit line."""
+    ref = parse_ref(ref_text)
+    s = store.load(ref.set_id)
+    where = ""
+    if ref.group is not None:
+        g = find_group(s, ref.group)
+        where = f", group {g.label}"
+        if ref.case is not None:
+            where += f", case {find_case(g, ref.case).id}"
+    return f"{format_ref(s.id, ref.group, ref.case)}\n{_cite(s, where)}\n{CREDIT}\n"

primarysource/cli.py

@@ -0,0 +1,107 @@
+"""The `primarysource` command.
+
+    primarysource collections                       list what is registered
+    primarysource identify <pdf or folder> ...      which collection knows each PDF, and how to import it
+    primarysource mcp --collection rfc [--collection nist ...] [--bare-names]
+                      [--transport http] [--host H] [--port P] [--allowed-host H] [--read-only]
+    primarysource rfc <command> ...                 the collection's own commands (sync, index, status, ...)
+
+`mcp` serves every named collection from one process, each with its own database and its tools named
+`<collection>_<tool>` (PLAN.md §5.12). `--bare-names` keeps a collection's own tool names instead; it is how the
+old single-collection commands (`rfclib mcp`) stay compatible, and two collections with the same bare names are
+refused at startup.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from primarysource import registry, scaffold, serve
+from primarysource.errors import LibError
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="primarysource", description="Search, read and cite primary sources.")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("collections", help="list the registered collections")
+    ident = commands.add_parser("identify", help="say which collection knows each PDF, and how to import it")
+    ident.add_argument("paths", nargs="+", type=Path, help="PDFs, or folders of PDFs")
+    mcp = commands.add_parser("mcp", help="run the MCP server for one or more collections")
+    mcp.add_argument(
+        "--collection", action="append", required=True, help="a collection to serve, e.g. rfc (repeatable)"
+    )
+    mcp.add_argument(
+        "--bare-names",
+        action="store_true",
+        help="keep each collection's own tool names (search, read) instead of <collection>_<tool>",
+    )
+    mcp.add_argument("--transport", default="stdio", help="stdio (one server per client) or http (one shared server)")
+    mcp.add_argument("--host", default="127.0.0.1", help="http: address to bind; there is no authentication")
+    mcp.add_argument("--port", type=int, default=serve.MCP_HTTP_PORT, help="http: TCP port")
+    mcp.add_argument("--allowed-host", action="append", default=[], help="http: Host header to accept (repeatable)")
+    mcp.add_argument("--read-only", action="store_true", help="never write the library and never fetch")
+    return parser
+
+
+def collection_server(collection: registry.Collection) -> Any:
+    """The `MCPServer` a collection's own module builds; a factory such as itu's `build()` is called."""
+    server = registry.attribute(collection, collection.server, "server")
+    if not hasattr(server, "run") and callable(server):
+        server = server()
+    return server
+
+
+def build_server(names: Sequence[str], *, bare: bool = False) -> Any:
+    """The one server for `names`, in the order given; a name given twice is served once."""
+    served = []
+    for name in dict.fromkeys(names):
+        collection = registry.load(name)
+        served.append(scaffold.Served(collection.name, collection.title, collection_server(collection)))
+    return scaffold.compose(served, bare=bare)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args_in = list(sys.argv[1:] if argv is None else argv)
+    try:
+        # `primarysource <collection> ...` hands the rest of the line to that collection's own command
+        if args_in and args_in[0] in registry.available():
+            collection = registry.load(args_in[0])
+            entry = registry.attribute(collection, collection.cli, "command line")
+            result = entry(args_in[1:])
+            return int(result or 0)
+        args = _parser().parse_args(args_in)
+        if args.command == "collections":
+            for name in registry.available():
+                print(name)
+            return 0
+        if args.command == "identify":
+            from primarysource import identify
+
+            hooks = identify.registered_hooks()
+            for path in identify.pdfs(args.paths):
+                try:
+                    print(identify.describe(path, identify.identify(identify.probe_pdf(path), hooks)))
+                except LibError as exc:
+                    print(f"{path.name}: {exc.message}")
+            return 0
+        transport = serve.normalise_transport(args.transport)
+        if args.read_only:
+            os.environ["PRIMARYSOURCE_READONLY"] = "1"
+        server = build_server(args.collection, bare=args.bare_names)
+        if transport == "http":
+            names = ", ".join(dict.fromkeys(args.collection))
+            print(f"primarysource mcp: {names} at http://{args.host}:{args.port}/mcp", file=sys.stderr)
+        serve.run(server, transport, host=args.host, port=args.port, allowed_hosts=args.allowed_host)
+        return 0
+    except LibError as exc:
+        print(exc.as_text(), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())