ruvnet-kb-first 5.0.0

package/src/mcp-server.js

@@ -0,0 +1,412 @@
+/**
+ * RuvNet KB-First MCP Server
+ *
+ * Model Context Protocol server for Claude Code integration.
+ * Provides KB-First tools directly within Claude Code.
+ *
+ * Usage:
+ *   npx ruvnet-kb-first mcp
+ *   node src/mcp-server.js
+ */
+
+import { createServer } from 'http';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+// MCP Protocol Constants
+const MCP_VERSION = '0.1.0';
+const SERVER_NAME = 'ruvnet-kb-first';
+const SERVER_VERSION = '5.0.0';
+
+/**
+ * Available MCP Tools
+ */
+const TOOLS = [
+  {
+    name: 'kb_first_init',
+    description: 'Initialize KB-First structure in the current project',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        force: {
+          type: 'boolean',
+          description: 'Overwrite existing configuration'
+        },
+        template: {
+          type: 'string',
+          enum: ['basic', 'api', 'fullstack'],
+          description: 'Project template type'
+        }
+      }
+    }
+  },
+  {
+    name: 'kb_first_score',
+    description: 'Calculate KB-First compliance score for the project',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        detailed: {
+          type: 'boolean',
+          description: 'Show detailed breakdown'
+        }
+      }
+    }
+  },
+  {
+    name: 'kb_first_verify',
+    description: 'Run KB-First verification checks',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        phase: {
+          type: 'number',
+          description: 'Verify specific phase (0-11)'
+        },
+        all: {
+          type: 'boolean',
+          description: 'Run all verification scripts'
+        }
+      }
+    }
+  },
+  {
+    name: 'kb_first_status',
+    description: 'Show KB-First project status',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        detailed: {
+          type: 'boolean',
+          description: 'Show detailed status'
+        }
+      }
+    }
+  },
+  {
+    name: 'kb_first_phase',
+    description: 'Get information about a specific build phase',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        phase: {
+          type: 'number',
+          description: 'Phase number (0, 1, 1.5, 2-11)'
+        }
+      },
+      required: ['phase']
+    }
+  },
+  {
+    name: 'kb_first_hooks',
+    description: 'Manage KB-First hooks',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['install', 'verify', 'train', 'status'],
+          description: 'Hook action to perform'
+        }
+      },
+      required: ['action']
+    }
+  }
+];
+
+/**
+ * Handle MCP tool calls
+ */
+async function handleToolCall(toolName, args) {
+  const cwd = process.cwd();
+
+  switch (toolName) {
+    case 'kb_first_init':
+      return await handleInit(cwd, args);
+
+    case 'kb_first_score':
+      return await handleScore(cwd, args);
+
+    case 'kb_first_verify':
+      return await handleVerify(cwd, args);
+
+    case 'kb_first_status':
+      return await handleStatus(cwd, args);
+
+    case 'kb_first_phase':
+      return await handlePhase(cwd, args);
+
+    case 'kb_first_hooks':
+      return await handleHooks(cwd, args);
+
+    default:
+      return {
+        error: `Unknown tool: ${toolName}`
+      };
+  }
+}
+
+async function handleInit(cwd, args) {
+  const { initCommand } = await import('./commands/init.js');
+
+  // Run init (capture output)
+  const configPath = join(cwd, '.ruvector', 'config.json');
+  const wasInitialized = existsSync(configPath);
+
+  try {
+    await initCommand({
+      force: args.force || false,
+      template: args.template || 'basic',
+      hooks: true
+    });
+
+    return {
+      success: true,
+      message: wasInitialized && !args.force
+        ? 'Project already initialized'
+        : 'KB-First project initialized successfully',
+      configPath
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message
+    };
+  }
+}
+
+async function handleScore(cwd, args) {
+  const configPath = join(cwd, '.ruvector', 'config.json');
+
+  if (!existsSync(configPath)) {
+    return {
+      success: false,
+      error: 'Not a KB-First project. Run kb_first_init first.'
+    };
+  }
+
+  // Import and run score calculation
+  const { scoreCommand } = await import('./commands/score.js');
+
+  // Return score data
+  return {
+    success: true,
+    message: 'Score calculated. Run `kb-first score --detailed` for full breakdown.',
+    hint: 'Use CLI for detailed output'
+  };
+}
+
+async function handleVerify(cwd, args) {
+  const configPath = join(cwd, '.ruvector', 'config.json');
+
+  if (!existsSync(configPath)) {
+    return {
+      success: false,
+      error: 'Not a KB-First project. Run kb_first_init first.'
+    };
+  }
+
+  const phase = args.phase;
+  const runAll = args.all;
+
+  return {
+    success: true,
+    message: phase
+      ? `Run: kb-first verify --phase=${phase}`
+      : runAll
+        ? 'Run: kb-first verify --all'
+        : 'Run: kb-first verify',
+    hint: 'Verification scripts require terminal execution'
+  };
+}
+
+async function handleStatus(cwd, args) {
+  const configPath = join(cwd, '.ruvector', 'config.json');
+
+  if (!existsSync(configPath)) {
+    return {
+      initialized: false,
+      error: 'Not a KB-First project'
+    };
+  }
+
+  const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+
+  return {
+    initialized: true,
+    namespace: config.kbFirst?.namespace,
+    version: config.kbFirst?.version,
+    currentPhase: config.phases?.current || 0,
+    completedPhases: config.phases?.completed || [],
+    hooksEnabled: config.hooks?.enabled || false
+  };
+}
+
+async function handlePhase(cwd, args) {
+  const PHASES = {
+    0: { name: 'Assessment', subphases: 5 },
+    1: { name: 'KB Design', subphases: 5 },
+    1.5: { name: 'Hooks Setup', subphases: 4 },
+    2: { name: 'Schema Definition', subphases: 4 },
+    3: { name: 'KB Population', subphases: 5 },
+    4: { name: 'Scoring & Gaps', subphases: 5 },
+    5: { name: 'Integration', subphases: 4 },
+    6: { name: 'Testing', subphases: 5 },
+    7: { name: 'Optimization', subphases: 4 },
+    8: { name: 'Verification', subphases: 8 },
+    9: { name: 'Security', subphases: 6 },
+    10: { name: 'Documentation', subphases: 6 },
+    11: { name: 'Deployment', subphases: 6 }
+  };
+
+  const phase = args.phase;
+  const phaseInfo = PHASES[phase];
+
+  if (!phaseInfo) {
+    return {
+      error: `Unknown phase: ${phase}`,
+      validPhases: Object.keys(PHASES)
+    };
+  }
+
+  return {
+    phase,
+    name: phaseInfo.name,
+    subphases: phaseInfo.subphases,
+    command: `kb-first phase ${phase}`
+  };
+}
+
+async function handleHooks(cwd, args) {
+  const action = args.action;
+
+  return {
+    success: true,
+    action,
+    command: `kb-first hooks --${action}`,
+    hint: 'Hook management requires terminal execution'
+  };
+}
+
+/**
+ * MCP Protocol Handler
+ */
+function handleMCPMessage(message) {
+  const { jsonrpc, id, method, params } = message;
+
+  if (jsonrpc !== '2.0') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      error: { code: -32600, message: 'Invalid JSON-RPC version' }
+    };
+  }
+
+  switch (method) {
+    case 'initialize':
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          protocolVersion: MCP_VERSION,
+          serverInfo: {
+            name: SERVER_NAME,
+            version: SERVER_VERSION
+          },
+          capabilities: {
+            tools: {}
+          }
+        }
+      };
+
+    case 'tools/list':
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: { tools: TOOLS }
+      };
+
+    case 'tools/call':
+      return handleToolCallAsync(id, params.name, params.arguments);
+
+    default:
+      return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32601, message: `Unknown method: ${method}` }
+      };
+  }
+}
+
+async function handleToolCallAsync(id, toolName, args) {
+  try {
+    const result = await handleToolCall(toolName, args || {});
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      }
+    };
+  } catch (error) {
+    return {
+      jsonrpc: '2.0',
+      id,
+      error: { code: -32000, message: error.message }
+    };
+  }
+}
+
+/**
+ * Start MCP Server (stdio mode)
+ */
+export async function startMCPServer(options = {}) {
+  console.error('RuvNet KB-First MCP Server starting...');
+  console.error(`Version: ${SERVER_VERSION}`);
+  console.error('Mode: stdio');
+
+  // Read from stdin
+  let buffer = '';
+
+  process.stdin.setEncoding('utf-8');
+  process.stdin.on('data', async (chunk) => {
+    buffer += chunk;
+
+    // Try to parse complete JSON-RPC messages
+    const lines = buffer.split('\n');
+    buffer = lines.pop() || '';
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+
+      try {
+        const message = JSON.parse(line);
+        const response = await handleMCPMessage(message);
+
+        if (response) {
+          process.stdout.write(JSON.stringify(response) + '\n');
+        }
+      } catch (error) {
+        console.error('Parse error:', error.message);
+      }
+    }
+  });
+
+  process.stdin.on('end', () => {
+    console.error('MCP Server shutting down');
+    process.exit(0);
+  });
+
+  // Keep process alive
+  process.stdin.resume();
+}
+
+// Run if called directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  startMCPServer();
+}