Gemini-FAF-MCP: Enhance AI Dev Efficiency with FAF Context & Auto Info Capture

Gemini Faf MCP

An MCP server that provides FAF - format project context understanding for the Gemini CLI. Automatically capture the project technology stack, goals, and quality standards through the .faf file, enabling AI to fully understand the project without repeated inquiries.

Developer tools Artificial intelligence chatbots #Project context #AI assistant #Automatic detection #Technology stack .Python

rating : 2 points

downloads : 0

update time : 2026-03-12

Open Site

What is Gemini FAF MCP?

This is an MCP server specifically designed for Google Gemini AI. It allows the AI assistant to immediately understand the全貌 of your project by reading the .faf file (a standardized project description format) in the project. Traditionally, every time a new conversation starts, the AI needs to re - understand your project: What is the technology stack? What framework is used? What are the code specifications? What are the testing standards? This wastes a lot of time. FAF (Format for AI) solves this problem - it packages your project information (language, framework, database, goals, quality standards, team background) into a machine - readable YAML file. The AI reads it once and fully understands it without guessing.

How to use Gemini FAF MCP?

It's very simple to use: 1. Create a .faf file in the project (or let the AI generate it automatically for you) 2. Install and configure the Gemini FAF MCP server 3. Directly ask questions about the project in the Gemini CLI The AI will automatically read the .faf file, understand your technology stack, project goals, and quality standards, and then provide accurate suggestions and code based on this information.

Applicable scenarios

• New team members join the project and need to quickly understand the project architecture • Cross - team collaboration to ensure that AI understands the same project context • Code review, providing suggestions based on project quality standards • Feature development, where AI generates code based on the correct technology stack • Project documentation generation, creating accurate documentation based on actual configurations • Technology stack migration assessment, where AI understands the differences between the current and target technology stacks

Main features

Automatically detect the technology stack

Intelligently scan project files (pyproject.toml, package.json, Cargo.toml, etc.), automatically identify programming languages, frameworks, databases, build tools, etc., and generate an accurate .faf file. It supports mainstream languages such as Python, JavaScript, Rust, and Go.

FAF validation and scoring

Validate the integrity of the .faf file, give a score from 0 - 100% and a grade (from red to trophy - level). Help you know how well the AI understands the project and identify information that needs to be supplemented.

AI - optimized context

Convert the .faf file into a format that is most easily understood by Gemini AI, including the project overview, technology stack details, and quality scores. Ensure that the AI obtains the most relevant and structured project information.

Multi - format export

Support exporting .faf information into formats required by different AI tools: GEMINI.md (Gemini CLI), AGENTS.md (OpenAI, Cursor, etc.), to achieve cross - platform project context sharing.

Project template library

Built - in 100% perfect - scoring examples of 15 common project types (MCP server, FastAPI application, React website, etc.) as reference templates for creating your own .faf file.

Cloud API integration

Provide a Cloud Run REST API, support obtaining project DNA and validating FAF files through HTTP requests, and support optimized response formats for different AI agents.

Advantages

🚀 Save time: AI can start substantial work directly without repeatedly asking for basic project information

🎯 Improve accuracy: Generate code and suggestions based on real project configurations, reducing incorrect assumptions

📊 Quantitative evaluation: The FAF scoring system allows you to know how well the AI understands the project

🔄 Consistency: Ensure that different conversations and different AI assistants have a consistent understanding of the project

🔧 Automation: Automatically detect the technology stack, reducing the workload of manual configuration

🌐 Standardization: Use the IANA - registered standard format, compatible with the entire FAF ecosystem

Limitations

📝 Require initial setup: Need to create or generate a .faf file (although it can be done automatically)

🔄 Require maintenance: The .faf file needs to be updated when the project changes to maintain accuracy

🔧 Technically demanding: Non - developers may need guidance to understand the concept of the technology stack

📚 Learning curve: Need to understand the basic structure of the FAF format and the scoring system

How to use

Install the extension

Install the FAF MCP extension in the Gemini CLI. This is the simplest way.

Create a FAF file

In the project root directory, let the AI automatically detect and create a .faf file.

Validate and optimize

Check the FAF score, supplement missing information according to the suggestions, and reach at least the bronze level (85%+).

Start using

Now the AI fully understands your project. You can directly ask technical questions or request code help.

Usage examples

Quick start for a new project

Newly join a Python FastAPI project and need to quickly understand the technology stack and start development.

Code review and quality check

Ensure that the new code meets the project's quality standards and architectural specifications.

Project documentation generation

Generate accurate architectural documentation and API documentation based on the actual project configuration.

Technology stack migration assessment

Assess the feasibility and workload of migrating from the current technology stack to a new one.

Frequently Asked Questions

What is a FAF file? Do I need to create it manually?

What does the FAF score mean? What score is considered good?

What if my project doesn't have standard configuration files?

Does the FAF file need to be updated frequently?

Is this tool only suitable for Gemini?

Should the FAF file be committed to version control?

Related resources

FAF official website

Complete specifications, examples, and documentation of the FAF format

IANA media type registration

Official IANA registration information of the FAF format

GitHub repository

Source code, issue tracking, and contribution guidelines

PyPI package page

Python package release and version history

FAF Python SDK

SDK for directly using FAF in Python

FAF CLI tool

Cross - platform FAF command - line tool

🚀 gemini-faf-mcp

Your project, understood by AI — in one file. 12 MCP tools for Gemini CLI.

MCP server for FAF — the IANA-registered format for AI project context (application/vnd.faf+yaml). One .faf file gives Gemini full project understanding: stack, goals, conventions, quality bar. No re-explaining. No context drift.

Built on FastMCP. Powered by faf-python-sdk.

🚀 Quick Start

Gemini CLI (recommended)

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

Then in any project directory:

> Auto-detect my project and create a .faf file
> What's the FAF score for this project?
> Export a GEMINI.md for this project

PyPI

pip install gemini-faf-mcp

MCP Config (manual)

{
  "mcpServers": {
    "faf": {
      "command": "python3",
      "args": ["-m", "server"]
    }
  }
}

✨ Features

What FAF Does

Every new session, AI starts from zero. It guesses your stack, misses conventions, asks the same questions. FAF fixes this.

A .faf file is structured YAML that captures your project DNA — language, framework, database, goals, quality standards, team context. Any AI reads it instantly instead of guessing.

# 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 filled with real values.

Score	Tier	Meaning
100%	🏆 Trophy	Perfect — AI has full autonomy
99%	🥇 Gold	Exceptional
95%	🥈 Silver	Top tier
85%	🥉 Bronze	Production ready — AI can work confidently
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

🔧 Technical Details

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.

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:

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.