Skip to main content
Glama
deenesjakoruzh
Wolfe-Jam

gemini-faf-mcp

by Wolfe-Jam
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

gemini-faf-mcp

Google Gemini 的持久化项目上下文。定义一次。随处同步。

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

无需再向每个新的 Gemini 会话重新解释您的项目。每个 Gemini 对话都是从零开始的——您每次都要重新陈述您的技术栈、目标和约定。.faf 是一个捕获所有这些信息的结构化文件。此包是让 Gemini 读取该文件的 MCP 服务器。

PyPI Downloads Tests IANA

前后对比

Without FAF                           With FAF (.faf at 85%+ Bronze)
─────────────────────────             ─────────────────────────
You: "I'm using FastAPI with...       You: "Add a /users/me endpoint"
      PostgreSQL, pytest, and..."     Gemini: [generates 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。

v2.2.0 的新功能

Mk4 冠军评分引擎 — 所有 12 个工具现在都使用与 Rust 编译器和 TypeScript CLI 相同的评分算法。faf_score 和 faf_validate 返回槽位级别的详细信息（populated、active、total）。分数在每种语言的每个 FAF 工具中保持一致。221 个测试，41 个新的 WJTTC 冠军测试。移除了死代码 (sync_faf.py)。

v2.2.1 是一个补丁版本 — 包描述与 PyPI、Gemini 扩展库和 MCP 注册表中的规范用语“Google Gemini 的持久化项目上下文”保持一致。无代码更改。

一分钟设置

1. 安装

pip install gemini-faf-mcp

2. 添加到 Gemini CLI

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

3. 生成您的项目上下文

在您的 Gemini CLI 中：

> /gemini-faf-mcp:setup

您应该会看到：Created project.faf — Score: 85% (BRONZE)。从现在起，该项目中的每个 Gemini 会话都会自动读取它。

提示： 85% (BRONZE) 的分数是 Gemini 停止猜测的最低要求。运行 /gemini-faf-mcp:score 查看缺少的内容以及如何达到 100% (TROPHY)。

Related MCP server: rust-faf-mcp RMCP

“单文件”优势

.faf 文件是捕获您项目 DNA 的结构化 YAML。每个 AI 代理读取一次即可确切知道您正在构建什么。

# 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

结果： Gemini 读取一次即可了解您的项目。无需 20 分钟的入职培训。没有错误的假设。每个会话开始时都保持一致。

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

我的 GEMINI.md 怎么办？

您不需要替换它。.faf 生成 它。运行 faf_gemini，您将获得一个全新的 GEMINI.md，其中包含作为 YAML frontmatter 嵌入的结构化项目数据——这与 Gemini CLI 已经读取的 GEMINI.md 相同，但它是从单一事实来源生成的，而不是手动维护的。

> /gemini-faf-mcp:export
# Generates GEMINI.md from project.faf

.faf 是源。GEMINI.md 是其输出之一。AGENTS.md (OpenAI Codex)、.cursorrules、CLAUDE.md 等也是同样的逻辑——一次编写，随处渲染。

自动检测您的技术栈

faf_auto 会扫描您项目的清单文件并生成一个具有准确槽位值的 .faf。无需手动输入。

> 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"
}

扫描内容：

文件

检测内容

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

Python (回退)

Gemfile

Ruby

composer.json

PHP

优先级规则： pyproject.toml / Cargo.toml / go.mod 的优先级高于 package.json。仅设置实际检测到的值 — 没有硬编码的默认值。

全部 12 个工具

创建与检测

工具

功能

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 的 YAML frontmatter 的 GEMINI.md

faf_agents

为 OpenAI Codex、Cursor 和其他 AI 工具导出 AGENTS.md

参考

工具

功能

faf_about

FAF 格式信息 — IANA 注册、版本、生态系统

faf_model

获取 15 种项目类型中任何一种的 100% Trophy 评分示例 .faf

评分与等级系统

您的 .faf 文件根据完整性进行评分 — 即有多少槽位填充了真实值。

分数

等级

含义

100%

TROPHY

AI 拥有您项目的完整上下文

99%

GOLD

卓越

95%

SILVER

顶级

85%

BRONZE

建议最低标准 — AI 可以从这里开始构建

70%

GREEN

坚实的基础

55%

YELLOW

需要改进

<55%

RED

重大差距 — AI 将会猜测

0%

WHITE

空

目标是青铜级 (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

架构

gemini-faf-mcp v2.2.1
├── 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)

MCP 服务器委托给 faf-python-sdk 进行解析、验证和 Mk4 评分。faf_auto 中的技术栈检测是 Python 原生的 — 没有外部 CLI 依赖。

测试

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

221 个测试在 9 个 WJTTC 等级中通过 (125 个 MCP 服务器 + 55 个云函数 + 41 个 Mk4 WJTTC 冠军测试)。冠军级测试覆盖率 — 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

在 Python 中直接使用 FAF，无需 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

用于徽章、多代理上下文代理和语音转 FAF 变更的实时端点。

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

通过 X-FAF-Agent 标头支持代理优化的响应 (Gemini, Claude, Grok, Jules, Codex/Copilot/Cursor)。通过 PUT 端点支持 Gemini Live 的语音变更。在推送到 main 时通过 Cloud Build 自动部署。

如果 gemini-faf-mcp 对您有用，请考虑给仓库加星 — 这有助于其他人找到它。

链接

许可证

MIT

由 @wolfe_jam 构建 | wolfejam.dev

获取 CLI

faf-cli — 最初的 AI 上下文 CLI。每个构建者的必备工具。

npx faf-cli auto

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd
A
license - permissive license
A
quality
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
2wRelease cycle
17Releases (12mo)
Commit activity

Resources

Tools

View all tools

Related MCP Servers

  • rust-faf-mcp RMCP

    Wolfe-Jam
    A
    license
    Not graded
    quality
    A
    maintenance
    Persistent project context in Rust. 8 MCP tools via rmcp SDK — parse, validate, score, compress, discover, and token analysis. Single binary, zero config. IANA-registered format (application/vnd.faf+yaml). One file, every AI platform.
    733
    4
    MIT

  • faf-mcp

    Wolfe-Jam
    A
    license
    A
    quality
    A
    maintenance
    Persistent project context MCP server that syncs a single .faf file to all AI tool formats (Cursor, Windsurf, Cline, etc.), enabling eternal bi-sync and optimized context for AI assistants.
    15
    239
    6
    MIT

  • codex-agent-mem

    MarceloCaporale
    A
    license
    B
    quality
    C
    maintenance
    Portable, auditable, local-first MCP memory for MCP-compatible AI agents and coding workflows. It keeps durable project memory outside the model runtime, compresses continuity into smaller working packs, and carries forward operational state so agents can resume with less repetition.
    28
    34
    Apache 2.0

View all related MCP servers

Related MCP Connectors

View all MCP Connectors

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