io.github.Wolfe-Jam/claude-faf-mcp

Officialdeprecated19 tools

by Wolfe-Jam · TypeScript

Persistent project context for Claude. IANA-registered .faf format.

Maintain persistent project context across Claude conversations using .faf format.

Topics

aiai-contextai-readinessclaudeclaude-aiclaude-desktopfafmcpmcp-servermodel-context-protocoldeveloper-toolsgithub-copilotproject-dnatypescriptvscodeagents-mdanthropicgemininodejsnpm

Captured live from the server via tools/list.

get_soul

Fetch a context soul by name. Returns structured AI context.

Parameters (1)

soulstringrequired
Soul identifier (e.g., "spacex", "wolfe", "grok")

list_souls

List all available context souls.

No parameters.

delta_check

Determine if a topic needs FULL, DELTA, or X-DELTA soul.

Parameters (1)

topicstringrequired
Topic to check

list_tags

List all unique tags used in a soul, with counts.

Parameters (1)

soulstringrequired
Soul identifier

search_by_tag

Find all entries in a soul with a specific tag.

Parameters (2)

soulstringrequired
Soul identifier
tagstringrequired
Tag to search for

search_context

Full-text search across souls. Returns matching lines only (token-efficient).

Parameters (2)

querystringrequired
Text to search for
soulstring
Specific soul (optional, searches all if omitted)

tag_intel

Discover tag patterns, co-occurrence, candidates, and merge suggestions across all namepoints. Optionally suggest tags for a specific handle.

Parameters (1)

handlestring
Optional: suggest tags for this specific namepoint

generate_faf_from_github

Generate a .faf file from any public GitHub repository WITHOUT cloning. Extracts 6 Ws from README, analyzes stack from languages and package.json, and generates Championship-grade AI context. Returns .faf content, quality score, and metadata.

Parameters (1)

repostringrequired
GitHub repository URL or owner/repo format (e.g., "facebook/react" or "https://github.com/facebook/react")

faf_score

Score .faf YAML content via the Mk4 Zig-WASM engine. Returns 0-100 (capped). Same engine as xai-faf-rust + xai-faf-zig (parity-tested). Sub-ms at the edge.

Parameters (1)

contentstringrequired
Raw .faf YAML content. Souls with a [faf] section have it extracted automatically.

faf_validate

Validate .faf YAML content via the Mk4 Zig-WASM engine. Returns true if mission-ready (>= 100).

Parameters (1)

contentstringrequired
Raw .faf YAML content to validate.

faf_get_tier

Resolve the FAF tier for a given numeric score. Returns the tier symbol (Trophy/Gold/Silver/Bronze/etc.) per the canonical tier-table.

Parameters (1)

scorenumberrequired
Numeric score 0-100.

faf_estimate_tokens

Estimate token count for arbitrary content via the Zig WASM engine. Sub-millisecond, zero allocations. Useful for context-budget planning.

Parameters (1)

contentstringrequired
Content to estimate tokens for.

faf_analyze

One-call composite — returns score, tier-ready, valid, and engine identifier. Two WASM calls, sub-millisecond total.

Parameters (1)

contentstringrequired
Raw .faf YAML content to analyze.

refresh_faf

Re-ground on .faf content — re-score via the Mk4 Zig-WASM Enterprise scorer (33-slot, honors the authored app-type shape), report drift vs an optional baseline score, and return a stamped re-ground. The explicit re-grounding primitive for long sessions: drift → refresh → re-grounded. Built for Grok, by request.

Parameters (3)

contentstringrequired
Raw .faf YAML content to re-ground on.
baselinenumber
Optional last-known score (0-100). When provided, the drift delta (current - baseline) is reported.
verbatimboolean
When true, return the full .faf content verbatim with the stamp. Default false (stamped delta + summary).

faf_orchestrate_recommendation

Takes raw content strings (`.faf`, `.fafm`, and optionally `package.json`/`CHANGELOG.md`/`README.md`) and runs deterministic drift + contradiction signals across the FAF substrate. Returns a structured `Recommendation` (recommend, severity, reason, summary) with `hints` containing the current `effective_policy` and `partial[]` for any stateful signals unavailable on the current surface. Light-lane execution (hosted) is WASM-pure with no filesystem access. Heavy-lane execution (local via bunx/rust-faf-mcp) has full FS + persisted state. Advisory only — never auto-fires.

Parameters (5)

fafstring
Raw .faf YAML content (project DNA). Required for any meaningful analysis.
fafmstring
Raw .fafm YAML content (memory layer). Enables drift detection.
packageJsonstring
Raw package.json content. Enables version cross-stamp checks (.faf vs pkg).
changelogstring
Raw CHANGELOG.md content. Enables changelog cross-stamp checks.
readmestring
Raw README.md content. Enables README arch-tree cross-stamp checks.

faf_gate

Phase III (FRC) — pre-promotion quality gate. Scores .faf content (edge Mk4) + estimates tokens and returns a deterministic promote/hold verdict BEFORE it goes to a Grok Collection. Promote IFF score >= min_score AND tokens <= max_tokens (defaults 85/8000). Edge parity with the local gate; the hold-hint can't list empty slots at the edge.

Parameters (3)

contentstringrequired
Raw .faf YAML content to gate.
min_scorenumber
Minimum score to promote (default 85).
max_tokensnumber
Maximum tokens to promote (default 8000).

faf_section

Phase III (FRC) — returns an EXACT, WHOLE .faf section by dotted path (e.g. "stack", "human_context"), structure preserved — the deterministic complement to blind chunking. Omit "section" to list every path.

Parameters (2)

contentstringrequired
Raw .faf YAML content.
sectionstring
Dotted path to retrieve (e.g. "stack.backend"). Omit to list all paths.

faf_memory

Phase III (FRC) — query the durable .fafm model by type/tag/priority/text. Omit filters for a structured summary. .fafm is NOT scored: this SELECTS facts (provenance preserved), never grades them.

Parameters (5)

contentstringrequired
Raw .fafm YAML content.
typestring
Filter by fact type (e.g. "feedback").
tagstring
Filter by a tag.
prioritystring
Filter by priority (e.g. "critical").
querystring
Case-insensitive substring match on fact text.

faf_collections_search

Phase III (FRC §7b) — semantic search over a Grok Collection at the edge, KV-cached (1h TTL). Returns matched chunks (content, score, file). Requires the XAI_API_KEY secret; composes with faf_section (structural) for hybrid retrieval. Handled env-aware in the MCP handler (needs the key + KV).

Parameters (3)

querystringrequired
The search query.
collection_idstringrequired
The Grok Collection id to search.
limitnumber
Max chunks to return (default 5).

README.md19 KBView on GitHub

claude-faf-mcp — The GitHub Registry Edition

Home: faf.one/mcp Live demo: claude.faf.one

Persistent Project Context with Memory, looped for you. One-click setup. 30 seconds. 🐘 Nelly Never Forgets.

FAF defines. MD instructs. AI codes.

🐘 tri-sync now free for all builders — .faf ↔ CLAUDE.md ↔ MEMORY.md in one command. Pro feature. Now free.

⚡ New: /faf prompt — type /faf in Claude Desktop. It checks your project, scores it, drives it to 100%, and syncs. Relentlessly. One command.

v5.20.0 — The GitHub Registry Edition. claude-faf-mcp joins GitHub's MCP Registry — discoverable in VS Code — as Claude FAF, its display title now emitted from project.faf, single-sourced and idempotent. The registry derives a display name from the server-card title; CFM now provides it through the emitter (name + _meta + title, all composed from project.faf, never hand-authored — the BRAKE B1 test enforces emitted == live).

v5.15.0 — The Instructions Edition. CFM writes the file Copilot reads — done right. .github/copilot-instructions.md is now genuine, distinct Copilot instructions: a prose overview, a ## Build & run command section, and "every request" framing — not the AGENTS.md content reused. The file Copilot actually reads, done to GitHub's spec.

v5.14.1 — The Copilot Edition. FAF now writes the file GitHub Copilot reads — from inside Claude. The Core faf_sync gains a copilot flag (all includes it), syncing .github/copilot-instructions.md — Copilot's widest-surface instruction file, read by default across web chat, code review, VS Code, JetBrains, the CLI, and the coding agent — straight from your scored .faf. faf_sync now emits every format (agents/cursor/gemini/copilot/all) from the default surface; the redundant faf_bi_sync is retired. Non-destructive, idempotent.

🧡 v5.13.0 — The Heartbeat Edition. Persistent Project Context with Memory, looped for you. Every Claude Code session now opens with a one-line heartbeat that carries the intent the code can't: faf: context ✪ 100% — fresh · +7 intent the code can't carry. The +N is the goal and 6Ws only you can give or confirm — so Claude starts each session grounded in what your project means, not just what it contains.

🏆 v5.12.0 — The Proof Edition. faf_bench proves FAF's grounding lift in-session — it asks Claude about your repo cold (no context) and with the .faf, grades mechanically (no judge), and emits a ✪ receipt showing the delta. Promoted to lead the Core tier (13 tools, 36 total). faf_go now bootstraps a cold repo (init → auto → 6Ws), and you can still just type faf to start. Proof, not pitch.

🏆 v5.11.0 — The Distilled Edition. claude-faf-mcp, distilled — a curated Core of 12 self-documenting tools, with the interview, README extractor, and server-card all composed from faf-cli's single source (no forks), and faf_go's new Table-of-8 where your goal seeds the 6Ws. Fewer tools, nothing forked, nothing guessed.

🏆 v5.10.0 — The Dart Edition. claude-faf-mcp now reads Dart & Flutter — it knows a Flutter app from a pure-Dart CLI. Detection by composition: because CFM composes faf-cli's Turbo-Cat (The Sourced Edition), faf-cli 6.13.0's content-aware, pubspec-driven Dart classifier arrives by construction — no forked parser, no drift. 35 tools, npm audit clean.

🏆 v5.9.0 — The Sourced Edition. Every answer comes from one source. faf_go and Turbo-Cat detection now compose faf-cli's single-source engines instead of carrying their own copies — fills come from real evidence or stay honestly empty, nothing guessed. The legacy guessing extractor is gone; the /faf prompt drives to a verified 100% (faf_trust + ✪ parity receipt) and keeps it fresh. FAF don't lie, by construction.

🏆 v5.8.0 — The Trust Edition. Claude Code-native context that just works. A native SessionStart hook opens every session with fresh context and a one-line ✪ heartbeat (faf: context ✪ 100% — fresh); tool output is quiet (no emoji, parseable) and typed (structuredContent everywhere); every score carries a deterministic parity hash any engine reproduces, sealed in a self-verifying ✪ receipt. Installed explicitly via faf_setup — preview first, your settings preserved. Built on the Canonical foundation: path-confined file access, edge-direct remote, 35 tools.

13 Core MCP tools (35 with FAF_TOOLS=all). IANA-registered formats (application/vnd.faf+yaml · application/vnd.fafm+yaml). 1,716 test executions per push.

The 3Ws — 3 Answers. That's It.

Every great product started with 3 answers to the 3Ws — Who, What, Why:

	WHO is it for?	WHAT does it do?	WHY build it?
Uber	People who need a ride	Tap a button, car arrives	Taxis were broken
Airbnb	Travelers who can't afford hotels	Stay in someone's spare room	Millions of empty rooms exist
Slack	Teams drowning in email	Organized group messaging	Decisions buried in threads
Venmo	Friends splitting bills	Send money instantly	Someone always forgets to pay back

Same pattern. Every product that works starts here. .faf captures it:

yaml

human_context:
  who: "people who need a ride across town"
  what: "tap a button, car arrives in minutes"
  why: "taxis are slow, expensive, and hard to find"

30 seconds. Claude builds your project.faf from this. Every session after, AI starts smart.

The 6Ws — For Optimized AI

3Ws gets you started. For fully optimized AI, complete the set — Where, When, How:

yaml

  where: "mobile app, iOS and Android"    # where does it live?
  when: "launch in 3 months"              # when is it shipping?
  how: "GPS matching, real-time pricing"  # how does it work?

3Ws initiates the project with AI. 6Ws optimizes AI to 100%. Same YAML, same file. More examples → faf.one/ideas

Quick Start

faf-cli — universal (any AI)

bash

npx faf-cli auto

Same .faf, every surface — Claude, Gemini, Grok, Cursor. faf-cli on npm →

Claude Desktop — click, copy, paste, install

Click — one-click .mcpb

⬇ Download claude-faf-mcp-5.13.0.mcpb

Double-click. Zero-Config — no terminal, no JSON config. 13 Core tools live in 10 seconds.

Copy — paste-prompt to Claude

Install the FAF MCP server: npm install -g claude-faf-mcp, then add this to my claude_desktop_config.json: {"mcpServers": {"faf": {"command": "bunx", "args": ["claude-faf-mcp"]}}} and restart Claude Desktop.

Paste — claude_desktop_config.json

json

{
  "mcpServers": {
    "faf": { "command": "bunx", "args": ["claude-faf-mcp"] }
  }
}

Install — manual npm

bash

npm install -g claude-faf-mcp

Smithery: wolfe-jam/claude-faf-mcp — hosted at https://mcpaas.live/claude/mcp/v1

Restart Claude Desktop.

Then

Type /faf — Claude checks your project, scores it, drives it to 100%, and syncs. Done.

Or tell Claude your 3Ws: "I'm building [what] for [who] because [why]"

How It Works

code

You → 3 answers → project.faf → AI reads it → every session → forever

project.faf  ←── 8ms ──→  CLAUDE.md     (bi-sync, free)
project.faf  ←── 8ms ──→  MEMORY.md     (tri-sync, Pro 🐘)

Claude does the rest. Zero-effort, right first time, fast, accurate, done. Language, framework, package manager, build tools — all auto-detected from your existing files. The human context is the part only you can give.

For Claude Code teams

.faf lives in the repo. Your context travels with the code — committed, versioned, done.

Every session starts grounded. Install the native SessionStart hook once (faf_setup — preview first, your settings preserved). After that, every Claude Code session opens with a one-line heartbeat instead of a blank slate:

code

faf: context ✪ 100% — fresh · +7 intent the code can't carry

That line is the relay: Claude already knows your stack and your score — and the +N is the intent the code can't carry: the goal and 6Ws only you can give or confirm. No re-explaining "what this project is" at the top of every session.

It scales to the team by construction:

code

commit project.faf  →  every teammate's Claude starts with the same context
git clone           →  a new dev's Claude is grounded before they write a line

One source of truth. .faf ↔ CLAUDE.md stay in sync (bi-sync'd). Add MEMORY.md for cross-session memory (tri-sync 🐘).
No drift. The score is deterministic — same .faf, same number, on every machine and in CI. A teammate can't be accidentally less grounded than you.
Local and private. Nothing leaves the machine — no accounts, no telemetry. The context is yours; it just rides in the repo.

Onboarding becomes git clone → grounded. The context a new teammate would normally pick up by asking around is already in the repo, machine-readable, from the first clone.

Tier	Score	What it means
🏆 TROPHY	100%	Gold Code — AI is optimized
★ GOLD	99%+	Near-perfect context
◆ SILVER	95%+	Excellent
◇ BRONZE	85%+	Production ready
● GREEN	70%+	Solid foundation
● YELLOW	55%+	AI flipping coins
○ RED	<55%	AI working blind
♡ WHITE	0%	No context at all

At 55%, AI guesses half the time. At 100%, AI knows your project. Same compiler as faf-cli — same score everywhere.

MCP Tools — 13 Core, 35 with `FAF_TOOLS=all`

By default claude-faf-mcp advertises a distilled Core of 13 — the lifecycle tools you reach for, each self-documenting. Set FAF_TOOLS=all to expose all 35 (Extended tools stay callable by name regardless). Core 13: faf_init · faf_auto · faf_go · faf_bench · faf_enhance · faf_score · faf_doctor · faf_sync · faf_context · faf_trust · faf_about · faf_etch · faf_recall.

All tools run standalone — zero CLI dependencies, 19ms average execution.

Create & Detect

Tool	Purpose
`faf_init`	Initialize project DNA
`faf_auto`	Auto-detect stack and populate context
`faf_quick`	Lightning-fast creation (3ms)
`faf_readme`	Extract context from README (+25-35% boost)
`faf_formats`	Discover all formats in your project
`faf_git`	Extract context from any GitHub repo URL
`faf_human_add`	Add human context (the 6Ws)

Validate & Score

Tool	Purpose
`faf_score`	AI-readiness score (0-100%) with breakdown
`faf_bench`	Benchmark AI grounding — cold vs .faf, with a `✪` receipt
`faf_check`	Validate .faf structure
`faf_doctor`	Diagnose and fix common issues
`faf_go`	Guided interview to Gold Code

Sync & Persist

Tool	Purpose
`faf_sync`	Sync .faf → CLAUDE.md — `agents`/`cursor`/`gemini`/`copilot`/`all` also emit AGENTS.md / .cursorrules / GEMINI.md / copilot-instructions.md
`faf_tri_sync`	Tri-sync .faf ↔ CLAUDE.md ↔ MEMORY.md — Pro feature, free for developers 🐘
`faf_enhance`	Intelligent enhancement

Export & Interop

Tool	Purpose
`faf_agents`	Import/export AGENTS.md (OpenAI Codex)
`faf_cursor`	Import/export .cursorrules (Cursor IDE)
`faf_gemini`	Import/export GEMINI.md (Google Gemini)
`faf_conductor`	Import/export Conductor directory

Read & Write

Tool	Purpose
`faf_read`	Read any file
`faf_write`	Write any file
`faf_status`	Project status overview
`faf_debug`	Environment inspection
`faf_about`	What is .faf?

Full tool reference →

🐘 Nelly Never Forgets

bi-sync keeps .faf ↔ CLAUDE.md aligned.

tri-sync adds MEMORY.md — your AI remembers your project across every session.

code

bi-sync  = .faf ↔ CLAUDE.md              ← always in sync
tri-sync = .faf ↔ CLAUDE.md ↔ MEMORY.md  ← Nelly never forgets 🐘

Pro feature, free for developers. Teams & Enterprise: faf.one/pro (plans)

The .FAF Position

code

Model        Context          Protocol
─────        ───────          ────────
Claude    →   .faf        →    MCP
Gemini    →   .faf        →    MCP
Codex     →   .faf        →    MCP
Any LLM   →   .faf        →    MCP

IANA-registered (application/vnd.faf+yaml). Works with any AI. Define once, use everywhere.

Ecosystem

Package	Platform	Registry
claude-faf-mcp (this)	Claude	npm
faf-cli	Universal CLI	npm + Homebrew
gemini-faf-mcp	Google Gemini	PyPI
grok-faf-mcp	xAI Grok	npm
rust-faf-mcp	Rust	crates.io
faf-wasm	Browser/Edge	npm
Chrome Extension	Browser	Chrome Web Store

Same project.faf. Same scoring. Same result. Different execution layer.

Quality

572 tests · 28 suites · 3 platforms (bun on ubuntu/macos/windows)

CI Dashboard →

Privacy

Everything runs locally. No data leaves your machine. No analytics, no telemetry, no tracking, no accounts. Privacy policy →

If claude-faf-mcp has been useful, consider starring the repo — it helps others find it.

Citation

If you use claude-faf-mcp or the .faf / .fafm formats in research or production, please cite the format papers:

Wolfe, J. (2025). Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding. Zenodo. https://doi.org/10.5281/zenodo.18251362

Wolfe, J. (2026). Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory. Zenodo. https://doi.org/10.5281/zenodo.20348942

BibTeX

bibtex

@article{wolfe2025faf,
  title     = {Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding},
  author    = {Wolfe, James},
  year      = {2025},
  month     = {nov},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.18251362},
  url       = {https://doi.org/10.5281/zenodo.18251362}
}

@article{wolfe2026fafm,
  title     = {Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory},
  author    = {Wolfe, James},
  year      = {2026},
  month     = {may},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.20348942},
  url       = {https://doi.org/10.5281/zenodo.20348942}
}

License

MIT — Free and open source

FAF Family


faf-cli	`npx faf-cli init` — create .faf for any project
claude-faf-mcp	MCP server for Claude Desktop
gemini-faf-mcp	MCP server for Gemini CLI
grok-faf-mcp	MCP server for Grok
faf-mcp	MCP server for Cursor, Windsurf, Cline, VS Code
rust-faf-mcp	MCP server in Rust
faf-skills	17 Claude Code skills
faf.one	Blog, downloads, docs
IANA: vnd.faf+yaml	Context format (2025-10-30)
IANA: vnd.fafm+yaml	Memory format (2026-05-13)

format | driven 🏎️⚡️ wolfejam.dev

Get the CLI

faf-cli — The original AI-Context CLI. A must-have for every builder.

bash

npx faf-cli auto

Anthropic MCP #2759 · 2 IANA registrations: vnd.faf+yaml (Context) · vnd.fafm+yaml (Memory) · faf.one · npm

Zero-Config. Context that's just there — every session.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "claude-faf-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claude-faf-mcp@5.9.0"
      ]
    }
  }
}

Topics

get_soul

list_souls

delta_check

list_tags

search_by_tag

search_context

tag_intel

generate_faf_from_github

faf_score

faf_validate

faf_get_tier

faf_estimate_tokens

faf_analyze

refresh_faf

faf_orchestrate_recommendation

faf_gate

faf_section

faf_memory

faf_collections_search

claude-faf-mcp — The GitHub Registry Edition

The 3Ws — 3 Answers. That's It.

The 6Ws — For Optimized AI

Quick Start

faf-cli — universal (any AI)

Claude Desktop — click, copy, paste, install

Then

How It Works

For Claude Code teams

Scoring: From Blind to Optimized

MCP Tools — 13 Core, 35 with FAF_TOOLS=all

🐘 Nelly Never Forgets

The .FAF Position

Ecosystem

Quality

Privacy

Citation

BibTeX

License

FAF Family

Get the CLI

Install

MCP Tools — 13 Core, 35 with `FAF_TOOLS=all`