{ "markdown": "\n\n\n# gemini-faf-mcp — The Agent Card Edition\n\n**Persistent Project Context for Google Gemini. Define once. Sync everywhere.**\n\n**FAF defines. MD instructs. AI codes.**\n\n⭐ **A star helps other devs discover gemini-faf-mcp** — despite the downloads, ~3 of 4 devs check stars first.\n\nStop re-explaining your project to every new Gemini session. Every Gemini conversation starts cold — you re-state your stack, your goals, your conventions every single time. `.faf` is one structured file that captures all of it. This package is the MCP server that lets Gemini read it.\n\n\n\n[![PyPI](https://img.shields.io/pypi/v/gemini-faf-mcp?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/gemini-faf-mcp/)\n[![FAF Trophy 100%](https://img.shields.io/badge/FAF-%F0%9F%8F%86%20100%25-000000?labelColor=FF6B35)](https://faf.one)\n[![Tests](https://img.shields.io/badge/Tests-243%20passing-brightgreen?style=for-the-badge)](https://github.com/Wolfe-Jam/gemini-faf-mcp)\n[![IANA: vnd.faf+yaml](https://img.shields.io/badge/IANA-vnd.faf%2Byaml-00D4D4?style=for-the-badge)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)\n[![IANA: vnd.fafm+yaml](https://img.shields.io/badge/IANA-vnd.fafm%2Byaml-00D4D4?style=for-the-badge)](https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml)\n[![DOI: Context paper](https://img.shields.io/badge/DOI-Context%20paper-FF6B35?style=for-the-badge)](https://doi.org/10.5281/zenodo.18251362)\n[![DOI: Memory paper](https://img.shields.io/badge/DOI-Memory%20paper-FF6B35?style=for-the-badge)](https://doi.org/10.5281/zenodo.20348942)\n[![DOI: Agents paper](https://img.shields.io/badge/DOI-Agents%20paper-FF6B35?style=for-the-badge)](https://doi.org/10.5281/zenodo.21951641)\n\n### Before and after\n\n```\nWithout FAF With FAF (.faf at 85%+ Bronze)\n───────────────────────── ─────────────────────────\nYou: \"I'm using FastAPI with... You: \"Add a /users/me endpoint\"\n PostgreSQL, pytest, and...\" Gemini: [generates correct code,\nGemini: \"Got it. What's the uses your auth pattern,\n codebase like?\" matches your test style]\nYou: \"It's a REST API for...\"\n[5 minutes of re-explaining]\nGemini: [now ready to help]\n```\n\n`.faf` is read once at session start. Every tool call lands on a Gemini that already knows your project.\n\n### What's New in v2.6.0 — The Agent Card Edition\n\n**A real agent.fafa passport, MCP Server Card, and AI Catalog entry — gemini-faf-mcp joins the wider agent-discovery ecosystem.**\n\n`agent.fafa` is authored from live introspection of the server's actual tools, not guessed. Ships alongside an MCP Server Card (SEP-2127) and a fresh AI Catalog entry (spec ratified Nov 2025). GEMINI.md now renders real setup/test/key-files content instead of a thin project/goal/language stub. Not in this release: A2A support — `faf cards --target a2a` correctly refuses to fabricate an endpoint this server doesn't serve; real A2A support is a future release, not a claim made early.\n\n> **v2.5.1** — one.faf namespace migration: gemini joins the fleet on `one.faf/gemini-faf-mcp` (registry publish now DNS-authenticated). **v2.5.0 — The Dart Edition** detects Dart/Flutter from `pubspec.yaml` — Flutter app vs package · Dart MCP / backend / CLI / library. **v2.4.3** made `faf_agents` / `faf_gemini` non-destructive (inject a structured `.faf` block, preserve your Markdown below). **v2.4.2 — The Confinement Edition** confined every caller `path` argument (security). **v2.4.0 — The Chameleon Edition** auto-selects its transport: stdio locally, Streamable HTTP on Cloud Run. 12 tools, zero config.\n\n---\n\n## One-Minute Setup\n\n### 1. Install\n\n```bash\nuvx gemini-faf-mcp # zero-install run via uvx (fetched from PyPI)\n# or: pip3 install gemini-faf-mcp\n```\n\n### 2. Add to Gemini CLI\n\n```bash\ngemini extensions install https://github.com/Wolfe-Jam/gemini-faf-mcp\n```\n\n### 3. Author your project context\n\nIn your Gemini CLI:\n\n```\n> /faf:setup\n```\n\nYou should see: `Created project.faf — Score: 85% (BRONZE)`. From this point, every Gemini session in this project reads it automatically.\n\n> **Tip:** A score of 85% (BRONZE) is the minimum where Gemini stops guessing. Run `/faf:score` to see what's missing and how to push to 100% (TROPHY).\n\n---\n\n## The \"One-File\" Advantage\n\nA `.faf` file is structured YAML that captures your project DNA. Every AI agent reads it once and knows exactly what you're building.\n\n```yaml\n# project.faf — your project, machine-readable\nfaf_version: '2.5.0'\nproject:\n name: my-api\n goal: REST API for user management\n main_language: Python\nstack:\n backend: FastAPI\n database: PostgreSQL\n testing: pytest\nhuman_context:\n who: Backend developers\n what: User CRUD with auth\n why: Replace legacy PHP service\n```\n\n**Result:** Gemini reads this once and knows your project. No 20-minute onboarding. No wrong assumptions. Every session starts aligned.\n\n> **FAF defines. MD instructs. AI codes.**\n\n### What about my `GEMINI.md`?\n\nYou don't replace it. `.faf` **authors** it. Run `faf_gemini` and you get a fresh `GEMINI.md` with the structured project data baked in as YAML frontmatter — the same `GEMINI.md` Gemini CLI already reads, but authored from a single source of truth instead of hand-maintained.\n\n```bash\n> /faf:export\n# Generates GEMINI.md from project.faf\n```\n\n`.faf` is the source. `GEMINI.md` is one of its outputs. Same logic for `AGENTS.md` (OpenAI Codex), `.cursorrules`, `CLAUDE.md`, and others — write once, render everywhere.\n\n---\n\n## Auto-Detect Your Stack\n\n`faf_auto` scans your project's manifest files and authors a `.faf` with accurate slot values. No manual entry needed.\n\n```\n> Auto-detect my project stack\n```\n\n```json\n{\n \"detected\": {\n \"main_language\": \"Python\",\n \"package_manager\": \"pip\",\n \"build_tool\": \"setuptools\",\n \"framework\": \"FastMCP\",\n \"api_type\": \"MCP\",\n \"database\": \"BigQuery\"\n },\n \"score\": 100,\n \"tier\": \"TROPHY\"\n}\n```\n\n**What it scans:**\n\n| File | Detects |\n|------|---------|\n| `pyproject.toml` | Python + build system + frameworks (FastAPI, Django, Flask, FastMCP) + databases |\n| `package.json` | JavaScript/TypeScript + frameworks (React, Vue, Next.js, Express) |\n| `Cargo.toml` | Rust + cargo + frameworks (Axum, Actix) |\n| `go.mod` | Go + go modules + frameworks (Gin, Echo) |\n| `requirements.txt` | Python (fallback) |\n| `Gemfile` | Ruby |\n| `composer.json` | PHP |\n\n**Priority rule:** `pyproject.toml` / `Cargo.toml` / `go.mod` take priority over `package.json`. Only sets values that are actually detected — no hardcoded defaults.\n\n---\n\n## All 12 Tools\n\n### Create & Detect\n\n| Tool | What it does |\n|------|-------------|\n| `faf_init` | Create a starter `.faf` file with project name, goal, and language |\n| `faf_auto` | Auto-detect stack from manifest files and author/update `.faf` |\n| `faf_discover` | Find `.faf` files in the project tree |\n\n### Validate & Score\n\n| Tool | What it does |\n|------|-------------|\n| `faf_validate` | Full Mk4 validation — score, tier, slot counts, errors, warnings |\n| `faf_score` | Quick Mk4 score — score, tier, populated/active/total slot counts |\n\n### Read & Transform\n\n| Tool | What it does |\n|------|-------------|\n| `faf_read` | Parse a `.faf` file into structured data |\n| `faf_stringify` | Convert parsed FAF data back to clean YAML |\n| `faf_context` | Get Gemini-optimized context (project + stack + score) |\n\n### Export & Interop\n\n| Tool | What it does |\n|------|-------------|\n| `faf_gemini` | Export `GEMINI.md` with YAML frontmatter for Gemini CLI |\n| `faf_agents` | Export `AGENTS.md` for OpenAI Codex, Cursor, and other AI tools |\n\n### Reference\n\n| Tool | What it does |\n|------|-------------|\n| `faf_about` | FAF format info — IANA registration, version, ecosystem |\n| `faf_model` | Get a 100% Trophy-scored example `.faf` for any of 15 project types |\n\n---\n\n## Score and Tier System\n\nYour `.faf` file is scored on completeness — how many slots are filled with real values.\n\n| Score | Tier | Meaning |\n|-------|------|---------|\n| 100% | TROPHY | AI has full context for your project |\n| 99% | GOLD | Exceptional |\n| 95% | SILVER | Top tier |\n| 85% | BRONZE | Minimum recommended — AI can build from here |\n| 70% | GREEN | Solid foundation |\n| 55% | YELLOW | Needs improvement |\n| <55% | RED | Major gaps — AI will guess |\n| 0% | WHITE | Empty |\n\n**Aim for Bronze (85%+).** That's where AI stops guessing and starts knowing.\n\n---\n\n## Using with Gemini CLI\n\n```\n> Create a .faf file for my Python FastAPI project\n> Auto-detect my project and fill in the stack\n> Score my .faf and show what's missing\n> Export GEMINI.md for this project\n> Show me a 100% example for an MCP server\n> What is FAF and how does it work?\n> Read my project.faf and summarize the stack\n> Validate my .faf and fix the warnings\n```\n\n---\n\n## Architecture\n\n```\ngemini-faf-mcp v2.4.2\n├── server.py → FastMCP MCP server (12 tools, dual-transport, Mk4 scoring)\n├── safe_path.py → path confinement for caller-supplied `path` args\n├── main.py → Cloud Run REST API (GET/POST/PUT)\n├── models.py → 15 project type examples\n└── src/gemini_faf_mcp/ → Python SDK (FAFClient, parser)\n```\n\nThe 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.\n\n---\n\n## Testing\n\n```bash\npip3 install -e \".[dev]\"\npython -m pytest tests/ -v\n```\n\n233 tests passing across 9 WJTTC tiers (137 MCP server + 55 Cloud Function + 41 Mk4 WJTTC championship). Championship-grade test coverage — [WJTTC certified](https://github.com/Wolfe-Jam/WJTTC).\n\n---\n\n## FAF Ecosystem\n\nOne format, every AI platform.\n\n| Package | Platform | Registry |\n|---------|----------|----------|\n| [claude-faf-mcp](https://npmjs.com/package/claude-faf-mcp) | Anthropic | npm + MCP #2759 |\n| **gemini-faf-mcp** | **Google** | **PyPI** |\n| [grok-faf-mcp](https://npmjs.com/package/grok-faf-mcp) | xAI | npm |\n| [rust-faf-mcp](https://crates.io/crates/rust-faf-mcp) | Rust | crates.io |\n| [faf-cli](https://npmjs.com/package/faf-cli) | Universal | npm |\n\n---\n\n## Python SDK\n\nUse FAF directly in Python without MCP:\n\n```python\nfrom gemini_faf_mcp import FAFClient, parse_faf, validate_faf, find_faf_file\n\n# Parse and validate locally\ndata = parse_faf(\"project.faf\")\nresult = validate_faf(data)\nprint(f\"Score: {result['score']}%, Tier: {result['tier']}\")\n\n# Find .faf files automatically\nfaf_path = find_faf_file(\".\")\n\n# Or use the Cloud Run endpoint\nclient = FAFClient()\ndna = client.get_project_dna()\n```\n\n---\n\n## Cloud Run REST API\n\nLive endpoint for badges, multi-agent context brokering, and voice-to-FAF mutations.\n\n```\nhttps://faf-source-of-truth-631316210911.us-east1.run.app\n```\n\nSupports 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`.\n\n---\n\nIf `gemini-faf-mcp` has been useful, consider starring the repo — it helps others find it.\n\n---\n\n## Links\n\n- [FAF Specification](https://faf.one)\n- [IANA Registration](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)\n- [faf-python-sdk](https://pypi.org/project/faf-python-sdk/)\n- [faf-cli](https://npmjs.com/package/faf-cli)\n- [Changelog](./CHANGELOG.md)\n\n## Citation\n\nIf you use `gemini-faf-mcp` or the `.faf` / `.fafm` / `.fafa` formats in research or production, please cite the format papers:\n\n> Wolfe, J. (2025). *Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding*. Zenodo. https://doi.org/10.5281/zenodo.18251362\n\n> Wolfe, J. (2026). *Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory*. Zenodo. https://doi.org/10.5281/zenodo.20348942\n\n> Wolfe, J. (2026). *Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era*. Zenodo. https://doi.org/10.5281/zenodo.21951641\n\n### BibTeX\n\n```bibtex\n@article{wolfe2025faf,\n title = {Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding},\n author = {Wolfe, James},\n year = {2025},\n month = {nov},\n publisher = {Zenodo},\n doi = {10.5281/zenodo.18251362},\n url = {https://doi.org/10.5281/zenodo.18251362}\n}\n\n@article{wolfe2026fafm,\n title = {Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory},\n author = {Wolfe, James},\n year = {2026},\n month = {may},\n publisher = {Zenodo},\n doi = {10.5281/zenodo.20348942},\n url = {https://doi.org/10.5281/zenodo.20348942}\n}\n\n@article{wolfe2026fafa,\n title = {Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era},\n author = {Wolfe, James},\n year = {2026},\n month = {aug},\n publisher = {Zenodo},\n doi = {10.5281/zenodo.21951641},\n url = {https://doi.org/10.5281/zenodo.21951641}\n}\n```\n\n## License\n\nMIT\n\n---\n\nBuilt by [@wolfe_jam](https://x.com/wolfe_jam) | [wolfejam.dev](https://wolfejam.dev)\n\n---\n\n### Get the CLI\n\n> **faf-cli** — The original AI-Context CLI. A must-have for every builder.\n\n```bash\nnpx faf-cli auto\n```\n\n**Anthropic MCP [#2759](https://github.com/modelcontextprotocol/servers/pull/2759)** · **IANA Registered:** `application/vnd.faf+yaml` · [faf.one](https://faf.one) · [npm](https://www.npmjs.com/package/faf-cli)\n", "bytes": 13668, "sha": "31b3143854ea5dad4403df590aa980752ebce289b8da2a2349ae516ab4ab8a9a", "repo_slug": "wolfe-jam/gemini-faf-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_wolfe_jam_gemini_faf_mcp_0acab3d7/readme" }