@velt-js/mcp-installer 0.1.0

package/src/utils/velt-docs-fetcher.js

@@ -0,0 +1,288 @@
+/**
+ * Velt Docs Fetcher
+ *
+ * Fetches Velt documentation from markdown (.md) URLs with fallback to Velt Docs MCP.
+ * For post-installation questions/troubleshooting, AI should query Velt Docs MCP directly.
+ *
+ * Source Priority:
+ * 1. Agent Skills Libraries (installed via `npx skills add velt-js/agent-skills`)
+ *    - Referenced by name in plan output; AI editor loads them automatically
+ * 2. Docs URLs (docs.velt.dev markdown) - for features without skills coverage
+ * 3. Velt Docs MCP - only on explicit user follow-up questions
+ */
+
+import { getDocUrl, getDocMarkdownUrl } from './velt-docs-urls.js';
+import { queryVeltDocsMCP } from './velt-mcp-client.js';
+
+/**
+ * Maps Velt features to their corresponding Agent Skill names.
+ * Skills are installed via `npx skills add velt-js/agent-skills` and
+ * loaded into the AI editor's context automatically.
+ *
+ * The MCP references these by name in plan output — it does NOT read skill files.
+ */
+export const FEATURE_SKILL_MAP = {
+  // Setup / Provider / Auth / Document
+  setup: 'velt-setup-best-practices',
+  provider: 'velt-setup-best-practices',
+  auth: 'velt-setup-best-practices',
+  document: 'velt-setup-best-practices',
+
+  // Comments (all types)
+  comments: 'velt-comments-best-practices',
+
+  // CRDT (all editor types)
+  crdt: 'velt-crdt-best-practices',
+
+  // Notifications
+  notifications: 'velt-notifications-best-practices',
+
+  // Features WITHOUT skills coverage — use docs URLs
+  // presence: null,
+  // cursors: null,
+  // recorder: null,
+};
+
+/**
+ * Returns the Agent Skill name for a given feature, or null if no skill covers it.
+ *
+ * @param {string} feature - Feature name (comments, crdt, notifications, presence, etc.)
+ * @param {string} [subtype] - Optional subtype (freestyle, tiptap, etc.) — unused for mapping but kept for API consistency
+ * @returns {string|null} Skill name or null
+ */
+export function getSkillForFeature(feature, subtype = null) {
+  return FEATURE_SKILL_MAP[feature] || null;
+}
+
+/**
+ * Returns an array of { feature, skillName } objects for all features that have skills,
+ * plus { feature, docsUrl } for features that fall back to docs.
+ *
+ * @param {string[]} features - Array of feature names
+ * @param {Object} [options] - Options
+ * @param {string} [options.commentType] - Comment subtype
+ * @param {string} [options.crdtEditorType] - CRDT editor subtype
+ * @returns {Array<{feature: string, skillName?: string, docsUrl?: string}>}
+ */
+export function getSkillReferences(features, options = {}) {
+  const { commentType, crdtEditorType } = options;
+  const refs = [];
+
+  // Always include setup skill
+  refs.push({
+    feature: 'setup',
+    skillName: FEATURE_SKILL_MAP.setup,
+    description: 'VeltProvider setup, authentication, document identity, project structure',
+  });
+
+  for (const feature of features) {
+    const skill = getSkillForFeature(feature);
+    if (skill) {
+      const subtype = feature === 'comments' ? commentType : feature === 'crdt' ? crdtEditorType : null;
+      refs.push({
+        feature: subtype ? `${feature} (${subtype})` : feature,
+        skillName: skill,
+      });
+    } else {
+      const subtype = feature === 'comments' ? commentType : feature === 'crdt' ? crdtEditorType : null;
+      refs.push({
+        feature: subtype ? `${feature} (${subtype})` : feature,
+        docsUrl: getDocMarkdownUrl(feature, subtype),
+      });
+    }
+  }
+
+  return refs;
+}
+
+/**
+ * Fetches implementation details for a comment type
+ *
+ * Strategy:
+ * 1. Fetch from docs.velt.dev markdown URLs directly (primary)
+ * 2. If that fails, use Velt Docs MCP (fallback)
+ * 3. If both fail, return basic structure with doc URL reference
+ *
+ * @param {Object} options - Fetch options
+ * @param {string} options.commentType - Comment type (freestyle, popover, etc.)
+ * @param {Object} [options.mcpClient] - Optional MCP client for fallback
+ * @returns {Promise<Object>} Implementation details
+ */
+export async function fetchCommentImplementation(options) {
+  const { commentType, mcpClient } = options;
+
+  console.error(`🔍 Fetching ${commentType} implementation from .md URL...`);
+
+  // Step 1: Fetch from markdown URL (primary)
+  console.error('   📄 Fetching from docs.velt.dev markdown...');
+  try {
+    const urlResult = await fetchFromMarkdownUrl('comments', commentType);
+    console.error('   ✅ Got documentation from markdown URL');
+    return urlResult;
+  } catch (error) {
+    console.error(`   ⚠️  Markdown fetch failed: ${error.message}`);
+  }
+
+  // Step 2: Fallback to Velt Docs MCP if .md URL failed
+  console.error('   📚 Falling back to Velt Docs MCP...');
+  try {
+    const query = `How do I implement ${commentType} comments in Next.js?`;
+    const mcpResult = await queryVeltDocsMCP(query);
+
+    if (mcpResult.success) {
+      console.error('   ✅ Got implementation from Velt Docs MCP');
+      return {
+        success: true,
+        source: 'velt-docs-mcp',
+        docUrl: getDocUrl('comments', commentType),
+        mdUrl: getDocMarkdownUrl('comments', commentType),
+        data: mcpResult.data,
+      };
+    }
+  } catch (error) {
+    console.error(`   ⚠️  Velt Docs MCP failed: ${error.message}`);
+  }
+
+  // Step 3: Return basic structure with doc URL
+  console.error('   📖 Returning basic structure with doc URL reference');
+  return getBasicStructure('comments', commentType);
+}
+
+/**
+ * Fetches documentation from markdown URL
+ */
+async function fetchFromMarkdownUrl(feature, subtype = null) {
+  const docUrl = getDocUrl(feature, subtype);
+  const mdUrl = getDocMarkdownUrl(feature, subtype);
+
+  try {
+    console.error(`   Fetching from: ${mdUrl}`);
+    const response = await fetch(mdUrl);
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const markdown = await response.text();
+
+    return {
+      success: true,
+      source: 'docs-md-url',
+      docUrl,
+      mdUrl,
+      data: {
+        markdown,
+        docUrl,
+      },
+    };
+  } catch (error) {
+    throw new Error(`Failed to fetch from ${mdUrl}: ${error.message}`);
+  }
+}
+
+/**
+ * Returns a basic structure with doc URL reference
+ */
+function getBasicStructure(feature, subtype = null) {
+  const docUrl = getDocUrl(feature, subtype);
+  const mdUrl = getDocMarkdownUrl(feature, subtype);
+
+  return {
+    success: true,
+    source: 'basic-structure',
+    docUrl,
+    mdUrl,
+    data: {
+      docUrl,
+      mdUrl,
+      note: 'Please refer to the documentation URL for implementation details',
+    },
+    warning: 'Could not fetch documentation - providing URL references only',
+  };
+}
+
+/**
+ * Fetches implementation details for any Velt feature
+ *
+ * Strategy:
+ * 1. Fetch from docs.velt.dev markdown URLs directly (primary)
+ * 2. If that fails, use Velt Docs MCP (fallback)
+ * 3. If both fail, return basic structure with doc URL reference
+ *
+ * @param {Object} options - Fetch options
+ * @param {string} options.feature - Feature name (comments, presence, cursors, notifications, recorder, crdt)
+ * @param {string} [options.subtype] - Optional subtype (e.g., 'freestyle' for comments, 'tiptap' for crdt)
+ * @param {Object} [options.mcpClient] - Optional MCP client for fallback
+ * @returns {Promise<Object>} Implementation details
+ */
+export async function fetchFeatureImplementation(options) {
+  const { feature, subtype = null, mcpClient } = options;
+
+  const featureDisplay = subtype ? `${feature}/${subtype}` : feature;
+  console.error(`🔍 Fetching ${featureDisplay} implementation from .md URL...`);
+
+  // Step 1: Fetch from markdown URL (primary)
+  console.error('   📄 Fetching from docs.velt.dev markdown...');
+  try {
+    const urlResult = await fetchFromMarkdownUrl(feature, subtype);
+    console.error('   ✅ Got documentation from markdown URL');
+    return urlResult;
+  } catch (error) {
+    console.error(`   ⚠️  Markdown fetch failed: ${error.message}`);
+  }
+
+  // Step 2: Fallback to Velt Docs MCP if .md URL failed
+  console.error('   📚 Falling back to Velt Docs MCP...');
+  try {
+    const query = subtype
+      ? `How do I implement ${subtype} ${feature} in Next.js?`
+      : `How do I implement ${feature} in Next.js?`;
+    const mcpResult = await queryVeltDocsMCP(query);
+
+    if (mcpResult.success) {
+      console.error('   ✅ Got implementation from Velt Docs MCP');
+      return {
+        success: true,
+        source: 'velt-docs-mcp',
+        docUrl: getDocUrl(feature, subtype),
+        mdUrl: getDocMarkdownUrl(feature, subtype),
+        data: mcpResult.data,
+      };
+    }
+  } catch (error) {
+    console.error(`   ⚠️  Velt Docs MCP failed: ${error.message}`);
+  }
+
+  // Step 3: Return basic structure with doc URL
+  console.error('   📖 Returning basic structure with doc URL reference');
+  return getBasicStructure(feature, subtype);
+}
+
+/**
+ * Fetches implementation details for CRDT feature
+ *
+ * @param {Object} options - Fetch options
+ * @param {string} options.editorType - Editor type (tiptap, codemirror, blocknote)
+ * @param {Object} [options.mcpClient] - Optional MCP client for fallback
+ * @returns {Promise<Object>} Implementation details
+ */
+export async function fetchCrdtImplementation(options) {
+  const { editorType, mcpClient } = options;
+
+  console.error(`🔍 Fetching CRDT ${editorType} implementation from .md URL...`);
+
+  return fetchFeatureImplementation({
+    feature: 'crdt',
+    subtype: editorType,
+    mcpClient,
+  });
+}
+
+export default {
+  fetchCommentImplementation,
+  fetchFeatureImplementation,
+  fetchCrdtImplementation,
+  FEATURE_SKILL_MAP,
+  getSkillForFeature,
+  getSkillReferences,
+};

package/src/utils/velt-docs-urls.js

@@ -0,0 +1,140 @@
+/**
+ * Velt Documentation URLs
+ *
+ * Comprehensive mapping of Velt feature documentation URLs for fallback when
+ * Velt Docs MCP is unavailable.
+ */
+
+/**
+ * All Velt feature documentation URLs
+ */
+export const VELT_DOCS_URLS = {
+  // Getting Started
+  quickstart: 'https://docs.velt.dev/get-started/quickstart',
+  keyConcepts: 'https://docs.velt.dev/key-concepts/overview',
+
+  // Comments
+  comments: {
+    setup: {
+      freestyle: 'https://docs.velt.dev/async-collaboration/comments/setup/freestyle',
+      popover: 'https://docs.velt.dev/async-collaboration/comments/setup/popover',
+      page: 'https://docs.velt.dev/async-collaboration/comments/setup/page',
+      text: 'https://docs.velt.dev/async-collaboration/comments/setup/text',
+      inline: 'https://docs.velt.dev/async-collaboration/comments/setup/inline-comments',
+      // Purpose-built library integrations
+      tiptap: 'https://docs.velt.dev/async-collaboration/comments/setup/tiptap',
+      lexical: 'https://docs.velt.dev/async-collaboration/comments/setup/lexical',
+      slate: 'https://docs.velt.dev/async-collaboration/comments/setup/slatejs',
+    },
+    customizeBehavior: 'https://docs.velt.dev/async-collaboration/comments/customize-behavior',
+  },
+
+  // Presence
+  presence: {
+    setup: 'https://docs.velt.dev/realtime-collaboration/presence/setup',
+    customizeBehavior: 'https://docs.velt.dev/realtime-collaboration/presence/customize-behavior',
+  },
+
+  // Notifications
+  notifications: {
+    setup: 'https://docs.velt.dev/async-collaboration/notifications/setup',
+    customizeBehavior: 'https://docs.velt.dev/async-collaboration/notifications/customize-behavior',
+  },
+
+  // Recorder
+  recorder: {
+    setup: 'https://docs.velt.dev/async-collaboration/recorder/setup',
+    customizeBehavior: 'https://docs.velt.dev/async-collaboration/recorder/customize-behavior',
+  },
+
+  // Cursors
+  cursors: {
+    setup: 'https://docs.velt.dev/realtime-collaboration/cursors/setup',
+    customizeBehavior: 'https://docs.velt.dev/realtime-collaboration/cursors/customize-behavior',
+  },
+
+  // CRDT (Collaborative Real-Time Document editing)
+  crdt: {
+    setup: {
+      tiptap: 'https://docs.velt.dev/realtime-collaboration/crdt/setup/tiptap',
+      codemirror: 'https://docs.velt.dev/realtime-collaboration/crdt/setup/codemirror',
+      blocknote: 'https://docs.velt.dev/realtime-collaboration/crdt/setup/blocknote',
+      reactflow: 'https://docs.velt.dev/realtime-collaboration/crdt/setup/reactflow',
+    },
+    overview: 'https://docs.velt.dev/multiplayer-editing/overview',
+  },
+
+};
+
+/**
+ * Gets the documentation URL for a specific feature or comment type
+ *
+ * @param {string} feature - Feature name (comments, presence, cursors, notifications, recorder)
+ * @param {string} [subtype] - Optional subtype (for comments: freestyle, popover, page, text, inline, tiptap, lexical, slate)
+ * @param {string} [page='setup'] - Page type (setup, customizeBehavior)
+ * @returns {string} Documentation URL
+ */
+export function getDocUrl(feature, subtype = null, page = 'setup') {
+  const featureConfig = VELT_DOCS_URLS[feature];
+
+  if (!featureConfig) {
+    console.warn(`Unknown feature: ${feature}, using quickstart`);
+    return VELT_DOCS_URLS.quickstart;
+  }
+
+  // If it's a simple string URL, return it
+  if (typeof featureConfig === 'string') {
+    return featureConfig;
+  }
+
+  // Handle comments with subtypes (freestyle, popover, etc.)
+  if (feature === 'comments' && subtype) {
+    if (featureConfig.setup && featureConfig.setup[subtype]) {
+      return featureConfig.setup[subtype];
+    }
+  }
+
+  // Handle CRDT with subtypes (tiptap, codemirror, blocknote)
+  if (feature === 'crdt' && subtype) {
+    if (featureConfig.setup && featureConfig.setup[subtype]) {
+      return featureConfig.setup[subtype];
+    }
+  }
+
+  // Handle page navigation (setup, customizeBehavior)
+  if (featureConfig[page]) {
+    return featureConfig[page];
+  }
+
+  // Fallback to setup
+  return featureConfig.setup || VELT_DOCS_URLS.quickstart;
+}
+
+/**
+ * Gets the markdown URL for a specific feature or comment type
+ *
+ * @param {string} feature - Feature name
+ * @param {string} [subtype] - Optional subtype (for comments)
+ * @param {string} [page='setup'] - Page type
+ * @returns {string} Markdown documentation URL
+ */
+export function getDocMarkdownUrl(feature, subtype = null, page = 'setup') {
+  const baseUrl = getDocUrl(feature, subtype, page);
+  return `${baseUrl}.md`;
+}
+
+/**
+ * Gets all available comment types
+ *
+ * @returns {string[]} Array of comment type names
+ */
+export function getAvailableCommentTypes() {
+  return Object.keys(VELT_DOCS_URLS.comments.setup);
+}
+
+export default {
+  VELT_DOCS_URLS,
+  getDocUrl,
+  getDocMarkdownUrl,
+  getAvailableCommentTypes,
+};

package/src/utils/velt-mcp-client.js

@@ -0,0 +1,202 @@
+/**
+ * Velt Docs MCP Client
+ * 
+ * Attempts to query Velt Docs MCP server through proper MCP protocol
+ * Falls back to direct documentation queries if MCP is unavailable
+ */
+
+import https from 'https';
+import { URL } from 'url';
+
+/**
+ * Queries Velt Docs MCP server properly
+ *
+ * Since HTTP-based MCP servers require IDE client access,
+ * we try multiple strategies to get documentation patterns.
+ *
+ * @param {string} query - Query string
+ * @param {number} maxRetries - Maximum number of retries (default: 2)
+ * @returns {Promise<Object>} Patterns result
+ */
+export async function queryVeltDocsMCP(query, maxRetries = 2) {
+  const veltDocsMCPUrl = 'https://docs.velt.dev/mcp';
+
+  // Strategy 1: Try MCP server with proper protocol and retry logic
+  let lastError = null;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      if (attempt > 0) {
+        const backoffDelay = Math.min(1000 * Math.pow(2, attempt - 1), 3000);
+        console.error(`   Retry attempt ${attempt}/${maxRetries} after ${backoffDelay}ms...`);
+        await new Promise(resolve => setTimeout(resolve, backoffDelay));
+      }
+
+      console.error('   Attempting MCP protocol query...');
+
+      // First, get available tools with timeout
+      const toolsResponse = await makeMCPRequestWithTimeout(veltDocsMCPUrl, {
+        jsonrpc: '2.0',
+        method: 'tools/list',
+        id: 1,
+      }, 5000);
+
+      if (toolsResponse.error) {
+        throw new Error(toolsResponse.error.message);
+      }
+
+      const tools = toolsResponse.result?.tools || [];
+      console.error(`   ✓ Found ${tools.length} tools`);
+
+      // Find search/query tool
+      const searchTool = tools.find(t =>
+        t.name.toLowerCase().includes('search') ||
+        t.name.toLowerCase().includes('query') ||
+        t.name.toLowerCase().includes('docs')
+      ) || tools[0];
+
+      if (!searchTool) {
+        throw new Error('No search tool available');
+      }
+
+      console.error(`   Calling tool: ${searchTool.name}`);
+
+      // Call the tool with timeout
+      const toolResponse = await makeMCPRequestWithTimeout(veltDocsMCPUrl, {
+        jsonrpc: '2.0',
+        method: 'tools/call',
+        id: 2,
+        params: {
+          name: searchTool.name,
+          arguments: {
+            query: query,
+          },
+        },
+      }, 5000);
+
+      if (toolResponse.error) {
+        throw new Error(toolResponse.error.message);
+      }
+
+      return {
+        success: true,
+        data: toolResponse.result,
+        source: 'velt-docs-mcp',
+      };
+
+    } catch (error) {
+      lastError = error;
+      console.error(`   MCP query failed (attempt ${attempt + 1}/${maxRetries + 1}): ${error.message}`);
+
+      // Don't retry on certain errors
+      if (error.message.includes('No search tool available') ||
+          error.message.includes('Failed to parse response')) {
+        break;
+      }
+    }
+  }
+
+  // All retries failed
+  throw lastError || new Error('MCP query failed after all retries');
+}
+
+/**
+ * Makes MCP protocol request with guaranteed timeout using Promise.race()
+ *
+ * This ensures the request will ALWAYS timeout, even if the server
+ * is sending data slowly or the connection hangs.
+ *
+ * @param {string} url - MCP server URL
+ * @param {Object} data - JSON-RPC request data
+ * @param {number} timeoutMs - Timeout in milliseconds (default: 5000)
+ * @returns {Promise<Object>} MCP response
+ */
+function makeMCPRequestWithTimeout(url, data, timeoutMs = 5000) {
+  // Create a promise that rejects after timeout
+  const timeoutPromise = new Promise((_, reject) => {
+    setTimeout(() => {
+      reject(new Error(`Request timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+
+  // Create the actual request promise
+  const requestPromise = makeMCPRequest(url, data, timeoutMs);
+
+  // Race between request and timeout
+  return Promise.race([requestPromise, timeoutPromise]);
+}
+
+/**
+ * Makes MCP protocol request (internal)
+ *
+ * @param {string} url - MCP server URL
+ * @param {Object} data - JSON-RPC request data
+ * @param {number} socketTimeout - Socket-level timeout (default: 5000)
+ * @returns {Promise<Object>} MCP response
+ */
+function makeMCPRequest(url, data, socketTimeout = 5000) {
+  return new Promise((resolve, reject) => {
+    const urlObj = new URL(url);
+    const postData = JSON.stringify(data);
+
+    const options = {
+      hostname: urlObj.hostname,
+      port: urlObj.port || 443,
+      path: urlObj.pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+        'Content-Length': Buffer.byteLength(postData),
+      },
+      timeout: socketTimeout,
+    };
+
+    const req = https.request(options, (res) => {
+      let responseData = '';
+      let responseSize = 0;
+      const maxResponseSize = 10 * 1024 * 1024; // 10MB max response size
+
+      res.on('data', (chunk) => {
+        responseSize += chunk.length;
+
+        // Prevent memory exhaustion from huge responses
+        if (responseSize > maxResponseSize) {
+          req.destroy();
+          reject(new Error(`Response too large (exceeded ${maxResponseSize} bytes)`));
+          return;
+        }
+
+        responseData += chunk;
+      });
+
+      res.on('end', () => {
+        // Check for HTTP errors
+        if (res.statusCode !== 200) {
+          reject(new Error(`HTTP ${res.statusCode}: ${res.statusMessage}`));
+          return;
+        }
+
+        try {
+          const parsed = JSON.parse(responseData);
+          resolve(parsed);
+        } catch (error) {
+          reject(new Error(`Failed to parse response: ${error.message}`));
+        }
+      });
+    });
+
+    req.on('error', (error) => {
+      reject(new Error(`Request error: ${error.message}`));
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('Socket timeout'));
+    });
+
+    req.write(postData);
+    req.end();
+  });
+}
+