gemini-faf-mcp

Постоянный контекст проекта для Google Gemini. Определите один раз. Синхронизируйте везде.

FAF определяет. MD инструктирует. ИИ пишет код.

Хватит заново объяснять свой проект каждой новой сессии Gemini. Каждый диалог с Gemini начинается с чистого листа — вы каждый раз заново описываете свой стек, цели и соглашения. .faf — это один структурированный файл, который фиксирует всё это. Этот пакет представляет собой MCP-сервер, который позволяет Gemini читать его.

До и после

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 и CLI TypeScript. faf_score и faf_validate возвращают детализацию на уровне слотов (populated, active, total). Оценки совпадают во всех инструментах FAF на любом языке. 221 тест, 41 новый тест чемпионата WJTTC. Удален мертвый код (sync_faf.py).

v2.2.1 — это патч-релиз, в котором описание пакета приведено в соответствие с канонической формулировкой «Постоянный контекст проекта для Google Gemini» на PyPI, в галерее расширений Gemini и реестре MCP. Изменений в коде нет.

Настройка за одну минуту

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 — это структурированный YAML, который фиксирует ДНК вашего проекта. Каждый ИИ-агент считывает его один раз и точно знает, что вы создаете.

# 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 инструктирует. ИИ пишет код.

А как насчет моего GEMINI.md?

Вы не заменяете его. .faf генерирует его. Запустите faf_gemini, и вы получите свежий GEMINI.md со структурированными данными проекта, встроенными в виде YAML frontmatter — тот же GEMINI.md, который уже читает Gemini CLI, но сгенерированный из единого источника истины, а не поддерживаемый вручную.

> /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%+). Именно здесь ИИ перестает гадать и начинает знать.

Использование с 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 Cloud Function + 41 Mk4 WJTTC championship). Тестовое покрытие чемпионского уровня — сертифицировано WJTTC.

Экосистема FAF

Один формат, любая платформа ИИ.

Python SDK

Используйте FAF напрямую в Python без 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

Поддерживает оптимизированные для агентов ответы (Gemini, Claude, Grok, Jules, Codex/Copilot/Cursor) через заголовок X-FAF-Agent. Голосовые мутации через Gemini Live через PUT-запрос. Автоматическое развертывание через Cloud Build при пуше в main.

Если gemini-faf-mcp был полезен, подумайте о том, чтобы поставить звезду репозиторию — это помогает другим найти его.

Ссылки

• Спецификация FAF

• Регистрация IANA

• faf-python-sdk

• faf-cli

• Журнал изменений

Лицензия

MIT

Создано @wolfe_jam | wolfejam.dev

Получить CLI

faf-cli — Оригинальный CLI для ИИ-контекста. Обязателен для каждого разработчика.

npx faf-cli auto

Anthropic MCP #2759 · Зарегистрировано IANA: application/vnd.faf+yaml · faf.one · npm