cfr-mcp 0.1.0__tar.gz

cfr_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run pytest -q

cfr_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/

cfr_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan McCalla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cfr_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: cfr-mcp
+Version: 0.1.0
+Summary: MCP server for the US Code of Federal Regulations (eCFR)
+Project-URL: Homepage, https://github.com/mccallar/cfr-mcp
+Project-URL: Repository, https://github.com/mccallar/cfr-mcp
+Project-URL: Issues, https://github.com/mccallar/cfr-mcp/issues
+License: MIT
+License-File: LICENSE
+Keywords: cfr,compliance,ecfr,government,mcp,regulations
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: lxml>=5.0
+Requires-Dist: mcp>=2.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cfr-mcp
+
+[![CI](https://github.com/mccallar/cfr-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mccallar/cfr-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/cfr-mcp)](https://pypi.org/project/cfr-mcp/)
+
+An MCP server that gives AI assistants access to the **US Code of Federal Regulations**.
+
+Ask "what does 21 CFR 101.9 require?" or "has 40 CFR 261 changed since 2023?" and get
+the actual regulation text, with citations, instead of a plausible-sounding guess.
+
+Unofficial community project. Not affiliated with or endorsed by the Office of the
+Federal Register, NARA, or GPO, and uses no government seals or logos.
+
+## Install
+
+Requires Python 3.11+. No API key — the eCFR API is open.
+
+Claude Code:
+
+```bash
+claude mcp add cfr -- uvx cfr-mcp
+```
+
+Any other MCP client:
+
+```json
+{
+  "mcpServers": {
+    "cfr": {
+      "command": "uvx",
+      "args": ["cfr-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `lookup_citation` | Text of a citation — `21 CFR 101.9`, `40 CFR 261.4(b)(1)`, `40 CFR Part 261 Subpart C` |
+| `search_regulations` | Full-text search; returns citations and snippets, never bodies |
+| `where_does_term_appear` | Which titles contain a term, with hit counts. Fetches no text |
+| `browse_structure` | The hierarchy of a title or part, no text |
+| `what_changed` | Amendment history and published corrections for a citation |
+| `list_agencies` | Maps agency names to the CFR titles they administer |
+
+Point-in-time works throughout: pass `date` as `YYYY-MM-DD` to read the CFR as it stood.
+
+## Design notes
+
+**Context budget is the whole game.** The eCFR `full` endpoint returns an entire
+downloadable XML document for a title-level request. Every tool here caps output and
+degrades to an outline rather than dumping text into the model's context. Title-level
+XML requests are refused outright.
+
+**Dates must be resolved, not assumed.** Versioner routes 404 on dates that aren't
+valid issue dates for a title, so the client resolves through `titles.json` first
+rather than passing today's date blindly.
+
+**Caching is courtesy.** The eCFR publishes no rate limit and has no key to identify
+callers politely, so the client caches to disk (historical dates forever, since
+point-in-time content is immutable) and self-limits concurrency. Set `CFR_MCP_CACHE_DIR`
+to relocate the cache.
+
+## Legal
+
+Regulation text is free to reproduce. **1 CFR 2.6** states that any person may reproduce
+or republish material appearing in the Federal Register, with no restrictions on what is
+reproduced, who reproduces it, or where. Federal government works are also outside
+copyright under 17 U.S.C. §105.
+
+**Incorporation by reference.** Some CFR sections incorporate private standards
+(ASTM, NFPA, ASHRAE) whose copyright status after incorporation remains unsettled.
+The eCFR does not contain the text of those standards and neither does this server —
+it returns the citation only. Obtain standards from the issuing organization or the
+Office of the Federal Register reading room.
+
+**Status of the text.** The eCFR is authoritative but unofficial. Anyone relying on it
+for legal research should verify against the current official CFR, the daily Federal
+Register, and the List of CFR Sections Affected (LSA).
+
+**Not legal advice.** This is a retrieval tool. It returns the text of regulations; it
+does not tell you whether you are compliant with them.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+```
+
+MIT licensed.

cfr_mcp-0.1.0/PLAN.md

@@ -0,0 +1,172 @@
+# PLAN.md — cfr-mcp: scaffold → published v0.1
+
+Execution plan for Claude Code. Work phase by phase; do not start a phase until
+the previous phase's acceptance criteria pass. Commit at the end of each phase.
+
+## Context
+
+The repo contains a working scaffold (~700 lines):
+
+- `src/cfr_mcp/citations.py` — CFR citation parser. **Tested, 20 cases passing.**
+- `src/cfr_mcp/client.py` — async httpx client. All endpoint paths in the
+  `ENDPOINTS` dict. **Never run against the live API.**
+- `src/cfr_mcp/xml_parse.py` — eCFR XML → text, with size capping.
+  **Written from documented conventions, never seen real XML.**
+- `src/cfr_mcp/cache.py` — disk cache. Historical dates cached forever.
+- `src/cfr_mcp/server.py` — FastMCP server, six tools. **JSON key names for
+  search/structure/versions/agencies responses are educated guesses.**
+- `tests/test_citations.py` — parser tests (pytest).
+
+The API: base `https://www.ecfr.gov`, no key. Services: admin
+(`/api/admin/v1/...`), search (`/api/search/v1/...`), versioner
+(`/api/versioner/v1/...`). Full endpoint list is in `client.py`.
+
+## Invariants — never violate these
+
+1. **Never request title-level XML.** `full_xml` refuses `is_title_only`
+   citations; keep it that way. Some titles are hundreds of MB.
+2. **Every tool output is capped.** Large content degrades to an outline with
+   instructions to drill down. No tool may return unbounded text.
+3. **Dates are resolved, not assumed.** Versioner routes 404 on invalid issue
+   dates; always resolve current dates through `titles.json`.
+4. **Cache failures never break lookups.** Cache is best-effort.
+5. **Errors are returned as readable strings to the model**, not raised through
+   the MCP layer, so the assistant can self-correct (e.g. bad date → explain).
+6. **Retrieval only.** No tool or description may imply compliance judgment or
+   legal advice. Keep the source disclaimer on content-bearing outputs.
+
+## Phase 0 — Environment (15 min)
+
+- [ ] `git init`, initial commit of the scaffold as-is.
+- [ ] `uv sync --extra dev`
+- [ ] `uv run pytest` → all citation tests pass.
+- [ ] Add MIT `LICENSE` file (year, author name).
+- [ ] In `client.py`, replace `YOURNAME`/`YOUR_EMAIL` in `USER_AGENT`
+      (ask the human for the GitHub username and contact email).
+
+**Accept:** pytest green, clean `git status`.
+
+## Phase 1 — Verify API reality, capture fixtures (1–2 h)
+
+Fetch real responses and save them under `tests/fixtures/`. Use small targets.
+
+- [ ] `GET /api/versioner/v1/titles.json` → `fixtures/titles.json`.
+      Confirm field names `number`, `latest_issue_date`, `up_to_date_as_of`.
+      Fix `latest_date_for_title()` if they differ.
+- [ ] `GET /api/versioner/v1/full/{date}/title-1.xml?part=2&section=2.6`
+      (Title 1 is tiny) → `fixtures/section_1_2_6.xml`.
+- [ ] Same for a mid-size section: `title-21 ... part=101&section=101.9`
+      → `fixtures/section_21_101_9.xml`.
+- [ ] A whole small part: `title-1 ... part=2` → `fixtures/part_1_2.xml`.
+- [ ] An appendix and a subpart request; confirm param names
+      (`appendix`, `subpart`) are what the API expects. Fix
+      `Citation.as_params()` if not.
+- [ ] `GET /api/search/v1/results?query=nutrition+labeling&per_page=3`
+      → `fixtures/search_results.json`. Record the real shape of results,
+      hierarchy fields, excerpt field, meta/total.
+- [ ] `GET /api/search/v1/counts/hierarchy?query=asbestos`
+      → `fixtures/counts_hierarchy.json`.
+- [ ] `GET /api/versioner/v1/structure/{date}/title-1.json`
+      → `fixtures/structure_title1.json`.
+- [ ] `GET /api/versioner/v1/versions/title-1.json` → `fixtures/versions.json`.
+      Confirm filter param names (`conditions[part]`,
+      `conditions[issue_date][gte]`) actually filter; note whether the
+      version entries include `amendment_date`, `issue_date`, `identifier`.
+- [ ] `GET /api/admin/v1/agencies.json` → `fixtures/agencies.json`.
+- [ ] `GET /api/admin/v1/corrections/title/1.json` → `fixtures/corrections.json`.
+- [ ] Write `tests/fixtures/NOTES.md` documenting every place the real
+      response differs from what the code assumes.
+
+**Accept:** all fixtures on disk; NOTES.md lists discrepancies (may be empty).
+
+## Phase 2 — Make the code match reality (2–4 h)
+
+- [ ] Fix `xml_parse._build()` against the XML fixtures. Verify: DIV nesting,
+      `TYPE`/`N` attributes, `HEAD` headings, paragraph elements, and that
+      heading number-stripping works on real headings.
+- [ ] Verify `extract_paragraphs` finds `(b)(1)` trails in real section text
+      (fixture 21 CFR 101.9 has deep paragraph nesting — ideal test).
+- [ ] Fix every guessed JSON key in `server.py` rendering loops
+      (search results, structure walk, versions, agencies, corrections).
+- [ ] Write fixture-backed tests (use `respx` to mock httpx against fixtures):
+      - `tests/test_xml_parse.py` — parse each XML fixture; assert headings,
+        section numbers, non-empty text; assert `render_capped` degrades to an
+        outline when `max_chars` is tiny.
+      - `tests/test_client.py` — date resolution from titles fixture; 404 →
+        readable `ECFRError`; title-level XML refusal; cache hit skips HTTP.
+      - `tests/test_tools.py` — call each of the six tools with mocked
+        transport; assert output is a string, contains expected citation,
+        and stays under the cap.
+- [ ] `uv run ruff check --fix .` and resolve remaining lint.
+
+**Accept:** full pytest suite green offline (fixtures only, no network).
+
+## Phase 3 — Live integration with Claude Code (1 h)
+
+- [ ] Register locally: `claude mcp add cfr -- uv run cfr-mcp`
+      (or `uv run mcp dev src/cfr_mcp/server.py` for the inspector).
+- [ ] Exercise each tool through the assistant and record results in
+      `docs/manual-test-log.md`:
+      1. "What does 21 CFR 101.9(c) require?" → correct paragraph text.
+      2. "Search the CFR for 'per- and polyfluoroalkyl'" → citations + snippets.
+      3. "Where does 'asbestos' appear in the CFR?" → hierarchy counts.
+      4. "Show the structure of 40 CFR Part 261" → outline, no text dump.
+      5. "Has 40 CFR 261.4 changed since 2023-01-01?" → amendment dates.
+      6. "Which CFR titles does the EPA administer?" → Title 40 (+ others).
+      7. Adversarial: "Give me all of Title 40" → graceful refusal with
+         guidance, not an error or a dump.
+      8. A paragraph that doesn't exist: "21 CFR 101.9(z)(9)" → falls back to
+         section text, does not fabricate.
+- [ ] Fix anything awkward the model trips on (tool descriptions are part of
+      the product — iterate on them here).
+
+**Accept:** all eight logged with sane transcripts.
+
+## Phase 4 — Hardening (1–2 h)
+
+- [ ] Title 35 is reserved: `lookup_citation("35 CFR 1.1")` must return a
+      clear "reserved title" message. Add test.
+- [ ] Very large part (e.g. 40 CFR 63): confirm outline degradation and
+      acceptable latency; consider streaming/size guard on the raw download
+      if response exceeds ~5 MB.
+- [ ] Date edge cases: pre-2017 dates (point-in-time floor), future dates,
+      malformed dates — each returns a helpful message. Tests.
+- [ ] Concurrency: fire 10 parallel `lookup_citation` calls; semaphore holds,
+      nothing corrupts the cache (meta/body write order).
+- [ ] Add `--version` / `-h` handling to `main()`.
+
+**Accept:** suite green, edge cases covered.
+
+## Phase 5 — Publish (1–2 h; human-in-the-loop)
+
+- [ ] README final pass: verify install block, tool table, legal section
+      (1 CFR 2.6, IBR caveat, "authoritative but unofficial" disclaimer,
+      no seals/no-endorsement note).
+- [ ] Create GitHub repo (human), push, add topics: `mcp`, `ecfr`, `cfr`,
+      `regulations`, `model-context-protocol`.
+- [ ] CI: GitHub Actions workflow running ruff + pytest on 3.11/3.12/3.13.
+- [ ] `uv build`; test the wheel in a clean venv: `uvx --from dist/*.whl cfr-mcp`
+      starts and responds to an MCP `initialize`.
+- [ ] Publish: human creates PyPI account + token; `uv publish`.
+- [ ] Verify end-to-end: `uvx cfr-mcp` from PyPI works in Claude Code.
+- [ ] Submit to the MCP registry / community server lists (human approves
+      the listing text).
+- [ ] Tag `v0.1.0`, GitHub release with a short changelog.
+
+**Accept:** a stranger can go from README to a working `lookup_citation`
+call in under five minutes.
+
+## Explicitly out of scope for v0.1
+
+- Hosted/remote transport (SSE/HTTP) — local stdio only.
+- Any paid features, alerting, or UI.
+- Fetching text of standards incorporated by reference — permanently out;
+  return citations only.
+- State regulations, Federal Register documents beyond corrections.
+
+## Backlog for v0.2 (do not build now)
+
+- Federal Register cross-links in `what_changed` (which rule caused the change).
+- Rendered side-by-side diffs between two dates.
+- `search_suggestions` tool using `/api/search/v1/suggestions`.
+- Prebuilt vertical part-bundles (food labeling, hazmat) as MCP resources.

cfr_mcp-0.1.0/README.md

@@ -0,0 +1,93 @@
+# cfr-mcp
+
+[![CI](https://github.com/mccallar/cfr-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mccallar/cfr-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/cfr-mcp)](https://pypi.org/project/cfr-mcp/)
+
+An MCP server that gives AI assistants access to the **US Code of Federal Regulations**.
+
+Ask "what does 21 CFR 101.9 require?" or "has 40 CFR 261 changed since 2023?" and get
+the actual regulation text, with citations, instead of a plausible-sounding guess.
+
+Unofficial community project. Not affiliated with or endorsed by the Office of the
+Federal Register, NARA, or GPO, and uses no government seals or logos.
+
+## Install
+
+Requires Python 3.11+. No API key — the eCFR API is open.
+
+Claude Code:
+
+```bash
+claude mcp add cfr -- uvx cfr-mcp
+```
+
+Any other MCP client:
+
+```json
+{
+  "mcpServers": {
+    "cfr": {
+      "command": "uvx",
+      "args": ["cfr-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `lookup_citation` | Text of a citation — `21 CFR 101.9`, `40 CFR 261.4(b)(1)`, `40 CFR Part 261 Subpart C` |
+| `search_regulations` | Full-text search; returns citations and snippets, never bodies |
+| `where_does_term_appear` | Which titles contain a term, with hit counts. Fetches no text |
+| `browse_structure` | The hierarchy of a title or part, no text |
+| `what_changed` | Amendment history and published corrections for a citation |
+| `list_agencies` | Maps agency names to the CFR titles they administer |
+
+Point-in-time works throughout: pass `date` as `YYYY-MM-DD` to read the CFR as it stood.
+
+## Design notes
+
+**Context budget is the whole game.** The eCFR `full` endpoint returns an entire
+downloadable XML document for a title-level request. Every tool here caps output and
+degrades to an outline rather than dumping text into the model's context. Title-level
+XML requests are refused outright.
+
+**Dates must be resolved, not assumed.** Versioner routes 404 on dates that aren't
+valid issue dates for a title, so the client resolves through `titles.json` first
+rather than passing today's date blindly.
+
+**Caching is courtesy.** The eCFR publishes no rate limit and has no key to identify
+callers politely, so the client caches to disk (historical dates forever, since
+point-in-time content is immutable) and self-limits concurrency. Set `CFR_MCP_CACHE_DIR`
+to relocate the cache.
+
+## Legal
+
+Regulation text is free to reproduce. **1 CFR 2.6** states that any person may reproduce
+or republish material appearing in the Federal Register, with no restrictions on what is
+reproduced, who reproduces it, or where. Federal government works are also outside
+copyright under 17 U.S.C. §105.
+
+**Incorporation by reference.** Some CFR sections incorporate private standards
+(ASTM, NFPA, ASHRAE) whose copyright status after incorporation remains unsettled.
+The eCFR does not contain the text of those standards and neither does this server —
+it returns the citation only. Obtain standards from the issuing organization or the
+Office of the Federal Register reading room.
+
+**Status of the text.** The eCFR is authoritative but unofficial. Anyone relying on it
+for legal research should verify against the current official CFR, the daily Federal
+Register, and the List of CFR Sections Affected (LSA).
+
+**Not legal advice.** This is a retrieval tool. It returns the text of regulations; it
+does not tell you whether you are compliant with them.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+```
+
+MIT licensed.

cfr_mcp-0.1.0/docs/manual-test-log.md

@@ -0,0 +1,100 @@
+# Manual test log — Phase 3 live integration
+
+2026-08-29, against the live eCFR API. Tools were exercised at the tool-call
+surface (the exact async functions MCP dispatches to), with arguments chosen
+as an assistant would choose them. Outputs below are summarized; sizes are
+exact.
+
+## 1. "What does 21 CFR 101.9(c) require?"
+
+`lookup_citation("21 CFR 101.9(c)")`
+
+- First run returned the full (c) block: correct text, but **35,281 chars —
+  violated the output cap invariant**. Fixed: an oversized paragraph now
+  returns its opening text plus a sub-paragraph list. Re-run: 3,340 chars,
+  begins with the correct "(c) The declaration of nutrition information…"
+  text and ends "Sub-paragraphs available: (1)…(9). Request a deeper
+  citation like 101.9(c)(1)". ✅
+
+## 2. "Search the CFR for 'per- and polyfluoroalkyl'"
+
+`search_regulations("per- and polyfluoroalkyl", limit=5)`
+
+- 1,268 chars. "72 result(s)… showing 5". Real citations (40 CFR 141.901,
+  705.1, 372.29, 705.3) with headings and clean snippets, no HTML. ✅
+
+## 3. "Where does 'asbestos' appear in the CFR?"
+
+`where_does_term_appear("asbestos")`
+
+- 4,616 chars. Title-level hit counts with top-3 parts nested under each
+  (e.g. Title 16 → Part 1304 Ban of Consumer Patching Compounds…). First
+  run leaked `<strong>` tags inside part headings (the counts endpoint
+  highlights the query term); fixed with the same HTML stripping used for
+  search. ✅
+
+## 4. "Show the structure of 40 CFR Part 261"
+
+`browse_structure(40, part="261")`
+
+- 6,378 chars. Subparts A–DD with section lines, appendices I–IX at the
+  bottom, zero body text. ✅
+
+## 5. "Has 40 CFR 261.4 changed since 2023-01-01?"
+
+`what_changed("40 CFR 261.4", since="2023-01-01")`
+
+- 1,358 chars. Eleven amendment entries 2023-03-29 → 2025-03-21 with
+  amendment and issue dates, plus part-261 published corrections with FR
+  citations. Filter params verified on the wire
+  (`part=261&issue_date[gte]=2023-01-01`). ✅
+
+## 6. "Which CFR titles does the EPA administer?"
+
+`list_agencies("environmental protection")`
+
+- 93 chars: "Environmental Protection Agency
+  [environmental-protection-agency] — Title(s) 2, 5, 40, 41, 48". First run
+  sorted titles as strings ("2, 40, 41, 48, 5"); fixed to numeric sort. ✅
+
+## 7. Adversarial: "Give me all of Title 40"
+
+`lookup_citation("Title 40")`
+
+- 124 chars, zero network calls: "'Title 40' names a whole CFR title, which
+  is far too large to retrieve. Use browse_structure to navigate it, or
+  name a part." Graceful refusal with guidance. ✅
+
+## 8. Nonexistent paragraph: "21 CFR 101.9(z)(9)"
+
+`lookup_citation("21 CFR 101.9(z)(9)")`
+
+- First run fell back to a degenerate outline (a childless section's
+  "outline" was just its heading, twice) and never said the paragraph was
+  missing. Fixed: now 192 chars — "Paragraph (z)(9) does not exist in
+  21 CFR 101.9. Top-level paragraphs present: (a)…(l). Request the whole
+  section or one of those paragraphs." No fabrication. ✅
+
+## Fixes made during this phase
+
+1. Output cap now applies to paragraph-narrowed text (scenario 1); oversized
+   paragraphs degrade to intro + sub-paragraph list.
+2. `where_does_term_appear` strips HTML from headings (scenario 3).
+3. `list_agencies` sorts titles numerically (scenario 6).
+4. Missing paragraphs get an explicit not-found message listing the
+   paragraphs that do exist (scenario 8).
+5. `render_capped` on a huge childless section now outlines its top-level
+   paragraphs instead of repeating the heading.
+
+All five have regression tests in `tests/`.
+
+## Phase 4 live checks
+
+- `lookup_citation("40 CFR Part 63")` (one of the largest CFR parts): the
+  streaming byte guard aborted the download at 20 MB after 18.1s with
+  "Request a smaller unit — a subpart or a section — or use
+  browse_structure to navigate this part." No multi-hundred-MB download,
+  no dump. ✅
+- `lookup_citation("40 CFR Part 261")` (mid-size, 1.5M chars of text,
+  ~6 MB XML): 1.7s, degraded to an 8,009-char subpart/section outline with
+  per-node sizes. ✅

cfr_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "cfr-mcp"
+version = "0.1.0"
+description = "MCP server for the US Code of Federal Regulations (eCFR)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["mcp", "cfr", "ecfr", "regulations", "government", "compliance"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Text Processing :: Indexing",
+]
+dependencies = [
+    "mcp>=2.0",
+    "httpx>=0.27",
+    "lxml>=5.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "respx>=0.21", "ruff>=0.6"]
+
+[project.scripts]
+cfr-mcp = "cfr_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/mccallar/cfr-mcp"
+Repository = "https://github.com/mccallar/cfr-mcp"
+Issues = "https://github.com/mccallar/cfr-mcp/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cfr_mcp"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100

cfr_mcp-0.1.0/src/cfr_mcp/cache.py

@@ -0,0 +1,78 @@
+"""Disk cache for eCFR responses.
+
+eCFR updates at most daily, and historical point-in-time content never changes
+at all. Caching is the whole reason this server can be a good citizen against
+an API that publishes no rate limit and has no key to identify us politely.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+DEFAULT_TTL = 24 * 60 * 60  # eCFR updates daily
+
+
+def _default_dir() -> Path:
+    env = os.environ.get("CFR_MCP_CACHE_DIR")
+    if env:
+        return Path(env)
+    base = os.environ.get("XDG_CACHE_HOME") or (Path.home() / ".cache")
+    return Path(base) / "cfr-mcp"
+
+
+class Cache:
+    def __init__(self, directory: Path | None = None, ttl: int = DEFAULT_TTL) -> None:
+        self.dir = directory or _default_dir()
+        self.ttl = ttl
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def key(self, path: str, params: dict[str, Any] | None = None) -> str:
+        blob = path + "?" + json.dumps(params or {}, sort_keys=True)
+        return hashlib.sha256(blob.encode()).hexdigest()[:32]
+
+    def _paths(self, key: str) -> tuple[Path, Path]:
+        return self.dir / f"{key}.body", self.dir / f"{key}.meta"
+
+    def get(self, key: str) -> str | None:
+        body_path, meta_path = self._paths(key)
+        if not (body_path.exists() and meta_path.exists()):
+            return None
+        try:
+            meta = json.loads(meta_path.read_text())
+        except (json.JSONDecodeError, OSError):
+            return None
+        if (
+            not meta.get("immutable")
+            and time.time() - meta.get("stored_at", 0) > self.ttl
+        ):
+            return None
+        try:
+            return body_path.read_text(encoding="utf-8")
+        except OSError:
+            return None
+
+    def set(self, key: str, body: str, *, immutable: bool = False) -> None:
+        body_path, meta_path = self._paths(key)
+        try:
+            # Write body first; a torn write leaves no meta and reads as a miss.
+            body_path.write_text(body, encoding="utf-8")
+            meta_path.write_text(
+                json.dumps({"stored_at": time.time(), "immutable": immutable})
+            )
+        except OSError:
+            pass  # cache failures must never break a lookup
+
+    def clear(self) -> int:
+        removed = 0
+        for f in self.dir.glob("*.*"):
+            try:
+                f.unlink()
+                removed += 1
+            except OSError:
+                pass
+        return removed // 2