@next-vibe/checker 1.0.11 → 1.0.13

package/src/app/api/[locale]/system/unified-interface/mcp/serve/route.ts

@@ -0,0 +1,14 @@
+import { endpointsHandler } from "@/app/api/[locale]/system/unified-interface/shared/endpoints/route/multi";
+import { Methods } from "@/app/api/[locale]/system/unified-interface/shared/types/enums";
+
+import serveDefinition from "./definition";
+import { mcpServeRepository } from "./repository";
+
+export const { POST, tools } = endpointsHandler({
+  endpoint: serveDefinition,
+  [Methods.POST]: {
+    handler: async ({ logger, locale }) => {
+      return await mcpServeRepository.startServer(logger, locale);
+    },
+  },
+});

package/src/app/api/[locale]/system/unified-interface/mcp/server/protocol-handler.ts

@@ -0,0 +1,309 @@
+/**
+ * MCP Protocol Handler
+ * Handles MCP JSON-RPC 2.0 protocol messages
+ */
+
+import "server-only";
+
+import { parseError } from "next-vibe/shared/utils";
+
+import { getCliUser } from "@/app/api/[locale]/system/unified-interface/cli/auth/cli-user";
+import type { JwtPayloadType } from "@/app/api/[locale]/user/auth/types";
+import type { CountryLanguage } from "@/i18n/core/config";
+
+import type { EndpointLogger } from "../../shared/logger/endpoint";
+import { Platform } from "../../shared/types/platform";
+import { endpointToMCPTool } from "../converter";
+import { mcpRegistry } from "../registry";
+import type {
+  IMCPProtocolHandler,
+  JsonRpcError,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  MCPInitializeParams,
+  MCPInitializeResult,
+  MCPToolCallParams,
+  MCPToolCallResult,
+  MCPToolsListParams,
+  MCPToolsListResult,
+  ParameterValue,
+} from "../types";
+import { MCPErrorCode, MCPMethod } from "../types";
+
+/**
+ * MCP Protocol Handler Implementation
+ */
+export class MCPProtocolHandler implements IMCPProtocolHandler {
+  private initialized = false;
+  private logger: EndpointLogger;
+  private locale: CountryLanguage;
+  private user: JwtPayloadType;
+
+  constructor(
+    logger: EndpointLogger,
+    locale: CountryLanguage,
+    user: JwtPayloadType,
+  ) {
+    this.logger = logger;
+    this.locale = locale;
+    this.user = user;
+  }
+
+  /**
+   * Handle incoming JSON-RPC request
+   */
+  async handleRequest(
+    // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Infrastructure: Protocol message handling requires 'unknown' for flexible message types
+    request: JsonRpcRequest<unknown>,
+  ): Promise<JsonRpcResponse> {
+    this.logger.debug("[MCP Protocol] Received request", {
+      method: request.method,
+      id: request.id,
+    });
+
+    try {
+      // Validate JSON-RPC version
+      if (request.jsonrpc !== "2.0") {
+        return this.fail(
+          request.id ?? null,
+          MCPErrorCode.INVALID_REQUEST,
+          "Invalid JSON-RPC version",
+        );
+      }
+
+      // Route to appropriate handler
+
+      // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Infrastructure: Request parsing requires 'unknown' for untrusted input
+      let result: unknown;
+
+      switch (request.method) {
+        case MCPMethod.INITIALIZE:
+          result = await this.handleInitialize(
+            request.params as MCPInitializeParams,
+          );
+          this.initialized = true;
+          break;
+
+        case MCPMethod.PING:
+          result = await this.handlePing();
+          break;
+
+        case MCPMethod.TOOLS_LIST:
+          if (!this.initialized) {
+            return this.fail(
+              request.id ?? null,
+              MCPErrorCode.INVALID_REQUEST,
+              // eslint-disable-next-line i18next/no-literal-string
+              "Server not initialized. Call initialize first.",
+            );
+          }
+          result = await this.handleToolsList(
+            request.params as MCPToolsListParams,
+          );
+          break;
+
+        case MCPMethod.TOOLS_CALL:
+          if (!this.initialized) {
+            return this.fail(
+              request.id ?? null,
+              MCPErrorCode.INVALID_REQUEST,
+              // eslint-disable-next-line i18next/no-literal-string
+              "Server not initialized. Call initialize first.",
+            );
+          }
+          result = await this.handleToolCall(
+            request.params as MCPToolCallParams,
+          );
+          break;
+
+        default:
+          return this.fail(
+            request.id ?? null,
+            MCPErrorCode.METHOD_NOT_FOUND,
+            // eslint-disable-next-line i18next/no-literal-string
+            `Method not found: ${request.method}`,
+          );
+      }
+
+      return this.success(request.id ?? null, result);
+    } catch (error) {
+      const parsedError = parseError(error);
+      this.logger.error("[MCP Protocol] Request handling failed", {
+        method: request.method,
+        error: parsedError.message,
+      });
+
+      return this.fail(
+        request.id ?? null,
+        MCPErrorCode.INTERNAL_ERROR,
+        parsedError.message,
+      );
+    }
+  }
+
+  /**
+   * Handle initialize request
+   */
+  async handleInitialize(
+    params: MCPInitializeParams,
+  ): Promise<MCPInitializeResult> {
+    this.logger.info("[MCP Protocol] Initializing", {
+      clientName: params.clientInfo.name,
+      clientVersion: params.clientInfo.version,
+      protocolVersion: params.protocolVersion,
+    });
+
+    // Initialize registry
+    await mcpRegistry.initialize(this.logger, this.locale);
+
+    const capabilities = {
+      tools: true,
+      prompts: false,
+      resources: false,
+    };
+
+    return {
+      protocolVersion: "2024-11-05",
+      capabilities: {
+        tools: capabilities.tools ? { listChanged: false } : undefined,
+        prompts: capabilities.prompts ? { listChanged: false } : undefined,
+        resources: capabilities.resources ? { subscribe: false } : undefined,
+      },
+      serverInfo: {
+        // eslint-disable-next-line i18next/no-literal-string
+        name: "Vibe MCP Server",
+        version: "1.0.0",
+      },
+    };
+  }
+
+  /**
+   * Handle tools/list request
+   */
+  async handleToolsList(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _params: MCPToolsListParams,
+  ): Promise<MCPToolsListResult> {
+    this.logger.info("[MCP Protocol] Listing tools");
+
+    // Get full endpoints with field information for proper schema generation
+    const endpoints = mcpRegistry.getEndpoints(this.user, this.logger);
+
+    // Convert to MCP tool format with proper JSON Schema and translated descriptions
+    const tools = endpoints.map((endpoint) =>
+      endpointToMCPTool(endpoint, this.locale),
+    );
+
+    this.logger.info("[MCP Protocol] Tools listed", {
+      count: tools.length,
+    });
+
+    return {
+      tools,
+      // No pagination for now
+    };
+  }
+
+  /**
+   * Handle tools/call request
+   */
+  async handleToolCall(params: MCPToolCallParams): Promise<MCPToolCallResult> {
+    this.logger.info("[MCP Protocol] Calling tool", {
+      toolName: params.name,
+    });
+
+    // Execute tool - params.arguments is already properly typed from MCPToolCallParams
+    const result = await mcpRegistry.executeTool(
+      {
+        toolName: params.name,
+        data: params.arguments || {},
+        user: this.user,
+        locale: this.locale,
+        requestId: Date.now(),
+        timestamp: Date.now(),
+        logger: this.logger,
+        platform: Platform.MCP,
+      },
+      this.logger,
+    );
+
+    this.logger.info("[MCP Protocol] Tool call complete", {
+      toolName: params.name,
+      isError: result.isError,
+    });
+
+    return result;
+  }
+
+  /**
+   * Handle ping request
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async handlePing(): Promise<Record<string, never>> {
+    this.logger.debug("[MCP Protocol] Ping");
+    return {};
+  }
+
+  /**
+   * Create success response
+   */
+  private success(
+    id: string | number | null,
+
+    // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Infrastructure: Response serialization requires 'unknown' for flexible response types
+    result: unknown,
+  ): JsonRpcResponse {
+    return {
+      jsonrpc: "2.0",
+      result,
+      id,
+    };
+  }
+
+  /**
+   * Create error response
+   */
+  private fail(
+    id: string | number | null,
+    code: MCPErrorCode,
+    message: string,
+    data?: Record<string, ParameterValue>,
+  ): JsonRpcResponse {
+    const error: JsonRpcError = {
+      code,
+      message,
+      data,
+    };
+
+    return {
+      jsonrpc: "2.0",
+      error,
+      id,
+    };
+  }
+}
+
+/**
+ * Create protocol handler with CLI user
+ */
+export async function createMCPProtocolHandler(
+  logger: EndpointLogger,
+  locale: CountryLanguage,
+): Promise<MCPProtocolHandler> {
+  // Get CLI user for authentication using consolidated factory
+  const cliUserResult = await getCliUser(logger, locale);
+
+  if (!cliUserResult.success) {
+    // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax, i18next/no-literal-string -- MCP server infrastructure requires throwing for invalid CLI user state
+    throw new Error(`CLI user authentication failed: ${cliUserResult.message}`);
+  }
+
+  const cliUser = cliUserResult.data;
+
+  if (!cliUser.isPublic && !cliUser.id) {
+    // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax, i18next/no-literal-string -- MCP server infrastructure requires throwing for invalid CLI user state
+    throw new Error("CLI user ID is required");
+  }
+
+  return new MCPProtocolHandler(logger, locale, cliUser);
+}

package/src/app/api/[locale]/system/unified-interface/mcp/server/server.ts

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * MCP Server Entry Point
+ * Main server class that ties together transport and protocol handler
+ */
+
+import "server-only";
+
+import { parseError } from "next-vibe/shared/utils/parse-error";
+
+import type { CountryLanguage } from "@/i18n/core/config";
+
+import type { EndpointLogger } from "../../shared/logger/endpoint";
+import { createMCPProtocolHandler } from "./protocol-handler";
+import { StdioTransport } from "./stdio-transport";
+
+/**
+ * MCP Server
+ */
+export class MCPServer {
+  private transport?: StdioTransport;
+  private running = false;
+
+  /**
+   * Start the MCP server
+   */
+  async start(logger: EndpointLogger, locale: CountryLanguage): Promise<void> {
+    if (this.running) {
+      logger.warn("[MCP Server] Server already running");
+      return;
+    }
+
+    const isMCPServerEnabled = process.env.VIBE_MCP_DISABLED !== "true";
+    if (!isMCPServerEnabled) {
+      logger.error("[MCP Server] MCP server is disabled");
+      // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax, i18next/no-literal-string -- MCP server infrastructure requires throwing for disabled server
+      throw new Error("MCP server is disabled");
+    }
+
+    try {
+      logger.info("[MCP Server] Starting...");
+
+      logger.info("[MCP Server] Configuration", {
+        // eslint-disable-next-line i18next/no-literal-string
+        name: "Vibe MCP Server",
+        version: "1.0.0",
+        locale: locale,
+        debug: logger.isDebugEnabled,
+      });
+
+      // Create protocol handler
+      const protocolHandler = await createMCPProtocolHandler(logger, locale);
+
+      // Create transport
+      this.transport = new StdioTransport(logger);
+
+      // Connect transport to protocol handler
+      this.transport.onMessage(async (request) => {
+        const response = await protocolHandler.handleRequest(request);
+
+        // Only send response if request had an ID (not a notification)
+        // JSON-RPC 2.0: notifications (id: null) must not receive responses
+        if (request.id !== null && request.id !== undefined) {
+          await this.transport!.send(response);
+        }
+      });
+
+      // Start transport
+      await this.transport.start();
+
+      this.running = true;
+      logger.info("[MCP Server] Server started successfully");
+
+      // Setup graceful shutdown
+      this.setupShutdownHandlers(logger);
+
+      // Keep process alive
+      await this.keepAlive();
+    } catch (error) {
+      logger.error("[MCP Server] Failed to start", {
+        error: parseError(error).message,
+      });
+      // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Re-throw MCP server startup errors for caller to handle
+      throw error;
+    }
+  }
+
+  /**
+   * Stop the MCP server
+   */
+  async stop(logger: EndpointLogger): Promise<void> {
+    if (!this.running) {
+      return;
+    }
+
+    logger.info("[MCP Server] Stopping...");
+
+    if (this.transport) {
+      await this.transport.stop();
+      this.transport = undefined;
+    }
+
+    this.running = false;
+    logger.info("[MCP Server] Server stopped");
+  }
+
+  /**
+   * Check if server is running
+   */
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  /**
+   * Setup graceful shutdown handlers
+   */
+  private setupShutdownHandlers(logger: EndpointLogger): void {
+    const shutdown = async (signal: string): Promise<void> => {
+      logger.info(`[MCP Server] Received ${signal}, shutting down...`);
+      await this.stop(logger);
+      process.exit(0);
+    };
+
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+
+    // Handle uncaught errors
+    process.on("uncaughtException", (error) => {
+      logger.error("[MCP Server] Uncaught exception", {
+        error: error.message,
+        stack: error.stack,
+      });
+      void shutdown("uncaughtException");
+    });
+
+    process.on("unhandledRejection", (reason) => {
+      logger.error("[MCP Server] Unhandled rejection", {
+        reason: String(reason),
+      });
+      void shutdown("unhandledRejection");
+    });
+  }
+
+  /**
+   * Keep process alive
+   */
+  private async keepAlive(): Promise<void> {
+    // Wait indefinitely
+    return await new Promise(() => {
+      // This promise never resolves, keeping the process alive
+      // The process will exit via shutdown handlers
+    });
+  }
+}

package/src/app/api/[locale]/system/unified-interface/mcp/server/stdio-transport.ts

@@ -0,0 +1,193 @@
+/**
+ * MCP STDIO Transport
+ * Handles communication via stdin/stdout
+ */
+
+import * as readline from "node:readline";
+
+import { parseError } from "next-vibe/shared/utils";
+
+import type { EndpointLogger } from "../../shared/logger/endpoint";
+import type { IMCPTransport, JsonRpcRequest, JsonRpcResponse } from "../types";
+
+/**
+ * STDIO Transport Implementation
+ */
+export class StdioTransport implements IMCPTransport {
+  private logger: EndpointLogger;
+  private messageHandler?: (message: JsonRpcRequest) => Promise<void>;
+  private readlineInterface?: readline.Interface;
+  private running = false;
+  private initializationReceived = false;
+  private startupTimeout?: ReturnType<typeof setTimeout>;
+
+  constructor(logger: EndpointLogger) {
+    this.logger = logger;
+  }
+
+  /**
+   * Start the transport
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async start(): Promise<void> {
+    if (this.running) {
+      return;
+    }
+
+    this.logger.info("[MCP Transport] Starting STDIO transport...");
+
+    // Create readline interface
+    // NOTE: Do NOT set output to process.stdout - it interferes with MCP protocol
+    this.readlineInterface = readline.createInterface({
+      input: process.stdin,
+      terminal: false,
+    });
+
+    // Handle incoming lines
+    this.readlineInterface.on("line", (line: string) => {
+      void this.handleIncomingMessage(line);
+    });
+
+    // Handle close
+    this.readlineInterface.on("close", () => {
+      this.logger.info("[MCP Transport] STDIO closed");
+      this.running = false;
+    });
+
+    // Handle errors
+    process.stdin.on("error", (error: Error) => {
+      this.logger.error("[MCP Transport] stdin error", {
+        error: error.message,
+      });
+    });
+
+    process.stdout.on("error", (error: Error) => {
+      this.logger.error("[MCP Transport] stdout error", {
+        error: error.message,
+      });
+    });
+
+    this.running = true;
+    this.logger.info("[MCP Transport] STDIO transport started");
+
+    // Set up startup timeout - exit if no initialization within 5 seconds
+    // This prevents hanging when health checks don't send initialization
+    const timeoutMs = parseInt(process.env.MCP_STARTUP_TIMEOUT || "5000", 10);
+    this.startupTimeout = setTimeout(() => {
+      if (!this.initializationReceived) {
+        this.logger.warn(
+          "[MCP Transport] No initialization received within timeout, exiting",
+        );
+        process.exit(0);
+      }
+    }, timeoutMs);
+  }
+
+  /**
+   * Stop the transport
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async stop(): Promise<void> {
+    if (!this.running) {
+      return;
+    }
+
+    this.logger.info("[MCP Transport] Stopping STDIO transport...");
+
+    if (this.startupTimeout) {
+      clearTimeout(this.startupTimeout);
+      this.startupTimeout = undefined;
+    }
+
+    if (this.readlineInterface) {
+      this.readlineInterface.close();
+      this.readlineInterface = undefined;
+    }
+
+    this.running = false;
+    this.logger.info("[MCP Transport] STDIO transport stopped");
+  }
+
+  /**
+   * Send a message
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async send(message: JsonRpcResponse): Promise<void> {
+    if (!this.running) {
+      // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax, i18next/no-literal-string -- Transport infrastructure requires throwing for invalid state
+      throw new Error("Transport not running");
+    }
+
+    try {
+      const json = JSON.stringify(message);
+
+      // Write to stdout with newline (MCP protocol)
+      // eslint-disable-next-line i18next/no-literal-string
+      process.stdout.write(`${json}\n`);
+    } catch (error) {
+      this.logger.error("[MCP Transport] Failed to send message", {
+        error: parseError(error).message,
+      });
+      // eslint-disable-next-line oxlint-plugin-restricted/restricted-syntax -- Re-throw transport errors for caller to handle
+      throw error;
+    }
+  }
+
+  /**
+   * Register message handler
+   */
+  onMessage(handler: (message: JsonRpcRequest) => Promise<void>): void {
+    this.messageHandler = handler;
+  }
+
+  /**
+   * Handle incoming message
+   */
+  private async handleIncomingMessage(line: string): Promise<void> {
+    if (!line.trim()) {
+      return; // Ignore empty lines
+    }
+
+    try {
+      const message = JSON.parse(line) as JsonRpcRequest;
+
+      // Mark initialization as received if this is an initialize method
+      if (message.method === "initialize") {
+        this.initializationReceived = true;
+        if (this.startupTimeout) {
+          clearTimeout(this.startupTimeout);
+          this.startupTimeout = undefined;
+        }
+      }
+
+      if (!this.messageHandler) {
+        this.logger.warn("[MCP Transport] No message handler registered");
+        return;
+      }
+
+      await this.messageHandler(message);
+    } catch (error) {
+      const parsedError = parseError(error);
+      this.logger.error("[MCP Transport] Failed to handle message", {
+        error: parsedError.message,
+        line: line.slice(0, 100), // Log first 100 chars
+      });
+
+      // Send error response if we can parse the ID
+      try {
+        const partialMessage = JSON.parse(line) as { id?: string | number };
+        await this.send({
+          jsonrpc: "2.0",
+          error: {
+            code: -32700,
+            // eslint-disable-next-line i18next/no-literal-string
+            message: "Parse error",
+          },
+          id: partialMessage.id || null,
+        });
+      } catch {
+        // Can't even parse for ID, ignore
+      }
+    }
+  }
+}