Gemini Faf MCP

🚀 gemini-faf-mcp

借助人工智能理解您的项目，一切尽在一个文件中。这是适用于Gemini CLI的12个MCP工具。

这是为 FAF 打造的MCP服务器，FAF是一种由IANA注册的AI项目上下文格式（application/vnd.faf+yaml）。只需一个 .faf 文件，就能让Gemini全面了解项目，包括技术栈、目标、规范和质量标准，无需反复解释，也不会出现上下文偏差。

本项目基于 FastMCP 构建，并由 faf-python-sdk 提供支持。

🚀 快速开始

推荐使用Gemini CLI

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

然后在任意项目目录下，您可以执行以下操作：

> 自动检测我的项目并创建一个 .faf 文件
> 这个项目的FAF分数是多少？
> 为这个项目导出一个 GEMINI.md 文件

通过PyPI安装

pip install gemini-faf-mcp

手动配置MCP

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

✨ 主要特性

FAF的作用

每次新会话开始时，人工智能都要从零开始。它需要猜测您的技术栈，可能会忽略一些规范，还会反复询问相同的问题。而FAF可以解决这些问题。

一个 .faf 文件是结构化的YAML文件，它记录了您项目的核心信息，包括编程语言、框架、数据库、目标、质量标准和团队背景等。任何人工智能都可以立即读取该文件，而无需进行猜测。

# project.faf — 您的项目，机器可读
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_auto 可以扫描项目的清单文件，并生成一个包含准确信息的 .faf 文件，无需手动输入。

> 自动检测我的项目技术栈

{
  "detected": {
    "main_language": "Python",
    "package_manager": "pip",
    "build_tool": "setuptools",
    "framework": "FastMCP",
    "api_type": "MCP",
    "database": "BigQuery"
  },
  "score": 100,
  "tier": "Trophy"
}

扫描内容：

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

全部12个工具

创建与检测

验证与评分

读取与转换

导出与互操作

参考

评分和等级系统

您的 .faf 文件会根据完整性进行评分，即有多少字段填充了实际值。

目标是达到Bronze（85% 以上）。达到这个水平后，人工智能就不再需要猜测，而是真正了解您的项目。

与Gemini CLI配合使用

> 为我的Python FastAPI项目创建一个 .faf 文件
> 自动检测我的项目并填充技术栈
> 对我的 .faf 文件进行评分并显示缺失的内容
> 为这个项目导出 GEMINI.md 文件
> 给我展示一个MCP服务器的100%示例
> 什么是FAF以及它是如何工作的？
> 读取我的 project.faf 文件并总结技术栈
> 验证我的 .faf 文件并修复警告

🔧 技术细节

架构

gemini-faf-mcp v2.1.0
├── server.py              → FastMCP MCP服务器（12个工具）
├── main.py                → Cloud Run REST API（GET/POST/PUT）
├── models.py              → 15种项目类型的示例
└── src/gemini_faf_mcp/    → Python SDK（FAFClient、解析器）

MCP服务器委托 faf-python-sdk 进行解析、验证和发现。faf_auto 中的技术栈检测是Python原生的，无需外部CLI依赖。

测试

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

在9个WJTTC等级中，有183个测试通过（126个MCP服务器测试 + 57个云函数测试）。测试覆盖率达到锦标赛级别，并通过了 WJTTC认证。

FAF生态系统

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

Python SDK

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

from gemini_faf_mcp import FAFClient, parse_faf, validate_faf, find_faf_file

# 本地解析和验证
data = parse_faf("project.faf")
result = validate_faf(data)
print(f"Score: {result['score']}%, Tier: {result['tier']}")

# 自动查找 .faf 文件
faf_path = find_faf_file(".")

# 或者使用Cloud Run端点
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）。通过Gemini Live的PUT端点支持语音转换。在推送到 main 分支时，会通过Cloud Build自动部署。

📚 详细文档

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

📄 许可证

本项目采用MIT许可证。

由 @wolfe_jam 开发 | wolfejam.dev