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-cli 8.2 の card init で作成した、更新版の FAF パスポート（agent.fafa）と MCP Server Card を用意しました。どちらもバージョンは 3.1.0 で、13 個すべてのツールと FAF のコンテキストが記載されています。
• Google Antigravity に対応しました。 ローカル（uvx）とホスト型（serverUrl）のどちらでも利用できます。下記のGoogle Antigravityをご覧ください。
• 新しいデザイン： Google の開発者になじむようにデザインを一新したgemini-faf-mcp のページをご覧ください。
• ホスト型関数は常に 33 点を算出します。 他のすべてと同じエンジンを使用します。

以前のバージョン：v3.0.0 — Always33 エディション — エンジンもスコアも 1 つだけ。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 スロットの完全なスキーマに書き換え、現在はすべて 100% Trophy になりました。この状態を維持するテストも追加されています。ツール 13 個 · テスト 265 件。

v2.7.1 / v2.7.0 — 相互運用エディション — faf_agents / faf_gemini を faf-python-sdk の作成ツールを呼び出すラッパーとして書き換えました（以前は 4 フィールドのスタブでした）。新しい faf_migrate を使うと、.faf を最新のフォーマットに更新できます。v2.6.0 — エージェントカードエディションでは、本物の 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 分でセットアップ

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 にリポジトリから内容を補完するよう依頼し（faf_auto が呼び出されます）、/faf:score を実行して残りの項目を確認します。以降、このプロジェクトのすべての Gemini セッションで自動的に読み込まれます。

ヒント： Trophy ✪ = 100%：AI がコーディングに最適化されています。/faf:score で、まだ空のスロットが正確にわかります。

---

「1 ファイル」の利点

.faf ファイルは、プロジェクトの DNA を記録する構造化 YAML です。すべての AI エージェントが一度読み込めば、何を構築しているかを正確に把握できます。

# 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 が GEMINI.md を作成します。faf_gemini を実行すると、Gemini CLI 独自の階層構造と @file インポート可能な規約に沿った新しい GEMINI.md が生成されます。セットアップ、検証、重要なファイル、スタック、事前確認が必要な操作が、手作業で管理するのではなく、単一の信頼できる情報源から作成されます。faf 管理ブロックの外側にある手書きの内容は保持されます。

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

.faf がソースで、GEMINI.md はその出力の 1 つです。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/ から取得されます。これらはマニフェストのスキャンでは検出できません。6 つの 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 は、~/.gemini/config/mcp_config.json という 1 つの MCP 設定ファイルを読み取り、どちらのモードにも対応します。

ローカル（stdio）：

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

ホスト型：

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

Antigravity が想定しているのは url や httpUrl ではなく、serverUrl です。

全 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	OpenAI Codex、Cursor、その他の AI ツール向けに、BETTER 形式の AGENTS.md をエクスポートします（非破壊）

移行

ツール	機能
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 に委任します。Full-Facts グラウンディングを含む faf_auto のスタック検出は Python ネイティブであり、外部 CLI への依存はありません。

---

テスト

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

FastMCP サーバー、CLI フラグ、Cloud Function、Mk4 WJTTC チャンピオンシップ、Full-Facts グラウンディング、パスの閉じ込め、書き込みガード、モデル間パリティ、Dart 検出、クライアントテレメトリの各スイートで、281 件のテストが成功しています。チャンピオンシップ級のテストカバレッジです。WJTTC 認定済み。

---

FAF エコシステム

1 つのフォーマットで、あらゆる 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()

FAFClient は、FAF_TELEMETRY=1 を設定しない限りテレメトリを送信しません。設定すると、起動時に 1 回だけ ping（パッケージ名とバージョン）が送信されます。FAF_TELEMETRY_OFF を設定すると、常に無効になります。リモートモードでは、リクエストが Cloud Run エンドポイントに送信されます。プライバシーについては、faf.one/privacy をご覧ください。

---

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 経由で自動デプロイされます。

---

gemini-faf-mcp が役に立った場合は、リポジトリにスターを付けてください。ほかのユーザーが見つけやすくなります。

---

リンク

• FAF 仕様
• IANA 登録
• faf-python-sdk
• faf-cli
• 変更履歴

引用

研究または本番環境で gemini-faf-mcp や .faf / .fafm / .fafa 形式を使用する場合は、以下のフォーマット論文を引用してください。

Wolfe, J. (2025). フォーマット駆動型 AI コンテキストアーキテクチャ：永続的なプロジェクト理解のための .faf 標準. Zenodo. https://doi.org/10.5281/zenodo.18251362

Wolfe, J. (2026). 永久記憶と即時想起：複数プロファイルの AI エージェントメモリのための .fafm 標準. Zenodo. https://doi.org/10.5281/zenodo.20348942

Wolfe, J. (2026). エージェントにパスポートが必要な理由：.fafa — エージェント時代に対応するポータブルなアイデンティティ. 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 コンテキスト CLI の元祖です。すべてのビルダーに必須です。

npx faf-cli auto

Anthropic MCP #2759 · IANA 登録済み： application/vnd.faf+yaml · faf.one · npm