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