gemini-faf-mcp
This MCP server lets Gemini/Antigravity read, create, validate, score, auto-detect, export, and migrate .faf project-context files.
Read/parse
.fafproject DNA, validate files, check scores/tiers/slot counts, and discover.faffiles.Create starter
.faffiles and auto-detect project stack from manifests, docker-compose, Makefile, and CI configs, filling empty slots.Convert FAF data back to YAML and get Gemini-optimized context with project, stack, instructions, and score.
Export non-destructive
GEMINI.mdandAGENTS.mdas managed blocks, preserving hand-written content.Migrate
.faffiles to the current format version, with optional dry-run preview.Get FAF format/about information and 100% Trophy example
.faffiles for 15 project types.
Automatically detects project stack and configuration for Rust projects using the Actix framework.
Scans composer.json files to automatically detect and integrate PHP project stack details into the FAF context.
Automatically detects project stack and dependency information for Django-based Python projects.
Identifies and integrates project stack details for applications built with the Express framework.
Automatically detects project stack and configuration for FastAPI applications.
Automatically detects project stack and configuration for Flask-based Python projects.
Identifies and integrates project stack details for Go applications using the Gin framework.
Provides Gemini-optimized project context and exports GEMINI.md files to align project goals and stack definitions within Google Gemini environments.
Auto-detects project DNA and stack details for JavaScript projects by scanning project manifest files.
Automatically detects project stack and configuration for Next.js applications.
Scans package.json to extract project stack and dependency data for Node.js environments.
Exports project context to AGENTS.md to align project goals and stack for OpenAI Codex and other OpenAI-compatible AI tools.
Auto-detects project DNA and stack details for PHP projects by scanning manifest files like composer.json.
Identifies PostgreSQL as the project database during automatic stack detection and FAF context generation.
Identifies pytest as the project testing framework during automatic stack detection and FAF context generation.
Auto-detects project DNA and stack details for Python projects by scanning pyproject.toml or requirements.txt.
Automatically detects project stack and configuration for React-based frontend projects.
Auto-detects project DNA and stack details for Ruby projects by scanning the Gemfile.
Auto-detects project DNA and stack details for Rust projects by scanning Cargo.toml.
Auto-detects project DNA and stack details for TypeScript projects by scanning project manifest files.
gemini-faf-mcp v3.3 — The Antigravity Edition 🚀
Persistent Project Context for Google Gemini. Define once. Sync everywhere.
⭐ Star it on GitHub: bookmarks it for you, helps other devs find it too.
FAF defines. AGENTS.md instructs. AI codes.
☆ Bookmark the gemini-faf-mcp page for later.
Stop re-explaining your project to every new Gemini session. Every Gemini conversation starts cold — you re-state your stack, your goals, your conventions every single time. .faf is one structured file that captures all of it. This package is the MCP server that lets Gemini read it.
Before and after
Without FAF With FAF (project.faf filled in)
───────────────────────── ─────────────────────────
You: "I'm using FastAPI with... You: "Add a /users/me endpoint"
PostgreSQL, pytest, and..." Gemini: [writes correct code,
Gemini: "Got it. What's the uses your auth pattern,
codebase like?" matches your test style]
You: "It's a REST API for..."
[5 minutes of re-explaining]
Gemini: [now ready to help]Gemini reads project.faf through the faf tools, and GEMINI.md written from it loads at session start, so a new session starts with your project.
What's New in v3.3.3 — The Antigravity Edition 🚀
3.3.3: one engine, one number, in the Python SDK too.
validate_fafgives the same score and tier asfaf_scoreand faf-cli (the always-33 kernel). It used to count its own 10 slots.validnow means what it means infaf_validate(the structure is valid),issueslists each empty slot, andtieris upper case (TROPHY…WHITE). It scores data already parsed; for a file's exact score, usefaf_score. See the CHANGELOG for every key that changed.The hosted badge uses faf-cli's tiers (✪ ★ ◆ ◇ ● ○ ♡), not the retired emoji ladder.
The FAQ says only what the code does, and the Big Orange 🍊 is described as a planned honor, not a score.
v3.3.1 — The Antigravity Edition 🚀
3.3.1: /setup detects your stack; your goal and six W's stay yours.
/setupdetects your stack first. It now createsproject.fafwithfaf_auto, so a new project starts with its language, framework, API type, package manager and test runner filled in. Before, it wrote a starter file that locked the stack, and filling it in afterwards wrote nothing.Your goal and the six W's are yours (the Human Slots rule, as in faf-cli 8.10). No placeholders or defaults are written into them. A description found in
pyproject.tomlis offered as a suggested goal for you to confirm, not written. Scores now match faf-cli on the same project; a new file scores lower until you fill these in, because empty slots no longer count as filled.faf_autosays what it really wrote: the slots it filled, "unchanged" when none, and detected values it skipped because the slot was already set.
v3.3.0 — The Antigravity Edition 🚀
3.3.0 brings gemini-faf-mcp to Antigravity CLI: install it as a plugin and it works in your project. Simple.
Install it as a plugin in Antigravity CLI (
agy, Google's successor to Gemini CLI):agy plugin install https://github.com/Wolfe-Jam/gemini-faf-mcp, then run/setupin your project. Moving from Gemini CLI,agy plugin import geminiconverts the extension.It works in your project.
agystarts a plugin's server in the plugin's own folder. The plugin now starts Python directly, so the server sees the folder you ranagyin, and finds yourproject.fafand writes there. In 3.2.1 this only worked when the server was started by hand.Safe to start anywhere. A
server.py(or any module) in your project is never run in place of the server's own, files are read and written as UTF-8 on every platform, and an older installed copy without the fix is never used.The skills are
/setup,/scoreand/exportinagy(/faf:setupand so on in Gemini CLI).
v3.2.1 — The Straight Answers Edition
3.2.1 lifts gemini-faf-mcp into Antigravity CLI: it installs as a plugin and works in your project.
Installs in Antigravity CLI (
agy, Google's successor to Gemini CLI):agy plugin install https://github.com/Wolfe-Jam/gemini-faf-mcp. Moving from Gemini CLI,agy plugin import gemininow converts the extension cleanly.Works in your project there.
agystarts a plugin's server in the plugin's own folder; gemini-faf-mcp now finds your project and writes there, never to a folder broader than it.The skills are
/setup,/scoreand/exportinagy(/faf:setupand so on in Gemini CLI).
v3.2.0 — The Straight Answers Edition
Every gemini-faf-mcp failure now reaches your client as an error: MCP's isError is set, the reason text is unchanged, and /faf:setup checks before it creates.
A missing file, invalid YAML, a refused write, a path outside the project, an unknown model: each now comes back to your client as an error (MCP
isError), with the same reason text as before. A success is unchanged.faf_scoresays when a file isn't valid YAML, using the same reader as the score (faf-cli parity). An empty file still scores 0, White./faf:setuplooks for aproject.fafin this folder first, and only creates one when there is none.
Heads up: Python scripts that call these tools through FastMCP's Client.call_tool now get a ToolError on a failure unless they pass raise_on_error=False. MCP clients that read isError now take their error path, with the same text.
v3.1.2
faf_gemini and faf_agents keep your hand-written GEMINI.md and AGENTS.md, and tell you what they couldn't write.
GEMINI.md and AGENTS.md are now written by faf-cli's rules: only faf's own block changes, your text stays, and a file faf can't safely write (not UTF-8, a link out of the project, read-only) is left as it is and named in the reply.
v3.1.1
gemini-faf-mcp --version and --help answer and exit. Before, both started the server.
--version(-V) prints the version;--help(-h) prints usage and a client config. Anything else starts the server as before, so your client config doesn't change.
v3.1.0 — The New Era Edition
Glass-box tools: every Gemini tool now says what it does — reads, writes or rewrites — so your client knows when to ask first. In Gemini CLI and Google Antigravity.
Every tool is labelled. All 13 tools carry MCP tool annotations, matched to what each one does: 8 read only, 4 write without losing anything (
faf_initnever overwrites,faf_autofills empty slots only,faf_geminiandfaf_agentskeep your own text), andfaf_migraterewrites the file. None reaches the network. Clients that read the labels can let reads run and ask before writes.Its own card. A refreshed FAF passport (
agent.fafa, written with faf-cli 8.2'scard init) and MCP Server Card, both 3.1.0 with all 13 tools and FAF's context.Works in Google Antigravity, local (
uvx) or hosted (serverUrl). See Google Antigravity below.A new look: the gemini-faf-mcp page, redesigned to feel at home for Google developers.
The hosted function scores always-33, the same engine as everything else.
Earlier: v3.0.0 — The Always33 Edition — one engine, one number: the same score as faf-cli 8, claude-faf-mcp 7, faf-mcp 4 and grok-faf-mcp 2.
v2.8.2 — The Full-Facts Edition
Privacy patch — FAFClient's start-up ping is now opt-in (FAF_TELEMETRY=1).
FAFClient (the Python SDK client — the MCP server never used it) sent a start-up ping, package name and version, by default, and the opt-out wasn't documented. It now sends only when you set FAF_TELEMETRY=1; FAF_TELEMETRY_OFF still turns it off. See faf.one/privacy.
v2.8.1 was a dependency patch —
faf-python-sdkfloor>=1.4.0, where the interop functions are now namedauthor_agents_md/author_gemini_md. Authored AGENTS.md / GEMINI.md output is byte-identical.
v2.8.0 — faf_auto now grounds its detection in the repo's own files, and every faf_model reference template scores 100% Trophy.
faf_auto used to read only the root manifest (pyproject.toml, package.json, …). It now also reads the files that carry the real stack: docker-compose service images map onto database / cache / search / storage (a running Postgres service is the database — it beats a dependency guess), Makefile / justfile targets map onto the commands block (test / build / check-all, root file or a nested backend/Makefile), and .github/workflows/ sets cicd. A polyglot repo that reported library / JavaScript now reports its real Postgres + Redis + FastAPI stack. In parity with faf-cli 7.10.
Separately: the 15 faf_model reference templates were scoring 48–57% — they filled 4 stack slots and used null. All rewritten to the full 21-slot schema; every one is 100% Trophy now, and a test keeps it that way. 13 tools · 265 tests.
v2.7.1 / v2.7.0 — The Interop Edition —
faf_agents/faf_geminirewritten asfaf-python-sdkauthoring-tool wrappers (were 4-field stubs); newfaf_migratebrings a.fafup to the current format. v2.6.0 — The Agent Card Edition added a realagent.fafapassport, an MCP Server Card (SEP-2127), and an AI Catalog entry. v2.5.0 — The Dart Edition detects Dart/Flutter frompubspec.yaml. v2.4.2 — The Confinement Edition confined every callerpathargument. v2.4.0 — The Chameleon Edition auto-selects its transport: stdio locally, Streamable HTTP on Cloud Run.
One-Minute Setup
1. Install
uvx gemini-faf-mcp # zero-install run via uvx (fetched from PyPI)
# or: pip3 install gemini-faf-mcp2. Add to Antigravity CLI
agy plugin install https://github.com/Wolfe-Jam/gemini-faf-mcpAntigravity CLI (agy) is Google's successor to Gemini CLI (announcement). The plugin brings the MCP server and the setup, score and export skills.
Moving from Gemini CLI? agy plugin import gemini converts the extension you already have. If it stops on .gemini/project.faf, that's a link versions up to 3.2.0 shipped: rm -f ~/.gemini/extensions/gemini-faf-mcp/.gemini/project.faf, then run the import again, or install fresh with the line above.
Still on Gemini CLI through work? gemini extensions install https://github.com/Wolfe-Jam/gemini-faf-mcp installs the same extension.
3. Author your project context
Run /setup (in Gemini CLI: /faf:setup).
That detects your stack from the repo's own files (it calls faf_auto), writes project.faf and scores it. Then fill in what only you know (the goal, who it's for, why it exists), and run /score (/faf:score in Gemini CLI) to see what's left. From then on, Gemini reads it through the faf tools; /export writes GEMINI.md from it, which Gemini loads at the start of every session.
Tip: Trophy ✪ = 100%: AI is optimized to code.
/scoreshows exactly which slots are still empty.
Related MCP server: rust-faf-mcp RMCP
The "One-File" Advantage
A .faf file is structured YAML that captures your project DNA. Every AI agent reads it once and knows exactly what you're building.
# project.faf — your project, machine-readable
faf_version: "3.0"
project:
name: my-api
goal: REST API for user management
main_language: Python
stack:
backend: FastAPI
database: PostgreSQL
testing: pytest
human_context:
who: Backend developers
what: User CRUD with auth
why: Replace legacy PHP serviceResult: Gemini knows your stack and goal from the file, not from you re-typing them each session.
FAF defines. MD instructs. AI codes.
What about my GEMINI.md?
You don't replace it. .faf authors it. Run faf_gemini and you get a fresh GEMINI.md in Gemini CLI's own hierarchical, @file-importable convention — setup, verify, key files, stack, confirm-first actions — authored from a single source of truth instead of hand-maintained. Your hand-written content outside the faf-managed block is preserved.
> /faf:export
# Authors GEMINI.md from project.faf (in Antigravity: /export).faf is the source. GEMINI.md is one of its outputs. Same logic for AGENTS.md (OpenAI Codex), .cursorrules, CLAUDE.md, and others — write once, render everywhere.
Auto-Detect Your Stack
faf_auto scans your project's manifest files and its docker-compose services, Makefile targets, and CI config, then authors a .faf with accurate slot values. No manual entry needed.
> Auto-detect my project stack{
"detected": {
"main_language": "Python",
"package_manager": "pip",
"framework": "FastAPI",
"api_type": "REST",
"database": "PostgreSQL",
"cache": "Redis",
"hosting": "Docker Compose",
"commands": { "test": "make test", "build": "make build", "lint": "make check-all" }
},
"score": 56,
"tier": "YELLOW"
}Shortened output from a real 3.3.3 run on a FastAPI project. database and cache came from docker-compose.yml and commands from the Makefile; cicd: GitHub Actions (from .github/workflows/) is written to the file too. None of these come from the manifest. The goal and the six W's are yours to fill in.
What it scans:
File | Detects |
| Python + build system + frameworks (FastAPI, Django, Flask, FastMCP) |
| JavaScript/TypeScript + frameworks (React, Vue, Next.js, Express) |
| Rust + cargo + frameworks (Axum, Actix) |
| Go + go modules + frameworks (Gin, Echo) |
| Python (fallback) / Ruby / PHP |
|
|
|
|
|
|
Priority rule: pyproject.toml / Cargo.toml / go.mod take priority over package.json. File-facts (a real compose service, a Makefile target) win over dependency guesses. Only sets values that are actually detected — no hardcoded defaults.
Google Antigravity
Antigravity reads MCP servers from ~/.gemini/config/mcp_config.json (every project) or .agents/mcp_config.json (one project); both take both modes. A plugin installed with agy plugin install brings its own.
Local (stdio):
{ "mcpServers": { "gemini-faf": { "command": "uvx", "args": ["gemini-faf-mcp"] } } }Hosted:
{ "mcpServers": { "gemini-faf": { "serverUrl": "https://mcpaas.live/gemini/mcp/v1" } } }Antigravity expects serverUrl, not url or httpUrl.
All 13 Tools
Real input and output for every tool: docs/TOOLS.md. Install, first run and fixes: docs/SETUP.md.
Every tool carries MCP tool annotations: read only (faf_read, faf_validate, faf_score, faf_discover, faf_stringify, faf_context, faf_about, faf_model), writes without losing anything (faf_init, faf_auto, faf_gemini, faf_agents), rewrites the file (faf_migrate).
Create & Detect
Tool | What it does |
| Create a starter |
| Auto-detect stack from manifest files and author/update |
| Find |
Validate & Score
Tool | What it does |
| Full Mk4 validation — score, tier, slot counts, errors, warnings |
| Quick Mk4 score — score, tier, populated/active/total slot counts |
Read & Transform
Tool | What it does |
| Parse a |
| Convert parsed FAF data back to clean YAML |
| Get Gemini-optimized context (project + stack + score) |
Export & Interop
Tool | What it does |
| Export |
| Export a BETTER-shaped |
Migrate
Tool | What it does |
| Bring a |
Reference
Tool | What it does |
| FAF format info — IANA registration, version, ecosystem |
| Get a 100% Trophy-scored example |
Score and Tier System
Your .faf file is scored on completeness — how many slots are filled with real values.
Score | Tier | Meaning |
100% | TROPHY | AI has full context for your project |
99% | GOLD | Exceptional |
95% | SILVER | Top tier |
85% | BRONZE | Minimum recommended — AI can build from here |
70% | GREEN | Solid foundation |
55% | YELLOW | Needs improvement |
<55% | RED | Major gaps — AI will guess |
0% | WHITE | Empty |
Aim for Bronze (85%+). That's where AI stops guessing and starts knowing.
Using with Antigravity or Gemini CLI
> Create a .faf file for my Python FastAPI project
> Auto-detect my project and fill in the stack
> Score my .faf and show what's missing
> Export GEMINI.md for this project
> Show me a 100% example for an MCP server
> What is FAF and how does it work?
> Read my project.faf and summarize the stack
> Validate my .faf and fix the warnings
> Migrate my project.faf to the current formatArchitecture
gemini-faf-mcp v3.3.3
├── server.py → FastMCP MCP server (13 tools, dual-transport, Mk4 scoring)
├── safe_path.py → path confinement for caller-supplied `path` args
├── inject.py → non-destructive faf-managed-block injection
├── interrogate.py → Full-Facts grounding (docker-compose + Makefile signals)
├── main.py → Cloud Run REST API (GET/POST/PUT)
├── models.py → 15 project type examples
└── src/gemini_faf_mcp/ → Python SDK (FAFClient, parser)The MCP server delegates to faf-python-sdk for parsing, validation, Mk4 scoring, and AGENTS.md / GEMINI.md authoring. Stack detection in faf_auto — including the Full-Facts grounding — is Python-native, no external CLI dependencies.
Testing
Clone, dev install and the full suite: CONTRIBUTING.md.
390 tests passing across the FastMCP server, CLI flags, Cloud Function, Mk4 WJTTC championship, Full-Facts grounding, path-confinement, write-guard, model-parity, Dart detection, and client-telemetry suites. Championship-grade test coverage — WJTTC.
FAF Ecosystem
One format, every AI platform.
Package | Platform | Registry |
Anthropic | npm + MCP #2759 | |
gemini-faf-mcp | PyPI | |
xAI | npm | |
Rust | crates.io | |
Universal | npm |
Python SDK
Use FAF directly in Python without MCP:
from gemini_faf_mcp import FAFClient, parse_faf, validate_faf, find_faf_file
# Parse and validate locally
data = parse_faf("project.faf")
result = validate_faf(data)
print(f"Score: {result['score']}%, Tier: {result['tier']}")
# validate_faf scores data already parsed; for a file's exact score (same as faf-cli), use the faf_score tool
# Find .faf files automatically
faf_path = find_faf_file(".")
# Or use the Cloud Run endpoint
client = FAFClient()
dna = client.get_project_dna()FAFClient sends no telemetry unless you set FAF_TELEMETRY=1, which adds one start-up ping (package name and version). FAF_TELEMETRY_OFF always turns it off. Remote mode sends your requests to the Cloud Run endpoint. Privacy: faf.one/privacy.
Cloud Run REST API
Live endpoint for badges, multi-agent context brokering, and voice-to-FAF mutations.
https://faf-source-of-truth-631316210911.us-east1.run.appSupports agent-optimized responses (Gemini, Claude, Grok, Jules, Codex/Copilot/Cursor) via X-FAF-Agent header. Voice mutations via Gemini Live through PUT endpoint. Auto-deploys via Cloud Build on push to main.
If gemini-faf-mcp has been useful, consider starring the repo — it helps others find it.
Links
Citation
If you use gemini-faf-mcp or the .faf / .fafm / .fafa 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
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}
}License
MIT
Built by @wolfe_jam | wolfejam.dev
Get the CLI
faf-cli — the original AI-context CLI.
npx faf-cli autoAnthropic MCP #2759 · IANA Registered: application/vnd.faf+yaml · faf.one · npm
Available Tools
13 toolsfaf_aboutFaf AboutARead-only
FAF format info — IANA registration, version, ecosystem. Returns metadata about the FAF format, server version, and available MCP bridges. Use this when users ask what FAF is or how it connects to other AI platforms.
Inputs: no named parameters. Returns: object
faf_agentsFaf AgentsAIdempotent
Export and write AGENTS.md from a .faf file (non-destructive).
Authors a BETTER-shaped AGENTS.md (setup · tests · layout · conventions ·
three-tier guardrails · definition of done · security · commit) via
faf-python-sdk's authoring tool — in parity with faf-cli's faf export --agents.
Injects it into AGENTS.md as a faf-managed block, preserving any hand
content. Re-running updates the block in place — it never overwrites your file.
Inputs: path. Returns: object
faf_autoFaf AutoBIdempotent
Auto-detect project stack and author/update a .faf file. Scans package.json, pyproject.toml, Cargo.toml, go.mod, and other manifest files for language, framework, database, API type, and build tools — then grounds the result in the repo's own files: docker-compose service images (Postgres, Redis, Elasticsearch...) map onto stack slots, and Makefile / justfile targets map onto test / build / lint commands. Facts from files, no hardcoded defaults. Creates a new .faf if none exists, or fills empty slots in an existing one.
Inputs: path, directory. Returns: object
faf_contextFaf ContextBRead-only
Get Gemini-optimized context from a .faf file. Returns the key sections an AI needs: project info, stack, instructions, and score. Use this to quickly understand a project without reading the full .faf structure.
Inputs: path. Returns: object
faf_discoverFaf DiscoverARead-only
Find .faf files in the project tree by walking up from start_dir. Searches the current directory and parent directories for project.faf. Use this before faf_read to locate the file automatically.
Inputs: start_dir. Returns: object
faf_geminiFaf GeminiAIdempotent
Export and write GEMINI.md from a .faf file (non-destructive).
Authors GEMINI.md in Gemini CLI's own convention (hierarchical,
@file-importable — setup · verify · key files · stack · confirm-first
actions) via faf-python-sdk's authoring tool, in parity with faf-cli's
faf export --gemini. Injects it as a faf-managed block, preserving any
hand content. Re-running updates the block in place.
Inputs: path. Returns: object
faf_initFaf InitAIdempotent
Create a starter .faf file with project name, goal, and language. Writes a valid FAF YAML file with all required sections. Will not overwrite an existing file — use faf_discover first to check. The path is confined to the project root (cwd / FAF_ALLOWED_ROOTS).
Inputs: goal, name, path, language. Returns: object
faf_migrateFaf MigrateADestructiveIdempotent
Migrate a .faf file to the current format version (3.0).
Bumps faf_version, ensures the section roots exist (project, stack,
human_context, monorepo), and re-serializes. Legacy slot names
(frontend/database/…) still score via the registry's aliases — this
only touches the version and structure, never your values. The file is
re-serialized, so YAML comments and formatting are not kept. Parity with
faf-cli's faf migrate. Pass dry_run=true to preview.
Inputs: path, dry_run. Returns: object
faf_modelFaf ModelARead-only
Get a 100% Trophy-scored example .faf file for a specific project type. Returns a complete, realistic project.faf that fills all 33 scored slots (populated, or slotignored where a slot does not apply). Use this as a reference when building or improving a .faf file — shows exactly what 100% looks like. Call without arguments to list all 15 available project types.
Inputs: project_type. Returns: object
faf_readFaf ReadARead-only
Read project DNA from a .faf file. Returns the full parsed structure including project info, stack, preferences, and scoring data. Use this as the first step to understand any FAF-enabled project.
Inputs: path. Returns: object
faf_scoreFaf ScoreARead-only
Quick Mk4 score check — returns score (0-100%), tier, and slot counts. Uses the Mk4 always-33 scoring engine (faf-kernel parity) for universal parity. Use this for status checks; use faf_validate when you need error details.
Inputs: path. Returns: object
faf_stringifyFaf StringifyBRead-only
Convert parsed FAF data back to YAML string. Useful for displaying the raw .faf content or preparing it for editing. Reads the file, parses it, then re-serializes to clean YAML.
Inputs: path. Returns: object
faf_validateFaf ValidateARead-only
Validate a .faf file and return score, tier, and issues. Returns errors (must fix) and warnings (should fix) with specific messages. Use after faf_init or when checking if a .faf file meets quality standards.
Inputs: path. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools target distinct operations (read, discover, init, migrate, export), and the descriptions actively differentiate the two closest pairs: faf_validate vs faf_score (error details vs quick status) and faf_read vs faf_context (full structure vs AI-optimized subset). The overlap is real but the guidance reduces misselection, leaving only mild ambiguity.
Every tool uses a uniform faf_ prefix followed by a single snake_case noun/verb (faf_read, faf_score, faf_discover, faf_migrate). The pattern is fully predictable throughout with no mixed conventions.
13 tools sit squarely in the well-scoped 3-15 range, and each maps to a concrete lifecycle step (discover, init/auto, read/context, validate/score, stringify, migrate, export). No tool feels redundant or padded.
The surface covers the full FAF lifecycle: discovery, creation (init/auto), reading (read/context), validation/scoring, serialization, migration, and two export targets (GEMINI.md, AGENTS.md). Minor gaps exist — no explicit delete/edit for arbitrary slots and no updater beyond faf_auto filling empty slots — but core workflows are covered.
Maintenance
Related MCP Connectors
Persistent project context for xAI Grok. IANA-registered .faf format.
Persistent project context for Claude. IANA-registered .faf format.
Persistent project context — Rust-native MCP server. IANA-registered .faf format.
Project management shared by people and AI agents, with persistent project state through MCP.
Related MCP Servers
- AlicenseAqualityBmaintenance.FAF (Foundational AI-context Format) with 50+ tools - Only Persistent project context that integrates seamlessly with Claude Desktop workflows. Officially merged (#2759) Anthropic MCP server.141,807 npm23MIT
- AlicenseNot gradedqualityBmaintenancePersistent project context in Rust. 8 MCP tools via rmcp SDK — parse, validate, score, compress, discover, and token analysis. Single binary, zero config. IANA-registered format (application/vnd.faf+yaml). One file, every AI platform.102 npm5MIT
- AlicenseAqualityBmaintenancePersistent project context MCP server that syncs a single .faf file to all AI tool formats (Cursor, Windsurf, Cline, etc.), enabling eternal bi-sync and optimized context for AI assistants.15699 npm7MIT
- AlicenseBqualityDmaintenancePortable, auditable, local-first MCP memory for MCP-compatible AI agents and coding workflows. It keeps durable project memory outside the model runtime, compresses continuity into smaller working packs, and carries forward operational state so agents can resume with less repetition.2841Apache 2.0