faf_agents
Export agent documentation from .faf files to create universal context files compatible with OpenAI Codex, Cursor, and other AI development tools.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | project.faf |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
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