Unify your AI project context with IANA-registered FAF files.
gemini-faf-mcp 🧬
Unify your AI project context. One file to rule them all. Bridges
CLAUDE.md,GEMINI.md, andAGENTS.mdinto 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.
| Feature | CLAUDE.md |
GEMINI.md |
AGENTS.md |
project.faf |
|---|---|---|---|---|
| Format | Markdown | Markdown | Markdown | Structured YAML |
| Schema | Custom | Custom | Custom | IANA Standard |
| Scoring | No | No | No | Yes (0-100%) |
| Auto-Detect | No | No | No | Yes (153+ files) |
| Vendor Neutral | No | No | No | Yes |
🚀 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:
| 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 validation — score, tier, errors, warnings |
faf_score |
Quick score check (0-100%) with tier name |
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
Tools (12)
faf_initCreate a starter .faf file with project name, goal, and language.faf_autoAuto-detect stack from manifest files and generate/update .faf.faf_discoverFind .faf files in the project tree.faf_validateFull validation of the .faf file including score, tier, errors, and warnings.faf_scoreQuick score check (0-100%) with tier name.faf_readParse a .faf file into structured data.faf_stringifyConvert parsed FAF data back to clean YAML.faf_contextGet Gemini-optimized context including project, stack, and score.faf_geminiExport GEMINI.md with YAML frontmatter for Gemini CLI.faf_agentsExport AGENTS.md for OpenAI Codex, Cursor, and other AI tools.faf_aboutGet FAF format info including IANA registration and version.faf_modelGet a 100% Trophy-scored example .faf for any of 15 project types.Configuration
{"mcpServers": {"gemini-faf-mcp": {"command": "faf", "args": ["mcp"]}}}