grok-faf-mcp 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to faf-mcp will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.2] - 2026-04-30
+
+### Added
+- **`CONTRIBUTING.md`** — TL;DR for xAI devs, PR conventions, branch
+  model, code style, CI doctrine, MCP-tool contribution path, npm
+  publish discipline, architecture decisions (`.faf` here / `.fafm`
+  in the Voice variant). Tight (~170 lines), F1-inspired tone.
+  Direct line for high-signal contributors landing on the repo.
+- **Voice variant cross-link** in README — points readers at
+  [`grok-faf-voice`](https://pypi.org/project/grok-faf-voice/), the
+  reference implementation of the **Voice Memory Layer (VML)**.
+  Same family (`.faf 🐘` for context / `.fafm 🐘🎙️` for voice
+  memory), different surface. Routes existing grok-faf-mcp traffic
+  to the new voice-side product.
+
+### Changed
+- **README H1 simplified** — `# grok-faf-mcp | FAST⚡️AF` →
+  `# FAST⚡️AF Context`. npm/PyPI both render the package name
+  above the README, so the prefix doubled up. New H1 is pure
+  positioning and pairs with `grok-faf-voice`'s "Fast⚡️AF memory
+  setup" as sibling FAST⚡️AF taglines (`.faf` = Context,
+  `.fafm` = memory).
+- **Tier ladder canonical alignment** — README scoring table now
+  matches `faf-cli/src/core/tiers.ts` exactly: 🏆 ★ ◆ ◇ ● ● ○ ♡.
+  Top 4 tiers (TROPHY → BRONZE) bolded to mirror the CLI's
+  orange/cyan emphasis; GREEN's symbol bolded to mirror
+  `bold('●')`; YELLOW/RED/WHITE plain to mirror `dim()`. Adds the
+  WHITE 0% row that was previously missing.
+- README test count corrected: 179 → 169 (actual passing count).
+  Honest pass for v1.2.2.
+
+### Notes
+- Docs-only patch — no behavior changes, no MCP protocol changes,
+  no new dependencies. Safe upgrade for all consumers.
+- Companion to `grok-faf-voice` v0.1.3 launch (PyPI live as of
+  2026-04-30); the cross-link routes existing grok-faf-mcp traffic
+  to the new Voice surface.
+
+## [1.2.1] - 2026-03-28
+
+### Changed
+- Bump @modelcontextprotocol/sdk from 1.20.1 to 1.27.1 (parity with claude-faf-mcp and faf-mcp)
+- Includes auth/pre-registration conformance, transport fixes, discovery caching
+- README: added star prompt and faf-cli cross-reference
+
 ## [1.2.0] - 2026-03-15
 
 ### Added

package/CLAUDE.md

@@ -1,17 +1,19 @@
+<!-- faf: grok-faf-mcp | TypeScript | grok-faf-mcp | FAST⚡️AF • First MCP server for Grok • URL-based AI context • IANA-registered .faf format (application/vnd.faf+yaml) -->
+
 # 🏎️ CLAUDE.md - grok-faf-mcp | FAST⚡️AF
 
-## PROJECT STATE: SHIPPING 🚀
-**Current Position:** First MCP server built for Grok
+## PROJECT STATE: SHIPPING
+**Current Position:** Persistent project context for xAI Grok — first MCP server built for Grok
 **Tyre Compound:** ULTRASOFT C5 (Maximum Performance)
 **Status:** URL-based, Vercel-deployed, Production-ready
 
 ---
 
-## 🎨 CORE CONTEXT
+## CORE CONTEXT
 
 ### Project Identity
 - **Name:** grok-faf-mcp
-- **Purpose:** First MCP server responding to Grok's URL request
+- **Purpose:** Persistent project context for xAI Grok — first MCP server responding to Grok's URL request
 - **Stack:** Node.js/TypeScript + Vercel
 - **Quality:** F1-INSPIRED (Championship Performance)
 - **Philosophy:** FAST⚡️AF - First to ship, zero friction, exactly what you asked for
@@ -20,7 +22,7 @@
 
 **Grok asked for MCP on a URL. This is it.**
 
-This is the FIRST MCP server specifically built for Grok/xAI, deployed on Vercel with URL-based access. No installation required. Point your Grok integration at the endpoint, get instant access to 17 MCP tools + 14 bundled commands.
+**Persistent project context for xAI Grok.** Deployed on Vercel with URL-first access — no installation required. Point your Grok integration at the endpoint, get persistent project context served via MCP SSE. First MCP server built specifically for Grok/xAI.
 
 ### Repository Structure
 
@@ -42,14 +44,14 @@ grok-faf-mcp/
 - **Why:** Grok asked for MCP on a URL - first to deliver
 - **Format:** IANA-registered .faf (application/vnd.faf+yaml)
 
-### 📊 Context Quality Status
+### Context Quality Status
 - **Overall Assessment:** Production-ready (based on faf-mcp v1.1.1)
 - **Last Updated:** 2025-11-18
 - **Version:** 1.0.0 (First Release)
 
 ---
 
-## 🚀 Deployment Architecture
+## Deployment Architecture
 
 ### Vercel Production
 - **URL:** https://grok-faf-mcp.vercel.app/
@@ -65,7 +67,7 @@ grok-faf-mcp/
 
 ---
 
-## 💡 Quick Start for AI
+## Quick Start for AI
 
 **Q: How do I use grok-faf-mcp?**
 
@@ -100,7 +102,7 @@ Use FAF to sync project context
 
 ---
 
-## 🚨 NPM PUBLISH PROTOCOL - MANDATORY 🚨
+## NPM PUBLISH PROTOCOL - MANDATORY
 
 **CRITICAL RULE: `npm publish` IS FORBIDDEN WITHOUT APPROVAL**
 
@@ -126,7 +128,7 @@ Before ANY npm publish of grok-faf-mcp:
 
 ---
 
-## 🎯 Strategic Position
+## Strategic Position
 
 ### Market Positioning
 
@@ -161,7 +163,7 @@ Before ANY npm publish of grok-faf-mcp:
 
 ---
 
-## 🔧 Development
+## Development
 
 ### Local Development
 
@@ -249,7 +251,7 @@ Status:               Production
 
 ---
 
-## 🌐 Community & Ecosystem
+## Community & Ecosystem
 
 **Official Links:**
 - Website: https://faf.one
@@ -265,7 +267,7 @@ Status:               Production
 
 ---
 
-**STATUS: PRODUCTION 🚀**
+**STATUS: PRODUCTION**
 
 *Built for Grok. Built for Speed. Built Right.*
 *FAST⚡️AF • First to Ship • Zero Friction*
@@ -273,7 +275,7 @@ Status:               Production
 **Built with F1-inspired engineering principles** 🏎️⚡
 ---
 
-**STATUS: BI-SYNC ACTIVE 🔗 - Synchronized with .faf context!**
+**STATUS: BI-SYNC ACTIVE - Synchronized with .faf context!**
 
 *Last Sync: 2026-03-15T19:48:38.492Z*
 *Sync Engine: F1-Inspired Software Engineering*

package/README.md

@@ -1,11 +1,11 @@
-# grok-faf-mcp | FAST⚡️AF
+# FAST⚡️AF Context
 
 <div align="center">
   <img src="https://www.faf.one/orange-smiley.svg" alt="FAF" width="80" />
 
   <h3>Grok asked for MCP on a URL. This is it.</h3>
 
-  <p><strong>First MCP server built for Grok</strong></p>
+  <p><strong>Persistent Project Context for xAI Grok. URL-based. Zero config.</strong></p>
   <p><code>URL-based • Zero config • Just works</code></p>
 
   [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/Wolfe-Jam/grok-faf-mcp)
@@ -18,20 +18,22 @@
   [![project.faf](https://img.shields.io/badge/project.faf-inside-00D4D4)](https://github.com/Wolfe-Jam/faf)
 </div>
 
+**FAF defines. MD instructs. AI codes.**
+
 ---
 
-## 📋 The 6 Ws - Quick Reference
+## The 6 Ws - Quick Reference
 
 Every README should answer these questions. Here's ours:
 
 | Question | Answer |
 |----------|--------|
-| **👥 WHO** is this for? | Grok/xAI developers and teams building with URL-based MCP |
-| **📦 WHAT** is it? | First MCP server built for Grok - URL-based AI context via IANA-registered .faf format |
-| **🌍 WHERE** does it work? | Vercel (production) • Local dev • Any MCP client supporting HTTP-SSE |
-| **🎯 WHY** do you need it? | Zero-config MCP on a URL - Grok asked for it, we built it first |
-| **⏰ WHEN** should you use it? | Grok integration testing, xAI projects, URL-based MCP deployments |
-| **🚀 HOW** does it work? | Point to `https://grok-faf-mcp.vercel.app/sse` - 21 tools instantly available |
+| **WHO** is this for? | Grok/xAI developers and teams building with URL-based MCP |
+| **WHAT** is it? | Persistent project context for xAI Grok — URL-first deployment, IANA-registered .faf format |
+| **WHERE** does it work? | Vercel (production) • Local dev • Any MCP client supporting HTTP-SSE |
+| **WHY** do you need it? | Zero-config MCP on a URL - Grok asked for it, we built it first |
+| **WHEN** should you use it? | Grok integration testing, xAI projects, URL-based MCP deployments |
+| **HOW** does it work? | Point to `https://grok-faf-mcp.vercel.app/sse` — context tools served via MCP SSE |
 
 **For AI:** Read the detailed sections below for full context.
 **For humans:** Use this pattern in YOUR README. Answer these 6 questions clearly.
@@ -58,7 +60,7 @@ With .faf     →  Grok already knows. Every session. Forever.
 ```
 faf_auto
 ━━━━━━━━━━━━━━━━━
-Score: 0% → 85% (+85) 🥉 Bronze
+Score: 0% → 85% (+85) ◇ BRONZE
 Steps:
   1. Created project.faf
   2. Detected stack from package.json
@@ -99,7 +101,7 @@ Format:  IANA-registered .faf (application/vnd.faf+yaml)
 Tools:   21 core MCP tools (55 total with advanced)
 Engine:  Mk4 WASM scoring (faf-scoring-kernel)
 Speed:   0.5ms average (was 19ms — 3,800% faster with Mk4)
-Tests:   179 passing (7 suites)
+Tests:   169 passed · 0 failed · 169 total (7 suites)
 Status:  FAST⚡️AF
 ```
 
@@ -111,19 +113,20 @@ Status:  FAST⚡️AF
 
 | Tier | Score | What it means |
 |------|-------|---------------|
-| 🏆 **Trophy** | 100% | Gold Code — AI is optimized |
-| 🥇 **Gold** | 99%+ | Near-perfect context |
-| 🥈 **Silver** | 95%+ | Excellent |
-| 🥉 **Bronze** | 85%+ | Production ready |
-| 🟢 **Green** | 70%+ | Solid foundation |
-| 🟡 **Yellow** | 55%+ | AI flipping coins |
-| 🔴 **Red** | <55% | AI working blind |
+| **🏆 TROPHY** | 100% | Gold Code — AI is optimized |
+| **★ GOLD** | 99%+ | Near-perfect context |
+| **◆ SILVER** | 95%+ | Excellent |
+| **◇ BRONZE** | 85%+ | Production ready |
+| **●** GREEN | 70%+ | Solid foundation |
+| ● YELLOW | 55%+ | AI flipping coins |
+| ○ RED | <55% | AI working blind |
+| ♡ WHITE | 0% | Empty — good luck |
 
 At 55%, Grok guesses half the time. At 100%, Grok knows your project.
 
 ---
 
-## 🚀 Three Ways to Deploy
+## Three Ways to Deploy
 
 ### 1. Hosted (Instant)
 ```
@@ -154,7 +157,7 @@ npx grok-faf-mcp
 
 ---
 
-## 🛠️ MCP Tools (21 Core)
+## MCP Tools (21 Core)
 
 **Create & Detect**
 
@@ -214,7 +217,7 @@ Benchmarked 10x per tool, warmed up, on local execution.
 ## Architecture
 
 ```
-grok-faf-mcp v1.2.0
+grok-faf-mcp v1.2.1
 ├── api/index.ts              → Vercel serverless (Express + SSE transport)
 ├── src/
 │   ├── server.ts             → MCP server (ClaudeFafMcpServer)
@@ -253,7 +256,7 @@ npm test    # runs all 179
 
 ---
 
-## 🔗 Endpoints
+## Endpoints
 
 | Endpoint | URL |
 |----------|-----|
@@ -264,7 +267,7 @@ npm test    # runs all 179
 
 ---
 
-## 📦 Ecosystem
+## Ecosystem
 
 One format, every AI platform.
 
@@ -274,14 +277,42 @@ One format, every AI platform.
 | [claude-faf-mcp](https://npmjs.com/package/claude-faf-mcp) | Anthropic | npm + MCP #2759 |
 | [gemini-faf-mcp](https://pypi.org/project/gemini-faf-mcp/) | Google | PyPI |
 | [rust-faf-mcp](https://crates.io/crates/rust-faf-mcp) | Rust | crates.io |
-| [faf-mcp](https://npmjs.com/package/faf-mcp) | Universal (Cursor, Windsurf, Cline) | npm |
-| [faf-cli](https://npmjs.com/package/faf-cli) | Terminal CLI | npm + Homebrew |
+| [faf-mcp](https://npmjs.com/package/faf-mcp) | Cursor, IDE's, VS Code | npm |
+| [faf-cli](https://npmjs.com/package/faf-cli) | Terminal CLI | bunx, npm + Homebrew |
 
 Same `project.faf`. Same scoring. Same result. Different execution layer.
 
 ---
 
-## 📄 License
+## Voice variant — `grok-faf-voice` (VML)
+
+`.fafm 🐘🎙️` — the voice variant of the `.faf 🐘` family.
+
+**[grok-faf-voice](https://pypi.org/project/grok-faf-voice/)** is the reference implementation of the **Voice Memory Layer (VML)** — what your voice agent *remembers* across sessions, devices, and model switches. Companion to `grok-faf-mcp`:
+
+- **`grok-faf-mcp`** (this) — `.faf` Foundational Context Layer for Grok via MCP-on-a-URL.
+- **`grok-faf-voice`** — `.fafm` Voice Memory Layer (VML) for Grok Voice via LiveKit + xAI realtime.
+
+Same family. Different surface. *Voice swappable; memory permanent.*
+
+[PyPI](https://pypi.org/project/grok-faf-voice/) · [GitHub](https://github.com/Wolfe-Jam/grok-faf-voice) · [Onboarding](https://wolfe-jam.github.io/grok-faf-voice/onboarding.html)
+
+---
+
+## Contributing
+
+PR conventions, code style, CI doctrine, MCP-tool contribution path,
+npm publish discipline, architecture decisions: **[CONTRIBUTING.md](CONTRIBUTING.md)**.
+
+xAI / Grok devs welcome — TL;DR setup at the top, F1-inspired tone throughout.
+
+---
+
+If grok-faf-mcp has been useful, consider starring the repo ⭐️ it helps others find it.
+
+---
+
+## License
 
 MIT — Free and open source
 
@@ -292,3 +323,15 @@ MIT — Free and open source
   <p>FAST⚡️AF • First to Ship • Zero Friction</p>
   <p><strong>Zero drift. Eternal sync. AI optimized.</strong> 🏆</p>
 </div>
+
+---
+
+### Get the CLI
+
+> **faf-cli** — The original AI-Context CLI. A must-have for every builder.
+
+```bash
+npx faf-cli auto
+```
+
+**Anthropic MCP [#2759](https://github.com/modelcontextprotocol/servers/pull/2759)** · **IANA Registered:** `application/vnd.faf+yaml` · [faf.one](https://faf.one) · [npm](https://www.npmjs.com/package/faf-cli)

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "grok-faf-mcp",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "mcpName": "io.github.Wolfe-Jam/grok-faf-mcp",
-  "description": "grok-faf-mcp | FAST⚡️AF • First MCP server for Grok • URL-based AI context • IANA-registered .faf format (application/vnd.faf+yaml)",
+  "description": "Persistent Project Context for xAI Grok. IANA-registered .faf format, MCP server on a URL, Vercel-deployed.",
   "icon": "./assets/icons/faf-icon-256.png",
   "logo": "./assets/icons/faf-icon-256.png",
-  "displayName": ".faf 🧡⚡️ for Grok",
+  "displayName": ".faf 🐘⚡️ for Grok",
   "main": "dist/src/index.js",
   "bin": {
     "grok-faf-mcp": "dist/src/index.js"
@@ -107,8 +107,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.20.1",
-    "@vercel/analytics": "^1.6.1",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@upstash/redis": "^1.37.0",
     "cors": "^2.8.5",
     "express": "^4.21.0",
     "faf-cli": ">=3.1.1",

package/project.faf

@@ -1,154 +1,40 @@
-faf_version: 2.5.0
-ai_scoring_system: 2025-09-20
-ai_score: 85%
-ai_confidence: HIGH
-ai_value: 30_seconds_replaces_20_minutes_of_questions
-ai_tldr:
-  project: Faf Mcp - "USE>FAF™ - IANA-registered format (application/vnd.faf+yaml)
-    • Universal AI context • MCP server for all platforms • Start with 'Use
-    FAF'"
-  stack: CLI/TypeScript/TypeScript (tsc)/npm registry/Node.js
-  quality_bar: ZERO_ERRORS_F1_STANDARDS
-  current_focus: Production deployment preparation
-  your_role: Build features with perfect context
-instant_context:
-  what_building: USE>FAF™ - IANA-registered format (application/vnd.faf+yaml) •
-    Universal AI context • MCP server for all platforms • Start with 'Use FAF'
-  tech_stack: CLI/TypeScript/TypeScript (tsc)/npm registry/Node.js
-  main_language: TypeScript
-  deployment: npm registry
-  key_files:
-    - package.json
-    - tsconfig.json
-context_quality:
-  slots_filled: 16/21 (76%)
-  ai_confidence: GOOD
-  handoff_ready: true
-  missing_context:
-    - CI/CD pipeline
-    - Database
-slot_ignore:
-  - database
-  - connection
+faf_version: "3.0"
 project:
   name: grok-faf-mcp
-  goal: grok-faf-mcp | FAST⚡️AF • First MCP server for Grok • URL-based AI context
-    • IANA-registered .faf format (application/vnd.faf+yaml)
+  goal: grok-faf-mcp | FAST⚡️AF • First MCP server for Grok • URL-based AI context • IANA-registered .faf format (application/vnd.faf+yaml)
   main_language: TypeScript
-  type: cli-ts
-  generated: 2025-11-13T20:02:03.291Z
-  mission: 🚀 Make Your AI Happy! 🧡 Trust-Driven 🤖
-  revolution: 30 seconds replaces 20 minutes of questions
-  brand: F1-Inspired Software Engineering - Championship AI Context
-ai_instructions:
-  how_to_start: Just USE FAF - Start every prompt with 'Use FAF to...' and MCP
-    tools handle the rest
-  priority_order:
-    - 1. Read THIS .faf file first
-    - 2. Check CLAUDE.md for session context
-    - 3. Review package.json for dependencies
-  quick_commands:
-    - Use FAF to initialize your project
-    - Use FAF to sync my project.faf to all platforms
-    - Use FAF to score my AI-readiness
-  working_style:
-    code_first: true
-    explanations: minimal
-    quality_bar: zero_errors
-    testing: required
-  warnings:
-    - Never modify dial components without approval
-    - All TypeScript must pass strict mode
-    - Test coverage required for new features
+  type: mcp
+  framework: mcp-sdk-ts
 stack:
-  frontend: CLI
-  css_framework: None
-  ui_library: None
-  state_management: None
-  backend: Node.js
-  runtime: Node.js >=18.0.0
-  database: None
+  frontend: slotignored
+  css_framework: slotignored
+  ui_library: slotignored
+  state_management: slotignored
+  backend: MCP SDK (TS)
+  api_type: MCP (stdio/SSE)
+  runtime: Node.js
+  database: slotignored
+  connection: slotignored
+  hosting: Vercel
   build: TypeScript (tsc)
-  package_manager: npm
-  api_type: CLI
-  hosting: npm registry
-  cicd: Vercel
-  targetUser: developers
-  coreProblem: understanding project
-  missionPurpose: project documentation
-  packageManager: npm/yarn/pnpm
-  mainLanguage: JavaScript/TypeScript
-preferences:
-  quality_bar: zero_errors
-  commit_style: conventional_emoji
-  response_style: concise_code_first
-  explanation_level: minimal
-  communication: direct
-  testing: required
-  documentation: as_needed
-state:
-  phase: development
-  version: 1.0.0
-  focus: production_deployment
-  status: green_flag
-  next_milestone: npm_publication
-  blockers: null
-tags:
-  auto_generated:
-    - faf-mcp
-    - cli
-    - typescript
-    - typescript-(tsc)
-    - npm-registry
-    - node.js
-  smart_defaults:
-    - .faf
-    - ai-ready
-    - "2025"
-    - software
-    - open-source
-  user_defined: null
+  cicd: GitHub Actions
+  monorepo_tool: slotignored
+  package_manager: slotignored
+  workspaces: slotignored
+  admin: slotignored
+  cache: slotignored
+  search: slotignored
+  storage: slotignored
 human_context:
-  who: Grok/xAI developers and teams
-  what: URL-based MCP server for Grok
-  why: Zero-config MCP on a URL - Grok asked for it
-  where: Vercel production + Local dev
-  when: Grok integration testing, xAI projects
-  how: Point to https://grok-faf-mcp.vercel.app/sse
-  additional_context:
-    what:
-      - First ever MCP for Grok
-      - First FAF MCP on web
-    why:
-      - Grok asked for MCP on a URL
-      - Zero installation, instant access
-      - FAST⚡️AF (19ms average)
-  context_score: 0
-  total_prd_score: 85
-  success_rate: 50%
-ai_scoring_details:
-  system_date: 2025-09-20
-  slot_based_percentage: 76
-  ai_score: 85
-  total_slots: 21
-  filled_slots: 16
-  scoring_method: Honest percentage - no fake minimums
-  trust_embedded: COUNT ONCE architecture - trust MY embedded scores
-faf_dna:
-  birth_dna: 22
-  birth_certificate: FAF-2025-FAFMCP-NR94
-  birth_date: 2025-11-13T20:02:03.306Z
-  current_score: 83
-generated: 2026-02-15T05:07:07.238Z
-stack_signature: typescript-nodejs-javascript
-detected_frameworks:
-  - Claude Code
-  - Jest
-  - Node.js
-  - JavaScript
-  - TypeScript
-  - Vercel
-turbo_cat_intelligence: 205
-stats:
-  last_auto_time: 0.2
-  times_run: 3
+  who: Developers using xAI Grok with MCP
+  what: First MCP server for Grok — persistent AI context via IANA-registered .faf format
+  why: Every AI session starts from zero. grok-faf-mcp gives Grok persistent project DNA.
+  where: npm registry, Vercel (grok-faf-mcp.vercel.app), MCP Registry
+  when: Shipped 2026, v1.2.1
+  how: npx grok-faf-mcp or Deploy to Vercel — 21 tools, SSE transport, WASM Mk4 scoring
+monorepo:
+  packages_count: slotignored
+  build_orchestrator: slotignored
+  versioning_strategy: slotignored
+  shared_configs: slotignored
+  remote_cache: slotignored