fpf-memory MCP server
Commit Nov 14, 2026Lets an AI client perform deterministic, vectorless retrieval over the First Principles Framework (FPF) patterns, routes, and technical specifications.
Also known as venikman/fpf-memory
- Stars
- 11
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- —
What is fpf-memory MCP?
fpf-memory lets an AI client perform deterministic, vectorless retrieval over the First Principles Framework (FPF) patterns, routes, and technical specifications. It exposes 8 tools, such as browse_fpf_catalog, search_fpf, ask_fpf.
Summary generated from the project's README
About fpf-memory MCP server
Retrieving structured technical specifications and reasoning patterns from the First Principles Framework is what this server enables for AI agents. It provides a deterministic, vectorless way to query a complex framework of named patterns, routes, and definitions, ensuring that meanings and claims remain stable across different contexts and tools. This is designed for engineering, research, and management teams who need to model complex work with inspectable reasoning.
Users can interact with the framework via a local MCP server using Bun or through a hosted HTTP endpoint. The system operates by compiling a markdown specification into a local index of IDs, relations, and anchors, avoiding the need for a vector database, Python, or remote indexing services. It supports various modes of operation, including a full surface for expert tools and a slim wiki projection for browsing. Developers can configure the runtime using environment variables to define source paths and upstream repository details.
What you can do with it
- 1Querying framework definitionsAsk an AI agent to explain specific framework concepts like bounded contexts using precise IDs.
- 2Validating framework complianceUse the Claude Code plugin to verify that reasoning aligns with the established technical specifications.
- 3Deterministic pattern retrievalRetrieve stable, non-probabilistic information about framework routes and patterns without relying on vector search.
Written from the project's README. Every use case is checked against a quote from it.
fpf-memory MCP tools 8
Detected from the READMEbrowse_fpf_catalogsearch_fpfask_fpfquery_fpf_specread_fpf_docget_fpf_index_statustrace_fpf_pathrefresh_fpf_index
Configuration
FPF_MCP_SURFACE
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablevenikman/fpf-memory is public and reachablegithub.com/venikman/fpf-memory ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-13github.com/venikman/fpf-memory ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubFPF Spec Runtime
FPF helps when raw insight is not enough: meanings, claims, alternatives, evidence, boundaries, and outputs must remain stable across contexts, time, people, tools, or AI agents.
Quick links: Website · MCP setup · Hosted MCP endpoint
FPF vs MCP: FPF is the upstream specification; FPF Reference MCP (
fpf_reference) is the hosted tool endpoint agents call to query it — not agent memory. Add the hosted URL to your client from mcp.fpf.sh.📖 Live reference: fpf.sh — searchable pattern catalog, routes, and preface. Type an ID like
A.2orroute:project-alignmentin the search box to jump in.🤖 Working with this repo as an agent? See
AGENTS.mdfor the MCP tool guide and workspace conventions.🧭 Coordinating repo automation? See the Automation Playbook for role boundaries, access rules, merge authority, and draft-only publishing packets.
About FPF
The First Principles Framework (FPF) is a structured framework for thinking and coordinating work. It is written more like a technical specification than like a management book: there are named patterns, definitions, and review rules. Its job is to help teams model complex work, make reasoning inspectable, and keep decisions stable across engineering, research, and management.
FPF is authored by Anatoly Levenchuk. The upstream publication source this runtime tracks is github.com/ailev/FPF, specifically FPF-Spec.md on main by default. This repository is a runtime + slim wiki projection of the published spec, not the spec itself.
What is this repo?
A local FPF spec runtime. Given a single markdown spec file, it compiles a deterministic, vectorless index of FPF IDs, routes, relations, and anchors, and exposes that as:
- an MCP server (public + optional full surface) for IDE agents like Codex
- a Bun CLI for queries, traces, and inspections
- a static docs site built from the same compiled artifacts
No vector database, no remote indexing, no Python, and no local LLM dependency. Answers are produced from deterministic retrieval over the compiled spec snapshot.
Claude Code plugin
This repository is also a Claude Code plugin marketplace. The fpf-reference
plugin registers the hosted fpf_reference MCP server, ships the setup skill,
and adds a /fpf-reference:validate first-call validation command:
/plugin marketplace add venikman/fpf-memory
/plugin install fpf-reference@fpf
Details: plugins/fpf-reference/README.md.
Quick start
bun install
cp .env.example .env # see Configuration below
bun run spec:download # fetch FPF-Spec.md into .fpf-upstream/
bun run publish:current # refresh the committed published/current/** surface
bun run cli -- query --question "What is U.BoundedContext?" --mode verbose
To run the local MCP server (full surface, expert tools enabled):
FPF_MCP_SURFACE=full bun run mcp
To browse docs locally:
bun run docs:dev
How it works
On each refresh trigger the runtime:
- hashes the spec file at
FPF_SPEC_SOURCE_PATHand reuses the snapshot if the hash matches - otherwise recompiles a local vectorless index, writing
snapshot.json,build-audit.json,index-map.json,indexing-view.json,pattern-graph.json,route-graph.json,lexicon.json, andanchor-map.jsonunderFPF_RUNTIME_ARTIFACT_DIR(default.runtime/fpf-index/) - enriches the index with deterministic section descriptions plus per-node metadata (role, route-bearing status, …)
- follows explicit references, route hints, and outline adjacency in a bounded frontier loop when the first anchor set is insufficient
- optionally reuses a short-lived in-memory session context when
queryortraceis called with--session/sessionId - answers with IDs, citations, constraints, relations, and snapshot metadata
Stack
- Bun — preferred local runtime and package manager
- Zod — repo-authored MCP contracts and validation
- Model Context Protocol SDK — direct MCP server/transport runtime for local stdio and hosted HTTP
- Hono — hosted server engine
- Rstest, Rslint, Rspress — test, lint, docs
Scope
In:
- one markdown spec file as the runtime source set (default:
published/current/FPF-Spec.md) - a gitignored local publish source:
.fpf-upstream/FPF-Spec.md, or any local checkout viaFPF_PUBLISH_SOURCE_PATH - generated pattern/route markdown under
docs/generated/**(not committed; produced bybun run docs:generate) - static docs build output under
doc_build/(deterministic, ignored)
Out:
- a vector database
- any remote indexing service
- any Python code
- a validation/tuning corpus inside the runtime path
Automated publication refresh
.github/workflows/sync-fpf.yml keeps both public surfaces current when FPF changes upstream in ailev/FPF:
- Fast path: a trusted origin notifier can send this repo a
repository_dispatchevent namedfpf-origin-updatedorfpf-sync-updatedwithclient_payload.sha/after,client_payload.ref/branch, and optionallyclient_payload.spec_url. - Backstops:
.github/workflows/fpf-sync-monitor.ymlruns daily (11:47 UTC) and triggers this worker when production is behind and no sync worker is already active; the worker can also be triggered manually with a branch, tag, commit SHA, or raw spec URL paired with an explicit upstream ref. - Work performed: download
FPF-Spec.md, runpublish:current, validatepublished/current/**, build the static website deployment, build the separate hosted MCP deployment, and open a publication PR only when files changed. - Hosted MCP handoff: before opening a new PR, the workflow closes superseded
chore/sync-fpf-*PRs. After the review window and required checks pass, it squash-merges the current PR and deploys the website and MCP production bundles through the repo CLI scripts. - Monitor:
.github/workflows/fpf-sync-monitor.ymlruns daily (11:47 UTC), checksailev/FPFHEAD againsthttps://mcp.fpf.sh/api/fpf/status, triggerssync-fpf.ymlwhen upstream is ahead, and redispatches it when a current generated PR exists but no worker is queued or running. It fails only when drift exceeds the configured SLO or the hosted runtime is internally stale. - Spend guardrail:
.github/workflows/vercel-spend-monitor.ymlruns every 6 hours withVERCEL_SPEND_MONITOR_TOKENorVERCEL_TOKEN, checks Vercel Function Duration GB-hours, platform error-code rows, and legacy/api/mcp/fpf_memoryfunction invocations, distinguishesok,breach,config_error,metrics_unavailable, andexpected_blocked_traffic, updates one open issue only when operator action is required, and closes it after a clean monitor window. - Keepalive:
.github/workflows/workflow-keepalive.ymlruns weekly and keeps the whole scheduled fleet alive across GitHub's 60-day inactivity auto-disable for public repositories — it re-enables every active or auto-disabled workflow (resetting each one's inactivity clock, sparing manually disabled ones) and, after 45 days without a push to any branch, refreshes a marker file on theautomation/keepalivebranch so real repository activity exists even when upstream is quiet.
Minimal dispatch payload:
{
"event_type": "fpf-origin-updated",
"client_payload": {
"sha": "<ailev/FPF commit sha>"
}
}
Publication QA follows FPF anchors directly:
B.5.1separates exploration, shaping, evidence, and operation: sync PRs do publication work; monitor runs production evidence.A.10andG.6make SHA, manifest, source hash, runtime freshness, and check URLs the evidence graph.B.3,E.19, andE.21keep quality gates explicit: source/ref coherence, runtime freshness, preview/E2E, CI, recoverability, and max drift are separate characteristics, not one vague "green" claim.
Configuration
Copy .env.example to .env. The most common settings:
| Variable | Default | Purpose |
|---|---|---|
FPF_SPEC_SOURCE_PATH |
published/current/FPF-Spec.md |
Local path to the spec the runtime reads (must be a filesystem path). |
FPF_PUBLISH_SOURCE_PATH |
.fpf-upstream/FPF-Spec.md |
Local source used by publish:current. |
FPF_UPSTREAM_OWNER |
ailev |
GitHub owner for upstream publication provenance and downloads. |
FPF_UPSTREAM_REPO |
FPF |
GitHub repo for upstream publication provenance and downloads. |
FPF_UPSTREAM_REF |
main |
Branch, tag, or SHA used by spec:download and publish:current. |
FPF_UPSTREAM_SPEC_PATH |
FPF-Spec.md |
Path to the spec inside the upstream repo. |
FPF_SYNC_MONITOR_STATUS_URL |
https://mcp.fpf.sh/api/fpf/status |
MCP production status endpoint checked by monitor:sync. |
FPF_CONTENT_QUALITY_BASE_URL |
https://fpf.sh |
Website production base URL checked by monitor:content --mode live. |
FPF_CONTENT_QUALITY_STATUS_URL |
https://mcp.fpf.sh/api/fpf/status |
Runtime status URL used for live content provenance checks. |
FPF_SYNC_MONITOR_MAX_DRIFT_HOURS |
26 |
Hours a publishable upstream commit may stay unpublished before breach. |
FPF_VERCEL_PROJECT |
fpf-reference-mcp |
Vercel MCP/API project checked by monitor:vercel:spend. |
FPF_VERCEL_SCOPE |
none (example: venikmans-projects) |
Vercel team scope for metrics and deploy commands. No built-in code default; seeded in .env.example. |
FPF_VERCEL_SPEND_WINDOW_MINUTES |
30 |
Metrics lookback window for spend guardrails. |
FPF_VERCEL_SPEND_MAX_FUNCTION_DURATION_GBHR |
0.25 |
Maximum Function Duration GB-hours allowed in the lookback window. |
FPF_VERCEL_SPEND_MAX_LEGACY_INVOCATIONS |
0 |
Maximum function invocations allowed for the legacy MCP route. |
FPF_VERCEL_SPEND_MAX_ERROR_INVOCATIONS |
0 |
Maximum function invocations allowed with non-empty Vercel error_code. |
FPF_RUNTIME_ARTIFACT_DIR |
.runtime/fpf-index |
Where compiled artifacts are written. |
FPF_QUERY_DEFAULT_MODE |
verbose |
Default mode for query_fpf_spec and ask_fpf. |
FPF_HOSTED_MCP_DISABLED |
false |
Emergency hosted /api/mcp/* shutoff; returns 503 before loading the MCP runtime. |
FPF_RUNTIME_LOG_PATH |
.runtime/logs/fpf-runtime.log |
Structured runtime/MCP logs. |
FPF_SPEC_SOURCE_PATH must be a local filesystem path — the runtime does not fetch https:// URLs. The default is the committed publication surface: published/current/FPF-Spec.md. Local memory preparation uses FPF_PUBLISH_SOURCE_PATH, which defaults to .fpf-upstream/FPF-Spec.md after bun run spec:download. You can instead point FPF_PUBLISH_SOURCE_PATH at a local checkout of github.com/ailev/FPF such as FPF-Spec.md. bun run spec:download tracks ailev/FPF main by default; the sync workflow resolves one upstream ref and passes it to both download and publish before writing published/current/manifest.json. Override owner/repo/ref/spec path with FPF_UPSTREAM_OWNER, FPF_UPSTREAM_REPO, FPF_UPSTREAM_REF, and FPF_UPSTREAM_SPEC_PATH; override the raw download URL or output path with FPF_UPSTREAM_SPEC_URL and FPF_DOWNLOAD_SPEC_OUTPUT. In automation, a raw spec_url must be paired with an explicit ref or SHA so manifest provenance remains verifiable. Keep FPF_SPEC_SOURCE_PATH aligned across .env, your shell, and any MCP config (server.json env) so every runtime/docs entrypoint agrees on the published file it should read.
FPF_UPSTREAM_SPEC_URL is intentionally constrained to the canonical https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<specPath> shape matching the declared owner, repo, ref, and spec path. This prevents publishing one source while recording another provenance ref.
FPF_QUERY_DEFAULT_MODE applies to query_fpf_spec and ask_fpf when mode is omitted. trace_fpf_path stays compact by default.
FPF_RUNTIME_LOG_PATH receives structured MCP usage events named mcp_tool_usage. These events capture the tool name, outcome, duration, coarse input shape, resolved FPF IDs/kinds, result counts, and status fields. They deliberately do not log raw questions, search text, selectors, markdown bodies, answer text, or session IDs. In Vercel, the same runtime logger writes JSON to stdout so Vercel logs can be used for privacy-preserving usage analysis.
Common commands
Grouped by what you're trying to do. See package.json for the full list.
Setup & publishing
bun install
bun run spec:download # download FPF-Spec.md into .fpf-upstream/
bun run publish:current # refresh published/current/** from FPF_PUBLISH_SOURCE_PATH
bun run stage:from-published # stage published/current/** for commit
bun run monitor:sync # compare mcp.fpf.sh status with upstream HEAD
bun run monitor:vercel:spend # check Vercel Function Duration and legacy-route guardrails
bun run hooks:install # install local git hooks
Develop, test, build
bun run lint
bun run check
bun run test
bun run build
bun run vercel:website:build
bun run vercel:mcp:build
Docs
bun run docs:generate # produce docs/generated/** from the published surface
bun run docs:build # static build into doc_build/
bun run docs:dev # local docs site
CLI
bun run cli -- status
bun run cli -- refresh
bun run cli -- query --question "What is U.BoundedContext?" --mode verbose
bun run cli -- query --question "How does it connect to role assignment?" --session s1
bun run cli -- inspect --selector "A.1.1"
bun run cli -- read-doc --selector "A.1.1"
bun run cli -- trace --question "How do U.RoleAssignment and U.BoundedContext connect?" --mode proof --session s1
MCP server
bun run mcp # public surface
FPF_MCP_SURFACE=full bun run mcp # full surface (expert tools)
bun run start # hosted HTTP runtime on Hono
bun run bench:mcp:qa # hosted Q&A correctness gate
bun run bench:mcp # hosted latency/correctness benchmark
bun run vercel:mcp:build # prebuild the MCP Vercel bundle
Public hosted status endpoint:
/api/fpf/status
This returns the published upstreamRef, sourceHash, publishedAt, specBytes, and split runtime evidence for the same bundled FPF source and snapshot used by the hosted MCP endpoint. runtime.snapshotConsistent means the deployed source, manifest, and snapshot agree internally. freshness.upstreamCurrentness is unknown on this endpoint by design; production currentness is proven only by monitors that compare publication.upstreamRef and publication.sourceHash against the intended upstream/current artifact.
The public interface contract card lives on mcp.fpf.sh. It keeps the fpf_reference entity, admissible/non-admissible uses, reliance gate, status/freshness semantics, public tool schema map, and acceptance tests in one place.
FPF work evaluation
Deterministic, local FPF-grounded review of the current branch or worktree:
bun run evaluate:work
bun run cli -- evaluate-work --target current-pr --base origin/main --format markdown
bun run cli -- evaluate-work --target working-tree --base origin/main --format json
bun run cli -- evaluate-work --spec ~/Downloads/FPF-Spec\(12\).md --out reports/fpf-work.md
The evaluator reads local git facts, the committed published/current/** surface, and the configured FPF spec. It does not call an LLM, fetch GitHub, or regenerate artifacts. By default it reads FPF_SPEC_SOURCE_PATH if set, otherwise published/current/FPF-Spec.md; it does not fall back to .fpf-upstream/.
Using it from Codex (and other MCP clients)
The current Codex default is the hosted public FPF Reference MCP:
https://mcp.fpf.sh/api/mcp/fpf_reference/mcp
Equivalent ~/.codex/config.toml:
[mcp_servers.fpf_reference]
url = "https://mcp.fpf.sh/api/mcp/fpf_reference/mcp"
This repo ships the same project-scoped configuration at .codex/config.toml and .mcp.json. Once the project is trusted, Codex can load the hosted fpf_reference server directly from the repo.
The legacy fpf_memory client name and endpoint are blocked during the May 2026 cost incident mitigation:
https://mcp.fpf.sh/api/mcp/fpf_memory/mcp
Do not remove the legacy route before the scheduled compatibility review on 2026-06-30; keep it explicitly routed so stale clients fail cheaply with a migration signal. Production blocks it at Vercel routing before the MCP function runs, with the in-process guard retained as a fallback. The compatibility summary lives on mcp.fpf.sh.
Recommended Codex tasks (public surface):
- answer a question —
Use only the fpf_reference MCP server. Call ask_fpf with question: "What is U.PromiseContent?" - structured query —
Use only the fpf_reference MCP server. Call query_fpf_spec with question: "What is an FPF pattern?" - read a generated page —
Use only the fpf_reference MCP server. Call read_fpf_doc with selector: "A.1.1" - check runtime freshness —
Use only the fpf_reference MCP server. Call get_fpf_index_status
Expert tasks (require local full-surface runtime, FPF_MCP_SURFACE=full bun run mcp):
- inspect retrieval evidence —
Use only the fpf_reference MCP server. Call trace_fpf_path with question: "How do U.RoleAssignment and U.BoundedContext connect?" - rebuild the local index —
Use only the fpf_reference MCP server. Call refresh_fpf_index
Smoke-test the local full-surface runtime before using expert tools or deploying changes:
bun run cli -- status
bun run cli -- refresh
bun run cli -- query --question "What is U.BoundedContext?" --mode verbose
bun run cli -- trace --question "How do U.RoleAssignment and U.BoundedContext connect?" --mode proof
bun run cli -- inspect --selector "A.1.1"
The direct stdio launcher (same entry as bun run mcp):
FPF_MCP_SURFACE=full bun run mcp
This starts a long-running stdio server; for a manual smoke check, stop it with Ctrl+C after startup confirmation. Omit FPF_MCP_SURFACE=full if you only want the public surface.
If this repo is registered as a Codex MCP server, restart Codex after changes and then test with a forced tool-use prompt:
Use only the fpf_reference MCP server.
Call ask_fpf with:
- question: "Give me a checklist for how to model my project's information system."
For a proof-style grounded answer, add mode: "proof". For the raw structured envelope, call query_fpf_spec instead. For a deterministic retrieval/debug trace, call trace_fpf_path.
Website and MCP are separate Vercel deployment surfaces. The fpf-sh project serves the static reference at https://fpf.sh/; the fpf-reference-mcp project serves the runtime API at https://mcp.fpf.sh/.
The canonical client aliases are https://fpf.sh/ for the static reference and https://mcp.fpf.sh/api/mcp/fpf_reference/mcp for MCP clients.
https://mcp.fpf.sh/api/mcp/fpf_memory/mcp is the legacy compatibility path and is blocked during the May 2026 cost incident mitigation; new and working clients must use the canonical fpf_reference endpoint.
Historical pre-rename project-origin URLs are audit records only; do not add project-origin hostnames to new client setup examples.
Historical errored preview deployments can remain in Vercel as audit records.
Treat current production readiness as the latest fpf.sh website production alias plus mcp.fpf.sh status, smoke, QA, and bundle-size gates, not as an absence of old preview errors.
bun run vercel:website:link
bun run vercel:website:build
bun run vercel:website:deploy:prod
bun run vercel:mcp:link
bun run vercel:mcp:build
bun run vercel:mcp:deploy:prod
bun run bench:mcp:qa -- --name mcp-production --url https://mcp.fpf.sh/api/mcp/fpf_reference/mcp --format markdown
Status API:
https://mcp.fpf.sh/api/fpf/status
MCP tools
Public (default surface):
browse_fpf_catalog— task-oriented discovery by part, status, or kindsearch_fpf— full-text search across compiled nodesask_fpf— markdown-first answersquery_fpf_spec— structured answer enveloperead_fpf_doc— exact generated markdown pagesget_fpf_index_status— runtime freshness check
Full-surface only (FPF_MCP_SURFACE=full):
inspect_fpf_node,inspect_fpf_anchor,expand_fpf_citations— deep inspectiontrace_fpf_path— retrieval evidence and provenancerefresh_fpf_index— rebuild the local artifact set
All MCP tools are deterministic. Set FPF_MCP_SURFACE=public on the deployed server to restrict it to public tools only.
fpf-memory MCP questions
What tools does fpf-memory MCP provide?
It exposes 8 tools, including browse_fpf_catalog, search_fpf, ask_fpf, query_fpf_spec, read_fpf_doc.
Does this server use a vector database?
No, it uses a deterministic, vectorless index of IDs, routes, relations, and anchors compiled from a markdown specification.