grok-faf-mcp 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -5,6 +5,44 @@ 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

package/CLAUDE.md

@@ -2,18 +2,18 @@
 
 # 🏎️ 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
@@ -22,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
 
@@ -44,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/
@@ -67,7 +67,7 @@ grok-faf-mcp/
 
 ---
 
-## 💡 Quick Start for AI
+## Quick Start for AI
 
 **Q: How do I use grok-faf-mcp?**
 
@@ -102,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**
 
@@ -128,7 +128,7 @@ Before ANY npm publish of grok-faf-mcp:
 
 ---
 
-## 🎯 Strategic Position
+## Strategic Position
 
 ### Market Positioning
 
@@ -163,7 +163,7 @@ Before ANY npm publish of grok-faf-mcp:
 
 ---
 
-## 🔧 Development
+## Development
 
 ### Local Development
 
@@ -251,7 +251,7 @@ Status:               Production
 
 ---
 
-## 🌐 Community & Ecosystem
+## Community & Ecosystem
 
 **Official Links:**
 - Website: https://faf.one
@@ -267,7 +267,7 @@ Status:               Production
 
 ---
 
-**STATUS: PRODUCTION 🚀**
+**STATUS: PRODUCTION**
 
 *Built for Grok. Built for Speed. Built Right.*
 *FAST⚡️AF • First to Ship • Zero Friction*
@@ -275,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**
 
@@ -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,18 +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.
 
 ---
 
-If `grok-faf-mcp` has been useful, consider starring the repo — it helps others find it.
+## 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
+## License
 
 MIT — Free and open source
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "grok-faf-mcp",
-  "version": "1.2.1",
+  "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"