gemini-faf-mcp
The gemini-faf-mcp server creates, manages, validates, and exports .faf (Foundational AI-context Format) files — a unified, IANA-registered YAML format for sharing project context across AI platforms like Gemini, Claude, and OpenAI.
faf_init– Generate a starter.faffile with a project name, goal, and language without overwriting existing files.faf_auto– Scan manifest files (package.json,pyproject.toml,Cargo.toml,go.mod, etc.) to auto-detect languages, frameworks, databases, and build tools, then generate or update a.faffile.faf_discover– Walk the directory tree to locate an existingproject.faffile.faf_read– Parse a.faffile into full structured data (project info, stack, preferences, scoring).faf_validate– Run full Mk4 validation returning a score (0–100%), tier (TROPHY → RED), slot counts, errors, and warnings.faf_score– Quick score check returning tier and slot counts without full validation detail.faf_stringify– Re-serialize parsed FAF data back into clean YAML.faf_context– Extract an AI-optimized project summary (info, stack, instructions, score) for instant context without reading the full file.faf_gemini– Export aGEMINI.mdfile with YAML frontmatter optimized for the Gemini CLI.faf_agents– Export anAGENTS.mdfile compatible with OpenAI Codex, Cursor, and other AI tools.faf_model– Retrieve a 100% Trophy-scored example.faffile for any of 15 supported project types.faf_about– Get FAF format metadata including IANA registration, server version, and ecosystem info.
The server also functions as a Cloud Run REST API supporting badges, multi-agent context brokering, and agent-optimized responses via the X-FAF-Agent header.
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 🧬
Unify your AI project context. One file to define them all. Bridges
CLAUDE.md,GEMINI.md,AGENTS.md, andGROK.mdinto a single, IANA-registered source of truth.
What's New in v2.2.0
Mk4 Championship Scoring Engine — all 12 tools now use the same scoring algorithm as the Rust compiler and TypeScript CLI. faf_score and faf_validate return slot-level detail (populated, active, total). Scores match across every FAF tool in every language. 221 tests, 41 new WJTTC championship tests. Dead code removed (sync_faf.py).
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 |
|
|
|
|
|
Format | Markdown | Markdown | Markdown | Markdown | Structured YAML |
Schema | Custom | Custom | Custom | Custom | IANA Standard |
Scoring | No | No | No | No | Yes (0-100%) |
Auto-Detect | No | No | No | No | Yes (153+ files) |
Vendor Neutral | No | No | No | No | Yes |
🚀 One-Minute Setup
1. Install
pip install gemini-faf-mcp2. Auto-Detect & Initialize
Scan your existing project and create your DNA in seconds (Zero install):
# Detects Python, JS/TS, Rust, Go, Ruby, and PHP manifests
bunx faf-cli auto3. 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 serviceResult: 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 |
| Python + build system + frameworks (FastAPI, Django, Flask, FastMCP) + databases |
| 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. Only sets values that are actually detected — no hardcoded defaults.
All 12 Tools
Create & Detect
Tool | What it does |
| Create a starter |
| Auto-detect stack from manifest files and generate/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 |
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 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 warningsArchitecture
gemini-faf-mcp v2.2.0
├── server.py → FastMCP MCP server (12 tools, Mk4 scoring)
├── 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
pip install -e ".[dev]"
python -m pytest tests/ -v221 tests passing across 9 WJTTC tiers (125 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 |
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']}")
# 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.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
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 autoAnthropic MCP #2759 · IANA Registered: application/vnd.faf+yaml · faf.one · npm
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Wolfe-Jam/gemini-faf-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server