gemini-faf-mcp

关键词

FAFAI-contextGeminiYAML工具导出

使用说明内容（Markdown格式）

  • 项目简介

    • gemini-faf-mcp 是一个基于 FastMCP 的 MCP 服务器实现，专注于 FAF（Foundational AI-context Format）上下文的管理与交互。通过 12 个工具向 LLM 客户端提供对资源、工具、提示模板等的标准化访问，支持多种交互场景（读取、验证、推理所需的上下文、导出文档等），并以 MCP 协议与客户端通信。

  • 主要功能点

    • 12 个 MCP 工具（faf_read、faf_validate、faf_score、faf_discover、faf_init、faf_stringify、faf_context、faf_gemini、faf_agents、faf_about、faf_model、faf_auto）覆盖 FAF 的创建、解析、验证、打分、上下文提取、导出、以及自动化栈检测等能力。
    • 本地和远程两种工作模式：可以从本地解析 .faf 文件，也可以通过 Cloud Run 风格端点对远端服务器进行交互。
    • FAF 解析与验证：集成 faf-python-sdk，支持解析、验证、打分、生成上下文等。
    • 基于 IANA 注册的 FAF 媒体类型支持：application/vnd.faf+yaml。
    • 自动化栈检测与 FAF 生成：faf_auto 根据 manifest 文件自动推断语言、框架、数据库等，并生成或更新 .faf 文件。
    • 多工具协同：faf_gemini 与 faf_agents 导出 Gemini/Giants 等格式的上下文描述文档，便于不同 AI 客户端使用。
    • 安全与审计：内置分级比分与层级（Trophy、Gold、Silver 等），并提供 FAF About、模型示例等元数据，帮助客户端理解生态。
    • 服务器端职责包括会话管理、能力声明、以及对不同客户端（Gemini、Claude、Grok、Jules、Codex 等）提供定制化的上下文载荷转换。
    • 提供了与 GitHub 的 Voice-to-FAF 功能的伪实现与管控逻辑（PUT 请求的更新、权限、日志、干跑等）。

  • 安装步骤

    • 直接获取并安装（推荐）：
      • 使用 PyPI 安装 gemini-faf-mcp（包含 MCP 服务器与 Python SDK 集成）。
      • 或从源码运行 server.py 启动一个本地 MCP 服务器实例。
    • 运行本地服务器示例（直接执行入口即可启动 MCP 服务）：
      • 运行方式1（直接运行入口脚本）: python3 server.py
      • 运行方式2（模块模式，依赖环境可能不同）: python3 -m server
    • 依赖说明
      • 需要 Python 版本支持、fastmcp、faf-python-sdk、yaml 等依赖。

  • 服务器配置（MCP 客户端需要的最小配置信息，JSON 格式） 说明：以下配置用于 MCP 客户端了解如何连接和启动该 MCP 服务器。名称字段对应仓库中的服务器标识，命令与参数指明如何启动服务器进程以及入口点。 配置示例 (JSON)： { "mcpServers": { "faf": { "serverName": "gemini-faf-mcp", "command": "python3", "args": ["server.py"] } } } 注释说明：

    • mcpServers.faf.serverName 指定 MCP 服务器的名称，与仓库中的服务器标识保持一致，便于管理与发现。
    • command 指定启动服务器的可执行程序，这里使用 Python 3 解释器。
    • args 指定启动参数，server.py 是 MCP 服务器入口脚本，执行该脚本即可启动 MCP 服务并注册 12 个工具。
    • 客户端在建立连接时需要使用以上配置中的 serverName、command、args 信息来启动并联系该 MCP 服务器。

  • 基本使用方法

    • 使用 FAF 文件进行本地上下文获取、解析与导出
    • 通过 MCP 客户端访问 12 种工具来完成 FAF 文件的读取、验证、打分、导出等工作
    • 支持不同 AI 客户端对上下文的定制化加载（Gemini、Claude、Grok、Jules、Codex/Copilot 等）

  • 运行与维护要点

    • 确保 FAF 文件与依赖库正确安装，服务器能够正确访问 faf-python-sdk。
    • 使用 faf_auto 自动检测栈时，优先级规则与实际 manifest 文件匹配，确保输出的 .faf 文件符合检测结果。
    • 注意工具输出的结构与字段在不同客户端的兼容性（faf_gemini/faf_agents 等导出的文档格式应符合预期）。

服务器信息

访问项目