specweave 0.18.1 → 0.20.1

package/plugins/specweave-kafka/lib/mcp/detector.ts

@@ -0,0 +1,352 @@
+/**
+ * MCP Server Detector
+ *
+ * Auto-detects installed and running MCP servers for Kafka integration.
+ * Supports: kanapuli, tuannvm, Joel-hanson, Confluent
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import {
+  MCPServerType,
+  MCPServerInfo,
+  MCPDetectionResult,
+  MCPServerCapabilities,
+  AuthMethod
+} from './types';
+
+const execAsync = promisify(exec);
+
+export class MCPServerDetector {
+  /**
+   * Detect all available MCP servers
+   */
+  async detectAll(): Promise<MCPDetectionResult> {
+    const servers: MCPServerInfo[] = [];
+
+    // Check each MCP server type
+    const checks = [
+      this.detectKanapuli(),
+      this.detectTuannvm(),
+      this.detectJoelHanson(),
+      this.detectConfluent()
+    ];
+
+    const results = await Promise.allSettled(checks);
+
+    results.forEach((result) => {
+      if (result.status === 'fulfilled' && result.value) {
+        servers.push(result.value);
+      }
+    });
+
+    // Rank servers (Confluent > tuannvm > kanapuli > Joel-hanson)
+    const recommended = this.rankServers(servers);
+
+    return {
+      servers,
+      recommended: recommended?.type || null,
+      rankingReason: this.getRankingReason(recommended, servers)
+    };
+  }
+
+  /**
+   * Detect kanapuli/mcp-kafka server
+   */
+  private async detectKanapuli(): Promise<MCPServerInfo | null> {
+    try {
+      // Check if npm package installed
+      const { stdout } = await execAsync('npm list -g mcp-kafka --json 2>/dev/null || echo "{}"');
+      const packageInfo = JSON.parse(stdout);
+
+      const installed = !!packageInfo.dependencies?.['mcp-kafka'];
+
+      if (!installed) {
+        return {
+          type: MCPServerType.KANAPULI,
+          version: 'unknown',
+          installed: false,
+          running: false,
+          capabilities: this.getKanapuliCapabilities()
+        };
+      }
+
+      // Check if running (look for process)
+      const running = await this.isProcessRunning('mcp-kafka');
+      const version = packageInfo.dependencies?.['mcp-kafka']?.version || 'unknown';
+
+      return {
+        type: MCPServerType.KANAPULI,
+        version,
+        installed: true,
+        running,
+        capabilities: this.getKanapuliCapabilities(),
+        connectionDetails: running ? {
+          host: 'localhost',
+          port: 3000, // Default MCP port
+          protocol: 'http',
+          healthEndpoint: '/health',
+          infoEndpoint: '/info'
+        } : undefined
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Detect tuannvm/kafka-mcp-server (Go implementation)
+   */
+  private async detectTuannvm(): Promise<MCPServerInfo | null> {
+    try {
+      // Check if binary exists
+      const { stdout } = await execAsync('which kafka-mcp-server 2>/dev/null || echo ""');
+      const installed = !!stdout.trim();
+
+      if (!installed) {
+        return {
+          type: MCPServerType.TUANNVM,
+          version: 'unknown',
+          installed: false,
+          running: false,
+          capabilities: this.getTuannvmCapabilities()
+        };
+      }
+
+      // Check if running
+      const running = await this.isProcessRunning('kafka-mcp-server');
+
+      // Try to get version
+      let version = 'unknown';
+      try {
+        const { stdout: versionOut } = await execAsync('kafka-mcp-server --version 2>/dev/null');
+        version = versionOut.trim();
+      } catch {}
+
+      return {
+        type: MCPServerType.TUANNVM,
+        version,
+        installed: true,
+        running,
+        capabilities: this.getTuannvmCapabilities(),
+        connectionDetails: running ? {
+          host: 'localhost',
+          port: 8080, // Default port
+          protocol: 'http'
+        } : undefined
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Detect Joel-hanson/kafka-mcp-server
+   */
+  private async detectJoelHanson(): Promise<MCPServerInfo | null> {
+    try {
+      // Check if Python package installed
+      const { stdout } = await execAsync('pip show kafka-mcp-server 2>/dev/null || echo ""');
+      const installed = stdout.includes('Name: kafka-mcp-server');
+
+      if (!installed) {
+        return {
+          type: MCPServerType.JOEL_HANSON,
+          version: 'unknown',
+          installed: false,
+          running: false,
+          capabilities: this.getJoelHansonCapabilities()
+        };
+      }
+
+      // Extract version
+      const versionMatch = stdout.match(/Version: ([\d.]+)/);
+      const version = versionMatch ? versionMatch[1] : 'unknown';
+
+      // Check if running
+      const running = await this.isProcessRunning('kafka-mcp-server');
+
+      return {
+        type: MCPServerType.JOEL_HANSON,
+        version,
+        installed: true,
+        running,
+        capabilities: this.getJoelHansonCapabilities(),
+        connectionDetails: running ? {
+          host: 'localhost',
+          port: 5000, // Default Python MCP port
+          protocol: 'http'
+        } : undefined
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Detect Confluent official MCP server
+   */
+  private async detectConfluent(): Promise<MCPServerInfo | null> {
+    try {
+      // Confluent MCP is typically part of Confluent Cloud CLI
+      const { stdout } = await execAsync('confluent version 2>/dev/null || echo ""');
+      const installed = !!stdout.trim();
+
+      if (!installed) {
+        return {
+          type: MCPServerType.CONFLUENT,
+          version: 'unknown',
+          installed: false,
+          running: false,
+          capabilities: this.getConfluentCapabilities()
+        };
+      }
+
+      // Extract version
+      const versionMatch = stdout.match(/Version:\s+([\d.]+)/);
+      const version = versionMatch ? versionMatch[1] : 'unknown';
+
+      // Confluent MCP runs as part of CLI, check if CLI is authenticated
+      let running = false;
+      try {
+        const { stdout: authOut } = await execAsync('confluent auth current 2>/dev/null');
+        running = authOut.includes('Logged in as');
+      } catch {}
+
+      return {
+        type: MCPServerType.CONFLUENT,
+        version,
+        installed: true,
+        running,
+        capabilities: this.getConfluentCapabilities()
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Check if process is running
+   */
+  private async isProcessRunning(processName: string): Promise<boolean> {
+    try {
+      const { stdout } = await execAsync(`ps aux | grep "${processName}" | grep -v grep || echo ""`);
+      return !!stdout.trim();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Rank servers by priority (Confluent > tuannvm > kanapuli > Joel-hanson)
+   */
+  private rankServers(servers: MCPServerInfo[]): MCPServerInfo | null {
+    const ranking = [
+      MCPServerType.CONFLUENT,
+      MCPServerType.TUANNVM,
+      MCPServerType.KANAPULI,
+      MCPServerType.JOEL_HANSON
+    ];
+
+    // Find highest-ranked installed server
+    for (const type of ranking) {
+      const server = servers.find(s => s.type === type && s.installed);
+      if (server) return server;
+    }
+
+    return null;
+  }
+
+  /**
+   * Get ranking reason
+   */
+  private getRankingReason(recommended: MCPServerInfo | null, servers: MCPServerInfo[]): string {
+    if (!recommended) {
+      return 'No MCP servers installed';
+    }
+
+    const reasons: Record<MCPServerType, string> = {
+      [MCPServerType.CONFLUENT]: 'Confluent official MCP (best features: natural language, Flink SQL)',
+      [MCPServerType.TUANNVM]: 'Go implementation (advanced SASL: SCRAM-SHA-256/512)',
+      [MCPServerType.KANAPULI]: 'Node.js implementation (basic operations, SASL_PLAINTEXT)',
+      [MCPServerType.JOEL_HANSON]: 'Python implementation (Claude Desktop integration)'
+    };
+
+    return reasons[recommended.type];
+  }
+
+  /**
+   * Get capabilities for each MCP server type
+   */
+  private getKanapuliCapabilities(): MCPServerCapabilities {
+    return {
+      authentication: [AuthMethod.SASL_PLAINTEXT, AuthMethod.PLAINTEXT],
+      operations: ['produce', 'consume', 'list-topics', 'describe-topic', 'get-offsets'],
+      advancedFeatures: []
+    };
+  }
+
+  private getTuannvmCapabilities(): MCPServerCapabilities {
+    return {
+      authentication: [
+        AuthMethod.SASL_SCRAM_SHA_256,
+        AuthMethod.SASL_SCRAM_SHA_512,
+        AuthMethod.SASL_PLAINTEXT,
+        AuthMethod.SASL_SSL,
+        AuthMethod.PLAINTEXT
+      ],
+      operations: [
+        'produce',
+        'consume',
+        'list-topics',
+        'create-topic',
+        'delete-topic',
+        'describe-topic',
+        'list-consumer-groups',
+        'describe-consumer-group',
+        'get-offsets',
+        'reset-offsets'
+      ],
+      advancedFeatures: ['consumer-group-management', 'offset-management']
+    };
+  }
+
+  private getJoelHansonCapabilities(): MCPServerCapabilities {
+    return {
+      authentication: [AuthMethod.SASL_PLAINTEXT, AuthMethod.PLAINTEXT, AuthMethod.SSL],
+      operations: ['produce', 'consume', 'list-topics', 'describe-topic'],
+      advancedFeatures: ['claude-desktop-integration']
+    };
+  }
+
+  private getConfluentCapabilities(): MCPServerCapabilities {
+    return {
+      authentication: [
+        AuthMethod.OAUTH,
+        AuthMethod.SASL_SCRAM_SHA_256,
+        AuthMethod.SASL_SCRAM_SHA_512,
+        AuthMethod.SASL_SSL
+      ],
+      operations: [
+        'produce',
+        'consume',
+        'list-topics',
+        'create-topic',
+        'delete-topic',
+        'describe-topic',
+        'list-consumer-groups',
+        'describe-consumer-group',
+        'schema-registry-operations',
+        'ksqldb-query',
+        'flink-sql-query'
+      ],
+      advancedFeatures: [
+        'natural-language-interface',
+        'schema-registry',
+        'ksqldb',
+        'flink-sql',
+        'cloud-managed'
+      ]
+    };
+  }
+}

package/plugins/specweave-kafka/lib/mcp/types.js

@@ -0,0 +1,21 @@
+var MCPServerType = /* @__PURE__ */ ((MCPServerType2) => {
+  MCPServerType2["KANAPULI"] = "kanapuli";
+  MCPServerType2["TUANNVM"] = "tuannvm";
+  MCPServerType2["JOEL_HANSON"] = "joel-hanson";
+  MCPServerType2["CONFLUENT"] = "confluent";
+  return MCPServerType2;
+})(MCPServerType || {});
+var AuthMethod = /* @__PURE__ */ ((AuthMethod2) => {
+  AuthMethod2["SASL_PLAINTEXT"] = "SASL_PLAINTEXT";
+  AuthMethod2["SASL_SCRAM_SHA_256"] = "SASL/SCRAM-SHA-256";
+  AuthMethod2["SASL_SCRAM_SHA_512"] = "SASL/SCRAM-SHA-512";
+  AuthMethod2["SASL_SSL"] = "SASL_SSL";
+  AuthMethod2["SSL"] = "SSL";
+  AuthMethod2["PLAINTEXT"] = "PLAINTEXT";
+  AuthMethod2["OAUTH"] = "OAUTH";
+  return AuthMethod2;
+})(AuthMethod || {});
+export {
+  AuthMethod,
+  MCPServerType
+};

package/plugins/specweave-kafka/lib/mcp/types.ts

@@ -0,0 +1,77 @@
+/**
+ * MCP Server Types and Interfaces
+ *
+ * Defines types for MCP server detection, configuration, and operations.
+ */
+
+export enum MCPServerType {
+  KANAPULI = 'kanapuli',
+  TUANNVM = 'tuannvm',
+  JOEL_HANSON = 'joel-hanson',
+  CONFLUENT = 'confluent'
+}
+
+export interface MCPServerInfo {
+  type: MCPServerType;
+  version: string;
+  installed: boolean;
+  running: boolean;
+  capabilities: MCPServerCapabilities;
+  connectionDetails?: MCPConnectionDetails;
+}
+
+export interface MCPServerCapabilities {
+  authentication: AuthMethod[];
+  operations: string[];
+  advancedFeatures: string[];
+}
+
+export enum AuthMethod {
+  SASL_PLAINTEXT = 'SASL_PLAINTEXT',
+  SASL_SCRAM_SHA_256 = 'SASL/SCRAM-SHA-256',
+  SASL_SCRAM_SHA_512 = 'SASL/SCRAM-SHA-512',
+  SASL_SSL = 'SASL_SSL',
+  SSL = 'SSL',
+  PLAINTEXT = 'PLAINTEXT',
+  OAUTH = 'OAUTH'
+}
+
+export interface MCPConnectionDetails {
+  host: string;
+  port: number;
+  protocol: string;
+  healthEndpoint?: string;
+  infoEndpoint?: string;
+}
+
+export interface MCPServerConfig {
+  serverType: MCPServerType;
+  brokerUrls: string[];
+  authentication: {
+    mechanism: AuthMethod;
+    username?: string;
+    password?: string;
+    saslMechanism?: string;
+    sslCertPath?: string;
+    sslKeyPath?: string;
+    sslCaPath?: string;
+  };
+  options?: Record<string, any>;
+}
+
+export interface MCPDetectionResult {
+  servers: MCPServerInfo[];
+  recommended: MCPServerType | null;
+  rankingReason: string;
+}
+
+export interface MCPOperationResult {
+  success: boolean;
+  data?: any;
+  error?: string;
+  metadata?: {
+    serverType: MCPServerType;
+    operation: string;
+    duration: number;
+  };
+}

package/plugins/specweave-kafka/lib/multi-cluster/cluster-config-manager.js

@@ -0,0 +1,193 @@
+import * as fs from "fs";
+import * as path from "path";
+class ClusterConfigManager {
+  constructor(configFilePath = path.join(process.cwd(), ".kafka-clusters.json")) {
+    this.configFilePath = configFilePath;
+    this.config = this.loadConfig();
+  }
+  /**
+   * Load configuration from file
+   */
+  loadConfig() {
+    if (fs.existsSync(this.configFilePath)) {
+      const data = fs.readFileSync(this.configFilePath, "utf-8");
+      return JSON.parse(data);
+    }
+    return {
+      activeClusterId: "dev",
+      clusters: [
+        {
+          id: "dev",
+          name: "Development",
+          environment: "dev",
+          bootstrapServers: ["localhost:9092"],
+          securityProtocol: "PLAINTEXT",
+          cloudProvider: "Self-Hosted"
+        }
+      ]
+    };
+  }
+  /**
+   * Save configuration to file
+   */
+  saveConfig() {
+    fs.writeFileSync(
+      this.configFilePath,
+      JSON.stringify(this.config, null, 2),
+      "utf-8"
+    );
+  }
+  /**
+   * Add cluster configuration
+   */
+  addCluster(cluster) {
+    if (this.config.clusters.some((c) => c.id === cluster.id)) {
+      throw new Error(`Cluster with ID "${cluster.id}" already exists`);
+    }
+    this.config.clusters.push(cluster);
+    this.saveConfig();
+  }
+  /**
+   * Update cluster configuration
+   */
+  updateCluster(clusterId, updates) {
+    const index = this.config.clusters.findIndex((c) => c.id === clusterId);
+    if (index === -1) {
+      throw new Error(`Cluster "${clusterId}" not found`);
+    }
+    this.config.clusters[index] = {
+      ...this.config.clusters[index],
+      ...updates,
+      id: clusterId
+      // Prevent ID change
+    };
+    this.saveConfig();
+  }
+  /**
+   * Remove cluster configuration
+   */
+  removeCluster(clusterId) {
+    if (clusterId === this.config.activeClusterId) {
+      throw new Error(`Cannot remove active cluster "${clusterId}". Switch to another cluster first.`);
+    }
+    const index = this.config.clusters.findIndex((c) => c.id === clusterId);
+    if (index === -1) {
+      throw new Error(`Cluster "${clusterId}" not found`);
+    }
+    this.config.clusters.splice(index, 1);
+    this.saveConfig();
+  }
+  /**
+   * Get cluster configuration
+   */
+  getCluster(clusterId) {
+    return this.config.clusters.find((c) => c.id === clusterId);
+  }
+  /**
+   * Get all clusters
+   */
+  getAllClusters() {
+    return [...this.config.clusters];
+  }
+  /**
+   * Get clusters by environment
+   */
+  getClustersByEnvironment(environment) {
+    return this.config.clusters.filter((c) => c.environment === environment);
+  }
+  /**
+   * Get active cluster ID
+   */
+  getActiveClusterId() {
+    return this.config.activeClusterId;
+  }
+  /**
+   * Get active cluster configuration
+   */
+  getActiveCluster() {
+    const cluster = this.getCluster(this.config.activeClusterId);
+    if (!cluster) {
+      throw new Error(`Active cluster "${this.config.activeClusterId}" not found`);
+    }
+    return cluster;
+  }
+  /**
+   * Set active cluster
+   */
+  setActiveCluster(clusterId) {
+    const cluster = this.getCluster(clusterId);
+    if (!cluster) {
+      throw new Error(`Cluster "${clusterId}" not found`);
+    }
+    this.config.activeClusterId = clusterId;
+    this.saveConfig();
+  }
+  /**
+   * Export configuration as JSON
+   */
+  exportConfig() {
+    return JSON.stringify(this.config, null, 2);
+  }
+  /**
+   * Import configuration from JSON
+   */
+  importConfig(jsonConfig) {
+    const imported = JSON.parse(jsonConfig);
+    if (!imported.activeClusterId || !Array.isArray(imported.clusters)) {
+      throw new Error("Invalid configuration format");
+    }
+    if (!imported.clusters.some((c) => c.id === imported.activeClusterId)) {
+      throw new Error(`Active cluster "${imported.activeClusterId}" not found in imported clusters`);
+    }
+    this.config = imported;
+    this.saveConfig();
+  }
+  /**
+   * Generate kafkajs client config for active cluster
+   */
+  getKafkaJSConfig() {
+    const cluster = this.getActiveCluster();
+    const config = {
+      clientId: `kafka-client-${cluster.id}`,
+      brokers: cluster.bootstrapServers
+    };
+    if (cluster.securityProtocol !== "PLAINTEXT") {
+      config.ssl = cluster.securityProtocol === "SSL" || cluster.securityProtocol === "SASL_SSL" ? {
+        rejectUnauthorized: true,
+        ...cluster.sslCaPath && { ca: [fs.readFileSync(cluster.sslCaPath)] },
+        ...cluster.sslCertPath && { cert: [fs.readFileSync(cluster.sslCertPath)] },
+        ...cluster.sslKeyPath && { key: [fs.readFileSync(cluster.sslKeyPath)] }
+      } : void 0;
+      if (cluster.securityProtocol.startsWith("SASL")) {
+        config.sasl = {
+          mechanism: cluster.saslMechanism || "PLAIN",
+          username: cluster.saslUsername || "",
+          password: cluster.saslPassword || ""
+        };
+      }
+    }
+    return config;
+  }
+  /**
+   * Validate cluster connectivity
+   */
+  async validateCluster(clusterId) {
+    const cluster = this.getCluster(clusterId);
+    if (!cluster) {
+      return { valid: false, error: `Cluster "${clusterId}" not found` };
+    }
+    try {
+      if (!cluster.bootstrapServers || cluster.bootstrapServers.length === 0) {
+        return { valid: false, error: "No bootstrap servers configured" };
+      }
+      return { valid: true };
+    } catch (error) {
+      return { valid: false, error: error.message };
+    }
+  }
+}
+var cluster_config_manager_default = ClusterConfigManager;
+export {
+  ClusterConfigManager,
+  cluster_config_manager_default as default
+};