claude-faf-mcp 2.6.0 → 2.6.1

package/CLAUDE.md

@@ -0,0 +1,289 @@
+# 🧡⚡️claude-faf-mcp v2.6.0 🏆 Claude Desktop MCP Server
+**Project DNA ✨ for AI-Context, On-Demand**
+
+## Project Overview
+**Package:** claude-faf-mcp
+**Version:** 2.6.0
+**Stack:** TypeScript 100%, Node.js 18+
+**License:** MIT (FREE FOREVER)
+**Status:** Published on npm, 800+ weekly downloads
+
+## What is claude-faf-mcp?
+Model Context Protocol (MCP) server that brings .faf Project DNA ✨ directly into Claude Desktop for AI-Context, On-Demand. 33+ tools for creating, scoring, syncing, and managing AI context without leaving your conversation.
+
+## MCP Architecture
+**Protocol:** Model Context Protocol (Anthropic)
+**Transport:** stdio (standard input/output)
+**SDK:** @modelcontextprotocol/sdk ^1.0.0
+**Tools:** 33 registered MCP tools
+
+## Installation
+Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "faf": {
+      "command": "npx",
+      "args": ["-y", "claude-faf-mcp"]
+    }
+  }
+}
+```
+
+## 33 MCP Tools
+
+### 🏎️ Power Tools
+- `faf_init` - Create .faf from project
+- `faf_auto` - Zero to Championship (auto-detect)
+- `faf_score` - Rate AI readiness (0-100%)
+- `faf_enhance` - AI-powered improvements
+
+### 😽 TURBO-CAT Tools
+- `faf_formats` - 153 format discovery
+- `faf_stacks` - Technology signatures
+- `faf_vibe` - Platform detection
+
+### 🧬 DNA & Evolution
+- `faf_dna` - Show evolution journey
+- `faf_log` - Complete history
+- `faf_update` - Save checkpoint
+- `faf_recover` - Disaster recovery
+- `faf_auth` - Birth certificate
+
+### 🏆 Scoring & Trust
+- `faf_score` - Context quality rating
+- `faf_trust` - Unified dashboard
+- `faf_credit` - Technical credit
+- `faf_check` - Validation
+- `faf_validate` - Structure check
+- `faf_audit` - Freshness check
+
+### 🔗 Sync & Mirror
+- `faf_bi_sync` - .faf ↔ CLAUDE.md (8ms!)
+- `faf_sync` - Dependency updates
+- `faf_tsa` - Inspect deps
+
+### 📝 Content Management
+- `faf_show` - Display content
+- `faf_edit` - Interactive editor
+- `faf_convert` - Format conversion
+- `faf_share` - Secure sharing
+
+### 🔍 Discovery & Analysis
+- `faf_search` - Content search
+- `faf_doctor` - Diagnose issues
+- `faf_verify` - AI compatibility
+
+### 🏁 Family & Integrations
+- `faf_fam` - View integrations (6 total)
+- `faf_fam_show` - Integration details
+
+### 📊 Information
+- `faf_status` - Quick health check
+- `faf_version` - Version info
+- `faf_welcome` - Onboarding guide
+
+## Key Features
+- **Zero Setup** - npx auto-installs, no config needed
+- **Real-time Context** - Tools execute in your project directory
+- **Championship Scoring** - 🏆 🥇 🥈 🥉 🟢 🟡 🔴 🤍
+- **Network Effects** - Works with 6 integrations (React, Next, Svelte, TS, Vite, n8n)
+- **Bi-directional Sync** - 8ms .faf ↔ CLAUDE.md mirroring
+
+## Architecture
+```
+claude-faf-mcp/
+├── src/
+│   ├── index.ts        # MCP server entry
+│   ├── cli.ts          # CLI wrapper
+│   ├── server.ts       # MCP implementation
+│   ├── tools/          # 33 MCP tool definitions
+│   └── handlers/       # Tool execution handlers
+├── dist/               # Compiled output
+├── assets/             # Icons, branding
+└── tests/              # Jest test suites
+```
+
+## Tool Definition Pattern
+Each MCP tool follows this structure:
+
+```typescript
+{
+  name: "faf_[command]",
+  description: "User-facing description for Claude",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Project path" },
+      // ... other params
+    }
+  }
+}
+```
+
+## Handler Pattern
+Handlers execute faf-cli commands via child_process:
+
+```typescript
+async function handleFafCommand(
+  command: string,
+  args: string[] = [],
+  cwd?: string
+): Promise<MCPResult> {
+  const { stdout, stderr } = await execCommand(
+    `faf ${command} ${args.join(' ')}`,
+    { cwd }
+  );
+  return { content: [{ type: "text", text: stdout }] };
+}
+```
+
+## Development
+```bash
+# Clone
+git clone https://github.com/Wolfe-Jam/claude-faf-mcp.git
+cd claude-faf-mcp
+
+# Install
+npm install
+
+# Build
+npm run build         # TypeScript → dist/
+
+# Test
+npm test             # Jest test suite
+npm run test:mcp     # MCP inspector
+
+# Dev modes
+npm run dev:stdio    # stdio transport (default)
+npm run dev:http     # HTTP-SSE transport
+npm run debug        # Node debugger
+```
+
+## Testing with MCP Inspector
+```bash
+# Start inspector
+npm run test:mcp
+
+# Or manually
+mcp-inspector stdio ts-node src/cli.ts
+```
+
+## Publishing
+```bash
+# Pre-publish
+npm run build        # Compile TypeScript
+npm test             # Run test suite
+
+# Publish
+npm publish          # Runs prepublishOnly automatically
+```
+
+## Dependencies
+**Production:** 1 only
+- `@modelcontextprotocol/sdk` ^1.0.0
+
+**Dev:** TypeScript 5.3.0, Jest 29.7.0, ts-node, eslint
+
+## Network Effects Strategy
+**Keywords (82 total):**
+- Core: `claude`, `mcp`, `model-context-protocol`, `claude-desktop`
+- Integrations: `chatgpt`, `gemini`, `cursor`, `codex`, `windsurf`, `warp`
+- Context: `ai-context`, `context-management`, `context-mirroring`
+- Features: `championship-scoring`, `bi-sync`, `zero-config`
+
+## Integration with faf-cli
+This MCP server wraps faf-cli commands:
+- **CLI required:** faf-cli must be installed globally or locally
+- **Execution:** Tools spawn `faf [command]` as child processes
+- **Output:** Captures stdout/stderr and returns to Claude
+- **Context:** Executes in user's project directory
+
+## Performance
+- **Tool Registration:** <100ms on startup
+- **Tool Execution:** Inherits faf-cli performance (<50ms)
+- **Bi-sync:** 8ms typical (via faf-cli)
+- **Zero overhead:** Direct CLI passthrough
+
+## Real Stats (Verified)
+- ✅ 800+ weekly downloads
+- ✅ 33 MCP tools
+- ✅ 100% TypeScript strict mode
+- ✅ Works with Claude Desktop
+- ✅ Zero-config installation
+
+## Claude Desktop Integration
+**Location:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**Restart Required:** After config changes, restart Claude Desktop
+
+**Debug Logs:**
+- macOS: `~/Library/Logs/Claude/mcp*.log`
+- Check for connection errors
+
+## Tool Usage in Claude
+Once installed, Claude can use tools naturally:
+
+```
+User: "Initialize a .faf file in my project"
+Claude: [Uses faf_init tool]
+
+User: "What's my AI readiness score?"
+Claude: [Uses faf_score tool]
+
+User: "Show me my project's evolution"
+Claude: [Uses faf_dna tool]
+```
+
+## NO BS ZONE 🛑
+**Trust is everything.**
+- NO fake statistics
+- NO inflated numbers
+- NO guarantees (it's free software)
+- ONLY verified claims
+- ONLY real achievements
+
+## Ecosystem
+- **CLI** - npmjs.com/package/faf-cli (main tool)
+- **MCP Server** (this) - npmjs.com/package/claude-faf-mcp
+- **Chrome Extension** - chromewebstore.google.com (LIVE)
+- **Website** - faf.one
+- **Homebrew** - brew install faf-cli
+
+## Important Context
+- **MCP** = Model Context Protocol (Anthropic standard)
+- **stdio** = Standard input/output (default transport)
+- **Tool** = MCP function Claude can call
+- **Handler** = Server-side function that executes the tool
+- **Orange Smiley MCP** = Our brand/nickname 🧡⚡️
+
+## Git Protocol
+**Professional. Boring. Trusted.**
+
+```
+fix: <what changed>
+feat: <what changed>
+docs: <what changed>
+
+- <specific change 1>
+- <specific change 2>
+```
+
+## Versioning
+- **v2.x** = MCP SDK 1.0 compatibility
+- **Sync with CLI:** MCP versions don't match CLI versions
+- **Independent:** MCP can work with any faf-cli version
+
+## Next Steps
+- Monitor npm download growth
+- Track Claude Desktop adoption
+- Add more MCP-specific tools
+- Improve error handling in stdio
+
+---
+
+**Championship-grade MCP server. Built with 🧡 by wolfejam.**
+
+*Generated: 2025-10-15*
+*Status: v2.6.0 live on npm*

package/README.md

@@ -86,8 +86,8 @@ Restart Claude Desktop → Ready! 🏁
 
 MCP server that brings `.faf` format to Claude Desktop for instant project understanding.
 
-**.faf = Project DNA for ANY AI ✨**
-Universal, shareable context for Claude, ChatGPT, Gemini, or any AI - regardless of stack, size, or setup.
+**.faf = Project DNA ✨ for AI-Context, On-Demand**
+Universal, shareable context for Claude, Codex, Gemini, or any AI - regardless of stack, size, or setup.
 
 ### Key Features
 
@@ -204,7 +204,7 @@ npm link
 
 ## 🔗 The FAF Ecosystem
 
-- [🩵 **faf-cli**](https://npmjs.com/package/faf-cli) - Command line tool (v2.4.6)
+- [🩵 **faf-cli**](https://npmjs.com/package/faf-cli) - Command line tool (v3.0.2 - Championship Edition 🏆 with Turbo Cat 😽)
 - [🧡 **claude-faf-mcp**](https://npmjs.com/package/claude-faf-mcp) - This MCP server
 - [💚 **faf.one**](https://faf.one) - Documentation & guides
 - [🖥️ **Chrome Extension**](https://chromewebstore.google.com/detail/lnecebepmpjpilldfmndnaofbfjkjlkm) - Browser integration

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "claude-faf-mcp",
-  "version": "2.6.0",
-  "description": "🧡⚡️ MCP for .faf | Project DNA ✨ for trusted AI context in Claude Desktop - Transform projects with perfect AI understanding • 33+ tools, Championship scoring • 100% TypeScript strict • Orange Smiley MCP • FREE & Open Source",
+  "version": "2.6.1",
+  "mcpName": "io.github.Wolfe-Jam/claude-faf-mcp",
+  "description": "🧡⚡️ MCP for .faf | Project DNA ✨ for AI-Context, On-Demand - Transform projects with perfect AI understanding • 33+ tools, Championship scoring • Works with Claude Desktop, VS Code, GitHub Copilot • Part of .faf ecosystem (see also: faf-cli) • 100% TypeScript strict • FREE & Open Source",
   "icon": "./assets/icons/faf-icon-64.png",
   "logo": "./assets/icons/faf-icon-64.png",
   "displayName": ".faf 🧡⚡️",