@next-vibe/checker 1.0.11 → 1.0.12

package/src/app/api/[locale]/system/unified-interface/mcp/README.md

@@ -0,0 +1,114 @@
+# MCP Server
+
+**Model Context Protocol executor for the Vibe unified-interface**
+
+Exposes API endpoints as MCP tools for AI assistants (Claude Desktop, Cline, etc.).
+
+## Quick Start
+
+Add to your AI assistant's MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "Vibe": {
+      "command": "vibe",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+## What is MCP?
+
+[Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI assistants to external tools via JSON-RPC over STDIO.
+
+## Configuration Examples
+
+### Claude Desktop
+
+macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "Vibe": {
+      "command": "npx",
+      "args": ["vibe", "mcp"],
+      "env": {
+        "NODE_ENV": "production"
+      }
+    }
+  }
+}
+```
+
+### VS Code (Cline)
+
+`.vscode/settings.json`:
+
+```json
+{
+  "cline.mcpServers": {
+    "Vibe": {
+      "command": "npx",
+      "args": ["vibe", "mcp"]
+    }
+  }
+}
+```
+
+## Architecture
+
+The MCP server is another executor of the unified-interface framework, reusing:
+
+- **Endpoint Discovery**: Same registry as CLI
+- **Route Execution**: Same handler as web APIs
+- **Authentication**: Same JWT system (uses `cli@system.local` user)
+- **Validation**: Same Zod schemas from definitions
+- **i18n**: Same translation system
+
+```
+AI Assistant → MCP Protocol (JSON-RPC/STDIO) → Tool Registry → Route Handler → API Endpoints
+```
+
+## Tool Naming
+
+Tools are named using API path structure:
+
+```
+/user/create (POST) → user_create_POST
+/leads/list (GET)    → leads_list_GET
+```
+
+Custom aliases can be defined in `definition.ts`:
+
+```typescript
+createEndpoint({
+  aliases: ["create-user"],
+  // ...
+});
+```
+
+## Authentication & Permissions
+
+- Uses same role-based access control as other interfaces
+- Auth flow: Session file (.vibe.session) → `VIBE_CLI_USER_EMAIL` env var → Public user with new lead
+- If `VIBE_CLI_USER_EMAIL` is set but user not found in DB, returns error
+- Public endpoints available without authentication
+
+## Debug Mode
+
+Add `--verbose` flag to enable debug logging:
+
+```json
+{
+  "mcpServers": {
+    "Vibe": {
+      "command": "vibe",
+      "args": ["mcp", "--verbose"]
+    }
+  }
+}
+```

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

@@ -0,0 +1,146 @@
+import "server-only";
+
+import { z } from "zod";
+
+import { zodSchemaToJsonSchema } from "@/app/api/[locale]/system/unified-interface/shared/endpoints/definition/endpoint-to-metadata";
+import { generateSchemaForUsage } from "@/app/api/[locale]/system/unified-interface/shared/field/utils";
+import type { CreateApiEndpointAny } from "@/app/api/[locale]/system/unified-interface/shared/types/endpoint";
+import { FieldUsage } from "@/app/api/[locale]/system/unified-interface/shared/types/enums";
+import type { CountryLanguage } from "@/i18n/core/config";
+
+import type { MCPTool } from "./types";
+
+function toolNameToApiPath(toolName: string): string {
+  const parts = toolName.split("_");
+  const method = parts.at(-1);
+  const pathParts = parts.slice(0, -1);
+  const apiPath = pathParts.join("/");
+  return `api/[locale]/${apiPath} (${method})`;
+}
+
+/**
+ * Generate input schema from endpoint fields with descriptions
+ * Combines RequestData and RequestUrlParams for MCP tools
+ */
+function generateInputSchema(
+  endpoint: CreateApiEndpointAny,
+  locale: CountryLanguage,
+): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  if (!endpoint.fields) {
+    return z.object({});
+  }
+
+  try {
+    // Combine request data and URL params
+    const requestDataSchema = generateSchemaForUsage(
+      endpoint.fields,
+      FieldUsage.RequestData,
+    ) as z.ZodObject<Record<string, z.ZodTypeAny>> | z.ZodNever;
+
+    const urlPathParamsSchema = generateSchemaForUsage(
+      endpoint.fields,
+      FieldUsage.RequestUrlParams,
+    ) as z.ZodObject<Record<string, z.ZodTypeAny>> | z.ZodNever;
+
+    const combinedShape: { [key: string]: z.ZodTypeAny } = {};
+
+    if (requestDataSchema instanceof z.ZodObject) {
+      Object.assign(combinedShape, requestDataSchema.shape);
+    }
+
+    if (urlPathParamsSchema instanceof z.ZodObject) {
+      Object.assign(combinedShape, urlPathParamsSchema.shape);
+    }
+
+    if (Object.keys(combinedShape).length === 0) {
+      return z.object({});
+    }
+    // Add descriptions from field metadata
+    const shapeWithDescriptions = addFieldDescriptions(
+      combinedShape,
+      endpoint.fields,
+      locale,
+      endpoint,
+    );
+
+    return z.object(shapeWithDescriptions);
+  } catch {
+    return z.object({});
+  }
+}
+
+/**
+ * Add descriptions to schema fields from endpoint field metadata
+ */
+function addFieldDescriptions(
+  shape: Record<string, z.ZodTypeAny>,
+  fields: CreateApiEndpointAny["fields"],
+  locale: CountryLanguage,
+  endpoint: CreateApiEndpointAny,
+): Record<string, z.ZodTypeAny> {
+  if (!fields || fields.type !== "object" || !fields.children) {
+    return shape;
+  }
+
+  const enhancedShape: Record<string, z.ZodTypeAny> = {};
+
+  for (const [key, schema] of Object.entries(shape)) {
+    const fieldDef = fields.children[key];
+    if (!fieldDef || fieldDef.type === "widget") {
+      enhancedShape[key] = schema;
+      continue;
+    }
+
+    // Get description from field UI config
+    let description: string | undefined;
+    if (
+      fieldDef.ui &&
+      "description" in fieldDef.ui &&
+      fieldDef.ui.description
+    ) {
+      const descKey = fieldDef.ui.description as string;
+      const { t } = endpoint.scopedTranslation.scopedT(locale);
+
+      description = t(descKey);
+    }
+
+    // Add description to schema
+    enhancedShape[key] = description ? schema.describe(description) : schema;
+  }
+
+  return enhancedShape;
+}
+
+/**
+ * Convert endpoint to MCP tool format
+ * Uses shared zodSchemaToJsonSchema for consistent schema conversion
+ */
+export function endpointToMCPTool(
+  endpoint: CreateApiEndpointAny,
+  locale: CountryLanguage,
+): MCPTool {
+  const toolName = `${endpoint.path.join("_")}_${endpoint.method.toUpperCase()}`;
+  const apiPath = toolNameToApiPath(toolName);
+
+  // Translate description and title keys
+  const { t } = endpoint.scopedTranslation.scopedT(locale);
+  const descriptionKey = endpoint.description || endpoint.title;
+  const translatedDescription = descriptionKey ? t(descriptionKey) : "";
+
+  const description = translatedDescription
+    ? `${translatedDescription}\n📁 ${apiPath}`
+    : apiPath;
+
+  // Generate Zod schema from endpoint fields with translated descriptions
+  const zodSchema = generateInputSchema(endpoint, locale);
+
+  // Convert to JSON Schema using shared utility
+  // z.toJSONSchema automatically handles transforms and includes descriptions
+  const jsonSchema = zodSchemaToJsonSchema(zodSchema);
+
+  return {
+    name: toolName,
+    description,
+    inputSchema: jsonSchema as MCPTool["inputSchema"],
+  };
+}

package/src/app/api/[locale]/system/unified-interface/mcp/i18n/de/index.ts

@@ -0,0 +1,182 @@
+import type { translations as enTranslations } from "../en";
+
+export const translations: typeof enTranslations = {
+  tools: {
+    category: "MCP-Tools",
+    tags: {
+      mcp: "MCP",
+    },
+    get: {
+      title: "MCP-Tools auflisten",
+      description:
+        "Alle verfügbaren MCP-Tools für den aktuellen Benutzer abrufen",
+      fields: {
+        name: "Tool-Name",
+        description: "Beschreibung",
+        inputSchema: "Eingabeschema",
+      },
+      response: {
+        title: "MCP-Tools-Liste",
+        description: "Liste der verfügbaren MCP-Tools",
+      },
+      errors: {
+        validation: {
+          title: "Validierung fehlgeschlagen",
+          description: "Ungültige Anfrageparameter",
+        },
+        network: {
+          title: "Netzwerkfehler",
+          description: "Verbindung zum Server fehlgeschlagen",
+        },
+        unauthorized: {
+          title: "Nicht autorisiert",
+          description: "Authentifizierung erforderlich",
+        },
+        forbidden: {
+          title: "Verboten",
+          description: "Sie haben keine Berechtigung für diese Ressource",
+        },
+        notFound: {
+          title: "Nicht gefunden",
+          description: "Ressource nicht gefunden",
+        },
+        server: {
+          title: "Serverfehler",
+          description: "Interner Serverfehler aufgetreten",
+        },
+        unknown: {
+          title: "Unbekannter Fehler",
+          description: "Ein unerwarteter Fehler ist aufgetreten",
+        },
+        unsavedChanges: {
+          title: "Nicht gespeicherte Änderungen",
+          description: "Sie haben nicht gespeicherte Änderungen",
+        },
+        conflict: {
+          title: "Konflikt",
+          description: "Ressourcenkonflikt erkannt",
+        },
+      },
+      success: {
+        title: "Erfolg",
+        description: "Tools erfolgreich abgerufen",
+      },
+    },
+  },
+  execute: {
+    category: "MCP ausführen",
+    tags: {
+      mcp: "MCP",
+    },
+    post: {
+      title: "MCP-Tool ausführen",
+      description: "Ein MCP-Tool nach Namen mit Argumenten ausführen",
+      fields: {
+        title: "Tool-Ausführungsparameter",
+        description: "Parameter für die Tool-Ausführung",
+        name: {
+          title: "Tool-Name",
+          description:
+            "Name des auszuführenden Tools (z.B. core:system:db:ping)",
+          placeholder: "core:system:db:ping",
+        },
+        arguments: {
+          title: "Argumente",
+          description: "Tool-Argumente als Schlüssel-Wert-Paare",
+          placeholder: "{}",
+        },
+      },
+      response: {
+        title: "Tool-Ausführungsergebnis",
+        description: "Ergebnis der Tool-Ausführung",
+        result: {
+          content: {
+            type: "Inhaltstyp",
+            text: "Inhalt",
+          },
+          isError: "Ist Fehler",
+        },
+      },
+      errors: {
+        validation: {
+          title: "Validierung fehlgeschlagen",
+          description: "Ungültiger Tool-Name oder Argumente",
+        },
+        network: {
+          title: "Netzwerkfehler",
+          description: "Verbindung zum Server fehlgeschlagen",
+        },
+        unauthorized: {
+          title: "Nicht autorisiert",
+          description: "Authentifizierung erforderlich",
+        },
+        forbidden: {
+          title: "Verboten",
+          description: "Sie haben keine Berechtigung, dieses Tool auszuführen",
+        },
+        notFound: {
+          title: "Tool nicht gefunden",
+          description: "Das angegebene Tool existiert nicht",
+        },
+        server: {
+          title: "Serverfehler",
+          description: "Tool-Ausführung fehlgeschlagen",
+        },
+        unknown: {
+          title: "Unbekannter Fehler",
+          description: "Ein unerwarteter Fehler ist aufgetreten",
+        },
+        unsavedChanges: {
+          title: "Nicht gespeicherte Änderungen",
+          description: "Sie haben nicht gespeicherte Änderungen",
+        },
+        conflict: {
+          title: "Konflikt",
+          description: "Ressourcenkonflikt erkannt",
+        },
+      },
+      success: {
+        title: "Erfolg",
+        description: "Tool erfolgreich ausgeführt",
+      },
+    },
+  },
+  serve: {
+    category: "MCP-Server",
+    tags: {
+      mcp: "MCP",
+    },
+    post: {
+      title: "MCP-Server starten",
+      description: "Starten Sie den Model Context Protocol Server",
+      response: {
+        title: "MCP-Server-Status",
+        description: "Status des MCP-Servers",
+      },
+      errors: {
+        validation: {
+          title: "Validierung fehlgeschlagen",
+          description: "Ungültige Anfrageparameter",
+        },
+        server: {
+          title: "Serverfehler",
+          description: "MCP-Server konnte nicht gestartet werden",
+        },
+        unauthorized: {
+          title: "Nicht autorisiert",
+          description: "Authentifizierung erforderlich",
+        },
+      },
+      success: {
+        title: "Erfolg",
+        description: "MCP-Server erfolgreich gestartet",
+      },
+    },
+  },
+  registry: {
+    toolNotFound: "Tool nicht gefunden",
+    endpointNotFound: "Endpunkt nicht gefunden",
+    permissionDenied: "Zugriff verweigert",
+    toolExecutionFailed: "Tool-Ausführung fehlgeschlagen",
+  },
+};

package/src/app/api/[locale]/system/unified-interface/mcp/i18n/en/index.ts

@@ -0,0 +1,179 @@
+export const translations = {
+  tools: {
+    category: "MCP Tools",
+    tags: {
+      mcp: "MCP",
+    },
+    get: {
+      title: "List MCP Tools",
+      description: "Get all available MCP tools for current user",
+      fields: {
+        name: "Tool Name",
+        description: "Description",
+        inputSchema: "Input Schema",
+      },
+      response: {
+        title: "MCP Tools List",
+        description: "List of available MCP tools",
+      },
+      errors: {
+        validation: {
+          title: "Validation Failed",
+          description: "Invalid request parameters",
+        },
+        network: {
+          title: "Network Error",
+          description: "Failed to connect to server",
+        },
+        unauthorized: {
+          title: "Unauthorized",
+          description: "Authentication required",
+        },
+        forbidden: {
+          title: "Forbidden",
+          description: "You don't have permission to access this resource",
+        },
+        notFound: {
+          title: "Not Found",
+          description: "Resource not found",
+        },
+        server: {
+          title: "Server Error",
+          description: "Internal server error occurred",
+        },
+        unknown: {
+          title: "Unknown Error",
+          description: "An unexpected error occurred",
+        },
+        unsavedChanges: {
+          title: "Unsaved Changes",
+          description: "You have unsaved changes",
+        },
+        conflict: {
+          title: "Conflict",
+          description: "Resource conflict detected",
+        },
+      },
+      success: {
+        title: "Success",
+        description: "Tools retrieved successfully",
+      },
+    },
+  },
+  execute: {
+    category: "MCP Execute",
+    tags: {
+      mcp: "MCP",
+    },
+    post: {
+      title: "Execute MCP Tool",
+      description: "Execute an MCP tool by name with arguments",
+      fields: {
+        title: "Tool Execution Parameters",
+        description: "Parameters for tool execution",
+        name: {
+          title: "Tool Name",
+          description:
+            "Name of the tool to execute (e.g., core:system:db:ping)",
+          placeholder: "core:system:db:ping",
+        },
+        arguments: {
+          title: "Arguments",
+          description: "Tool arguments as key-value pairs",
+          placeholder: "{}",
+        },
+      },
+      response: {
+        title: "Tool Execution Result",
+        description: "Result of tool execution",
+        result: {
+          content: {
+            type: "Content Type",
+            text: "Content",
+          },
+          isError: "Is Error",
+        },
+      },
+      errors: {
+        validation: {
+          title: "Validation Failed",
+          description: "Invalid tool name or arguments",
+        },
+        network: {
+          title: "Network Error",
+          description: "Failed to connect to server",
+        },
+        unauthorized: {
+          title: "Unauthorized",
+          description: "Authentication required",
+        },
+        forbidden: {
+          title: "Forbidden",
+          description: "You don't have permission to execute this tool",
+        },
+        notFound: {
+          title: "Tool Not Found",
+          description: "The specified tool does not exist",
+        },
+        server: {
+          title: "Server Error",
+          description: "Tool execution failed",
+        },
+        unknown: {
+          title: "Unknown Error",
+          description: "An unexpected error occurred",
+        },
+        unsavedChanges: {
+          title: "Unsaved Changes",
+          description: "You have unsaved changes",
+        },
+        conflict: {
+          title: "Conflict",
+          description: "Resource conflict detected",
+        },
+      },
+      success: {
+        title: "Success",
+        description: "Tool executed successfully",
+      },
+    },
+  },
+  serve: {
+    category: "MCP Server",
+    tags: {
+      mcp: "MCP",
+    },
+    post: {
+      title: "Start MCP Server",
+      description: "Start the Model Context Protocol server",
+      response: {
+        title: "MCP Server Status",
+        description: "Status of the MCP server",
+      },
+      errors: {
+        validation: {
+          title: "Validation Failed",
+          description: "Invalid request parameters",
+        },
+        server: {
+          title: "Server Error",
+          description: "Failed to start MCP server",
+        },
+        unauthorized: {
+          title: "Unauthorized",
+          description: "Authentication required",
+        },
+      },
+      success: {
+        title: "Success",
+        description: "MCP server started successfully",
+      },
+    },
+  },
+  registry: {
+    toolNotFound: "Tool not found",
+    endpointNotFound: "Endpoint not found",
+    permissionDenied: "Permission denied",
+    toolExecutionFailed: "Tool execution failed",
+  },
+};