primarysource 0.1.0__py3-none-any.whl

primarysource/rfc/library.py

@@ -0,0 +1,294 @@
+"""Library lifecycle: what is on disk, how it gets there, what it can answer.
+
+A library fills in tiers, and every view works with whatever tier exists:
+
+  catalog    `rfclib init`: the RFC index (rfc-index.xml), bulk errata and
+             the RFC Editor subject tree. Status, obsolete chains, info,
+             document search, browse and errata work for every RFC.
+  on demand  the first read/grep/outline/cite/links of an RFC fetches its
+             txt (and RFCXML for RFC 8650+) from rfc-editor.org, segments
+             and indexes it in well under a second, and keeps it.
+  synced     `rfclib sync` / `rfclib init --content ...` prefetch documents
+             in bulk, so full-text section search covers them all.
+
+Nothing here runs at import time, and the MCP server never blocks startup
+on it: an empty library answers with what to do instead of "no matches".
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .config import NetworkDisabled, Paths, network_mode, read_only
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def state(conn: sqlite3.Connection) -> dict:
+    from .sync.state import get_meta
+    one = lambda sql, *a: conn.execute(sql, a).fetchone()[0]  # noqa: E731
+    subjects = 0
+    if one("SELECT COUNT(*) FROM sqlite_master WHERE name='subjects'"):
+        subjects = one("SELECT COUNT(*) FROM subjects")
+    return {
+        "docs": one("SELECT COUNT(*) FROM docs"),
+        "rfcs": one("SELECT COUNT(*) FROM docs WHERE series='RFC'"),
+        "current_rfcs": one("SELECT COUNT(*) FROM docs WHERE series='RFC' "
+                            "AND is_current=1"),
+        "txt_local": one("SELECT COUNT(*) FROM files WHERE fmt='txt'"),
+        "indexed": one("SELECT COUNT(*) FROM chunk_src"),
+        "indexed_current": one(
+            "SELECT COUNT(*) FROM chunk_src s JOIN docs d USING(doc_id) "
+            "WHERE d.is_current=1 AND d.series='RFC'"),
+        "embedded_chunks": one("SELECT COUNT(*) FROM embed_state"),
+        "errata": one("SELECT COUNT(*) FROM errata"),
+        "subjects": subjects,
+        "manifest_synced_at": get_meta(conn, "manifest_synced_at"),
+        "errata_synced_at": get_meta(conn, "errata_bulk_synced_at"),
+        "subjects_synced_at": get_meta(conn, "subjects_synced_at"),
+        "network": network_mode(),
+    }
+
+
+def features() -> dict[str, bool]:
+    """Optional components (pip extras) available in this environment."""
+    import importlib.util as u
+    return {
+        "mcp": u.find_spec("mcp") is not None,
+        "semantic": (u.find_spec("model2vec") is not None
+                     and u.find_spec("sqlite_vec") is not None),
+        "zim": u.find_spec("libzim") is not None,
+    }
+
+
+def initialized(conn: sqlite3.Connection) -> bool:
+    return conn.execute("SELECT 1 FROM docs LIMIT 1").fetchone() is not None
+
+
+def not_initialized(conn: sqlite3.Connection | None = None
+                    ) -> tuple[str, str, str]:
+    """(message, hint, action) for a library with no catalog yet: the
+    fields of the error every view raises (PLAN.md §5.10)."""
+    if _bootstrap.running:
+        return ("The RFC library is being initialized in the background "
+                f"({_bootstrap.step})", "retry the same call in a minute", "")
+    home = Paths.default().home
+    return (f"The RFC library at {home} is empty; once its catalog is in "
+            "(the RFC index, errata and subject tree, about a minute), RFCs "
+            "are fetched on first use", "",
+            "rfclib init (or `rfclib init --content current`, which also "
+            "prefetches every current RFC for full-text search, ~10 min)")
+
+
+def coverage_note(conn: sqlite3.Connection) -> str:
+    """'' when section search covers (nearly) every current RFC, else a
+    line saying what was searched, for the top of search results."""
+    s = conn.execute(
+        "SELECT (SELECT COUNT(*) FROM docs WHERE series='RFC' AND "
+        "is_current=1), (SELECT COUNT(*) FROM chunk_src s JOIN docs d "
+        "USING(doc_id) WHERE d.is_current=1 AND d.series='RFC')").fetchone()
+    total, done = s[0], s[1]
+    if not total or done >= total * 0.95:
+        return ""
+    return (f"coverage: section search covers the {done:,} of {total:,} "
+            "current RFCs fetched so far. scope='documents' searches all of "
+            "them; read() fetches any RFC on demand; `rfclib sync` "
+            "prefetches the rest.")
+
+
+# --------------------------------------------------------------------------
+# on demand
+
+_fetch_locks: dict[str, threading.Lock] = {}
+_fetch_guard = threading.Lock()
+
+
+def ensure_indexed(conn: sqlite3.Connection, doc_id: str) -> bool:
+    """Make doc_id readable: fetch its files if missing (RFC 8650+ also gets
+    its RFCXML for exact structure), segment and index it, embed its
+    sections if the model is already on disk. True when the document is
+    indexed afterwards. Raises NetworkDisabled when it would need the
+    network and RFCLIB_NETWORK=offline."""
+    if conn.execute("SELECT 1 FROM chunk_src WHERE doc_id=?",
+                    (doc_id,)).fetchone():
+        return True
+    if read_only():         # indexing is a write; the shared server does it
+        raise NetworkDisabled(
+            f"{doc_id} is not indexed in this library and this server is "
+            "read-only (RFCLIB_READONLY)",
+            "read it through the shared rfclib server once",
+            "rfclib sync && rfclib index build")
+    with _fetch_guard:
+        lock = _fetch_locks.setdefault(doc_id, threading.Lock())
+    with lock:
+        if conn.execute("SELECT 1 FROM chunk_src WHERE doc_id=?",
+                        (doc_id,)).fetchone():
+            return True
+        from . import graph, query as q
+        from .index import search as ix_search
+        from .sync.state import mirror_of
+        mirror = mirror_of(conn)
+        txt = q._content_path(conn, doc_id, "txt", mirror, fetch=True)
+        if txt is None:
+            return False
+        row = conn.execute("SELECT formats FROM docs WHERE doc_id=?",
+                           (doc_id,)).fetchone()
+        if row and "xml" in (row["formats"] or ""):
+            try:
+                q._content_path(conn, doc_id, "xml", mirror, fetch=True)
+            except (NetworkDisabled, OSError):
+                pass            # txt structure is a fine fallback
+        ok = ix_search.index_doc(conn, doc_id)
+        try:
+            graph.build(conn, [doc_id])
+        except Exception:  # noqa: BLE001 - citations are a bonus here
+            pass
+        _embed_if_model_present(conn, doc_id)
+        return ok
+
+
+def _embed_if_model_present(conn: sqlite3.Connection, doc_id: str) -> None:
+    """Never download a 30 MB model inside a tool call: embed only when the
+    model is already in the library (rfclib init --content / index embed)."""
+    from .index import embed as ix_embed
+    if not (ix_embed.model_dir() / "config.json").is_file():
+        return
+    try:
+        ix_embed.embed_pending(conn, doc_id=doc_id)
+    except Exception:  # noqa: BLE001 - semantic search is optional
+        pass
+
+
+# --------------------------------------------------------------------------
+# init: the catalog tier, then optional bulk content
+
+def init_catalog(conn: sqlite3.Connection, paths: Paths, *,
+                 subjects: bool = True, refresh: bool = False,
+                 say=lambda m: None) -> dict:
+    """RFC index + errata + subject tree. Each step is idempotent and skips
+    work already done, so an interrupted init simply resumes."""
+    from . import errata as errata_mod, subjects as subj_mod
+    from .sync.manifest import download_manifest, parse_manifest
+    from .sync.state import (rebuild_fts, refresh_current_flags, set_meta,
+                             upsert_docs)
+    out: dict = {}
+    _bootstrap.step = "RFC index"
+    say("RFC index (rfc-index.xml, ~14 MB) ...")
+    dest = download_manifest(paths.manifest_xml, force=refresh)
+    n_docs, n_rel = upsert_docs(conn, parse_manifest(dest))
+    refresh_current_flags(conn)
+    rebuild_fts(conn)
+    set_meta(conn, "manifest_synced_at", _now())
+    from .index.lexical import mine_acronyms
+    out["acronyms"] = mine_acronyms(conn)     # titles/abstracts: seconds
+    out["documents"], out["relations"] = n_docs, n_rel
+
+    _bootstrap.step = "errata"
+    if refresh or not errata_mod.bulk_synced_at(conn):
+        say("errata (RFC Editor bulk feed, ~12 MB) ...")
+        try:
+            out["errata"] = errata_mod.sync_bulk(conn)["errata"]
+        except NetworkDisabled:
+            out["errata"] = "skipped (offline)"
+
+    if subjects:
+        _bootstrap.step = "subject tree"
+        if refresh or not subj_mod.subjects_ready(conn):
+            say("subject tree (rfc-editor.org/subjects, ~640 pages, "
+                "a few minutes; cached and resumable) ...")
+            res = subj_mod.sync(conn, paths, progress=say)
+            out["subjects"] = res.get("subjects", res)
+    return out
+
+
+def init_content(conn: sqlite3.Connection, paths: Paths, scope: str, *,
+                 embed: bool = True, say=lambda m: None,
+                 concurrency: int = 8) -> dict:
+    """Prefetch documents and build the full indexes. scope: current (every
+    RFC not obsoleted) | all (including obsolete)."""
+    from . import graph
+    from .index import embed as ix_embed, search as ix_search
+    from .sync import downloader
+    from .sync.state import missing_docs
+    out: dict = {}
+    inc_obs = scope == "all"
+    for fmt in ("txt", "xml"):
+        todo = missing_docs(conn, [fmt], include_obsolete=inc_obs)
+        if todo:
+            _bootstrap.step = f"downloading {len(todo)} {fmt} files"
+            say(f"downloading {len(todo):,} {fmt} files from rfc-editor.org ...")
+            res = downloader.fetch_docs(conn, paths.mirror, todo, [fmt],
+                                        concurrency=concurrency)
+            out[f"{fmt}_ok"] = sum(1 for _, _, s in res if s == "ok")
+    _bootstrap.step = "indexing sections"
+    say("indexing sections (RFCXML for RFC 8650+, ToC-driven for older) ...")
+    out["index"] = ix_search.build_chunks(conn, paths.mirror)
+    say("mining citations ...")
+    out["refs"] = graph.build(conn)
+    if embed:
+        _bootstrap.step = "embedding"
+        say("embedding sections (model ~30 MB, kept in the library) ...")
+        try:
+            out["embed"] = ix_embed.embed_pending(conn)
+        except RuntimeError as e:   # rfclib[semantic] not installed
+            out["embed"] = f"skipped: {e}"
+    return out
+
+
+# --------------------------------------------------------------------------
+# optional background bootstrap for the MCP server (RFCLIB_AUTO_INIT=1)
+
+class _Bootstrap:
+    running = False
+    step = ""
+    error = ""
+    _lock = threading.Lock()
+
+    def start(self, paths: Paths) -> bool:
+        """Start a catalog init in a background thread once per process.
+        Opt-in: an MCP server that downloads on its own surprises people."""
+        if os.environ.get("RFCLIB_AUTO_INIT", "") not in ("1", "true", "yes"):
+            return False
+        if network_mode() == "offline":
+            return False
+        with self._lock:
+            if self.running:
+                return True
+            self.running, self.error, self.step = True, "", "starting"
+        threading.Thread(target=self._run, args=(paths,), daemon=True).start()
+        return True
+
+    def _run(self, paths: Paths) -> None:
+        from .fsutil import LockHeld, bulk_lock
+        from .sync.state import open_db
+        try:
+            with bulk_lock(paths.home):
+                conn = open_db(paths.db)
+                # index + errata only (seconds); the ~640-page subject crawl
+                # stays an explicit `rfclib init`
+                init_catalog(conn, paths, subjects=False)
+        except LockHeld:
+            self.error = "another rfclib process is initializing"
+        except Exception as e:  # noqa: BLE001 - reported via status
+            self.error = f"{type(e).__name__}: {e}"
+        finally:
+            self.running, self.step = False, ""
+
+
+_bootstrap = _Bootstrap()
+
+
+def maybe_bootstrap(conn: sqlite3.Connection) -> None:
+    if not initialized(conn):
+        _bootstrap.start(Paths.default().ensure())
+
+
+def _home(conn: sqlite3.Connection) -> Path:
+    from .sync.state import mirror_of
+    return mirror_of(conn).parent

primarysource/rfc/mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP interface package."""

primarysource/rfc/mcp/server.py

@@ -0,0 +1,381 @@
+"""FastMCP server exposing the local RFC library over the MCP protocol.
+
+Nine tools, one job each, all answering in compact plain text and all
+addressed by the same refs (see rfclib.views): search -> read -> cite is the
+core loop; outline/grep/links/info/browse/errata support it. Tool names are
+what a deferred-tool client sees first, so each one says what it does. The
+heavy lifting lives in rfclib.views; this module only maps errors to
+isError results and declares annotations, prompts and resources.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ResourceError
+from mcp.types import (Completion, PromptReference, ResourceTemplateReference,
+                       ToolAnnotations)
+
+from primarysource.errors import LibError
+from primarysource.scaffold import guard
+
+from .. import __version__, library
+from .. import query as q
+from .. import views
+from ..config import NetworkDisabled, Paths, read_only
+from ..sync.state import open_db
+
+INSTRUCTIONS = (
+    "RFC library: the full RFC/BCP/STD/FYI corpus from the RFC Editor, "
+    "searchable by section, with status (obsolete/superseded), errata, "
+    "citations and the RFC Editor subject tree. Use it for any question "
+    "about an IETF protocol or standard (HTTP, TLS, QUIC, DNS, TCP, IP, "
+    "SMTP, URI, BGP...): search('<question>') -> read('<ref>') -> follow "
+    "the 'next:' ref -> cite('<ref>'). Refs are citations: 'RFC9000' "
+    "(overview), 'RFC9000§9.6' (section), 'RFC9000§9.6¶2' (paragraph), "
+    "'RFC9000:2964-2979' (lines); BCP/STD aliases resolve. NEVER open the "
+    "mirror's .txt files directly: they are long and get truncated. "
+    "Before quoting a document check that it is current (read/info show "
+    "OBSOLETE + successor). read(view='normative') lists MUST/SHOULD "
+    "statements; view='code' the ABNF/YANG/figures. If the library is "
+    "empty or partly synced, tools say so and what to run."
+)
+
+# Everything is read-only over local state; tools that may fetch a missing
+# file or errata from rfc-editor.org are open-world.
+RO = ToolAnnotations(read_only_hint=True, idempotent_hint=True,
+                     destructive_hint=False, open_world_hint=False)
+RO_NET = ToolAnnotations(read_only_hint=True, idempotent_hint=True,
+                         destructive_hint=False, open_world_hint=True)
+# Claude Code defers MCP tools behind tool search, and a model that calls a
+# deferred tool without loading its schema guesses argument names (the
+# agent eval caught errata(query=...) 5 times in 22 tasks). The core loop
+# (search, read) and errata, which read headers send agents to, load up
+# front.
+ALWAYS = {"anthropic/alwaysLoad": True}
+
+mcp = MCPServer("rfclib", version=__version__, instructions=INSTRUCTIONS)
+
+_REF_HELP = ("ref forms: 'RFC9000' | 'RFC9000§9.6' | 'RFC9000§9.6¶2' | "
+             "'RFC9000#table-2' | 'RFC9000:2964-2979'.")
+
+
+def _conn():
+    if read_only():                     # never create or migrate anything
+        paths = Paths.default()
+        try:
+            return open_db(paths.db, read_only=True), paths
+        except sqlite3.OperationalError:
+            raise LibError(
+                f"cannot open {paths.db}: a read-only server needs an "
+                "existing library", "",
+                "rfclib init, or start the shared rfclib server first"
+            ) from None
+    paths = Paths.default().ensure()
+    conn = open_db(paths.db)
+    library.maybe_bootstrap(conn)       # no-op unless RFCLIB_AUTO_INIT=1
+    return conn, paths
+
+
+@mcp.custom_route("/healthz", methods=["GET"])
+async def healthz(request):
+    """Liveness for the HTTP transport (Docker HEALTHCHECK, monitors): the
+    process is up and can open its library. Not part of MCP."""
+    from starlette.responses import JSONResponse
+    try:
+        conn, _paths = _conn()
+        docs = conn.execute("SELECT COUNT(*) FROM docs").fetchone()[0]
+        conn.close()
+    except Exception as e:  # noqa: BLE001 - report, never raise
+        return JSONResponse({"status": "error", "error": str(e)[:300]},
+                            status_code=503)
+    return JSONResponse({"status": "ok", "version": __version__,
+                         "documents": docs, "read_only": read_only()})
+
+
+def _run(fn, *a, **k) -> str:
+    """Call a view; anticipated failures become a `LibError`, which `guard`
+    turns into an isError result of `error:`/`hint:`/`action:` lines
+    (PLAN.md §5.10): `hint` is the tool call to make next, `action` the
+    command a human runs."""
+    try:
+        return fn(*a, **k)
+    except views.RefError as e:
+        # a ref problem that names no remedy of its own gets the ref forms
+        hint = e.hint or ("" if e.action else _REF_HELP)
+        raise LibError(e.message, hint, e.action) from None
+    except q.NotFound as e:
+        raise LibError(f"{e} is not in the local index", "",
+                       "rfclib manifest --refresh") from None
+    except NetworkDisabled as e:
+        raise LibError(e.message, e.hint, e.action) from None
+    except sqlite3.OperationalError as e:
+        if "readonly" not in str(e) or not read_only():
+            raise
+        raise LibError(
+            "this server is read-only (RFCLIB_READONLY) and the library "
+            "needs a write first, most likely a schema update",
+            "call it through the shared rfclib server once",
+            "rfclib status") from None
+
+
+@mcp.tool(annotations=RO, structured_output=False, meta=ALWAYS)
+@guard
+def search(query: str, scope: str = "sections", mode: str = "hybrid",
+           limit: int = 8, subject: str | None = None,
+           status: str | None = None, include_obsolete: bool = False,
+           detail: str = "concise") -> str:
+    """Find where RFCs answer a question. Hits are refs (paragraph-precise
+    when possible) with a snippet, ready for read() and cite().
+
+    scope: sections (default: which passage says X) | documents (which RFC
+      is about X; matches titles/abstracts/keywords).
+    mode (sections): hybrid (default, keyword+semantic) | exact (FTS5:
+      "quoted phrase", AND/OR, prefix*, NEAR(a b, 40)) | semantic
+      (paraphrase/concept).
+    subject/status: restrict documents to an RFC-Editor subject slug
+      ('quic', 'http') or status ('INTERNET STANDARD', 'BCP').
+    Obsolete documents are excluded unless include_obsolete=True.
+    detail: concise | detailed (adds line ranges and which index matched).
+    """
+    conn, _ = _conn()
+    return _run(views.search_text, conn, query, scope=scope, mode=mode,
+                limit=limit, subject=subject, status=status,
+                include_obsolete=include_obsolete, detail=detail)
+
+
+@mcp.tool(annotations=RO_NET, structured_output=False, meta=ALWAYS)
+@guard
+def read(ref: str, max_tokens: int = 2000, view: str = "text",
+         lang: str | None = None, format: str = "txt") -> str:
+    """Read RFC text by ref. Pages are cut at paragraph boundaries within
+    max_tokens and end with 'next: <ref>' (call read with it to continue)
+    plus up/after neighbours. Paragraphs are marked [§9.6¶2] so any of them
+    is citable.
+
+    ref: 'RFC9000' (abstract + outline) | 'RFC9000§9.6' | 'RFC9000§9.6¶2'
+      | 'RFC9000#table-2' | 'RFC9000:2964-2979' | 'BCP14' (alias -> RFC).
+    view: text | normative (only MUST/SHOULD/MAY statements) | code
+      (sourcecode/figures; lang='abnf'|'yang'|'asn.1'|...) | refs (what
+      this scope cites).
+    format: txt (default) | html | xml | json: raw slice of another
+      rendering by line range (e.g. read('RFC9000:1-200', format='xml')).
+    """
+    conn, paths = _conn()
+    fmt = (format or "txt").lower().strip(". ")
+    if fmt != "txt":
+        if fmt not in ("html", "xml", "json", "pdf"):
+            raise LibError(f"unknown format {format!r}",
+                           "format is txt | html | xml | json")
+        ref_ = _run(views.parse_ref, conn, ref, need_text=False)
+        try:
+            return q.read_document(conn, ref_.served, mirror_root=paths.mirror,
+                                   fmt=fmt, start_line=ref_.start or 1,
+                                   count=((ref_.end or (ref_.start or 1) + 199)
+                                          - (ref_.start or 1) + 1),
+                                   max_chars=max(400, max_tokens * 4))
+        except q.NotFound as e:
+            raise LibError(f"unknown document {e}", _REF_HELP) from None
+    return _run(views.read, conn, ref, mirror_root=paths.mirror,
+                max_tokens=max_tokens, view=view, lang=lang)
+
+
+@mcp.tool(annotations=RO, structured_output=False)
+@guard
+def outline(ref: str, depth: int | None = 2,
+            contains: str | None = None) -> str:
+    """Section outline of one document (ref='RFC9112'): one line per section
+    with its line range (depth 2 by default, all levels when contains=
+    filters by number/title, e.g. contains='security'). Then
+    read('RFC9112§<num>')."""
+    conn, _ = _conn()
+    return _run(views.outline, conn, ref.split("§")[0].split(":")[0],
+                depth=depth, contains=contains)
+
+
+@mcp.tool(annotations=RO_NET, structured_output=False)
+@guard
+def grep(ref: str, pattern: str, max_hits: int = 25,
+         ignore_case: bool = True) -> str:
+    """Regex search inside ONE document or section (ref='RFC9110' or
+    'RFC9110§15'); each hit carries its paragraph ref and line. The cheap
+    way to find a field name, ABNF rule or error code in a known RFC.
+    Invalid regexes fall back to a literal search."""
+    conn, paths = _conn()
+    return _run(views.grep, conn, ref, pattern, mirror_root=paths.mirror,
+                max_hits=max_hits, ignore_case=ignore_case)
+
+
+@mcp.tool(annotations=RO, structured_output=False)
+@guard
+def cite(ref: str, style: str = "verbose") -> str:
+    """Checkable citation for a ref: label, title, date, status (warns when
+    obsolete), anchor URL, errata status and a hash of the cited span.
+    style: verbose | short | markdown | comment | bibtex. Cite rather than
+    paraphrase normative text."""
+    conn, paths = _conn()
+    return _run(views.cite, conn, ref, mirror_root=paths.mirror, style=style)
+
+
+@mcp.tool(annotations=RO, structured_output=False)
+@guard
+def links(ref: str, direction: str = "out", limit: int = 30) -> str:
+    """Citation links of a document or section, section-precise where the
+    text says so ('RFC9000§8.1 cites RFC9002 §6.2 [normative]').
+    direction: out (what it cites) | in (who cites it) | related (other
+    documents in the same RFC-Editor subjects)."""
+    conn, _ = _conn()
+    return _run(views.links, conn, ref, direction=direction, limit=limit)
+
+
+@mcp.tool(annotations=RO, structured_output=False)
+@guard
+def info(ref: str, detail: str = "concise") -> str:
+    """Bibliographic record and status of one document: title, status,
+    current/OBSOLETE with successor, obsoletes/updates graph, BCP/STD
+    alias members (BCP14 -> RFC2119 + RFC8174), authors, subjects, errata
+    summary, abstract. ref is a document id ('RFC2616', 'BCP14'); a section
+    part is ignored. detail='full' returns the complete JSON record."""
+    conn, _ = _conn()
+    doc = ref.split("§")[0].split(":")[0].split("#")[0]
+    if (detail or "").lower() == "full":
+        try:
+            return json.dumps(q.get_metadata(conn, q.normalize_doc_id(doc)),
+                              ensure_ascii=False, indent=1)
+        except (ValueError, q.NotFound) as e:
+            raise LibError(f"unknown document {doc!r}: {e}",
+                           "search(<topic>, scope='documents')") from None
+    return _run(views.info_text, conn, doc)
+
+
+@mcp.tool(annotations=RO, structured_output=False)
+@guard
+def browse(subject: str | None = None, parent: str | None = None,
+           contains: str | None = None, recent: bool = False,
+           offset: int = 0, limit: int = 30,
+           include_obsolete: bool = False) -> str:
+    """Browse without a query: the RFC Editor subject tree and what is new.
+
+    no args: the top-level subjects (slug, doc count, subtopics);
+    parent='web': one level down; contains='http': find subjects by name;
+    subject='quic': the documents in that subject (newest first, paged with
+    offset); recent=True: most recently published RFCs."""
+    conn, _ = _conn()
+    if recent:
+        return views.recent_text(conn, limit=limit)
+    if subject:
+        return _run(views.subject_docs, conn, subject, offset=offset,
+                    limit=limit, include_obsolete=include_obsolete)
+    return _run(views.subjects_tree, conn, parent=parent, contains=contains)
+
+
+@mcp.tool(annotations=RO_NET, structured_output=False, meta=ALWAYS)
+@guard
+def errata(ref: str, status: str = "verified",
+           section: str | None = None, max_tokens: int = 2000) -> str:
+    """Errata for a document or one section, with the corrected text:
+    ref='RFC791' or 'RFC791§3.1' (or section='3.1'). status: verified
+    (default; the authoritative corrections) | open (reported/held) | all.
+    Check before implementing."""
+    conn, _ = _conn()
+    try:
+        return _run(views.errata_text, conn, ref, status=status,
+                    section=section, max_tokens=max_tokens)
+    except LibError:
+        raise
+    except Exception as e:  # noqa: BLE001 - upstream/network
+        raise LibError(f"errata unavailable: {e}",
+                       "retry the same call later",
+                       "rfclib errata --sync-all (while online)") from None
+
+
+# --------------------------------------------------------------------------
+# resources: '@rfclib:rfc://RFC9000§9.6' attaches a section to a prompt
+
+@mcp.resource("rfc://{ref}", name="rfc", mime_type="text/plain",
+              description="RFC text by ref, e.g. rfc://RFC9000§9.6 or "
+                          "rfc://RFC9112§6.3¶2 (first page; the footer gives "
+                          "the next ref).")
+def rfc_resource(ref: str) -> str:
+    conn, paths = _conn()
+    try:
+        return views.read(conn, ref, mirror_root=paths.mirror,
+                          max_tokens=4000)
+    except views.RefError as e:
+        raise ResourceError(e.as_text()) from None
+    except q.NotFound as e:
+        raise ResourceError(str(e)) from None
+
+
+# --------------------------------------------------------------------------
+# prompts: user-invoked workflows (/rfclib:explain, /rfclib:checklist, ...)
+
+@mcp.prompt(name="explain", title="Explain an RFC section")
+def explain_prompt(ref: str) -> str:
+    """Explain what a section requires, grounded in its text and status."""
+    return (f"Explain {ref} for an implementer. First call "
+            f"mcp__rfclib__read('{ref}') (follow 'next:' until the section "
+            "ends) and mcp__rfclib__info on its document; if the document "
+            "is obsolete, say so and find the successor's matching section. "
+            f"Check mcp__rfclib__errata for that section. Summarise the "
+            "behaviour in plain language, quote the MUST/SHOULD sentences "
+            "verbatim, and finish with mcp__rfclib__cite for each passage "
+            "you relied on.")
+
+
+@mcp.prompt(name="checklist", title="Compliance checklist for a section")
+def checklist_prompt(ref: str) -> str:
+    """Turn a section's normative statements into a checklist."""
+    return (f"Build an implementation checklist for {ref}. Call "
+            f"mcp__rfclib__read('{ref}', view='normative') and page with "
+            "'next:'. One checklist item per requirement: the keyword "
+            "(MUST/SHOULD/MAY), a short imperative, and the paragraph ref "
+            "it comes from. Group by subsection. Add verified errata from "
+            f"mcp__rfclib__errata that touch these sections. Do not "
+            "paraphrase away conditions: keep every 'if/when/unless'.")
+
+
+@mcp.prompt(name="current", title="Find the current spec for a topic")
+def current_prompt(topic: str) -> str:
+    """Which RFCs currently define a topic, and what they replaced."""
+    return (f"Which RFCs currently specify {topic}? Use "
+            f"mcp__rfclib__search('{topic}', scope='documents') and "
+            "mcp__rfclib__browse(contains=...) for the subject. For each "
+            "candidate call mcp__rfclib__info: report only current "
+            "documents, each with its status and what it obsoletes/updates. "
+            "Mention obsolete predecessors people still cite and what "
+            "replaced them.")
+
+
+# --------------------------------------------------------------------------
+# completions: document ids and section numbers for prompts and rfc://
+
+@mcp.completion()
+async def complete(ref, argument, context):
+    if not isinstance(ref, (PromptReference, ResourceTemplateReference)):
+        return None
+    if argument.name not in ("ref", "doc"):
+        return None
+    conn, _ = _conn()
+    val = (argument.value or "").strip()
+    if "§" in val:                      # doc chosen: complete its sections
+        doc, part = val.split("§", 1)
+        try:
+            did = q.resolve(conn, q.normalize_doc_id(doc))
+        except ValueError:
+            return Completion(values=[])
+        rows = conn.execute(
+            "SELECT DISTINCT sec_num FROM chunks WHERE doc_id=? AND "
+            "sec_num LIKE ? ORDER BY start_line LIMIT 50",
+            (did, part + "%")).fetchall()
+        vals = [f"{doc}§{r['sec_num']}" for r in rows if r["sec_num"]]
+        return Completion(values=vals[:100], has_more=len(vals) >= 100)
+    digits = "".join(ch for ch in val if ch.isdigit())
+    series = "".join(ch for ch in val if ch.isalpha()).upper() or "RFC"
+    rows = conn.execute(
+        "SELECT doc_id FROM docs WHERE doc_id LIKE ? ORDER BY is_current "
+        "DESC, length(doc_id), doc_id LIMIT 20",
+        (f"{series}{digits}%",)).fetchall()
+    return Completion(values=[r["doc_id"] for r in rows])

primarysource/rfc/packs/__init__.py

@@ -0,0 +1 @@
+"""Content packs: curated RFC collections exported as .rfcpack zips."""