gemini-faf-mcp

gemini-faf-mcp v3.1 — 新时代版

为 Google Gemini 提供持久的项目上下文。定义一次，处处同步。

FAF 负责定义。AGENTS.md 负责指导。AI 负责编码。

☆ 收藏 gemini-faf-mcp 页面，以便日后查看。

别再向每个新的 Gemini 会话重新介绍你的项目了。每次 Gemini 对话都从零开始——你每次都要重申技术栈、目标和约定。.faf 是一个结构化文件，可记录所有这些信息。此软件包是让 Gemini 读取它的 MCP 服务。

使用前后对比

Without FAF                           With FAF (project.faf filled in) 
─────────────────────────             ─────────────────────────
You: "I'm using FastAPI with...       You: "Add a /users/me endpoint"
      PostgreSQL, pytest, and..."     Gemini: [writes correct code,
Gemini: "Got it. What's the              uses your auth pattern,
        codebase like?"                  matches your test style]
You: "It's a REST API for..."
[5 minutes of re-explaining]
Gemini: [now ready to help]

会话开始时只需读取一次 .faf。每次调用工具时，Gemini 都已了解你的项目。

v3.1.1 新特性

gemini-faf-mcp --version 和 --help 现在会输出结果并退出。之前，这两个参数都会启动服务。

• --version (-V) 会打印版本号；--help (-h) 会打印用法和客户端配置。其他任何情况都与之前一样启动服务，因此无需更改客户端配置。

v3.1.0 — 新时代版

透明可见的工具：每个 Gemini 工具现在都会说明自己的操作——读取、写入还是重写——让客户端知道何时应先询问。在 Gemini CLI 和 Google Antigravity 中均可使用。

• 每个工具都有标注。 全部 13 个工具都带有 MCP 工具注释，且与各自的操作相符：8 个只读，4 个写入但不会丢失任何内容（faf_init 永不覆盖，faf_auto 只填写空白项，faf_gemini 和 faf_agents 保留你自己的文本），而 faf_migrate 会重写文件。它们都不会访问网络。能够读取这些标注的客户端可以直接执行读取操作，并在写入前先询问。
• 专属名片。 更新后的 FAF 护照（agent.fafa，使用 faf-cli 8.2 的 card init 生成）和 MCP Server Card，版本均为 3.1.0，包含全部 13 个工具和 FAF 的上下文。
• 支持 Google Antigravity，可本地运行（uvx）或托管运行（serverUrl）。请参阅下方的 Google Antigravity。
• 全新外观： gemini-faf-mcp 页面，经重新设计，更符合 Google 开发者的使用习惯。
• 托管函数始终采用 always-33 评分，与其他所有产品使用同一引擎。

更早版本：v3.0.0 — Always33 版 — 一个引擎，一个数字：与 faf-cli 8、claude-faf-mcp 7、faf-mcp 4 和 grok-faf-mcp 2 的评分相同。

v2.8.2 — 完整事实版

隐私补丁 — FAFClient 的启动 ping 现在默认关闭（需设置 FAF_TELEMETRY=1 才会启用）。

FAFClient（Python SDK 客户端，MCP 服务从未使用过它）默认会发送启动 ping、包名和版本号，而且文档未说明如何选择退出。现在只有设置 FAF_TELEMETRY=1 时才会发送；FAF_TELEMETRY_OFF 仍可将其关闭。请参阅 faf.one/privacy。

v2.8.1 是一个依赖补丁 — faf-python-sdk 的最低版本要求为 >=1.4.0，其中互操作函数现已命名为 author_agents_md / author_gemini_md。生成的 AGENTS.md / GEMINI.md 输出在字节层面完全相同。

v2.8.0 — faf_auto 现在会依据仓库自身的文件进行检测，而每个 faf_model 参考模板的 Trophy 评分都达到 100%。

过去，faf_auto 只会读取根目录清单（pyproject.toml、package.json 等）。现在，它还会读取承载真实技术栈的文件：docker-compose 服务镜像会映射到 database / cache / search / storage（正在运行的 Postgres 服务就是数据库，优先于依赖项推测）；Makefile / justfile 目标会映射到 commands 区块（test / build / check-all，可以是根目录文件，也可以是嵌套的 backend/Makefile）；而 .github/workflows/ 会设置 cicd。以前报告为 library / JavaScript 的多语言仓库，现在会报告真实的 Postgres + Redis + FastAPI 技术栈。与 faf-cli 7.10 保持一致。

另外：15 个 faf_model 参考模板的评分只有 48–57%，因为它们只填了 4 个技术栈槽位，并使用了 null。现已全部重写为完整的 21 槽位架构，每个模板的 Trophy 评分现在都达到 100%，并有测试确保这一点。13 个工具 · 265 项测试。

v2.7.1 / v2.7.0 — 互操作版 — faf_agents / faf_gemini 已重写为 faf-python-sdk 创作工具包装器（原先只是包含 4 个字段的存根）；新增 faf_migrate，可将 .faf 更新到当前格式。v2.6.0 — Agent Card 版新增了真正的 agent.fafa 护照、MCP Server Card（SEP-2127）和 AI Catalog 条目。v2.5.0 — Dart 版可从 pubspec.yaml 检测 Dart/Flutter。v2.4.2 — 限定版限制了每个调用方传入的 path 参数。v2.4.0 — 变色龙版会自动选择传输方式：本地使用 stdio，Cloud Run 使用 Streamable HTTP。

---

一分钟设置

1. 安装

uvx gemini-faf-mcp          # zero-install run via uvx (fetched from PyPI)
# or: pip3 install gemini-faf-mcp

2. 添加到 Gemini CLI

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

3. 编写项目上下文

在 Gemini CLI 中：

> /faf:setup

这会写入一个初始 project.faf 并为其评分。然后让 Gemini 根据你的仓库补全它（Gemini 会调用 faf_auto），再运行 /faf:score 查看剩余内容。从此以后，该项目中的每个 Gemini 会话都会自动读取它。

提示： Trophy ✪ = 100%：AI 已针对编码进行优化。/faf:score 会准确显示哪些槽位仍为空。

---

“单文件”优势

.faf 文件是一种结构化 YAML，用于记录项目的 DNA。每个 AI Agent 只需读取一次，就能准确了解你正在构建什么。

# project.faf — your project, machine-readable
faf_version: "3.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

结果： Gemini 只需读取一次，就能了解你的项目。无需 20 分钟的入门介绍，不会产生错误假设。每个会话从一开始就目标一致。

FAF 定义。MD 指导。AI 编码。

那我的 GEMINI.md 呢？

你无需替换它。.faf 会生成它。运行 faf_gemini，即可获得一个全新的 GEMINI.md，采用 Gemini CLI 自有的分层、可通过 @file 导入的约定，包含设置、验证、关键文件、技术栈和先确认再执行的操作；它由单一事实来源生成，无需手动维护。faf 管理区块之外的手写内容会保留。

> /faf:export
# Authors GEMINI.md from project.faf

.faf 是源文件。GEMINI.md 是它的一种输出。AGENTS.md（OpenAI Codex）、.cursorrules、CLAUDE.md 等也同理——编写一次，随处生成。

---

自动检测技术栈

faf_auto 会扫描项目的清单文件、Docker Compose 服务、Makefile 目标和 CI 配置，然后生成槽位值准确的 .faf 文件。无需手动填写。

> Auto-detect my project stack

{
  "detected": {
    "main_language": "Python",
    "package_manager": "uv",
    "framework": "FastAPI",
    "api_type": "REST",
    "database": "PostgreSQL",
    "cache": "Redis",
    "hosting": "Docker Compose",
    "cicd": "GitHub Actions",
    "commands": { "test": "make test", "build": "make build", "lint": "make check-all" }
  },
  "score": 79,
  "tier": "GREEN"
}

database 和 cache 来自 docker-compose.yml，commands 来自 Makefile，cicd 来自 .github/workflows/——这些都不会被清单扫描发现。补全六个 W，即可达到 Trophy。

扫描内容：

文件	检测内容
pyproject.toml	Python + 构建系统 + 框架（FastAPI、Django、Flask、FastMCP）
package.json	JavaScript/TypeScript + 框架（React、Vue、Next.js、Express）
Cargo.toml	Rust + cargo + 框架（Axum、Actix）
go.mod	Go + Go 模块 + 框架（Gin、Echo）
requirements.txt / Gemfile / composer.json	Python（备用）/ Ruby / PHP
docker-compose.yml	根据服务镜像检测 database / cache / search / storage（Postgres、Redis、Elasticsearch、MinIO、ClickHouse、Qdrant 等）
Makefile / justfile	根据目标检测 test / build / lint 命令（根目录或嵌套的 backend/ 目录）
.github/workflows/	cicd: GitHub Actions（也包括 GitLab CI、CircleCI）

优先级规则： pyproject.toml / Cargo.toml / go.mod 的优先级高于 package.json。文件事实（实际的 Compose 服务、Makefile 目标）优先于依赖项推测。只设置实际检测到的值，不使用硬编码默认值。

---

Google Antigravity

Antigravity 只读取一个 MCP 配置文件 ~/.gemini/config/mcp_config.json，并支持两种模式。

本地（stdio）：

{ "mcpServers": { "gemini-faf": { "command": "uvx", "args": ["gemini-faf-mcp"] } } }

托管：

{ "mcpServers": { "gemini-faf": { "serverUrl": "https://mcpaas.live/gemini/mcp/v1" } } }

Antigravity 需要 serverUrl，而不是 url 或 httpUrl。

全部 13 个工具

每个工具都带有 MCP 工具注释：只读（faf_read、faf_validate、faf_score、faf_discover、faf_stringify、faf_context、faf_about、faf_model）、写入时不会丢失任何内容（faf_init、faf_auto、faf_gemini、faf_agents）、重写文件（faf_migrate）。

创建与检测

工具	功能
faf_init	创建入门用 .faf 文件，包含项目名称、目标和语言
faf_auto	根据清单文件自动检测技术栈，并生成或更新 .faf
faf_discover	在项目目录树中查找 .faf 文件

验证与评分

工具	功能
faf_validate	完整的 Mk4 验证——分数、等级、槽位计数、错误和警告
faf_score	快速 Mk4 评分——分数、等级、已填充/活跃/总槽位数

读取与转换

工具	功能
faf_read	将 .faf 文件解析为结构化数据
faf_stringify	将解析后的 FAF 数据转换回简洁的 YAML
faf_context	获取针对 Gemini 优化的上下文（项目 + 技术栈 + 分数）

导出与互操作

工具	功能
faf_gemini	按照 Gemini CLI 的层级惯例导出 GEMINI.md（非破坏性）
faf_agents	导出符合 BETTER 结构的 AGENTS.md，供 OpenAI Codex、Cursor 和其他 AI 工具使用（非破坏性）

迁移

工具	功能
faf_migrate	将 .faf 更新至当前格式版本（3.0）；使用 dry_run 预览

参考

工具	功能
faf_about	FAF 格式信息——IANA 注册、版本和生态系统
faf_model	获取适用于 15 种项目类型中任意一种、Trophy 评分达 100% 的 .faf 示例

---

评分与等级系统

你的 .faf 文件根据完整度评分——即填写了多少个槽位的真实值。

评分	等级	含义
100%	TROPHY	AI 已全面了解你的项目
99%	GOLD	卓越
95%	SILVER	顶级
85%	BRONZE	最低推荐标准——AI 已能从这里开始构建
70%	GREEN	基础扎实
55%	YELLOW	需要改进
<55%	RED	存在重大缺漏——AI 只能猜测
0%	WHITE	空白

目标是达到 Bronze（85% 及以上）。 达到这个标准后，AI 就不会再猜测，而是能真正了解你的项目。

---

与 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
> Migrate my project.faf to the current format

---

架构

gemini-faf-mcp v3.1.1
├── server.py              → FastMCP MCP server (13 tools, dual-transport, Mk4 scoring)
├── safe_path.py           → path confinement for caller-supplied `path` args
├── inject.py              → non-destructive faf-managed-block injection
├── interrogate.py         → Full-Facts grounding (docker-compose + Makefile signals)
├── main.py                → Cloud Run REST API (GET/POST/PUT)
├── models.py              → 15 project type examples
└── src/gemini_faf_mcp/    → Python SDK (FAFClient, parser)

MCP 服务将解析、验证、Mk4 评分以及 AGENTS.md / GEMINI.md 编写工作委托给 faf-python-sdk。faf_auto 中的技术栈检测（包括 Full-Facts grounding）原生基于 Python，无需外部 CLI 依赖。

---

测试

pip3 install -e ".[dev]"
python -m pytest tests/ -v

FastMCP 服务、CLI 标志、Cloud Function、Mk4 WJTTC 冠军赛、Full-Facts grounding、路径限制、写入保护、模型一致性、Dart 检测和客户端遥测测试套件共 281 项测试全部通过。冠军级测试覆盖率——WJTTC 认证。

---

FAF 生态系统

一种格式，适用于所有 AI 平台。

软件包	平台	注册表
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	通用	npm

---

Python SDK

无需 MCP，直接在 Python 中使用 FAF：

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()

除非设置 FAF_TELEMETRY=1，否则 FAFClient 不会发送任何遥测数据；设置后会发送一次启动 ping（软件包名称和版本）。FAF_TELEMETRY_OFF 始终会关闭遥测。远程模式会将请求发送到 Cloud Run 端点。隐私政策：faf.one/privacy。

---

Cloud Run REST API

用于徽章、多 Agent 上下文中转和语音转 FAF 修改的在线端点。

https://faf-source-of-truth-631316210911.us-east1.run.app

通过 X-FAF-Agent 标头支持面向 Agent 优化的响应（Gemini、Claude、Grok、Jules、Codex/Copilot/Cursor）。通过 PUT 端点使用 Gemini Live 进行语音修改。推送到 main 后通过 Cloud Build 自动部署。

---

如果 gemini-faf-mcp 对你有帮助，请考虑为此仓库点星标——这能帮助其他人找到它。

---

链接

• FAF 规范
• IANA 注册
• faf-python-sdk
• faf-cli
• 更新日志

引用

如果你在研究或生产环境中使用 gemini-faf-mcp 或 .faf / .fafm / .fafa 格式，请引用以下格式论文：

Wolfe, J. (2025). Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding. Zenodo. https://doi.org/10.5281/zenodo.18251362

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

Wolfe, J. (2026). Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era. Zenodo. https://doi.org/10.5281/zenodo.21951641

BibTeX

@article{wolfe2025faf,
  title     = {Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding},
  author    = {Wolfe, James},
  year      = {2025},
  month     = {nov},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.18251362},
  url       = {https://doi.org/10.5281/zenodo.18251362}
}

@article{wolfe2026fafm,
  title     = {Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory},
  author    = {Wolfe, James},
  year      = {2026},
  month     = {may},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.20348942},
  url       = {https://doi.org/10.5281/zenodo.20348942}
}

@article{wolfe2026fafa,
  title     = {Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era},
  author    = {Wolfe, James},
  year      = {2026},
  month     = {aug},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.21951641},
  url       = {https://doi.org/10.5281/zenodo.21951641}
}

许可证

MIT

---

由 @wolfe_jam 构建 | wolfejam.dev

---

获取 CLI

faf-cli — 原版 AI-Context CLI。每位构建者的必备工具。

npx faf-cli auto

Anthropic MCP #2759 · IANA 已注册： application/vnd.faf+yaml · faf.one · npm