
sureforge-cfr
io.github.SureForgeTech/sureforge-cfr
Self-hosted, searchable index of US Title 38 CFR (veterans' benefits rules) built from eCFR.
Documentation
sureforge-cfr
Names. This repository is
sureforge-cfr. The npm package and the command it installs are still calledcfr-free(npm install -g cfr-free,npx -y cfr-free …), so the commands below keep that name.
Self-hosted Title 38 CFR data service: it builds a local, full-text searchable index of Title 38 of the Code of Federal Regulations (the VA benefits rulebook) straight from the public eCFR API, and serves it through an MCP server (for AI assistants like Claude) and a small HTTP API ("Titan-style" query surface). No cloud dependencies, no API keys, no telemetry — one Node process and one SQLite file.
What you get
- Local full-text search over every section and appendix of Title 38, powered by SQLite FTS5 (BM25-ranked with citation/heading weighting, relevance snippets, and the matched terms shown per hit).
- Honest about images: a few provisions publish their rating tables as
eCFR images rather than text. Those provisions carry an explicit
[image content not included: <path>]marker where the graphic belongs, so a missing table is never mistaken for complete text. Nothing is fetched or transcribed — the service stays fully offline. - Read-only web UI (search, browse, section reads, line-level redlines, copy-a-citation) over the same JSON API — rating tables keep their structure, and the whole UI is reachable from the keyboard.
- MCP server with ten read-only tools any MCP client can use: seven
offline index-backed ones (
search_regulations,get_section,browse_title38,index_status,list_parts,health,compare_snapshots) plus three that fetch the live eCFR versioner on demand (get_section_at(one provision as it stood at a date),diff_issues,redline). - HTTP JSON API for scripts and apps: search, read sections, browse the CFR hierarchy, health check, Prometheus metrics.
- Measured retrieval: a frozen query set and runner score the search
over citations, abbreviations and plain-language questions — see
docs/research/retrieval-baseline-2026-10-20.md. - Freshness tracking: the index records the eCFR issue date it was built from and warns when it goes stale or drifts from the structure tree.
- One store, several titles:
CFR_TITLESnames the CFR titles a sync covers (Title 38 by default). Each title's provisions are stored under its own authority — a Title 32 sync never touches Title 38's rows — with per-title issue dates, structure and corpus receipts. Reads still default to Title 38. - Backup-friendly:
cfr-free export <path> [jsonl|md]writes a consistent snapshot of the index you can copy anywhere (sqlite default;jsonlandmdfor pipeline ingestion).cfr-free compare <from> <to>and thecompare_snapshotsMCP tool compare two stored SQLite snapshots offline, reporting added, removed and changed provisions with dated source links and bounded text-change hunks. - Verifiable copies:
cfr-free verify [snapshot]checks that a local index or a stored snapshot opens cleanly and that the corpus receipt it records still describes its own Title 38 rows — offline, and without touching the file it reads.
Requirements
- Node.js ≥ 22.16 (uses the built-in
node:sqlitewith FTS5; Node 22.16 is the first release whosenode:sqliteenables it) - Network access only for
cfr-free sync,cfr-free diff,cfr-free redlineandcfr-free historical(~2–3 MB from ecfr.gov per full-title fetch; the two-date views fetch twice); the startup refresh of a stale or empty index bysearch,serveandmcp(unlessCFR_AUTO_SYNC=0); the opt-in periodic re-sync inserveandmcpwhenCFR_REFRESH_HOURSis set (default 0 = off);serve's/api/v1/diffand/api/v1/redlineroutes; andmcp's three eCFR-backed tools (get_section_at,diff_issues,redline), which fetch from eCFR on demand. Reads from a fresh index never touch the network.
Quickstart
Five ways in, depending on what you have. The first needs nothing but Docker; the second needs only npm; the third needs only Node and runs the package straight from a release tarball (no compiler); the fourth needs npm and a compiler; the fifth needs a checkout.
New here? First 10 minutes picks one of these routes and walks it end to end: build the local index, search it, read a provision and cite it.
1. Docker (nothing to install)
No published image yet. No container image is published under
ghcr.io/sureforgetechso far. Build one from a checkout first withdocker build -t cfr-free:local .; the commands below use that local tag. The oldghcr.io/deffenda/cfr-freeimage predates the move to SureForgeTech and is not maintained here.
docker run -d --name cfr-free -p 127.0.0.1:8787:8787 -v cfr-data:/data \
cfr-free:local
The image is built locally (see above). It syncs the index on first
start (~5 s, ~2–3 MB from eCFR) and serves the API on
http://127.0.0.1:8787; the index persists in the cfr-data volume. Any
CLI command works the same way, e.g. docker run --rm -v cfr-data:/data cfr-free:local sync to refresh, or … export /data/backup.sqlite to snapshot into the volume. Details under
Docker below.
The API has no authentication. The command above publishes it on loopback
only, so only this machine can reach it. Publishing it on every interface
takes -p 8787:8787 instead — and then it needs your own auth in front.
2. From npm (no compiler, no Docker)
npm install -g cfr-free
# or, with no install at all:
npx -y cfr-free version # -> 0.2.1
npx -y cfr-free sync # build the local index (~2-3 MB, ~5 s)
npx -y cfr-free serve # HTTP API on http://127.0.0.1:8787
The published tarball ships the compiled dist/, so this route needs
neither a compiler nor a checkout — it is the fastest way in.
3. From a release tarball (no compiler)
npx -y https://github.com/SureForgeTech/sureforge-cfr/releases/download/v0.2.1/cfr-free-0.2.1.tgz version # -> 0.2.1
npx -y https://github.com/SureForgeTech/sureforge-cfr/releases/download/v0.2.1/cfr-free-0.2.1.tgz serve # HTTP API on http://127.0.0.1:8787
Every GitHub release carries the package tarball at
releases/download/<tag>/cfr-free-<version>.tgz; for v0.2.1 that
tarball holds the same contents the npm registry serves (verified by
unpacking both: identical file trees). npx installs the tarball
directly from the URL — the cfr-free package itself never comes from
the registry, no compiler runs on first use, and the version in the URL
pins the release exactly. npx does still fetch the package's runtime
dependencies from npm (they are not bundled). Verified on the v0.2.1
release, 2026-10-29: both commands above ran end to end (version →
0.2.1; serve answered /health with HTTP 200). Swap the tag and
filename together to pick another release.
4. From GitHub (no publish step)
npx -y github:SureForgeTech/sureforge-cfr version # -> 0.2.3
npx -y github:SureForgeTech/sureforge-cfr serve # HTTP API on http://127.0.0.1:8787
npx fetches and compiles the project on first use, so the first run takes
a minute and needs a compiler (npm runs the project's prepare script when
it installs from a git URL, and that script runs tsc). The Docker route
above needs neither.
To use it as a dependency of your own project:
npm install github:SureForgeTech/sureforge-cfr
A global install from a git URL (
npm install -g github:…) does not work, and the failure is npm's rather than the project's. Measured on npm 11.20.0, five runs in a row left the SAME broken end state: the package is not installed, and thecfr-freecommand npm puts in your PATH points at a file that does not exist, so running it fails with "no such file or directory".Whether npm reports the failure varies, and the quiet case is the more misleading one: most runs print "added 104 packages" and exit 0, so nothing looks wrong until you run the command; some abort part-way with
ENOENT … chmod … node_modules/which/bin/node-which(exit 254). On npm 10.9.9 the same class of failure presents as a dropped dependency tree (ENOENT … readlink … node_modules/.bin/fxparser). All of this was measured, and it reproduces on the unmodified repository too. Usenpx, a project-local install, the npm route above, or the Docker image instead — all four were re-verified on npm 11.20.0.
5. From a source checkout
# requires Node >= 22.16
git clone https://github.com/SureForgeTech/sureforge-cfr.git
cd sureforge-cfr
npm ci # install the pinned dependencies
npm run build # compile to dist/ (the CLI entry point is dist/cli.js)
node dist/cli.js version # -> 0.2.3 (verifies the build)
node dist/cli.js sync # build the local index (~2-3 MB download, ~5 s)
node dist/cli.js serve # HTTP API on http://127.0.0.1:8787
# or
node dist/cli.js mcp # MCP server on stdio (default command)
node dist/cli.js export ./backup.sqlite # consistent snapshot of the local index
node dist/cli.js search PTSD # ranked provisions from the local index
node dist/cli.js diff 2026-01-01 2026-06-01 # provision changes between two issue dates
node dist/cli.js export /tmp/old.sqlite # store a snapshot before refreshing
node dist/cli.js compare /tmp/old.sqlite ./backup.sqlite # offline snapshot comparison
node dist/cli.js redline 2026-01-01 2026-06-01 4.125 # line-level redline of one provision
npm link in the checkout puts cfr-free on your PATH, after which the
examples above work verbatim as cfr-free ….
Searching from the command line
cfr-free search runs the same search the MCP and HTTP surfaces run, and
takes the same parameters — the flag names mirror the API's query
parameters (--per-page is per_page, --kind is kind):
cfr-free search PTSD # the hits, then the grounding summary
cfr-free search --json PTSD # the search response verbatim, for a script
cfr-free search --per-page 20 PTSD # 20 hits per page (1-20; the default is 10)
cfr-free search --page 2 --per-page 20 PTSD # the second page
cfr-free search --part 4 --chapter I PTSD # narrowed to one part and chapter
cfr-free search --kind appendix PTSD # sections (the default) or appendices
cfr-free search --title 32 PTSD # another CFR title (the default is 38)
cfr-free search --title all PTSD # every stored title, each hit labeled
The flags are query parameters, not configuration: everything that configures the service stays an environment variable, so an MCP client config stays uniform.
--title takes a CFR title number or all: the search runs in that
title, and every hit says which title it belongs to (--title all searches
every stored title). Title 38 is the default.
cfr-free sync writes the index at ~/.cfr-free/index.sqlite. To try it
against a throwaway index instead of your own, point CFR_INDEX_PATH
somewhere else:
CFR_INDEX_PATH=/tmp/cfr-smoke.sqlite node dist/cli.js sync # ~5 s, then delete the file
Verifying an index or a snapshot
cfr-free verify answers two questions about a local file: is it usable, and
does the corpus receipt it records still describe its own Title 38 rows?
Verification runs offline and leaves the main database file and its
permissions intact. The configured index is read with SQLite's WAL protocol
while sync or serve is running. SQLite can update shared memory in the
existing -shm file and can create missing -wal and -shm sidecars if the
directory is writable. A positional snapshot must be a standalone file
without journal sidecars and is opened immutably.
cfr-free verify # the index at CFR_INDEX_PATH
cfr-free verify ./backup.sqlite # a stored snapshot instead
verified /home/you/.cfr-free/index.sqlite
schema: ok (quick_check passed)
provisions: 2953 sections + 17 appendices (Title 38)
issue date: 2026-10-16
corpus receipt: match — the recorded hash equals the receipt recomputed from the current Title 38 rows
note: a receipt over this index that detects ACCIDENTAL corruption of the local copy — not a signature, and no claim about the upstream text
The receipt is the SHA-256 digest of the file's Title 38 per-provision
content hashes. Verify reads title.38.corpus_hash first and falls back to
the legacy corpus_hash key. Comparing the recorded and recomputed
digests can detect changes such as a truncated or edited row. If the receipt
is absent, the file is readable and usable, but the report cannot
establish whether its rows are the ones a sync wrote.
| Situation | Exit | Meaning |
|---|---|---|
| The file opens, its schema is intact | 0 | The index is usable — including an absent receipt, which the report states plainly |
| The recorded receipt does not match the rows | 1 | The file is readable but is not the copy its receipt describes |
| The path is missing, unreadable, or not a cfr-free index | 2 | Nothing was verified — the path is the reader's mistake, not a defect in the file |
No new exit code is introduced: verify reuses the tool's existing contract
(2 for a usage error, 1 for a failure).
Docker
docker run -d --name cfr-free -p 127.0.0.1:8787:8787 -v cfr-data:/data \
cfr-free:local
The API has no authentication. The command above publishes it on loopback
only, so only this machine can reach it. Publishing it on every interface
takes -p 8787:8787 instead — and then it needs a reverse proxy with auth in
front of it.
The container syncs on first start (~5 s, ~2–3 MB from eCFR), then serves
the HTTP API; the index persists in the cfr-data volume mounted at /data.
Any CLI command works the same way, e.g.
docker run --rm -v cfr-data:/data cfr-free:local sync to
refresh, or … export /data/backup.sqlite to snapshot into the volume.
The image runs as a non-root user and binds 0.0.0.0 inside the container with the remote opt-in already set. That part is a container-networking requirement, not an exposure decision: a process bound to the container's own 127.0.0.1 cannot be reached through a published port, so the published port is the exposure gate — and the documented default publishes on loopback. Outside Docker the CLI still defaults to 127.0.0.1 with CFR_ALLOW_REMOTE=1 required. When you do expose it, a per-peer token-bucket rate limit (60-burst, 10 tokens/s) turns on automatically. The budget is spent by cost, not by request: a read of the local index costs one token, and a route that pulls the whole upstream document from eCFR costs ten.
Behind a TLS-terminating proxy, add Strict-Transport-Security there rather than in the app: the header is a promise about the public hostname, and the app does not know it. The app answers with Referrer-Policy: no-referrer on every route, so a link out of a response cannot carry the URL you were reading to the next site. The release workflow is set up to publish images to GHCR on v* tags with build-provenance attestations; none has been published under ghcr.io/sureforgetech yet.
Compose is the one-command deployment, and it binds loopback too:
docker compose up -d --build serves the API on 127.0.0.1:8787 with a
named volume, healthcheck, and sync left explicit
(docker compose run --rm cfr-free sync) so starts never trigger a surprise
download.
The package is on npm (npm view cfr-free version prints the latest; see
Quickstart). Releases publish from the v*-tag workflow
with OIDC provenance (no publish token), gated behind the
NPM_TRUSTED_PUBLISHING repository variable plus one-time
trusted-publisher registration on npmjs.com. The publish job verifies
before it publishes that the packed tarball carries the executable and
every file it imports, and that the tag matches the package.json
version — so a release cannot ship a broken package.
Verify the install (smoke checklist)
Every command below was run against an isolated throwaway index
(CFR_INDEX_PATH=/tmp/smoke.sqlite) on the 2026-10-16 corpus; the
outputs are what you should see. Nothing outside /tmp is touched.
The install routes were measured, not assumed. A clean global install of
the packed tarball into a throwaway prefix was run and the installed binary
was exercised (--version, and a search against a copy of the index); the
GitHub Release asset route — the same tarball, fetched from a release URL —
was created, downloaded and installed end to end in a scratch
repository; it now also runs straight from this repository's own
releases (v0.2.1, verified 2026-10-29, see Quickstart). A
project-local npm install github:deffenda/cfr-free was run and its
binary exercised, and npx -y github:deffenda/cfr-free was run, MCP over
stdio included.
The route that does not work — npm install -g github:… — was measured
too, and the failure is npm's (see Quickstart). The sequence
below was run against a provisioned checkout; what it does not cover is an
install on a machine with no npm cache and no network beyond the first
fetch.
export CFR_INDEX_PATH=/tmp/smoke.sqlite # never your real index
# 1. the build is what you think it is
node dist/cli.js version # -> 0.2.3
# 2. network: build the index (~2-3 MB, ~5 s)
node dist/cli.js sync
# -> synced 2953 sections + 17 appendices (issue date 2026-10-16; ...
# 9 provisions contain image content not included; 2134 ms; corpus hash ...)
# 3. HTTP read (no network from here on)
CFR_PORT=8791 node dist/cli.js serve & SERVER_PID=$!
curl -s http://127.0.0.1:8791/health | head -c 80
# -> {"status":"ok","issueDate":"2026-10-16","syncedAt":...
curl -s 'http://127.0.0.1:8791/api/v1/search?q=4.130&per_page=1' | head -c 80
# -> {"query":"4.130","page":1,"perPage":1,"total":42,...
curl -s http://127.0.0.1:8791/api/v1/sections/4.130 | head -c 80
# -> {"citation":"4.130","kind":"section","heading":"Schedule of ratings...
# 4. offline restart: reads come from the local index, no network
kill "$SERVER_PID"; CFR_PORT=8791 node dist/cli.js serve & SERVER_PID=$!
# /health answers identically — that is the point
# 5. MCP over stdio: initialize, then call a tool
printf '%s\n%s\n%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_section","arguments":{"citation":"38 C.F.R. § 4.130"}}}' \
| node dist/cli.js mcp | tail -1 | head -c 120
# -> {"result":{"content":[{"type":"text","text":"citation: 4.130\nkind: section\nheadi...
# (note: the DOTTED display citation resolves — P1-03; the text channel is a
# human-readable rendering, the machine contract is `structuredContent`)
# 6. export: the whole corpus, offline
node dist/cli.js export /tmp/smoke.jsonl jsonl
# -> exported 2970 provisions as jsonl (17062107 bytes) to /tmp/smoke.jsonl
kill "$SERVER_PID"; rm -f /tmp/smoke.sqlite /tmp/smoke.jsonl # clean up
Only steps 1–2 need the network; 3–6 are fully offline once the index exists. If step 3 answers and step 4 answers identically after the restart, your install reads from the local index exactly as intended.
Use with Claude (MCP)
Add to your MCP client config (e.g. claude_desktop_config.json):
{
"mcpServers": {
"cfr-free": {
"command": "npx",
"args": ["-y", "cfr-free", "mcp"]
}
}
}
Using Claude Code? The same server registers in one command (verified 2026-10-29):
claude mcp add cfr-free -- npx -y cfr-free mcp
That writes the local scope — this project only, the default;
claude mcp add -s user cfr-free -- npx -y cfr-free mcp registers it for
every project instead.
All of these forms run npx -y cfr-free mcp under the hood: nothing
installed, no path to edit, and the published tarball ships compiled —
no compiler runs on first use. The JSON config also works from the git URL
("args": ["-y", "github:SureForgeTech/sureforge-cfr", "mcp"]), which npx fetches
and compiles on first use (verified end to end: the list_parts tool
answers over stdio). If you built it from a checkout, use the absolute
path to the built CLI, because MCP clients do not inherit your shell's
PATH:
{
"mcpServers": {
"cfr-free": {
"command": "/absolute/path/to/cfr-free/dist/cli.js",
"args": ["mcp"]
}
}
}
Then ask things like "What does 38 CFR 4.125 say about diagnosing mental disorders?" or "Search Title 38 for traumatic brain injury compensation."
MCP tools
| Tool | Arguments | Returns |
|---|---|---|
search_regulations | query, page?, per_page?, part?, kind?, chapter?, title? | Ranked hits: citation (+ 38 C.F.R. § display form, ecfr.gov link), heading, snippet, score, matches — with exact-citation pinning, "quoted phrase" search, and claims-acronym expansion (PTSD, TDIU, SMC, …). Each response also carries matchedTerms/unmatchedTerms: the query's content words the returned hits did and did not answer. title selects the CFR title (the default is 38; all searches every stored title), and every hit carries the title it belongs to |
get_section | citation (e.g. 38 CFR 4.125), title? | Full section text as markdown + ecfr.gov link + cross-references with availability flags. title names the CFR title to read within. With no title in the request or citation text, the read checks only Title 38. A miss returns not_found with title=N guidance for any other stored titles holding the citation. |
browse_title38 | chapter?, part?, subpart?, subject_group? | Children of the requested hierarchy level (a subject_group holds the sections of one regulatory subject) |
index_status | — | Issue date, last sync, row counts, staleness, drift flag, corpus receipt hash, and what the last sync amended/added/removed |
list_parts | — | Parts in the index with titles and section/appendix counts |
health | — | One-call readiness verdict: ready, stale, degraded (structure drift), or empty |
compare_snapshots | from_snapshot, to_snapshot, part? | Offline comparison of two stored index snapshots: added/removed/changed provisions with both recorded issue dates, hierarchy, dated ecfr.gov permalinks, image-content flags and bounded text-change hunks |
get_section_at | at_date (YYYY-MM-DD), citation | One provision as it stood at a date: the eCFR revision in force then, fetched from eCFR on demand (no local index; a short-lived in-memory memo may reuse a document fetched moments ago; the point-in-time archive starts 2017-01-01) |
diff_issues | from_date, to_date | Provision-level diff between two eCFR issue dates: changed/added/removed citations (capped, with a truncation flag) |
redline | from_date, to_date, citation | Line-level redline of one provision between two eCFR issue dates: status, both sides' text, and per-line hunks |
All tools are read-only; the seven index tools query only the local index
and never hit the network (compare_snapshots reads two stored SQLite
snapshots and never contacts eCFR), while get_section_at, diff_issues and
redline fetch from eCFR on demand (a point-in-time revision, or two issue
dates' full-title XML); a fetched document is reused for up to five minutes by
the process that fetched it (at most four documents are kept), and concurrent
readers of the same date share one upstream fetch. Search and section
responses carry a freshness envelope (indexStale + a notice when the local
index has aged out) so a client can never unknowingly quote a lapsed version.
Beyond tools, the server exposes three MCP resources that clients can read
directly — cfr://index/status (freshness JSON: issue date, last sync, row
counts, staleness, drift, corpus receipt hash), cfr://title38/parts (parts with titles and
counts), and cfr://title38/definitions (§ 3.1 master definitions section
detail) — plus two prompts: cfr_research (topic, part?), which walks
a model through the search → read → cite workflow, and
cfr_claim_evaluation (issue, part?, citation?), which encodes the
adjudicator workflow: readiness gate → locate criteria → quote verbatim →
follow cross-references → paste-ready citations with source URLs.
HTTP API
| Method | Path | Query params |
|---|---|---|
GET / HEAD | /health | — |
GET / HEAD | /metrics | — (Prometheus text format) |
GET / HEAD | /api/v1/search | q (required), page, per_page, part, kind, chapter, title |
GET / HEAD | /api/v1/sections/:citation | — (URL-encode citations with spaces), title |
GET / HEAD | /api/v1/browse | chapter, part, subpart, subjgrp |
GET / HEAD | /api/v1/diff | from, to (both required; fetches from eCFR on demand) |
GET / HEAD | /api/v1/redline | from, to, citation (all required; fetches from eCFR on demand) |
title selects the CFR title a read runs in — a title number (the default is 38) or all for the search route, where every hit then carries the title it
belongs to. A section read with no title in the request or citation text looks
only in Title 38. A miss returns 404 not_found with title=N guidance for any
other stored title holding the citation. When a search query is a citation that
names a title outside the search scope, notice suggests passing title=N.
/health and /metrics additionally expose diskFree/diskTotal and the
cfr_free_disk_free_bytes/cfr_free_disk_total_bytes gauges when the platform
provides fs.statfs (as of boot or last refresh round); omitted otherwise.
The three index-backed reads (/api/v1/search, /api/v1/sections/:citation,
/api/v1/browse) send a strong ETag over the response payload. Resend it as
If-None-Match and the server answers 304 Not Modified with no body when the
text has not changed, so a client can confirm the provision it quotes without
downloading it again:
etag=$(curl -sD - -o /dev/null 'http://127.0.0.1:8787/api/v1/sections/4.125' \
| awk 'tolower($1) == "etag:" { print $2 }' | tr -d '\r')
curl -s -o /dev/null -w '%{http_code}\n' -H "If-None-Match: $etag" \
'http://127.0.0.1:8787/api/v1/sections/4.125' # 304
/health, /metrics and the two eCFR-fetching routes (/api/v1/diff,
/api/v1/redline) carry no validator, and an error response is never a 304.
curl 'http://127.0.0.1:8787/api/v1/search?q=traumatic%20brain%20injury&part=4'
curl 'http://127.0.0.1:8787/api/v1/sections/4.125'
curl 'http://127.0.0.1:8787/api/v1/browse?chapter=I&part=17'
curl 'http://127.0.0.1:8787/metrics'
The full request/response contract (schemas, error envelopes) is documented in
docs/openapi.yaml (OpenAPI 3.1).
The API is intentionally minimal: GET-only, no request bodies, no
templating, bound to 127.0.0.1 by default. The deliberate non-JSON
responses are /metrics (Prometheus exposition text for scrapers) and the
static web UI assets. There is no authentication — if you bind it to a
non-loopback address you must put it behind your own reverse proxy/auth
(CFR_ALLOW_REMOTE=1 is required to allow that, as an explicit opt-in).
The serve root / also serves a read-only web UI (search + section
reader with chapter/part browse + a redline view, over the same JSON API, hash-routed) — no auth, loopback bind by
default like the rest of the surface.
The XML parser escapes inline links, reference links, images, raw HTML and angle-bracket autolinks in the Markdown body. Bare URLs are preserved.
Configuration
All configuration is environment variables (flags are deliberately avoided so MCP client configs stay uniform):
| Variable | Default | Meaning |
|---|---|---|
CFR_INDEX_PATH | ~/.cfr-free/index.sqlite | SQLite index location |
CFR_TITLES | 38 | CFR titles to sync (comma-separated, 1–50); each is stored under its own authority |
CFR_MAX_AGE_DAYS | 7 | Index older than this is reported stale |
CFR_AUTO_SYNC | 1 | Sync at startup when index empty/stale |
CFR_REFRESH_HOURS | 0 | Hours between background refreshes while serving (0 = off) |
CFR_HOST | 127.0.0.1 | HTTP bind address |
CFR_PORT | 8787 | HTTP bind port |
CFR_ALLOW_REMOTE | unset | Set 1 to permit non-loopback binds |
CFR_ALLOWED_HOSTS | unset | Host names the server answers to besides loopback (a proxy); setting it also guards a remote bind |
CFR_TRUSTED_PROXIES | unset | Comma-separated proxy IPs trusted to forward client addresses for rate limiting |
CFR_LOG_LEVEL | info | debug | info | warn | error |
Logs are structured JSON lines on stderr only — stdout is reserved for MCP's JSON-RPC protocol.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Generic error (sync failure, corrupt index, …) |
2 | Usage or configuration error |
3 | Index unavailable (empty, and auto-sync disabled) |
4 | HTTP port could not be bound (in use or permission denied) |
5 | Refused to overwrite an existing export file (remove it or pick another path) |
Scripts can branch on these — e.g. retry later on 3, pick another port
on 4. cfr-free verify adds one meaning to 1: the file opened, but the
corpus receipt it records does not match its own rows.
Development
npm ci
npm run ci # format:check + lint + workflow lint + typecheck + tests + build + audit
npm run test:coverage
npm run scan # gitleaks + osv-scanner + trivy + semgrep (skips missing tools)
Local LLM review (Gemma via LM Studio)
npm run review # reviews docs/SPEC.md + src/ with the local model
npm run review:spec # spec only
Talks to LM Studio's OpenAI-compatible endpoint (http://localhost:1234 by
default, model google/gemma-4-12b). Configure with LMSTUDIO_BASE_URL,
LMSTUDIO_MODEL, LLM_REVIEW_TIMEOUT_MS, or --model / --base-url /
--max-tokens / --instruction flags. Reasoning models are handled
automatically (retries with a larger token budget when the visible answer
has not been emitted yet).
Architecture
eCFR API ──sync──▶ SQLite (sections + FTS5 + structure meta)
▲ ▲
│ │
MCP tools (stdio) HTTP API (node:http)
src/core/— eCFR client, XML parser, FTS5 store, sync, service facadesrc/mcp/— MCP server and tool registrationssrc/titan/— HTTP JSON APIsrc/commands/— one entrypoint per subcommand:mcp,sync,diff,compare,redline,historical,search,serve,export,verify(helpandversiondispatch fromsrc/cli.ts)docs/SPEC.md— the design authority;docs/research/delivery-log.md— the review dispositions and the closed delivery record
Sync is atomic: the title's slice of the index is replaced inside one
BEGIN IMMEDIATE transaction under WAL, so concurrent readers never see a
partial build, and an interrupted sync simply rolls back.
Data source & attribution
Regulatory content comes from the eCFR API operated by the Office of the Federal Register and the Government Publishing Office. eCFR content is in the public domain (17 U.S.C. § 105). cfr-free is an independent project and is not endorsed by or affiliated with the VA, the OFR, or GPO. This tool is not legal advice; verify citations against the official eCFR.
Security
See SECURITY.md for reporting vulnerabilities and the security posture summary. Reported by default: lint/strict-TS/typecheck/coverage/Audit gates (plus local trivy/semgrep/osv-scanner/gitleaks scans), zero runtime dependencies beyond the MCP SDK, XML parser hardening (no DOCTYPE, bounded depth/size), FTS query sanitization (no SQL injection surface), and loopback-only networking by default.
Feedback
Wrong citation, ranking surprise, installation obstacle, feature request: open an issue (usage questions fit Discussions). User feedback is the project's demand signal — the roadmap's stage E reads it before any expansion decision.
License
Apache-2.0. Releases up to and including v0.2.1 were published under the MIT License.
cfr-freenpm install cfr-free