gemini-faf-mcp

Instructions

Implementation Reference

• server.py:270-314 (handler)

  The main faf_agents tool handler function. Exports AGENTS.md content from a .faf file. Takes a path parameter (default 'project.faf'), parses and validates the file, then generates markdown content with project info, context, and stack. Returns a dict with success status, content, or error message.

  @mcp.tool()
  def faf_agents(path: str = "project.faf") -> dict:
      """Export AGENTS.md content from a .faf file.
      Generates a universal agent context file compatible with OpenAI Codex, Cursor, and other AI tools.
      Write the output to AGENTS.md in the project root."""
      try:
          faf = parse_file(path)
          data = faf.data
          result = validate(faf)
  
          md = f"""# AGENTS.md — {data.project.name}
  
  ## Project
  - **Name:** {data.project.name}
  - **Goal:** {data.project.goal or 'Not specified'}
  - **Language:** {data.project.main_language or 'Not specified'}
  - **FAF Score:** {result.score}%
  
  ## Instructions for AI Agents
  - This project uses FAF (Foundational AI-context Format)
  - Read project.faf for complete project DNA
  - Media Type: application/vnd.faf+yaml (IANA registered)
  """
  
          if data.human_context:
              md += f"""
  ## Context
  - **Who:** {data.human_context.who or 'Not specified'}
  - **What:** {data.human_context.what or 'Not specified'}
  - **Why:** {data.human_context.why or 'Not specified'}
  """
  
          if data.stack:
              md += f"""
  ## Stack
  - **Frontend:** {data.stack.frontend or 'N/A'}
  - **Backend:** {data.stack.backend or 'N/A'}
  - **Database:** {data.stack.database or 'N/A'}
  - **Testing:** {data.stack.testing or 'N/A'}
  """
          return {"success": True, "content": md}
      except FileNotFoundError:
          return {"success": False, "error": f"File not found: {path}"}
      except FafParseError as e:
          return {"success": False, "error": str(e)}

• server.py:270-270 (registration)

  Tool registration via @mcp.tool() decorator. This registers the faf_agents function as an MCP tool with FastMCP, making it discoverable and callable by MCP clients.

  @mcp.tool()

• server.py:20-24 (registration)

  FastMCP server instance creation. Creates the 'mcp' object with name 'gemini-faf-mcp', version, and instructions. The @mcp.tool() decorator registers tools with this server instance.

  mcp = FastMCP(
      "gemini-faf-mcp",
      version=__version__,
      instructions="FAF — Universal AI context from IANA-registered .faf files",
  )

• server.py:12-14 (helper)

  Import statements for faf_sdk functions and FafParseError. These external SDK functions (parse_file, validate) are core helpers used by faf_agents to parse and validate .faf files.

  from faf_sdk import parse_file, parse, validate, find_faf_file, stringify
  from faf_sdk.parser import FafParseError
  from models import get_model, list_models