faf-mcp 1.0.0

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "faf-mcp",
+  "version": "1.0.0",
+  "mcpName": "io.github.Wolfe-Jam/faf-mcp",
+  "description": "IANA-registered format (application/vnd.faf+yaml) • Persistent project context • MCP server for all platforms • MIT License",
+  "icon": "./assets/icons/faf-icon-256.png",
+  "logo": "./assets/icons/faf-icon-256.png",
+  "displayName": ".faf 🧡⚡️",
+  "main": "dist/src/index.js",
+  "bin": {
+    "faf-mcp": "dist/src/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/server.ts",
+    "dev:stdio": "ts-node src/cli.ts --transport stdio",
+    "dev:http": "ts-node src/cli.ts --transport http-sse --port 3001",
+    "test": "jest",
+    "test:mcp": "mcp-inspector stdio ts-node src/cli.ts",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "type-check": "tsc --noEmit",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "postinstall": "node scripts/postinstall.js",
+    "debug": "node --inspect-brk=0.0.0.0:9229 -r ts-node/register src/cli.ts"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "faf",
+    ".faf",
+    "dot-faf",
+    "claude",
+    "claude-desktop",
+    "cursor",
+    "cursor-ide",
+    "windsurf",
+    "windsurf-editor",
+    "gemini",
+    "vscode",
+    "anthropic",
+    "ai-context",
+    "project-dna",
+    "ai-readiness",
+    "context-management",
+    "persistent-project-context",
+    "universal-context",
+    "iana-format",
+    "project-intelligence",
+    "codebase-understanding",
+    "ai-assistant",
+    "ai-tools",
+    "llm-tools",
+    "developer-tools",
+    "devtools",
+    "typescript",
+    "open-source",
+    "mit-license",
+    "free-forever"
+  ],
+  "author": {
+    "name": "wolfejam",
+    "email": "team@faf.one",
+    "url": "https://wolfejam.dev"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Wolfe-Jam/faf-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Wolfe-Jam/faf-mcp/issues"
+  },
+  "homepage": "https://faf.one",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "assets/**/*",
+    "scripts/**/*",
+    "skill/SKILL.md",
+    "README.md",
+    "CLAUDE.md",
+    ".faf",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "faf-cli": ">=3.1.1",
+    "@modelcontextprotocol/sdk": "^1.20.1",
+    "yaml": "^2.4.1"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.1.2",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.3",
+    "@types/jest": "^30.0.0",
+    "@types/jsonwebtoken": "^9.0.5",
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.0"
+  }
+}

package/scripts/discord-sync-curated.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+
+/**
+ * Discord Documentation Sync Tool (Curated Content)
+ * Posts hand-crafted summaries of FAF documentation to Discord
+ *
+ * Usage: node scripts/discord-sync-curated.js <webhook-url>
+ */
+
+const https = require('https');
+
+// Curated messages for Discord
+const MESSAGES = [
+  {
+    title: '📚 FAF MCP Server Documentation',
+    content: `Welcome to **claude-faf-mcp** - the Model Context Protocol server that brings FAF (Foundational AI-context Format) to Claude Desktop!
+
+**What is FAF?**
+🧡 IANA-registered AI context format (\`application/vnd.faf+yaml\`)
+📦 Universal project DNA that works with any AI tool
+🏆 F1-inspired scoring system for project quality
+
+**Two Tools Available:**
+• **MCP Server** (1,231/week downloads) - For Claude Desktop integration
+• **CLI Tool** (235/week downloads) - Command-line standalone tool
+
+Choose MCP for Claude Desktop, CLI for terminal workflows, or both!
+
+Full documentation below...`,
+    order: 1
+  },
+  {
+    title: '🚀 Quick Start - Claude Desktop Setup',
+    content: `**Install the MCP server:**
+\`\`\`bash
+npm install -g claude-faf-mcp
+\`\`\`
+
+**Add to Claude Desktop config:**
+\`\`\`json
+{
+  "mcpServers": {
+    "faf": {
+      "command": "npx",
+      "args": ["claude-faf-mcp"]
+    }
+  }
+}
+\`\`\`
+
+**Config location:**
+• macOS: \`~/Library/Application Support/Claude/claude_desktop_config.json\`
+• Windows: \`%APPDATA%\\Claude\\claude_desktop_config.json\`
+
+**Restart Claude Desktop**, then test with: \`faf_score()\`
+
+[Full Quick Start Guide](https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/docs/QUICK_START.md)`,
+    order: 2
+  },
+  {
+    title: '🏆 The PODIUM Scoring System',
+    content: `**Gamifying Software Excellence**
+
+\`\`\`
+🥉 85/100 = BRONZE PODIUM (3rd Place)
+🥈 95/100 = SILVER PODIUM (2nd Place)
+🥇 99/100 = GOLD PODIUM (1st Place)
+🏆 105/100 = TROPHY (Beyond Podium)
+\`\`\`
+
+**The Psychology:**
+When you see your project is BRONZE (85%), you can't help it...
+**YOU'RE GONNA WANNA WIN.**
+
+**How scores work:**
+• .faf file: 40 points
+• CLAUDE.md: 30 points
+• README.md: 15 points
+• Project file (package.json, etc): 14 points
+
+Nobody wants to ship BRONZE when GOLD is 14 points away.
+
+[Read PODIUM System](https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/docs/PODIUM-SYSTEM.md)`,
+    order: 3
+  },
+  {
+    title: '❓ Common Questions',
+    content: `**Do I need the FAF CLI installed?**
+No. The MCP server works standalone. Some advanced features currently require CLI but are being migrated.
+
+**What's the difference between MCP and CLI?**
+• **MCP Server**: Claude Desktop integration, native tools
+• **CLI Tool**: Terminal-based, standalone commands
+
+**How is the score calculated?**
+40 (.faf) + 30 (CLAUDE.md) + 15 (README.md) + 14 (project file) = 99% max
+The final 1% represents perfect human-AI collaboration.
+
+**Is my code safe?**
+Yes. Everything runs locally. No data sent externally. No network capabilities.
+
+**Which commands work without CLI?**
+\`faf_score\`, \`faf_detect\`, \`faf_list\`, \`faf_read\`, \`faf_write\`, \`faf_debug\`
+
+[Full FAQ](https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/docs/FAQ.md)`,
+    order: 4
+  },
+  {
+    title: '📚 User Guide Overview',
+    content: `**Core Features:**
+
+**Project Scoring** - \`faf_score()\`
+Evaluates your project's AI-readiness (0-99%, with Claude able to grant 100%)
+
+**Project Detection** - \`faf_detect()\`
+Automatically identifies your stack and frameworks
+
+**Directory Exploration** - \`faf_list()\`
+View project structure with smart file type detection
+
+**File Operations** - \`faf_read()\` / \`faf_write()\`
+Native file system operations
+
+**Best Practices:**
+1. Start with detection - let FAF understand your project
+2. Check your score - see where you stand
+3. Follow suggestions - each command guides next steps
+4. Build gradually - improve incrementally
+
+[Complete User Guide](https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/docs/USER_GUIDE.md)`,
+    order: 5
+  },
+  {
+    title: '🔗 Links & Resources',
+    content: `**Main Sites:**
+• [faf.one](https://faf.one) - FAF Format homepage
+• [GitHub - MCP Server](https://github.com/Wolfe-Jam/claude-faf-mcp)
+• [GitHub - CLI Tool](https://github.com/Wolfe-Jam/faf-cli)
+
+**npm Packages:**
+• [claude-faf-mcp](https://www.npmjs.com/package/claude-faf-mcp) - 6.1k downloads
+• [faf-cli](https://www.npmjs.com/package/faf-cli) - 6.2k downloads
+
+**Getting Help:**
+• Discord: This server! Ask in #help
+• GitHub Issues: Report bugs & request features
+• Documentation: All docs linked above
+
+**IANA Registration:** \`application/vnd.faf+yaml\`
+🧡 Official AI context format standard`,
+    order: 6
+  }
+];
+
+function postToDiscord(webhookUrl, content) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(webhookUrl);
+    const payload = JSON.stringify({
+      content: content.substring(0, 2000)
+    });
+
+    const options = {
+      hostname: url.hostname,
+      path: url.pathname + url.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(payload)
+      }
+    };
+
+    const req = https.request(options, (res) => {
+      let body = '';
+      res.on('data', chunk => body += chunk);
+      res.on('end', () => {
+        if (res.statusCode === 204 || res.statusCode === 200) {
+          resolve();
+        } else {
+          reject(new Error(`Discord returned status ${res.statusCode}: ${body}`));
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+async function syncDocs(webhookUrl) {
+  console.log('🔄 Starting Discord documentation sync (curated)...\n');
+
+  const sortedMessages = MESSAGES.sort((a, b) => a.order - b.order);
+
+  for (const msg of sortedMessages) {
+    const message = `**${msg.title}**
+
+${msg.content}`;
+
+    try {
+      await postToDiscord(webhookUrl, message);
+      console.log(`✅ Posted ${msg.title}`);
+
+      // Rate limit: Discord allows 5 requests per 2 seconds
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    } catch (error) {
+      console.error(`❌ Failed to post ${msg.title}:`, error.message);
+    }
+  }
+
+  console.log('\n✨ Sync complete!');
+}
+
+// Main execution
+if (require.main === module) {
+  const webhookUrl = process.argv[2];
+
+  if (!webhookUrl) {
+    console.error('Usage: node scripts/discord-sync-curated.js <webhook-url>');
+    console.error('\nGet your webhook URL from Discord:');
+    console.error('1. Server Settings > Integrations > Webhooks');
+    console.error('2. Create New Webhook or use existing');
+    console.error('3. Copy Webhook URL');
+    process.exit(1);
+  }
+
+  syncDocs(webhookUrl).catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });
+}
+
+module.exports = { syncDocs };

package/scripts/discord-sync-final.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+/**
+ * Discord Documentation Sync Tool (Final Version)
+ * Posts clean summaries with links to GitHub (single source of truth)
+ *
+ * Usage: node scripts/discord-sync-final.js <webhook-url>
+ */
+
+const https = require('https');
+
+// Clean messages that link to GitHub as source of truth
+const MESSAGES = [
+  {
+    title: '📚 Welcome to FAF',
+    content: `**FAF (Foundational AI-context Format)** - IANA-registered AI context standard
+
+🧡 **IANA Format:** \`application/vnd.faf+yaml\`
+📦 **MCP Server:** 6.1k downloads (1,231/week)
+⚡ **CLI Tool:** 6.2k downloads (235/week)
+
+**Two packages, one ecosystem:**
+• \`claude-faf-mcp\` - For Claude Desktop (MCP integration)
+• \`faf-cli\` - For terminal workflows
+
+**⭐️ Help us grow:** <https://github.com/Wolfe-Jam/claude-faf-mcp>
+Every star helps more devs discover FAF!
+
+━━━━━━━━━━━━━━━━━━━━━`,
+    order: 1
+  },
+  {
+    title: '🚀 Quick Start',
+    content: `**Get started in 2 minutes:**
+
+\`\`\`bash
+npm install -g claude-faf-mcp
+\`\`\`
+
+**Add to Claude Desktop config:**
+\`\`\`json
+{
+  "mcpServers": {
+    "faf": {
+      "command": "npx",
+      "args": ["claude-faf-mcp"]
+    }
+  }
+}
+\`\`\`
+
+**Restart Claude Desktop** → Test with \`faf_score()\`
+
+📖 **Full guide:** <https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/docs/QUICK_START.md>`,
+    order: 2
+  },
+  {
+    title: '🏆 PODIUM Scoring',
+    content: `**Gamifying Software Excellence**
+
+\`\`\`
+🥉 85% = BRONZE PODIUM
+🥈 95% = SILVER PODIUM
+🥇 99% = GOLD PODIUM
+🏆 105% = TROPHY
+\`\`\`
+
+When you see BRONZE (85%), you can't help it...
+**YOU'RE GONNA WANNA WIN.**
+
+**Score breakdown:**
+• 40 points: .faf file (project context)
+• 30 points: CLAUDE.md (AI instructions)
+• 15 points: README.md (documentation)
+• 14 points: Project file (package.json, etc)
+
+📖 **Full system:** <https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/docs/PODIUM-SYSTEM.md>`,
+    order: 3
+  },
+  {
+    title: '❓ FAQ',
+    content: `**Common Questions:**
+
+**Do I need the CLI installed?**
+No. v3.0.5 is 100% standalone (50/50 tools operational).
+
+**What's MCP vs CLI?**
+MCP = Claude Desktop integration
+CLI = Terminal standalone tool
+
+**How are scores calculated?**
+.faf (40) + CLAUDE.md (30) + README (15) + project file (14) = 99%
+Final 1% = perfect collaboration (only Claude can grant)
+
+**Is my code safe?**
+Yes. Everything runs locally. No external data transmission.
+
+📖 **Full FAQ:** <https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/docs/FAQ.md>`,
+    order: 4
+  },
+  {
+    title: '📖 Documentation',
+    content: `**All docs available on GitHub:**
+
+• **Quick Start:** <https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/docs/QUICK_START.md>
+• **User Guide:** <https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/docs/USER_GUIDE.md>
+• **FAQ:** <https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/docs/FAQ.md>
+• **PODIUM System:** <https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/docs/PODIUM-SYSTEM.md>
+• **Main README:** <https://github.com/Wolfe-Jam/claude-faf-mcp>
+
+**npm packages:**
+• MCP: <https://www.npmjs.com/package/claude-faf-mcp>
+• CLI: <https://www.npmjs.com/package/faf-cli>
+
+**Website:** <https://faf.one>`,
+    order: 5
+  },
+  {
+    title: '⭐️ Support FAF',
+    content: `**Help FAF grow:**
+
+⭐️ **Star on GitHub:** <https://github.com/Wolfe-Jam/claude-faf-mcp>
+Every star helps developers discover this tool!
+
+💬 **Join the community:**
+Already here? Introduce yourself in #introductions!
+
+📣 **Share FAF:**
+Know someone building with Claude? Share the npm link:
+<https://www.npmjs.com/package/claude-faf-mcp>
+
+🐛 **Report issues:** <https://github.com/Wolfe-Jam/claude-faf-mcp/issues>
+
+━━━━━━━━━━━━━━━━━━━━━
+Thanks for being part of the FAF community! 🧡`,
+    order: 6
+  }
+];
+
+function postToDiscord(webhookUrl, content) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(webhookUrl);
+    const payload = JSON.stringify({
+      content: content.substring(0, 2000)
+    });
+
+    const options = {
+      hostname: url.hostname,
+      path: url.pathname + url.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(payload)
+      }
+    };
+
+    const req = https.request(options, (res) => {
+      let body = '';
+      res.on('data', chunk => body += chunk);
+      res.on('end', () => {
+        if (res.statusCode === 204 || res.statusCode === 200) {
+          resolve();
+        } else {
+          reject(new Error(`Discord returned status ${res.statusCode}: ${body}`));
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+async function syncDocs(webhookUrl) {
+  console.log('🔄 Starting Discord documentation sync (final)...\n');
+
+  const sortedMessages = MESSAGES.sort((a, b) => a.order - b.order);
+
+  for (const msg of sortedMessages) {
+    const message = `**${msg.title}**
+
+${msg.content}`;
+
+    try {
+      await postToDiscord(webhookUrl, message);
+      console.log(`✅ Posted ${msg.title}`);
+
+      // Rate limit: Discord allows 5 requests per 2 seconds
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    } catch (error) {
+      console.error(`❌ Failed to post ${msg.title}:`, error.message);
+    }
+  }
+
+  console.log('\n✨ Sync complete!');
+}
+
+// Main execution
+if (require.main === module) {
+  const webhookUrl = process.argv[2];
+
+  if (!webhookUrl) {
+    console.error('Usage: node scripts/discord-sync-final.js <webhook-url>');
+    console.error('\nGet your webhook URL from Discord:');
+    console.error('1. Server Settings > Integrations > Webhooks');
+    console.error('2. Create New Webhook or use existing');
+    console.error('3. Copy Webhook URL');
+    process.exit(1);
+  }
+
+  syncDocs(webhookUrl).catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });
+}
+
+module.exports = { syncDocs };