gemini-faf-mcp 🧬

Unify your AI project context. One file to rule them all. Bridges CLAUDE.md, GEMINI.md, and AGENTS.md into a single, IANA-registered source of truth.

Stop re-explaining your project to every new AI session.

Gemini, Claude, and OpenAI all have different ways of "learning" your project. FAF (Foundational AI-context Format) unifies them into one machine-readable .faf file.

Result: Zero context drift. Zero-minute onboarding. 100% project alignment.

🚀 One-Minute Setup

1. Install

pip install gemini-faf-mcp

2. Auto-Detect & Initialize

Scan your existing project and create your DNA in one command:

# Detects Python (FastAPI/Django), JS/TS (React/Next.js), Rust (Axum), and Go (Gin)
faf auto

3. Add to Gemini CLI

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

💎 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: '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.

Auto-Detect Your Stack

faf_auto scans your project's manifest files and generates a .faf with accurate slot values. No manual entry needed.

> Auto-detect my project stack

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

What it scans:

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

Validate & Score

Read & Transform

Export & Interop

Reference

Score and Tier System

Your .faf file is scored on completeness — how many slots are filled with real values.

Aim for Bronze (85%+). That's where AI stops guessing and starts knowing.

Using with 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

Architecture

gemini-faf-mcp v2.1.0
├── server.py              → FastMCP MCP server (12 tools)
├── 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 discovery. Stack detection in faf_auto is Python-native — no external CLI dependencies.

Testing

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

183 tests passing across 9 WJTTC tiers (126 MCP server + 57 Cloud Function). Championship-grade test coverage — WJTTC certified.

FAF Ecosystem

One format, every AI platform.

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

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.

Links

• FAF Specification

• IANA Registration

• faf-python-sdk

• faf-cli

• Changelog

License

MIT

Built by @wolfe_jam | wolfejam.dev