FAF

# claude-faf-mcp


`claude-faf-mcp` is the FAF MCP server for Claude-compatible clients, providing **33 tools** to create, validate, score, and synchronize `.faf` Project DNA context files.

## What this server does

Persistent project context for AI, powered by FAF and package.json-aware project context.

FAF (Foundational AI-Context Format) is a portable YAML context format for preserving project intent across sessions, assistants, and IDE agents.
`claude-faf-mcp` exposes FAF workflows through MCP tools so agents can operate on persistent project context in a structured, repeatable way.

## Key capabilities

- Generate and manage `.faf` project context files
- Validate context quality and completeness
- Score context to identify confidence gaps and improvement opportunities
- Keep context synchronized as project intent evolves
- Return structured outputs suitable for multi-step agent workflows

## Core tools

- `faf_init` — Initialize project DNA
- `faf_auto` — Auto-detect stack and populate context
- `faf_git` — Extract context from any GitHub repo URL
- `faf_score` — AI-readiness score (0-100%) with breakdown
- `faf_sync` — Sync `.faf` → `CLAUDE.md`
- `faf_go` — Guided interview to Gold Code
- `faf_agents` — Import/export `AGENTS.md` (OpenAI Codex)
- `faf_cursor` — Import/export `.cursorrules` (Cursor IDE)
- `faf_gemini` — Import/export `GEMINI.md` (Google Gemini)
- `faf_conductor` — Import/export Conductor directory
- `faf_formats` — Discover all formats in your project

## Why teams use it

- Reduces context drift between AI sessions
- Moves repetitive context operations from prompts into deterministic tools
- Gives Claude/IDE agent workflows a shared, portable context layer

## Quick start

### Install

```bash
npm install -g claude-faf-mcp
```

### Install options (npm vs Homebrew)

- **`claude-faf-mcp` server:** install via **npm**
- **`faf-cli` utility:** available via **npm** and Homebrew (see FAF CLI docs/tap)

### MCP config example

```json
{
"mcpServers": {
"claude-faf-mcp": {
"command": "npx",
"args": ["-y", "claude-faf-mcp"]
}
}
}
```

## Smithery settings: Description field

If you are editing `https://smithery.ai/servers/wolfe-jam/claude-faf-mcp/settings`, paste the block below into the **Description** field:

```md
claude-faf-mcp is the FAF MCP server for Claude-compatible clients.

It provides 33 tools to initialize, validate, score, and synchronize `.faf` Project DNA files so AI agents can keep project context accurate across sessions and IDE workflows.

Core tools include `faf_init`, `faf_auto`, `faf_git`, `faf_score`, and `faf_sync`, plus import/export support for `AGENTS.md`, `.cursorrules`, and `GEMINI.md`.
```

## Example prompts

- "Analyze this repo and generate a starter `.faf` context file."
- "Validate my `.faf` file and list missing or weak sections."
- "Score this `.faf` and recommend the top 5 improvements."
- "Sync project context so `.faf` reflects current code and intent."

## Useful one-liners

```bash
npx faf-cli@latest git https://github.com/facebook/react
npx faf-cli@latest git https://github.com/your-repo
```

## Smithery publish checklist (important)

Use these if your Smithery release scan fails or times out:

1. Keep `-n` on the same command line (do **not** split onto a new line).
2. Publish an endpoint that is reachable from the public internet.
3. Provide `configSchema` if your server requires keys/config.
4. Add `/.well-known/mcp/server-card.json` to let Smithery skip fragile auto-scan steps.

### Example publish commands

```bash
smithery mcp publish https://claude-faf-mcp.vercel.app/sse -n Wolfe-Jam/claude-faf-mcp
smithery mcp publish https://mcpaas.live/sse -n Wolfe-Jam/faf-mcp
```

## Compatibility

- Claude Desktop and other MCP-compatible clients
- Common IDE-agent workflows (including VS Code/Cursor setups)

## Safety / scope

- Designed for project context operations
- Effective permissions and access scope are controlled by your MCP client configuration
- Review write-capable actions before applying changes to local files

## Auto-CLI listing (Smithery)

- Smithery server listing: https://smithery.ai/servers/wolfe-jam/claude-faf-mcp
- Use this listing for auto-CLI discovery/install workflows

## Links

- GitHub: https://github.com/Wolfe-Jam/claude-faf-mcp
- npm: https://www.npmjs.com/package/claude-faf-mcp
- Smithery (auto-CLI): https://smithery.ai/servers/wolfe-jam/claude-faf-mcp
- FAF overview: https://faf.one
- MIME type reference: `application/vnd.faf+yaml`

---

## Short version (optional)

`claude-faf-mcp` is the FAF MCP server for Claude-compatible clients, with 33 tools for creating, validating, scoring, and syncing `.faf` Project DNA files.

Install: `npm install -g claude-faf-mcp`

It helps reduce AI context drift by making project context operations structured and repeatable across sessions and IDE agents.

GitHub: https://github.com/Wolfe-Jam/claude-faf-mcp
npm: https://www.npmjs.com/package/claude-faf-mcp
Smithery (auto-CLI): https://smithery.ai/servers/wolfe-jam/claude-faf-mcp