one.faf/gemini-faf-mcp

Official

by Wolfe-Jam · Python

Gemini FAF

Persistent project context for Google Gemini. Python/FastMCP. IANA-registered .faf format.

Persistent project context manager for Google Gemini using Python and FastMCP.

Topics

gemini-cli-extensionai-contextdeveloper-toolsfafgeminigemini-cligoogle-cloudmcpmcp-servermodel-context-protocolpythonagents-mdai-readinesscontext-engineeringcrates-ioiananpmproject-dnapypiyaml

README.md11 KBView on GitHub

gemini-faf-mcp — The Dart Edition

Persistent Project Context for Google Gemini. Define once. Sync everywhere.

FAF defines. MD instructs. AI codes.

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

code

Without FAF                           With FAF (.faf at 85%+ Bronze)
─────────────────────────             ─────────────────────────
You: "I'm using FastAPI with...       You: "Add a /users/me endpoint"
      PostgreSQL, pytest, and..."     Gemini: [generates 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 v2.5.0 — The Dart Edition

v2.5.1 — one.faf namespace migration: gemini joins the fleet on one.faf/gemini-faf-mcp (registry publish now DNS-authenticated). No tool or behaviour changes.

gemini-faf-mcp now understands Dart and Flutter projects.

Detects Dart/Flutter from a pubspec.yaml — Flutter app vs package · Dart MCP / backend / CLI / library — by composing faf-python-sdk's detector, the shared engine, not a fork. Zero-Config, 12 exact tools.

v2.4.3 made faf_agents / faf_gemini non-destructive (inject a structured .faf block, preserve your Markdown below). v2.4.2 — The Confinement Edition confined every caller path argument (security). v2.4.0 — The Chameleon Edition auto-selects its transport: stdio locally, Streamable HTTP on Cloud Run. 12 tools, zero config.

One-Minute Setup

1. Install

bash

uvx gemini-faf-mcp          # zero-install run via uvx (fetched from PyPI)
# or: pip3 install gemini-faf-mcp

2. Add to Gemini CLI

bash

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

3. Generate your project context

In your Gemini CLI:

code

> /faf:setup

You should see: Created project.faf — Score: 85% (BRONZE). From this point, every Gemini session in this project reads it automatically.

Tip: A score of 85% (BRONZE) is the minimum where Gemini stops guessing. Run /faf:score to see what's missing and how to push to 100% (TROPHY).

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.

yaml

# project.faf — your project, machine-readable
faf_version: '2.5.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 generates it. Run faf_gemini and you get a fresh GEMINI.md with the structured project data baked in as YAML frontmatter — the same GEMINI.md Gemini CLI already reads, but generated from a single source of truth instead of hand-maintained.

bash

> /faf:export
# Generates GEMINI.md from project.faf

.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 generates a .faf with accurate slot values. No manual entry needed.

code

> Auto-detect my project stack

json

{
  "detected": {
    "main_language": "Python",
    "package_manager": "pip",
    "build_tool": "setuptools",
    "framework": "FastMCP",
    "api_type": "MCP",
    "database": "BigQuery"
  },
  "score": 100,
  "tier": "TROPHY"
}

What it scans:

File	Detects
`pyproject.toml`	Python + build system + frameworks (FastAPI, Django, Flask, FastMCP) + databases
`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`	Python (fallback)
`Gemfile`	Ruby
`composer.json`	PHP

Priority rule: pyproject.toml / Cargo.toml / go.mod take priority over package.json. Only sets values that are actually detected — no hardcoded defaults.

All 12 Tools

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 generate/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` with YAML frontmatter for Gemini CLI
`faf_agents`	Export `AGENTS.md` for OpenAI Codex, Cursor, and other AI tools

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 Gemini CLI

code

> 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

Architecture

code

gemini-faf-mcp v2.4.2
├── server.py              → FastMCP MCP server (12 tools, dual-transport, Mk4 scoring)
├── safe_path.py           → path confinement for caller-supplied `path` args
├── 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, and Mk4 scoring. Stack detection in faf_auto is Python-native — no external CLI dependencies.

Testing

bash

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

233 tests passing across 9 WJTTC tiers (137 MCP server + 55 Cloud Function + 41 Mk4 WJTTC championship). 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:

python

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()

Cloud Run REST API

Live endpoint for badges, multi-agent context brokering, and voice-to-FAF mutations.

code

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.

License

MIT

Built by @wolfe_jam | 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 · IANA Registered: application/vnd.faf+yaml · faf.one · npm

Install

claude_desktop_config.json

{
  "mcpServers": {
    "gemini-faf-mcp": {
      "command": "uvx",
      "args": [
        "gemini-faf-mcp"
      ]
    }
  }
}

Topics

gemini-faf-mcp — The Dart Edition

Before and after

What's New in v2.5.0 — The Dart Edition

One-Minute Setup

1. Install

2. Add to Gemini CLI

3. Generate your project context

The "One-File" Advantage

What about my GEMINI.md?

Auto-Detect Your Stack

All 12 Tools

Create & Detect

Validate & Score

Read & Transform

Export & Interop

Reference

Score and Tier System

Using with Gemini CLI

Architecture

Testing

FAF Ecosystem

Python SDK

Cloud Run REST API

Links

License

Get the CLI

Install

What about my `GEMINI.md`?