gemini-faf-mcp

Google Gemini를 위한 지속적인 프로젝트 컨텍스트. 한 번 정의하고 어디서나 동기화하세요.

FAF가 정의하고, MD가 지시하며, AI가 코딩합니다.

새로운 Gemini 세션을 시작할 때마다 프로젝트를 다시 설명하는 일을 멈추세요. 모든 Gemini 대화는 초기 상태에서 시작되며, 매번 스택, 목표, 규칙을 다시 말해야 합니다. .faf는 이 모든 것을 담고 있는 하나의 구조화된 파일입니다. 이 패키지는 Gemini가 해당 파일을 읽을 수 있게 해주는 MCP 서버입니다.

이전과 이후

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 Extensions Gallery 및 MCP Registry 전반에서 패키지 설명을 "Google Gemini를 위한 지속적인 프로젝트 컨텍스트"라는 표준 문구로 정렬했습니다. 코드 변경 사항은 없습니다.

1분 설정

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를 실행하면 YAML 프런트매터에 구조화된 프로젝트 데이터가 포함된 새로운 GEMINI.md를 얻게 됩니다. 이는 Gemini CLI가 이미 읽고 있는 것과 동일한 GEMINI.md이지만, 수동으로 유지 관리하는 대신 단일 진실 공급원(Single Source of Truth)에서 생성됩니다.

> /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 / Cargo.toml / go.mod가 package.json보다 우선합니다. 실제로 감지된 값만 설정하며, 하드코딩된 기본값은 없습니다.

12개의 모든 도구

생성 및 감지

검증 및 점수 산정

읽기 및 변환

내보내기 및 상호 운용성

참조

점수 및 등급 시스템

.faf 파일은 완전성, 즉 실제 값으로 채워진 슬롯의 수에 따라 점수가 매겨집니다.

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

아키텍처

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 서버는 파싱, 검증 및 Mk4 점수 산정을 위해 faf-python-sdk에 위임합니다. faf_auto의 스택 감지는 Python 네이티브이며 외부 CLI 종속성이 없습니다.

테스트

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

9개의 WJTTC 등급에 걸쳐 221개의 테스트가 통과되었습니다(125개 MCP 서버 + 55개 Cloud Function + 41개 Mk4 WJTTC 챔피언십). 챔피언십 수준의 테스트 커버리지 — WJTTC 인증.

FAF 생태계

하나의 형식으로 모든 AI 플랫폼 지원.

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

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가 유용했다면 저장소에 별표를 눌러주세요. 다른 사람들이 찾는 데 도움이 됩니다.

링크

• FAF 사양

• IANA 등록

• faf-python-sdk

• faf-cli

• 변경 로그

라이선스

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