[5.5.2] - 2026-05-03

Added

• Postinstall star CTA — runs once on npm install -g claude-faf-mcp after the success confirmation. Quiet, no throws, no spam.

Changed

• displayName standardized to .faf 🐘 — pairs the constant elephant family mark with each surface's modifier in MCP client lists (matches grok-faf-mcp's .faf 🐘⚡️ for Grok pattern).
• Package description aligned to "Persistent project context for AI" — the canonical positioning across the FAF family. npm and MCP Registry catalogs both pick this up.
• Branding pass — README scoring table now uses geometric tier symbols (★ ◆ ◇ ● ○ ♡) matching faf-cli/src/core/tiers.ts. 🏆 is the only emoji marker; decorative emojis stripped from CLI surfaces.
• manifest.json description sharpened to "Persistent project context that survives sessions, works across AI tools, and eliminates re-explaining" — strengthens the user-facing pitch in Claude Desktop's Extensions catalog.

Fixed

• vercel.json restored — fixes the "No Output Directory" deploy error that surfaced after a prior cleanup pass. claude-faf-mcp.vercel.app builds cleanly again.
• MCP Registry hygiene — server.json metadata pass for cleaner Registry listing.

Internal

• CI Performance Check job is now non-gating — perf tests report but don't block main CI. Restores red-means-real signal integrity.
• Perf-check fake-fail eliminated — test:performance now overrides testPathIgnorePatterns so Jest actually picks up tests/performance.test.ts. Workflow had been silently exit-1'ing on "No tests found" for months, painting a fake red X on every commit. Real perf gate restored: 10/10 perf tests pass in 14s ("Championship Performance Achieved").
• Removed npm publish from CI workflow (#50). /pubpro is the single source of truth for shipping; CI validates only.
• Removed publish-mcp.yml auto-publisher. Same doctrine: CI validates, pubpro publishes — never both.
• Weekly npm audit auto-fix kept current.

Notes

• Docs + branding + CI hygiene patch — no MCP protocol changes, no breaking changes for tool users. Safe upgrade for all consumers.
• First release after the FAF Foundation alignment sweep (.faf 🐘 family mark, "Persistent project context" tagline, three-reader tree).

381 / 381 tests passing · TTT: PASS · MCP Registry: schema 2025-12-11

FAF defines. MD instructs. AI codes.

Docs-only release

The v5.5.0 Extension Edition shipped .mcpb support, but the README didn't promote it. v5.5.1 fixes that — the one-click install is now the hero.

Changed

• README hero now promotes one-click .mcpb install as the primary path
• manifest.json version bumped to 5.5.1

Unchanged

• 32 MCP tools
• 391/391 tests passing
• Code (identical to v5.5.0)

Install (one-click)

Download claude-faf-mcp-5.5.1.mcpb below → double-click → 32 tools live in Claude Desktop.

FAF defines. MD instructs. AI codes.

The Extension Edition

Desktop Extension (.mcpb) — one-click install for Claude Desktop. No JSON config, no terminal, no path debugging. Drag and click.

What's New

• Desktop Extension (.mcpb) — one-click install, 6.2MB bundle
• destructiveHint annotations on all 32 tools — Anthropic Connectors Directory compliant
• faf_read/faf_write tilde fix — all tools now handle ~/ paths consistently
• examples/test-project/ — sample project for reviewer testing
• pack:mcpb build script — repeatable .mcpb packaging

Security

• Removed behavioral-instruction.ts (unused prompt instruction wrapper)
• Updated PRIVACY.md — discloses GitHub API for faf_git
• npm audit: 0 vulnerabilities

Cleanup

• 27 junk files removed (test debris, Python artifacts, old reports)
• servers/ submodule removed (28MB)
• SECURITY.md updated to v5.x/4.x

Testing

• 118 tests, 0 code failures
• WJTTC v5.5.0: 67/67 Championship Grade
• Adversarial security suite: 25/25 (path traversal, resource exhaustion, prompt injection)
• 391 Jest tests passing

FAF defines. MD instructs. AI codes.

The Relentless Edition

FAF is relentless in its pursuit of 100% persistent project context — one source of truth that every AI and every MD can benefit from.

Added

• /faf MCP Prompt — type /faf in Claude Desktop. Check → Score → Improve → Sync → Lock 🏆
  • Relentlessly seeks 100%. Does not stop until the score is Trophy.
  • Syncs .faf ↔ CLAUDE.md ↔ MEMORY.md on completion.
  • "Claude is now optimized for [project name]. FAF defines. MD instructs. AI codes."
• Prompts capability added to MCP server

Changed

• Removed faf_what — 32 tools, zero redundancy
• tri-sync free for all developers (from v5.3.1)

Numbers

• 391/391 tests passing
• 32 tools + 1 prompt
• 50k+ downloads across npm, PyPI, crates.io

FAF defines. MD instructs. AI codes. 🏎️

v5.2.0 — Enhanced Scoring

Same compiler, same score — whether you're in Claude Desktop or the terminal. We went into the weeds, so you don't have to.

Changed

• FafCompiler scoring engine — faf_score now powered by the same FafCompiler that drives faf-cli
  • Type-aware precision: CLI (9 slots), fullstack (21 slots), web-app, API — each scored correctly
  • Section breakdown with project/stack/human percentages and next milestone
  • Real error diagnostics replace generic messages
• CI hardened: deprecated actions fixed, dependabot replaced by automated audit

Added

• 40-test WJTTC compiler scoring edge case suite across 5 tiers
• Test count: 351 → 391 (12 suites, 2,346 executions per push)
• README rewrite — 3Ws/6Ws onboarding (Uber, Airbnb, Slack, Venmo examples), categorized tools, 🐘 Nelly branding

The Desktop Edition

Tool annotations on all 32 MCP tools. Ready for Claude Desktop Extensions submission.

Added

• Tool annotations on all 32 tools — title, readOnlyHint, destructiveHint, openWorldHint per MCP spec
• PRIVACY.md — privacy policy (local-only processing, no telemetry, no tracking)
• manifest.json — Desktop Extensions manifest (manifest_version 0.3)
• Non-developer section in README — 3-step install for Claude Desktop users
• Privacy section in README linking to PRIVACY.md

Changed

• Tool descriptions: "THE JPEG for AI" → "project DNA for AI"

Why Major Version

Tool annotations change the MCP contract surface. All 32 tools now expose structured metadata that clients use for UI, permissions, and safety classification.

351/351 tests passing.

npm: npx [email protected]

AI Format Interop — Define Once, Generate Everywhere

Added

• 5 new MCP tools for cross-platform AI context
  • faf_agents: Import/export/sync AGENTS.md (OpenAI Codex / Linux Foundation)
  • faf_cursor: Import/export/sync .cursorrules (Cursor IDE)
  • faf_gemini: Import/export/sync GEMINI.md (Google Gemini CLI)
  • faf_conductor: Import/export Conductor directory structure
  • faf_git: Extract .faf context from any public GitHub repo URL
• Bi-sync --all flag — Sync project.faf to all formats at once (CLAUDE.md + AGENTS.md + .cursorrules + GEMINI.md)
• 7 bundled parsers — All parser logic runs standalone, zero CLI dependency
• 95 new tests across 7 WJTTC tiers (351 total)
• Tool count: 56 → 61 (25 core + 36 advanced)

README Upgrade

• 6 Ws Quick Reference table
• Navigation bar, DAAFT economics hook, CLI vs MCP comparison

project.faf → CLAUDE.md    (Anthropic)
            → AGENTS.md    (OpenAI / Linux Foundation)
            → .cursorrules (Cursor IDE)
            → GEMINI.md    (Google Gemini CLI)

One file defines your project. Every AI tool reads it in its own language.

npm: npm install -g claude-faf-mcp

Fixed

• Remove 105% scoring system - Align with official FAF tier system (0-100%)
  • Remove Easter egg logic that awarded 105% for rich .faf + CLAUDE.md
  • Update to Trophy (100%) as perfect score
  • 🍊 Big Orange is now a BADGE awarded separately, not a calculated score
  • Update tests and documentation to reflect correct tier system
  • Fixes alignment with FAF standard where scores range 0-100%

Changed

• Updated faf-cli dependency to v4.4.0

Tests

• ✅ 256/256 passing
• ✅ All tier display logic updated
• ✅ Easter egg removed, Trophy (100%) system implemented

Package Registry:

• npm: https://www.npmjs.com/package/claude-faf-mcp/v/4.1.3
• MCP Registry: https://registry.modelcontextprotocol.io/servers/io.github.Wolfe-Jam~claude-faf-mcp

FAF Ecosystem #2759

🚀 v4.1.0 - Adoption Catalysts Edition

Two major features to make AI-readiness instant and effortless:

✨ New Features

1. faf_human_add - 6Ws Builder Integration

• Complete workflow for faf.one/6ws web form
• Merge YAML from web form directly into project.faf
• Set individual fields (who/what/where/why/when/how)
• Non-interactive bundled command (MK3 engine)
• Instant +25-35% AI-readiness score boost

2. faf_readme - Automatic README Extraction

• Intelligent pattern matching for 6 Ws extraction
• Confidence scoring per field
• Extract-only mode (preview what's found)
• Auto-merge mode (add to project.faf)
• Overwrite mode (replace existing fields)
• Same +25-35% score boost, zero manual work required

📊 Infrastructure

• Tests: 256 passing (+44 new tests for championship coverage)
  • 21 tests for human-context management
  • 23 tests for README extraction
• Code: 1,706 lines of new production code
• Bundled Commands: 3 new commands in MK3 engine
• Dependencies: Updated faf-cli v3.2.6 → v4.3.0

🎯 User Impact

Before: Manual context entry, incomplete information, low scores
After: Instant extraction from README OR guided web form → 🥉 Bronze (85%+)

Two paths to Gold Code:

1. Have a README? Use faf_readme - automatic extraction
2. Start fresh? Use faf.one/6ws → faf_human_add

📦 Installation

npm install -g [email protected]
# or
npx -y claude-faf-mcp

🔗 Links

• npm Package
• 6Ws Builder
• Documentation
• Changelog

All tests passing. Championship-grade quality maintained. 🏆

Co-authored-by: Claude Sonnet 4.5

claude-faf-mcp v4.0.0 - The Championship Release

Full feature parity with faf-cli v4.0.0 - Both packages now share the same powerful toolset.

What's New: 6 Flagship Tools

| Tool | Purpose | One-liner |
|------|---------|-----------|
| faf_go | Guided interview | Answer questions → get Gold Code |
| faf_auto | One command magic | Zero to Championship instantly |
| faf_dna | Journey tracking | See your evolution over time |
| faf_formats | TURBO-CAT | Discover all formats in your project |
| faf_quick | Lightning creation | One line → complete .faf |
| faf_doctor | Health check | Diagnose and fix issues |

User Guide

Getting Started

Install or update:

npm install -g [email protected]

Add to Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "faf": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

Tool Reference

1. faf_auto - The One Command ⚡

Best for: New projects, quick setup, "just make it work"

Use: faf_auto
Path: /path/to/your/project (optional, defaults to cwd)

What it does:

1. Creates project.faf if missing
2. Runs TURBO-CAT to discover your stack
3. Extracts context from README
4. Creates CLAUDE.md for bi-sync
5. Shows before/after score

Example output:

🏎️ FAF AUTO - Zero to Championship!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Created project.faf
✅ Discovered: TypeScript, React, Jest
✅ Extracted README context
✅ Created CLAUDE.md

Score: 22% → 85% (+63%) 🚀
Time: 47ms

2. faf_go - Guided Interview 🎯

Best for: Maximum AI-readiness, thorough setup

Use: faf_go
Phase 1: Returns questions (use with AskUserQuestion)
Phase 2: Pass answers back to apply them

Two-phase operation:

1. Call faf_go → get JSON questions
2. Present questions to user (Claude handles this)
3. Call faf_go with answers → updates .faf

Questions cover:

• Project basics (name, goal, language)
• Human context (who, what, why, where, when, how)
• Stack details (frontend, backend, database, hosting)

3. faf_dna - Journey Tracking 🧬

Best for: Seeing progress, motivation, history

Use: faf_dna
Path: /path/to/your/project

What it shows:

🧬 FAF DNA Journey
━━━━━━━━━━━━━━━━━

Birth: 22% (2025-01-15)
Current: 🥇 99%

Journey: 22% → 47% → 85% → 99%
Evolutions: 4
Growth: +77% 🔥

Milestones:
  📍 Created project.faf
  📍 First enhancement
  📍 Reached Bronze (85%)
  📍 Reached Gold (99%)

4. faf_formats - TURBO-CAT Discovery 😽

Best for: Understanding your project, filling stack slots

Use: faf_formats
Path: /path/to/your/project
JSON: true/false (structured or human-readable)

Discovers:

• package.json intelligence (dependencies, scripts)
• Config files (.eslintrc, tsconfig.json, etc.)
• Framework markers (next.config.js, vite.config.ts)
• CI/CD files (.github/workflows, Dockerfile)

Output:

😽 TURBO-CAT Format Discovery
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Found 8 formats:
  📦 package.json (npm)
  ⚙️ tsconfig.json (TypeScript)
  🧪 jest.config.js (Jest)
  📝 .eslintrc (ESLint)
  🚀 vercel.json (Vercel)
  🐳 Dockerfile (Docker)
  🔄 .github/workflows (GitHub Actions)
  📖 README.md (Documentation)

Stack Signature: TypeScript + React + Jest + Vercel
Recommended slots: frontend, testing, hosting, cicd

5. faf_quick - Lightning Creation ⚡

Best for: Fast setup, when you know what you want

Use: faf_quick
Input: "project-name, A cool project, TypeScript, React, Vercel"

Format: name, description, language, framework, hosting

Minimum required: name, description

Examples:

"my-api, REST API for users, Python"
"landing-page, Marketing site, TypeScript, Next.js, Vercel"
"cli-tool, Developer utility, Rust"

6. faf_doctor - Health Check 🏥

Best for: Troubleshooting, validation, fixing issues

Use: faf_doctor
Path: /path/to/your/project

Checks:

• ✅ .faf file exists and is valid YAML
• ✅ Required fields present
• ✅ CLAUDE.md exists and synced
• ✅ package.json matches .faf
• ✅ No deprecated fields

Example output:

🏥 FAF Doctor - Health Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━

Checking: /Users/dev/my-project

✅ project.faf exists
✅ Valid YAML structure
✅ Required fields present
⚠️ CLAUDE.md out of sync (run faf_sync)
✅ package.json name matches

Health: 4/5 checks passed
Suggestion: Run faf_sync to update CLAUDE.md

Recommended Workflows

New Project (fastest)

faf_auto → done!

New Project (thorough)

faf_go → answer questions → Gold Code

Existing Project

faf_formats → see what you have
faf_auto → fill the gaps
faf_doctor → verify health

Maintenance

faf_dna → check journey
faf_doctor → verify health
faf_sync → keep CLAUDE.md updated

Stats

• Tools: 27 (was 21)
• Tests: 212 passing
• Performance: <50ms average operation
• Compatibility: Claude Desktop, any MCP client

Links

• npm: https://www.npmjs.com/package/claude-faf-mcp
• Docs: https://faf.one
• Issues: https://github.com/Wolfe-Jam/claude-faf-mcp/issues

Full Changelog: https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/CHANGELOG.md

Fixed

• faf_enhance MCP tool - Fixed "undefined" error when tool returned results (#3)
  • Changed property access to check .message before .output in EnhanceResult

Install/Update

npm install -g [email protected]

Full changelog: https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/CHANGELOG.md

Triple Crown 333 🏆🏆🏆

Fixed

• Mk3 Tier System Alignment - Synchronized tier system across all code paths

  • JSON output now uses canonical tier names (Trophy, Gold, Silver, Bronze, Green, Yellow, Red, White)
  • Fixed 0% edge case to show White tier (🤍)
  • All scorecard renders now use unified getScoreMedal() function

• Removed Unauthorized Branding - Cleaned up hallucinated F1/racing terminology

  • Removed "Championship", "Podium Edition", "Race ready", "Pit Stop" from user-facing output
  • Tool descriptions updated to neutral language
  • Help text now shows proper Mk3 tier system

• README Cleanup - Removed F1 branding, aligned with code changes

Governance

• Added CODE CHANGE PROTOCOL to CLAUDE.md - AI must now get explicit approval before writing code

Full Changelog: https://github.com/Wolfe-Jam/claude-faf-mcp/compare/v3.3.2...v3.3.3

🚀 Minimal README & Traffic Optimization

What's New

• Simplified Quick Start: "Copy and paste this to Claude/your AI" - zero friction installation
• Traffic Optimized: npm as primary method for maximum discoverability
• Clean Landing Page: Removed verbose sections, moved to docs
• Professional Polish: Following Claude Code's minimalist approach

Installation

Copy and paste this to Claude/your AI:

Install the FAF MCP server: npm install -g claude-faf-mcp, then add this to my claude_desktop_config.json: {"mcpServers": {"faf": {"command": "npx", "args": ["-y", "claude-faf-mcp"]}}} and restart Claude Desktop.

One-Click Alternative: Desktop Extension (.mcpb)

Changes

• README reduced by 2 KB (111 lines removed)
• Single-line config instruction
• Desktop Extension as alternative
• Projects Convention → moved to docs
• Troubleshooting → moved to docs

Impact

Better npm search ranking + lower barrier to entry = more users discovering FAF.

Package size: 398.8 kB | Total files: 207

🚀 One-Command Installation

What's New

• Auto-Install faf-cli: npm install -g claude-faf-mcp now installs everything
• Desktop Extension: Drag-and-drop .mcpb with FAF orange icon
• Dual Metrics: Both packages counted separately

Installation Options

Option 1: npm (Recommended)

npm install -g claude-faf-mcp

Option 2: Desktop Extension

1. Download claude-faf-mcp-v3.3.0.mcpb
2. Settings → Extensions → Install Extension
3. Orange icon everywhere!

Full Changelog

See CHANGELOG.md for complete details.

Package size: 399.1 kB | Bundle size: 26 MB

v3.2.1 - Auto-Detection & Discovery

Works automatically in Claude Desktop now. No more 'command not found' errors.

What's New

• Auto-detects CLI installation (no configuration needed)
• New faf_list tool to discover your FAF projects
• Better error messages show readable text
• Clear installation order guidance

Install Options

Desktop Extension (One-Click with FAF Orange Icon 🧡):
Download claude-faf-mcp-v3.2.1.mcpb from assets below, then:

• Claude Desktop → Settings → Extensions → Install Extension
• Select the downloaded .mcpb file
• Restart Claude Desktop
• FAF orange smiley icon will show in your MCP list!

npm (Traditional):
npm install -g [email protected]

Install CLI first, then MCP.

v3.2.0 - Podium Edition Scorecard & README Restructure

Added

• Podium Edition Scorecard - Full championship-style scorecard with faf_score --full flag
  • Dynamic status tiers (PODIUM EDITION, RACE READY, QUALIFYING, IN DEVELOPMENT)
  • Four detailed sections with live progress bars (Core Intelligence, Context Delivery, Performance, Standalone Operation)
  • Real-time metrics calculated based on project files (project.faf, CLAUDE.md, README.md, package.json)
  • Smart next steps based on what's missing in your project
  • Mobile-friendly "project.faf score: podium" format
  • Includes new Claude quote: "It's so logical if it didn't exist, AI would have built it itself"

Changed

• README Restructure - Following Svelte/Vercel pattern for clean landing page
  • README.md now uses clean landing page content (155 lines → from 564 lines)
  • Version history moved to CHANGELOG.md
  • GitHub Pages (wolfe-jam.github.io/claude-faf-mcp/) is now canonical documentation
  • Landing page tagline updated to new Claude quote
  • Title color changed to orange (#FF8C00) for brand consistency

Project Milestone

This release inaugurates the "project.faf scorecard era" - transforming the static documentation scorecard into a dynamic, interactive feature accessible through MCP tools.

Install

npm install -g [email protected]

Try the New Scorecard

# In Claude Desktop, use the faf_score tool with --full flag
faf_score --full

What's New in v3.0.5

100% Standalone MCP Server

• Discord Release Automation - Automatic Discord announcements for new releases
• MCP Mission Statement - Clarified .faf's position as universal Context layer for Model Context Protocol
• Documentation Polish - Updated README from beta messaging to stable v3.0.4+ docs
• Standalone Deployment - No more npm peer dependency warnings
• MCP 1.0.4 Integration - Full MCP SDK 1.0.4 compliance
• 55 Production Tools - Complete FAF toolchain (38 core + 17 MK3 experimental)
• IANA Format Standard - Official application/vnd.faf+yaml media type

Installation

npm install -g [email protected]

Links

• npm Package
• Docs
• Discord Community
• MCP Registry

🏆 Historic Milestone: 100% Standalone Operation

Zero CLI dependencies across all 50 MCP tools

Key Achievements

• ✅ 50/50 MCP tools operational (100% standalone)
• ✅ 14/14 bundled commands tested and passing
• ✅ 16.2x average speedup over CLI versions
• ✅ 19ms average execution across all bundled commands

New Bundled Commands

• faf_quick - Lightning-fast project.faf creation (3ms avg)
• faf_enhance - Intelligent enhancement with auto-detection + MCP-native questionnaire (63ms)

Performance Metrics

• Average execution: 19ms (championship grade)
• Fastest command: 1ms (formats)
• Unmeasurable: 0ms (migrate - too fast to measure!)
• Speedup vs CLI: 16.2x average
• Memory: Zero leaks with championship performance
• WJTTC Certified: 14/14 bundled commands, 50/50 tools, 100% pass rate

Mk3 Bundled Engine

Core FAF CLI compiler code bundled directly into MCP:

• Direct function calls (no process spawning)
• Real FafCompiler scoring integration
• TypeScript strict mode (100%)
• Comprehensive error handling

Technical Validation

• IANA Registration: application/vnd.faf+yaml
• Anthropic MCP Registry: PR #2759 (merged)
• Google Chrome: 2x approved
• npm: 5.2k+ downloads

Installation

npm install -g [email protected]
# or
npx -y claude-faf-mcp

Full blog post: https://faf.one/blog/mcp-v3-standalone

🏎️ Championship-grade engineering delivered.

Official Anthropic MCP Registry Server

🏆 The Only Persistent Project Context MCP

Claude's own words: This is the first and only MCP server providing persistent project context that survives across sessions, tools, and AIs.

Achievements

• ☑️ MCP Registry Approved - Met Anthropic's standards (PR #2759 MERGED)
• ☑️ First & Only - Persistent project context in MCP ecosystem
• ☑️ 94.4/100 Gold Standard - WJTTC certified quality
• ☑️ TypeScript Strict Mode - Zero-compromise type safety
• ☑️ 33+ MCP Tools - Complete project context management

Installation

Homebrew:

brew install wolfe-jam/faf/claude-faf-mcp

npm (Claude Desktop config):

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

Made with 🧡 by wolfejam.dev