claude-faf-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Works on one project at a time: faf_context shows the active folder; tools without a path use it. For questions about the project (stack, goal, commands), read project.faf first and answer from it. faf_score shows what is missing; faf_doctor says why. No project.faf yet: faf_auto creates it from the repo. The human slots (name, goal, who, what, why, where, when, how) come from the user through faf_go: show its suggestions, ask, and write only what the user confirms. project.faf is the source, one way: edit it, then faf_sync writes CLAUDE.md and faf_tri_sync also Claude Code's MEMORY.md. Use faf_etch only when the user asks to remember something; faf_recall reads it back from soul.fafm.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| faf_aboutA | Explain what the .faf format is — project context for AI, IANA-registered as application/vnd.faf+yaml — and how this server uses it. Returns a short plain-text overview with this server's version. Reads nothing and writes nothing. Use it when someone asks what FAF is. |
| faf_scoreA | Score the project's .faf with faf-cli's scorer — the one score every faf tool reports: 0–100%, the tier, populated/active slots, and a faf-parity/v1 hash of the result. details: true lists every slot as populated, empty or slotignored. Reads only. Use faf_doctor for what to fix. |
| faf_initA | Create a new project.faf for a folder: faf-cli detects its name, language and stack, and the reply gives the file path, faf-cli's starting score and the birth .faf-dna. An existing project.faf is left as it is — use faf_auto to fill its empty slots from your manifests, or faf_go for the human 6Ws. force: true replaces an existing project.faf with a fresh one, after copying the old file to a backup beside it. |
| faf_trustA | Attest the project's .faf: faf-cli's validateFaf, faf-cli's score, and a faf-parity/v1 hash (claude-faf-mcp's own spec) of that score that anyone can check with sha256(projection) === parityHash. Returns a trust receipt whose subject is the project. An invalid .faf, or a score that is unknown, gets no receipt (isError). Reads only. |
| faf_setupA | Install the native SessionStart hook in the project settings (/.claude/settings.json) — every Claude Code session in this project starts with fresh .faf context. Shows the exact settings first (preview); writes only with confirm: true, install or remove. faf changes only its own hook entry; every other key and hook stays as written. remove: true takes out only the hook whose command is exactly the faf hook command. Never writes the user settings: the home folder is refused. |
| faf_syncA | Write project.faf into CLAUDE.md as a faf-managed block (faf-cli's render and injector), and on request into AGENTS.md (agents), .cursorrules (cursor), GEMINI.md (gemini) and .github/copilot-instructions.md (copilot) — or all of them (all) — with faf-cli's writers. Each file keeps every line outside faf's block. Returns the files written and any requested file that could not be written, with the reason (then isError). Use it after editing project.faf. |
| faf_contextA | Show the active project — the folder every faf_* call without a path uses — and the .faf there; pass path to make another folder the active project (your home folder and the filesystem root are refused). detail: true also returns the .faf's text. Writes no file. Call it once at the start of a session. |
| faf_goA | The human half of project.faf. Without answers it returns the Table-of-8 — project name, goal and the 6Ws (who, what, why, where, when, how) — each filled, seeded from the goal, or empty, with faf-cli's score and, for each slot still empty, whether it is a fact from repo (faf_auto writes it: its dry run, the one faf_formats shows) or needs an answer here. An empty goal or W carries faf-cli's suggestion from the repo with its |
| faf_autoA | Create /project.faf, or fill the empty slots of the one there, with faf-cli's detection over the repo's own files (package.json, Cargo.toml, pyproject.toml, go.mod…) — no hardcoded defaults. A value already there is kept. A typed None or placeholder word is an empty slot: in a tech slot the app-type uses, only a repo fact replaces it (with no fact it stays as typed); in a tech slot the app-type leaves out, faf_auto writes slotignored; in a 6W it stays as typed (faf_go asks). Every value it changes is listed. Then writes CLAUDE.md's faf-managed block. Returns what was filled and faf-cli's score before and after. faf_go does the human 6Ws. |
| faf_benchA | Prove the .faf earns its place — measure how much the context is worth, on THIS repo, falsifiably. Questions derive from the project.faf's own populated slots (the .faf is the answer key), so grading is mechanical — no judge, no rubric. action=questions returns the answer-key-safe question set; action=grade takes your answers WITHOUT the .faf (cold) and WITH it (faf), grades both, and returns the cold→with-faf lift with a receipt hash. The delta is the product; the cold number belongs to the absence of context, never to FAF. Reads only. |
| faf_doctorA | Diagnose the project's .faf: faf-cli's validateFaf errors, faf-cli's score with every empty slot and the tool that fills it (faf_auto from the repo, faf_go for the 6Ws), whether CLAUDE.md is there, and the formats faf-cli finds in the folder. Returns a checklist of findings, each with its fix. Reads only. Use it when faf_score is below 100%. |
| faf_tri_syncA | Write project.faf as a faf-managed block into the MEMORY.md Claude Code loads for this project (~/.claude/projects//memory/MEMORY.md, or under CLAUDE_CONFIG_DIR). Only the block changes; every note of Claude's is kept, and the reply says so only after reading the file back. action: status reads only. faf_sync writes CLAUDE.md. |
| faf_etchA | Remember a decision, gotcha, or win across sessions by writing it to the project soul (soul.fafm) with faf-cli's Soul. Returns the stored memory and the soul's size. Re-etching an id updates that memory in place. Use it to persist something an AI should recall later; faf_recall reads them back. |
| faf_recallA | Recall memories from the project soul (soul.fafm), ranked by priority then recency, filtered by query/tags/type. Returns the matching entries. Reads only. Use it to surface past decisions; faf_etch adds new ones. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| faf | Relentless pursuit of a verified 100% — FAF does all it can, you do only what only you can. One source of truth for every AI, every MD. FAF defines. MD instructs. AI codes. |
| faf-bench | Prove the .faf earns its place — run the AI-grounding benchmark honestly, in two passes (cold, then with the .faf), and report the cold→with-faf delta with its receipt. The delta is the product. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| Current FAF Context | The active project's .faf as JSON: its path, faf-cli's score and the parsed data. |
| FAF Status Summary | One line of text: the active project's .faf path and faf-cli's score. |
TDQS
Scored across 14 tools
Most tools have sharply distinct purposes (init=create, auto=fill from repo, go=human 6Ws, sync=CLAUDE.md, tri_sync=MEMORY.md, etch/recall=memory), and the descriptions explicitly cross-reference and disambiguate. The weak spot is the read-only score cluster — faf_score, faf_doctor, faf_trust, and faf_bench all report a score/hash, and an agent must parse dense prose to decide which to call.
Every tool follows the same faf_<short_verb_or_noun> snake_case pattern with no casing or prefix deviations. The suffixes (init, auto, go, score, sync, tri_sync, etch, recall) are readable and predictable.
14 tools sit comfortably in the ideal range for a CLI-backed project-context server. Each maps to a real, named step in the .faf lifecycle, and none look like filler.
The surface covers the full lifecycle: create, fill (machine and human), validate/score, attest, render to five target files, install a session hook, benchmark value, and persist/recall memory. Minor gaps: no way to delete a .faf or 'forget' an etched memory (etch updates but never removes), and no multi-project listing beyond faf_context.