io.github.Wolfe-Jam/gemini-faf-mcp
FAF Source of Truth for Gemini. Read project DNA from .faf files. Ecosystem: #2759
Ask AI about io.github.Wolfe-Jam/gemini-faf-mcp
Powered by Claude Β· Grounded in docs
I know everything about io.github.Wolfe-Jam/gemini-faf-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 | CLAUDE.md | GEMINI.md | AGENTS.md | GROK.md | project.faf |
|---|---|---|---|---|---|
| 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-mcp
2. 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 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 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
> 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.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/ -v
221 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 |
|---|---|---|
| claude-faf-mcp | Anthropic | npm + MCP #2759 |
| gemini-faf-mcp | 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()
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
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
