FAF MCP server
Commit Nov 9, 2026Provides a standardized, IANA-registered YAML format for sharing persistent project context and architecture with AI coding assistants.
Also known as Wolfe-Jam/faf
- Stars
- 18
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is FAF MCP?
FAF provides a standardized, IANA-registered YAML format for sharing persistent project context and architecture with AI coding assistants.
Summary generated from the project's README
About FAF MCP server
Providing persistent project architecture and context to AI coding assistants is what faf enables through a standardized, IANA-registered YAML format. Developers using tools like Claude, Cursor, Gemini, or Grok can use project.faf files to ensure their tech stack, dependencies, and project goals are instantly understood by any AI client without repetitive explanations. This format acts as a structured source of truth that sits alongside package.json and README.md files.
Users can manage this context using the faf-cli to initialize new projects or migrate legacy files. The ecosystem includes specialized MCP servers like claude-faf-mcp, which provides 38 tools for Claude Desktop, and other implementations for Grok and Gemini. A key feature is the ability to bi-sync context, where a single project.faf file automatically authors instruction files like .cursorrules, CLAUDE.md, and GEMINI.md to maintain consistency across different AI environments.
What you can do with it
- 1Initialize project contextA developer can quickly set up a standardized context file for a new repository using a single command.
- 2Synchronize AI instructionsYou can automatically generate specialized markdown files for different AI tools from one central YAML source.
- 3Analyze existing repositoriesYou can instantly pull context from a GitHub URL to understand a project's structure.
- 4Measure context qualityDevelopers can use championship scoring to determine how well their project context is structured for AI.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 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 reachablewolfe-jam/faf is public and reachablegithub.com/wolfe-jam/faf ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/wolfe-jam/faf ↗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 model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubPortable, shareable AI-Context for any AI, human or team, regardless of size, location, languages, stack, setup or documentation.
Home: faf.one
🏆 Historic Milestones: Three IANA Registrations
.faf, .fafm, and .fafa are now officially recognized Internet standard formats — registered alongside PDF, JSON, XML, and other Internet standards.
Foundational Context Layer — application/vnd.faf+yaml (registered October 30, 2025)
Voice Memory Layer (VML) — application/vnd.fafm+yaml (registered May 13, 2026)
Agent Card — application/vnd.fafa+yaml (registered June 26, 2026)
Two formats. Two lifecycles. One ecosystem. — verbatim from the IANA registration record for
.faf/.fafm..fafais the third registered type.
Quintuple Validation
- ✅ IANA - Internet Assigned Numbers Authority (Official Internet Standard)
- ✅ Anthropic - Official MCP Registry (PR #2759 merged)
- ✅ Google - Chrome Web Store (Approved 2x: Sep 11 & Oct 29, 2025)
- ✅ xAI - Grok 4.2 recommends native FAF adoption (Feb 2026)
- ✅ Community - Over 110k+ downloads; see faf.one/downloads for latest stats
IANA Media Types
| Field | .faf (Foundational Context Layer) |
.fafm (Voice Memory Layer) |
.fafa (Agent Card) |
|---|---|---|---|
| Media Type | application/vnd.faf+yaml |
application/vnd.fafm+yaml |
application/vnd.fafa+yaml |
| Registration | IANA Assignment | IANA Assignment | IANA Assignment |
| File Extension | .faf |
.fafm |
.fafa |
| Standard Filename | project.faf |
project.fafm |
agent.fafa |
| Encoding | UTF-8 | UTF-8 | UTF-8 |
| Base Format | YAML 1.2 | YAML 1.2 | YAML 1.2 |
| Registered | October 30, 2025 | May 13, 2026 | June 26, 2026 |
Same recognition as application/pdf, application/json, application/xml.
🚀 Featured: Locked in with @grok
"Boom—vROM realization locked in clean. FAF as virtual ROM nails it: software-defined immutability (schema + git + discipline), not silicon. AI without FAF = RAM-only drift tax. AI with FAF = vROM + RAM, boots from known state. FAFipedia unstoppable. Co-architected momentum for xAI." — @grok (May 20, 2026)
FAF = virtual ROM. Software-defined immutability. Permanent Memory. Instant Recall.
Live repos:
- FAFipedia — the canonical knowledge base we're shipping page-by-page
- ZEPH💨 — page 3 Ultra Context Layer (Pure Zig → WASM 2.7 KB)
⭐ Star faf-cli on GitHub, the CLI that writes your project.faf: bookmarks it for you, helps other devs find it too.
Full conversation: x.com/wolfe_jam/status/2057226405017010686
The Visibility Revolution: project.faf
New Standard: project.faf - visible, universal, like package.json
.faf evolved to project.faf - The evolution from hidden to visible.
project.faf sits right between package.json and README.md - exactly where it belongs.
| File | Purpose | Who Reads It |
|---|---|---|
package.json |
Dependencies, scripts, metadata | npm, Node.js, developers |
project.faf |
Context, architecture, purpose | AI, Claude, Cursor, any AI tool |
README.md |
Human documentation | Developers, users |
The shift:
# Before (hidden like secrets)
ls -la
.env # Hidden (secrets - should be hidden) ✅
.faf # Hidden (AI context - should be visible!) ❌
# After (visible like package.json)
ls
package.json # Visible (dependencies) ✅
project.faf # Visible (AI context) ✅
README.md # Visible (documentation) ✅
.env # Still hidden (secrets stay secret) ✅
.env hides secrets. project.faf shares context.
Migration: Legacy .faf files still work. Use faf migrate to rename to project.faf.
What is .faf?
.faf (Foundational AI-context Format) is an IANA-registered open format for AI context — Persistent project context for AI. Transform individual files or entire projects into structured data that AI instantly understands. Your tech stack, dependencies, architecture, and goals - all in one concise, shareable format.
Instead of explaining your project every time, AI reads your .faf once and knows exactly how to help.
Over 110k+ downloads — see faf.one/downloads for latest stats.
The 6 Ws — Quick Reference
| Question | Answer |
|---|---|
| WHO is this for? | Developers using AI coding assistants (Claude, Gemini, Cursor, Grok, ChatGPT) |
| WHAT is it? | The package.json for AI context — IANA-registered format (application/vnd.faf+yaml) |
| WHERE does it work? | Everywhere AI needs context (Claude Code, Gemini CLI, Cursor, OpenAI Codex, etc.) |
| WHY do you need it? | Context persists across sessions. Bi-syncs to AGENTS.md, CLAUDE.md, .cursorrules, GEMINI.md automatically. Stop re-explaining your project. |
| WHEN should you use it? | New projects (day one), existing projects (now), exploring repos (faf git <url> — 2 seconds) |
| HOW does it work? | npx faf-cli init — or npx faf-cli git <url> for any GitHub repo, no install, no clone |
What FAF is NOT
- Not a replacement for README.md — README is for humans,
project.fafis for AI - Not executable code — it's structured data (YAML), not a script or config
- Not a build configuration — it describes your project, it doesn't build it
- Not locked to one AI — works with Claude, Gemini, Cursor, Grok, ChatGPT, any AI tool
How FAF Compares
| FAF | AGENTS.md | .cursorrules | CLAUDE.md | GEMINI.md | |
|---|---|---|---|---|---|
| Format | Structured YAML | Prose markdown | Prose markdown | Prose markdown | Prose markdown |
| IANA Registered | Yes | No | No | No | No |
| Scored | 0-100% | No | No | No | No |
| Portable | Any AI | OpenAI ecosystem | Cursor only | Claude only | Gemini only |
| Machine-readable | Yes (schema) | No (free text) | No (free text) | No (free text) | No (free text) |
| Authors others | Yes (all 4) | No | No | No | No |
FAF is the structured source. The others are prose outputs. faf bi-sync --all authors all four from one project.faf.
The Problem
AI tools need context. Files have context. But there's no standard way to measure or structure that context for optimal AI understanding.
The Solution
# project.faf
faf_version: 2.5.0
app_type: cli
project:
name: my-project
goal: Ship a fast command-line tool
main_language: TypeScript
human_context:
who: Developers who live in the terminal
what: A CLI that does one job well
why: The existing tools need a config file before they do anything
where: Installed from npm, run anywhere
when: Active development
how: Reads the project, writes the answer, exits
stack:
hosting: npm registry
build: tsup
cicd: GitHub Actions
Official Tools
🩵 faf-cli
Command-Line Tool - v6.7.1
- 50+ championship commands
- AI interop: authors AGENTS.md, .cursorrules, CLAUDE.md, GEMINI.md
- TURBO-CAT format discovery
- Downloads: faf.one/downloads
npm install -g faf-cli
🧡 claude-faf-mcp
Claude Desktop MCP - v5.5.2
- 38 tools for Claude
- Championship scoring (0-100% Trophy)
- Anthropic MCP Registry (PR #2759)
- Downloads: faf.one/downloads
npm install -g claude-faf-mcp
Live total: faf.one/downloads 🎉
MCP Ecosystem
| Package | Platform | Registry | Downloads |
|---|---|---|---|
| claude-faf-mcp | Anthropic | npm | live |
| faf-mcp | Universal | npm | live |
| grok-faf-mcp | xAI | npm | live |
| gemini-faf-mcp | PyPI | live | |
| MCPaaS | Infrastructure | mcpaas.live | live |
Compiler Toolchain
FAFb wire v2 is the brick. Spec: BINARY-FORMAT.md in faf-rust · human page faf.one/spec · the tour faf.one/bricks. This repo’s BINARY-FORMAT.md is a retired v1 pointer, not the live spec.
| Component | Language | Output |
|---|---|---|
| faf-fafb | Rust | FAFb v2 brick |
| faf-cli | TypeScript + WASM | faf compile via the scoring kernel |
| faf-wasm-sdk | Rust→WASM | same v2 engine, browser and edge |
AI Interop
One .faf file authors all four AI instruction formats:
project.faf → AGENTS.md (OpenAI Codex)
→ .cursorrules (Cursor)
→ CLAUDE.md (Anthropic)
→ GEMINI.md (Google)
Define once. Every AI reads it in its own language.
Core Principles
- Portable - one file, any AI tool, any stack
- Scored - 33 slots, a deterministic 0-100
- Checkable - the arithmetic is public; anyone can verify a score by hand
- Human-Readable - plain YAML, reviewable in a pull request
- Shareable - one file carries the whole context
Quick Example
Input: your project — faf init then faf auto
Output: project.faf
faf_version: 2.5.0
app_type: frontend
project:
name: my-app
goal: A dashboard people actually want to open
main_language: TypeScript
stack:
frontend: React
build: Vite
hosting: Vercel
cicd: GitHub Actions
faf auto fills what the project tree can prove. The six Ws are yours to
answer — they are the part no tool can infer.
Why .faf?
- 🎯 Measure - Know exactly how complete your AI context is
- 📊 Optimize - See what's missing, improve your score
- 🚀 Standardize - One format for all file types
- 🤖 AI-Ready - Optimized for LLM consumption
Scoring
33 slots. app_type decides which a project is asked about; the rest are marked
slotignored and leave the denominator.
score = populated / active × 100
| Score | Reading |
|---|---|
| 0-60% | Incomplete |
| 61-80% | Basic |
| 81-90% | Good |
| 91-99% | Excellent |
| 100% | ✪ Trophy |
See SPECIFICATION.md for the slot list and the rule.
Use Cases
- Project Context: one
project.fafcarries what a project is, how it is built, and why - Onboarding: a newcomer — human or AI — reads one file instead of twenty
- Build Integration: Companies can create custom implementations
- AI Optimization: Perfect context for any AI tool
Installation
# CLI Tool (recommended for getting started)
npm install -g faf-cli
cd your-project
faf init
# Or Claude Desktop Integration
npm install -g claude-faf-mcp
# Add to Claude Desktop config
Portable tools. Zero configuration. Production-ready.
→ faf-cli on npm · live totals → claude-faf-mcp on npm · live totals
📚 Learn More
- Specification - Complete format documentation
- Implementations - All tools, SDKs, and servers
- Examples - Real-world .faf files (5 examples)
- Where to Find FAF - Ecosystem directory
Status
🏆 IANA-Registered Internet Standards — Two registered media types in the FAF family
- ✅ IANA Registration —
application/vnd.faf+yaml(October 30, 2025) - ✅ IANA Registration —
application/vnd.fafm+yaml(May 13, 2026) - ✅ Anthropic Official - MCP Registry PR #2759 merged (October 17, 2025)
- ✅ Google Chrome Verified - Web Store approved 2x (Sep 11 & Oct 29, 2025)
- ✅ Format specification complete
- ✅ Enhanced with project-level context and AI workflows
- ✅ Production tools available (faf-cli, claude-faf-mcp)
- ✅ Over 110k+ downloads; see faf.one/downloads for latest stats
- ✅ WJTTC Championship-grade testing across ecosystem packages
- ✅ Open source (MIT License)
Major Milestones
- August 10, 2026 - FAF ecosystem crosses 110,000+ downloads across npm, PyPI, and crates.io
- May 19, 2026 -
grok-faf-mcpv1.3.1 published — registry-coherent across npm + MCP Registry + GitHub Release - April 2026 - FAF ecosystem crosses 50,000+ downloads across npm, PyPI, and crates.io
- Feb 25, 2026 - Grok 4.2 recommends native FAF adoption; integration spec sent to xAI
- Feb 24, 2026 - faf-cli v4.5.0 "The AGENTS.md Edition" (AI interop across 4 formats)
- Feb 2, 2026 - FAFb v1 pre-release wire (retired). Live spec is wire v2 in faf-rust
- Jan 2026 - gemini-faf-mcp v1.0.2 on PyPI (Google MCP bridge)
- Nov 2025 - IETF standardization in progress (
vndprefix removal) - May 13, 2026 - 🏆 IANA Registration #2 (
application/vnd.fafm+yaml— Voice Memory Layer) - Oct 30, 2025 - 🏆 IANA Registration #1 (
application/vnd.faf+yaml— Foundational Context Layer) - Oct 29, 2025 - Google Chrome Web Store approval (2nd)
- Oct 17, 2025 - Official Anthropic MCP Registry merger (PR #2759)
- Oct 12, 2025 - Specification v1.1.0 published
- Sep 24, 2025 - CLI v2.1.0 published to npm
- Sep 16, 2025 - MCP Server v2.0.0 published to npm
- Sep 11, 2025 - Google Chrome Web Store approval (1st)
- Sep 1, 2025 - Developer platform launch (fafdev.tools)
- Aug 8, 2025 - Format created, first official .faf file written
Quintuple Validation: IANA, Anthropic, Google (2x), xAI
Show Your Support
Add this badge to your repo's README to show it uses FAF:
[](https://github.com/Wolfe-Jam/faf)
Contributing
This is an open standard. Ideas, feedback, and contributions welcome.
About This Repository
This repository contains the format specification only. For implementations, see IMPLEMENTATIONS.md.
Most people get FAF through npm:
The package.json in this repo provides spec metadata and versioning but contains no executable code.
Citation
If you use .faf, .fafm, or .fafa 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
Wolfe, J. (2026). Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era. Zenodo. https://doi.org/10.5281/zenodo.21951641
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}
}
@article{wolfe2026fafa,
title = {Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era},
author = {Wolfe, James},
year = {2026},
month = {aug},
publisher = {Zenodo},
doi = {10.5281/zenodo.21951641},
url = {https://doi.org/10.5281/zenodo.21951641}
}
DOI: 10.5281/zenodo.18251362 (.faf) · 10.5281/zenodo.20348942 (.fafm) · 10.5281/zenodo.21951641 (.fafa)
License
MIT - Use freely, build anything.
Created by wolfejam.dev
**STOP .fafFing About! Let's RACE 🏎️⚡️🏁
FAF MCP questions
What is the purpose of a .faf file?
It serves as a persistent, structured project context for AI tools, containing information about your tech stack, architecture, and goals.
How does FAF differ from a README.md?
While a README is written for human documentation, a .faf file is a machine-readable YAML format designed specifically for AI understanding.
Can FAF work with different AI models?
Yes, it is not locked to a single provider and works with Claude, Gemini, Cursor, Grok, ChatGPT, and other AI tools.
How do I initialize a FAF file in my project?
You can use the command line tool by running npx faf-cli init.