faf-mcp 1.0.0

package/scripts/discord-sync-simple.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+/**
+ * Discord Documentation Sync Tool (Simplified)
+ * Posts FAF documentation to Discord as messages
+ *
+ * Usage: node scripts/discord-sync-simple.js <webhook-url>
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+const DOCS_DIR = path.join(__dirname, '../docs');
+
+// Documentation files to sync
+const DOCS_TO_SYNC = [
+  {
+    file: 'QUICK_START.md',
+    title: '🚀 **Quick Start Guide**',
+    url: 'https://faf.one',
+    order: 1
+  },
+  {
+    file: 'FAQ.md',
+    title: '❓ **Frequently Asked Questions**',
+    url: 'https://faf.one',
+    order: 2
+  },
+  {
+    file: 'USER_GUIDE.md',
+    title: '📚 **User Guide**',
+    url: 'https://faf.one',
+    order: 3
+  },
+  {
+    file: 'PODIUM-SYSTEM.md',
+    title: '🏆 **Podium Scoring System**',
+    url: 'https://faf.one',
+    order: 4
+  }
+];
+
+function postToDiscord(webhookUrl, content) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(webhookUrl);
+    const payload = JSON.stringify({ content });
+
+    const options = {
+      hostname: url.hostname,
+      path: url.pathname + url.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': payload.length
+      }
+    };
+
+    const req = https.request(options, (res) => {
+      if (res.statusCode === 204 || res.statusCode === 200) {
+        resolve();
+      } else {
+        let body = '';
+        res.on('data', chunk => body += chunk);
+        res.on('end', () => {
+          reject(new Error(`Discord returned status ${res.statusCode}: ${body}`));
+        });
+      }
+    });
+
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+function createSummary(content, maxLength = 1500) {
+  const lines = content.split('\n');
+  let summary = '';
+  let lineCount = 0;
+
+  for (const line of lines) {
+    // Skip title lines
+    if (line.startsWith('# ')) continue;
+
+    summary += line + '\n';
+    lineCount++;
+
+    // Stop at reasonable length or after good amount of content
+    if (summary.length > maxLength || lineCount > 30) {
+      break;
+    }
+  }
+
+  return summary.trim();
+}
+
+async function syncDocs(webhookUrl) {
+  console.log('🔄 Starting Discord documentation sync...\n');
+
+  // Post intro message
+  const introMessage = `## 📚 FAF Documentation
+
+Welcome to the FAF (Foundational AI-context Format) documentation!
+
+**🧡 IANA-registered format** · \`application/vnd.faf+yaml\`
+**📦 MCP:** 6.1k downloads, 1,231/week
+**⚡ CLI:** 6.2k downloads, 235/week
+
+Full docs available at **https://faf.one**
+
+---`;
+
+  try {
+    await postToDiscord(webhookUrl, introMessage);
+    console.log('✅ Posted intro message');
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  } catch (error) {
+    console.error('❌ Failed to post intro:', error.message);
+  }
+
+  // Sort docs by order
+  const sortedDocs = DOCS_TO_SYNC.sort((a, b) => a.order - b.order);
+
+  for (const doc of sortedDocs) {
+    const filePath = path.join(DOCS_DIR, doc.file);
+
+    if (!fs.existsSync(filePath)) {
+      console.log(`⚠️  Skipping ${doc.file} (not found)`);
+      continue;
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const summary = createSummary(content);
+
+    const message = `${doc.title}
+
+${summary}
+
+**[Read full guide →](${doc.url})**`;
+
+    try {
+      await postToDiscord(webhookUrl, message);
+      console.log(`✅ Posted ${doc.title}`);
+
+      // Rate limit: Discord allows 5 requests per 2 seconds
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    } catch (error) {
+      console.error(`❌ Failed to post ${doc.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-simple.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-working.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+/**
+ * Discord Documentation Sync Tool (Working Version)
+ * Posts FAF documentation to Discord as properly formatted messages
+ *
+ * Usage: node scripts/discord-sync-working.js <webhook-url>
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+const DOCS_DIR = path.join(__dirname, '../docs');
+
+// Documentation files to sync
+const DOCS_TO_SYNC = [
+  {
+    file: 'QUICK_START.md',
+    title: '🚀 Quick Start Guide',
+    url: 'https://faf.one',
+    order: 1
+  },
+  {
+    file: 'FAQ.md',
+    title: '❓ Frequently Asked Questions',
+    url: 'https://faf.one',
+    order: 2
+  },
+  {
+    file: 'USER_GUIDE.md',
+    title: '📚 User Guide',
+    url: 'https://faf.one',
+    order: 3
+  },
+  {
+    file: 'PODIUM-SYSTEM.md',
+    title: '🏆 Podium Scoring System',
+    url: 'https://faf.one',
+    order: 4
+  }
+];
+
+function postToDiscord(webhookUrl, content) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(webhookUrl);
+
+    // Create clean payload - only content field
+    const payload = JSON.stringify({
+      content: content.substring(0, 2000) // Discord limit is 2000 chars per message
+    });
+
+    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();
+  });
+}
+
+function createSummary(content, maxLength = 1800) {
+  const lines = content.split('\n');
+  let summary = '';
+  let lineCount = 0;
+
+  for (const line of lines) {
+    // Skip main title (first # line)
+    if (lineCount === 0 && line.startsWith('# ')) {
+      lineCount++;
+      continue;
+    }
+
+    // Stop if we're getting too long
+    if (summary.length + line.length > maxLength) {
+      break;
+    }
+
+    // Stop after reasonable number of lines
+    if (lineCount > 40) {
+      break;
+    }
+
+    summary += line + '\n';
+    lineCount++;
+  }
+
+  return summary.trim();
+}
+
+async function syncDocs(webhookUrl) {
+  console.log('🔄 Starting Discord documentation sync...\n');
+
+  // Post intro message
+  const introMessage = `**📚 FAF Documentation**
+
+Welcome to the FAF (Foundational AI-context Format) documentation!
+
+🧡 **IANA-registered format** • \`application/vnd.faf+yaml\`
+📦 **MCP:** 6.1k downloads, 1,231/week
+⚡ **CLI:** 6.2k downloads, 235/week
+
+Full docs available at **https://faf.one**
+
+━━━━━━━━━━━━━━━━━━━━━`;
+
+  try {
+    await postToDiscord(webhookUrl, introMessage);
+    console.log('✅ Posted intro message');
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  } catch (error) {
+    console.error('❌ Failed to post intro:', error.message);
+  }
+
+  // Sort docs by order
+  const sortedDocs = DOCS_TO_SYNC.sort((a, b) => a.order - b.order);
+
+  for (const doc of sortedDocs) {
+    const filePath = path.join(DOCS_DIR, doc.file);
+
+    if (!fs.existsSync(filePath)) {
+      console.log(`⚠️  Skipping ${doc.file} (not found)`);
+      continue;
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const summary = createSummary(content);
+
+    const message = `**${doc.title}**
+
+${summary}
+
+**[Read full guide →](${doc.url})**`;
+
+    try {
+      await postToDiscord(webhookUrl, message);
+      console.log(`✅ Posted ${doc.title}`);
+
+      // Rate limit: Discord allows 5 requests per 2 seconds
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    } catch (error) {
+      console.error(`❌ Failed to post ${doc.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-working.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.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+/**
+ * Discord Documentation Sync Tool
+ * Posts FAF documentation to Discord using webhooks
+ *
+ * Usage: node scripts/discord-sync.js <webhook-url>
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+const DOCS_DIR = path.join(__dirname, '../docs');
+const MAX_EMBED_LENGTH = 4096;
+const CYAN_COLOR = 0x00D4D4; // FAF cyan
+
+// Documentation files to sync
+const DOCS_TO_SYNC = [
+  {
+    file: 'QUICK_START.md',
+    title: '🚀 Quick Start Guide',
+    description: '5-minute setup for claude-faf-mcp',
+    order: 1
+  },
+  {
+    file: 'FAQ.md',
+    title: '❓ Frequently Asked Questions',
+    description: 'Common questions and answers',
+    order: 2
+  },
+  {
+    file: 'USER_GUIDE.md',
+    title: '📚 User Guide',
+    description: 'Complete guide to MCP features',
+    order: 3
+  },
+  {
+    file: 'PODIUM-SYSTEM.md',
+    title: '🏆 Podium Scoring System',
+    description: 'F1-inspired scoring tiers',
+    order: 4
+  }
+];
+
+function postToDiscord(webhookUrl, embed) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(webhookUrl);
+    const payload = JSON.stringify({
+      embeds: [embed]
+    });
+
+    const options = {
+      hostname: url.hostname,
+      path: url.pathname + url.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': payload.length
+      }
+    };
+
+    const req = https.request(options, (res) => {
+      if (res.statusCode === 204) {
+        resolve();
+      } else {
+        reject(new Error(`Discord returned status ${res.statusCode}`));
+      }
+    });
+
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+function truncateContent(content, maxLength) {
+  if (content.length <= maxLength) {
+    return content;
+  }
+
+  const truncated = content.substring(0, maxLength - 50);
+  const lastNewline = truncated.lastIndexOf('\n');
+
+  return truncated.substring(0, lastNewline > 0 ? lastNewline : maxLength - 50) +
+         '\n\n...(view full docs at faf.one)';
+}
+
+function extractSummary(content) {
+  // Extract first few sections only (intro + first topic)
+  const lines = content.split('\n');
+  let summary = '';
+  let sectionCount = 0;
+
+  for (const line of lines) {
+    if (line.startsWith('# ')) {
+      // Skip title
+      continue;
+    }
+
+    if (line.startsWith('## ')) {
+      sectionCount++;
+      if (sectionCount > 2) break; // Stop after 2 sections
+    }
+
+    summary += line + '\n';
+
+    if (summary.length > 1500) {
+      break;
+    }
+  }
+
+  return summary.trim() + '\n\n**[View full documentation →](https://faf.one)**';
+}
+
+function formatMarkdownForDiscord(content) {
+  // Extract just a summary instead of full content
+  return extractSummary(content);
+}
+
+async function syncDocs(webhookUrl) {
+  console.log('🔄 Starting Discord documentation sync...\n');
+
+  // Sort docs by order
+  const sortedDocs = DOCS_TO_SYNC.sort((a, b) => a.order - b.order);
+
+  for (const doc of sortedDocs) {
+    const filePath = path.join(DOCS_DIR, doc.file);
+
+    if (!fs.existsSync(filePath)) {
+      console.log(`⚠️  Skipping ${doc.file} (not found)`);
+      continue;
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const formattedContent = formatMarkdownForDiscord(content);
+
+    const embed = {
+      title: doc.title,
+      description: formattedContent,
+      color: CYAN_COLOR,
+      footer: {
+        text: '🧡 faf.one • IANA-registered AI Context format'
+      },
+      timestamp: new Date().toISOString()
+    };
+
+    try {
+      await postToDiscord(webhookUrl, embed);
+      console.log(`✅ Posted ${doc.title}`);
+
+      // Rate limit: Discord allows 5 requests per 2 seconds
+      await new Promise(resolve => setTimeout(resolve, 500));
+    } catch (error) {
+      console.error(`❌ Failed to post ${doc.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.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, formatMarkdownForDiscord };

package/scripts/postinstall.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install check: Verify faf-cli is installed
+ *
+ * This script runs after npm install to ensure users installed
+ * faf-cli BEFORE claude-faf-mcp (required installation order).
+ */
+
+const { execSync } = require('child_process');
+const os = require('os');
+
+function checkFafCli() {
+  try {
+    // Try to find faf CLI
+    const command = os.platform() === 'win32' ? 'where faf' : 'which faf';
+    execSync(command, { stdio: 'ignore' });
+
+    // CLI found - success!
+    console.log('✅ faf-cli detected - installation order correct');
+    return true;
+  } catch (error) {
+    // CLI not found - warn user
+    console.error('');
+    console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.error('⚠️  WARNING: faf-cli NOT DETECTED');
+    console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.error('');
+    console.error('claude-faf-mcp requires faf-cli to be installed FIRST.');
+    console.error('');
+    console.error('CORRECT INSTALLATION ORDER:');
+    console.error('  1️⃣  npm install -g faf-cli        (DO THIS FIRST)');
+    console.error('  2️⃣  npm install -g claude-faf-mcp  (ALREADY DONE)');
+    console.error('');
+    console.error('Please install faf-cli now:');
+    console.error('  npm install -g faf-cli');
+    console.error('');
+    console.error('Then restart Claude Desktop to use all MCP features.');
+    console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.error('');
+    return false;
+  }
+}
+
+// Run check
+checkFafCli();