Gemini Faf

gemini-faf-mcp v3.2 — The Straight Answers 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.

PyPI FAF Trophy 100% Tests IANA: vnd.faf+yaml IANA: vnd.fafm+yaml DOI: Context paper DOI: Memory paper DOI: Agents paper Business card · Get yours →

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]

.faf is read once at session start. Every tool call lands on a Gemini that already knows your project.

What's New in 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_score says 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:setup looks for a project.faf in 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_init never overwrites, faf_auto fills empty slots only, faf_gemini and faf_agents keep your own text), and faf_migrate rewrites 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's card 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-sdk floor >=1.4.0, where the interop functions are now named author_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_gemini rewritten as faf-python-sdk authoring-tool wrappers (were 4-field stubs); new faf_migrate brings a .faf up to the current format. v2.6.0 — The Agent Card Edition added a real agent.fafa passport, an MCP Server Card (SEP-2127), and an AI Catalog entry. v2.5.0 — The Dart Edition detects Dart/Flutter from pubspec.yaml. v2.4.2 — The Confinement Edition confined every caller path argument. 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-mcp

2. Add to Antigravity CLI

agy plugin install https://github.com/Wolfe-Jam/gemini-faf-mcp

Antigravity 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

Ask the agent to run the setup skill (in Gemini CLI: /faf:setup).

That writes a starter project.faf and scores it. Then ask Gemini to fill it in from your repo (it calls faf_auto), and run the score skill (/faf:score in Gemini CLI) to see what's left. From then on, every Gemini session in this project reads it automatically.

Tip: Trophy ✪ = 100%: AI is optimized to code. The score skill shows exactly which slots are still empty.

---

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 service

Result: Gemini reads this once and knows your project. No 20-minute onboarding. No wrong assumptions. Every session starts aligned.

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 (Gemini CLI; in Antigravity, ask for the export skill)

.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": "uv",
    "framework": "FastAPI",
    "api_type": "REST",
    "database": "PostgreSQL",
    "cache": "Redis",
    "hosting": "Docker Compose",
    "cicd": "GitHub Actions",
    "commands": { "test": "make test", "build": "make build", "lint": "make check-all" }
  },
  "score": 79,
  "tier": "GREEN"
}

database and cache came from docker-compose.yml, commands from the Makefile, cicd from .github/workflows/ — none of which the manifest scan sees. Fill in the six W's and you are at Trophy.

What it scans:

File	Detects
pyproject.toml	Python + build system + frameworks (FastAPI, Django, Flask, FastMCP)
package.json	JavaScript/TypeScript + frameworks (React, Vue, Next.js, Express)
Cargo.toml	Rust + cargo + frameworks (Axum, Actix)
go.mod	Go + go modules + frameworks (Gin, Echo)
requirements.txt / Gemfile / composer.json	Python (fallback) / Ruby / PHP
docker-compose.yml	database / cache / search / storage from service images (Postgres, Redis, Elasticsearch, MinIO, ClickHouse, Qdrant, …)
Makefile / justfile	test / build / lint commands from targets (root, or a nested backend/ dir)
.github/workflows/	cicd: GitHub Actions (also GitLab CI, CircleCI)

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

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
faf_init	Create a starter .faf file with project name, goal, and language
faf_auto	Auto-detect stack from manifest files and author/update .faf
faf_discover	Find .faf files in the project tree

Validate & Score

Tool	What it does
faf_validate	Full Mk4 validation — score, tier, slot counts, errors, warnings
faf_score	Quick Mk4 score — score, tier, populated/active/total slot counts

Read & Transform

Tool	What it does
faf_read	Parse a .faf file into structured data
faf_stringify	Convert parsed FAF data back to clean YAML
faf_context	Get Gemini-optimized context (project + stack + score)

Export & Interop

Tool	What it does
faf_gemini	Export GEMINI.md in Gemini CLI's hierarchical convention (non-destructive)
faf_agents	Export a BETTER-shaped AGENTS.md for OpenAI Codex, Cursor, and other AI tools (non-destructive)

Migrate

Tool	What it does
faf_migrate	Bring a .faf up to the current format version (3.0); dry_run to preview

Reference

Tool	What it does
faf_about	FAF format info — IANA registration, version, ecosystem
faf_model	Get a 100% Trophy-scored example .faf for any of 15 project types

---

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 format

---

Architecture

gemini-faf-mcp v3.2.0
├── 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

pip3 install -e ".[dev]"
python -m pytest tests/ -v

320 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 certified.

---

FAF Ecosystem

One format, every AI platform.

Package	Platform	Registry
claude-faf-mcp	Anthropic	npm + MCP #2759
gemini-faf-mcp	Google	PyPI
grok-faf-mcp	xAI	npm
rust-faf-mcp	Rust	crates.io
faf-cli	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']}")

# 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.app

Supports 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

• FAF Specification
• IANA Registration
• faf-python-sdk
• faf-cli
• Changelog

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. A must-have for every builder.

npx faf-cli auto

Anthropic MCP #2759 · IANA Registered: application/vnd.faf+yaml · faf.one · npm