feat(backend): enhance MCP server creation and update descriptions

Lasim · Lasim · commit 69f482953026 · 2025-08-17T19:46:28.000+02:00
diff --git a/services/backend/api-spec.json b/services/backend/api-spec.json
@@ -14487,7 +14487,7 @@
         "tags": [
           "MCP Servers"
         ],
-        "description": "Create a new global MCP server - requires global admin permissions. Global servers are visible to all users. Requires Content-Type: application/json header when sending request body.",
+        "description": "Create a new global MCP server - requires global admin permissions. Global servers are visible to all users. If transport_type is not provided, it will be automatically extracted from claude_desktop_config (CLI commands like npx, node, python = stdio). Requires Content-Type: application/json header when sending request body.",
         "requestBody": {
           "content": {
             "application/json": {
@@ -14670,7 +14670,6 @@
                   "description",
                   "language",
                   "runtime",
-                  "transport_type",
                   "claude_desktop_config"
                 ],
                 "additionalProperties": false
@@ -15143,7 +15142,7 @@
         "tags": [
           "MCP Servers"
         ],
-        "description": "Update an existing global MCP server - requires global admin permissions. Only global servers can be updated through this endpoint. Requires Content-Type: application/json header when sending request body.",
+        "description": "Update an existing global MCP server - requires global admin permissions. Only global servers can be updated through this endpoint. If transport_type is not provided but claude_desktop_config is, transport_type will be automatically extracted. Requires Content-Type: application/json header when sending request body.",
         "parameters": [
           {
             "schema": {
diff --git a/services/backend/api-spec.yaml b/services/backend/api-spec.yaml
@@ -9974,8 +9974,11 @@ paths:
       tags:
         - MCP Servers
       description: "Create a new global MCP server - requires global admin
-        permissions. Global servers are visible to all users. Requires
-        Content-Type: application/json header when sending request body."
+        permissions. Global servers are visible to all users. If transport_type
+        is not provided, it will be automatically extracted from
+        claude_desktop_config (CLI commands like npx, node, python = stdio).
+        Requires Content-Type: application/json header when sending request
+        body."
       requestBody:
         content:
           application/json:
@@ -10107,7 +10110,6 @@ paths:
                 - description
                 - language
                 - runtime
-                - transport_type
                 - claude_desktop_config
               additionalProperties: false
         required: true
@@ -10392,8 +10394,9 @@ paths:
         - MCP Servers
       description: "Update an existing global MCP server - requires global admin
         permissions. Only global servers can be updated through this endpoint.
-        Requires Content-Type: application/json header when sending request
-        body."
+        If transport_type is not provided but claude_desktop_config is,
+        transport_type will be automatically extracted. Requires Content-Type:
+        application/json header when sending request body."
       parameters:
         - schema:
             type: object
diff --git a/services/backend/src/routes/mcp/servers/create-global.ts b/services/backend/src/routes/mcp/servers/create-global.ts
@@ -4,18 +4,7 @@ import { createSchema } from 'zod-openapi';
 import { requireGlobalAdmin } from '../../../middleware/roleMiddleware';
 import { McpCatalogService } from '../../../services/mcpCatalogService';
 import { getDb } from '../../../db';
-
-// Claude Desktop configuration schema
-const claudeDesktopConfigSchema = z.object({
-  mcpServers: z.record(z.string(), z.object({
-    command: z.string().min(1, 'Command is required'),
-    args: z.array(z.string()),
-    env: z.record(z.string(), z.string()).optional()
-  }))
-}).refine(
-  (config) => Object.keys(config.mcpServers).length === 1,
-  { message: "Claude Desktop config must contain exactly one MCP server" }
-);
+import { claudeDesktopConfigSchema, extractMcpConfigData } from '../../../utils/mcpConfigExtractor';
 
 // Request schema for creating global MCP servers
 const createGlobalServerRequestSchema = z.object({
@@ -25,7 +14,7 @@ const createGlobalServerRequestSchema = z.object({
   language: z.string().min(1, 'Language is required'),
   runtime: z.string().min(1, 'Runtime is required'),
   claude_desktop_config: claudeDesktopConfigSchema,
-  transport_type: z.enum(['stdio', 'http', 'sse']).default('stdio'),
+  transport_type: z.enum(['stdio', 'http', 'sse']).optional(),
   tools: z.array(z.object({
     name: z.string().min(1, 'Tool name is required'),
     description: z.string().min(1, 'Tool description is required')
@@ -55,32 +44,6 @@ const createGlobalServerRequestSchema = z.object({
   featured: z.boolean().default(false)
 });
 
-// Utility function to extract MCP configuration data from Claude Desktop config
-function extractMcpConfigData(claudeConfig: z.infer<typeof claudeDesktopConfigSchema>) {
-  const serverKey = Object.keys(claudeConfig.mcpServers)[0];
-  const serverConfig = claudeConfig.mcpServers[serverKey];
-  
-  // Extract installation_methods (Claude Desktop format)
-  const installation_methods = [{
-    client: "claude-desktop",
-    command: serverConfig.command,
-    args: serverConfig.args,
-    env: serverConfig.env || {}
-  }];
-  
-  // Extract environment_variables metadata
-  const environment_variables = Object.keys(serverConfig.env || {}).map(envKey => ({
-    name: envKey,
-    description: `${envKey} environment variable`,
-    required: true,
-    type: "password",
-    validation: "",
-    placeholder: serverConfig.env![envKey]
-  }));
-  
-  return { installation_methods, environment_variables };
-}
-
 // Response schema for successful creation
 const createGlobalServerResponseSchema = z.object({
   success: z.boolean(),
@@ -133,7 +96,7 @@ export default async function createGlobalServer(server: FastifyInstance) {
     schema: {
       tags: ['MCP Servers'],
       summary: 'Create global MCP server (Global Admin only)',
-      description: 'Create a new global MCP server - requires global admin permissions. Global servers are visible to all users. Requires Content-Type: application/json header when sending request body.',
+      description: 'Create a new global MCP server - requires global admin permissions. Global servers are visible to all users. If transport_type is not provided, it will be automatically extracted from claude_desktop_config (CLI commands like npx, node, python = stdio). Requires Content-Type: application/json header when sending request body.',
       security: [{ cookieAuth: [] }],
       // Plain JSON Schema for Fastify validation
       body: {
@@ -214,7 +177,7 @@ export default async function createGlobalServer(server: FastifyInstance) {
           tags: { type: 'array', items: { type: 'string' } },
           featured: { type: 'boolean' }
         },
-        required: ['name', 'description', 'language', 'runtime', 'transport_type', 'claude_desktop_config'],
+        required: ['name', 'description', 'language', 'runtime', 'claude_desktop_config'],
         additionalProperties: false
       },
       // createSchema() for OpenAPI documentation
@@ -258,14 +221,15 @@ export default async function createGlobalServer(server: FastifyInstance) {
         claudeConfig: requestData.claude_desktop_config
       }, 'Extracting MCP configuration data from Claude Desktop config');
       
-      const { installation_methods, environment_variables } = extractMcpConfigData(requestData.claude_desktop_config);
+      const { installation_methods, environment_variables, transport_type: extractedTransportType } = extractMcpConfigData(requestData.claude_desktop_config);
       
       request.log.debug({
         operation: 'create_global_mcp_server',
         userId: request.user?.id,
         extractedData: {
           installation_methods,
-          environment_variables
+          environment_variables,
+          extractedTransportType
         }
       }, 'Successfully extracted MCP configuration data');
       
@@ -289,7 +253,7 @@ export default async function createGlobalServer(server: FastifyInstance) {
         author_contact: requestData.author_contact,
         organization: requestData.organization,
         license: requestData.license,
-        transport_type: requestData.transport_type,
+        transport_type: requestData.transport_type || extractedTransportType,
         environment_variables,
         dependencies: requestData.dependencies,
         category_id: requestData.category_id,
diff --git a/services/backend/src/routes/mcp/servers/update-global.ts b/services/backend/src/routes/mcp/servers/update-global.ts
@@ -4,6 +4,7 @@ import { createSchema } from 'zod-openapi';
 import { requireGlobalAdmin } from '../../../middleware/roleMiddleware';
 import { McpCatalogService } from '../../../services/mcpCatalogService';
 import { getDb } from '../../../db';
+import { claudeDesktopConfigSchema, extractTransportTypeFromClaudeConfig } from '../../../utils/mcpConfigExtractor';
 
 // Path parameters schema
 const updateGlobalServerParamsSchema = z.object({
@@ -43,6 +44,7 @@ const updateGlobalServerRequestSchema = z.object({
   author_contact: z.string().optional(),
   organization: z.string().optional(),
   license: z.string().optional(),
+  claude_desktop_config: claudeDesktopConfigSchema.optional(),
   transport_type: z.enum(['stdio', 'http', 'sse']).optional(),
   environment_variables: z.array(z.object({
     name: z.string().min(1, 'Environment variable name is required'),
@@ -109,7 +111,7 @@ export default async function updateGlobalServer(server: FastifyInstance) {
     schema: {
       tags: ['MCP Servers'],
       summary: 'Update global MCP server (Global Admin only)',
-      description: 'Update an existing global MCP server - requires global admin permissions. Only global servers can be updated through this endpoint. Requires Content-Type: application/json header when sending request body.',
+      description: 'Update an existing global MCP server - requires global admin permissions. Only global servers can be updated through this endpoint. If transport_type is not provided but claude_desktop_config is, transport_type will be automatically extracted. Requires Content-Type: application/json header when sending request body.',
       security: [{ cookieAuth: [] }],
       params: createSchema(updateGlobalServerParamsSchema),
       requestBody: {
@@ -189,6 +191,20 @@ export default async function updateGlobalServer(server: FastifyInstance) {
         });
       }
 
+      // Extract transport_type from claude_desktop_config if provided but transport_type is not
+      let finalUpdateData = { ...updateData };
+      if (updateData.claude_desktop_config && !updateData.transport_type) {
+        const extractedTransportType = extractTransportTypeFromClaudeConfig(updateData.claude_desktop_config);
+        finalUpdateData.transport_type = extractedTransportType;
+        
+        request.log.debug({
+          operation: 'update_global_mcp_server',
+          userId: request.user?.id,
+          serverId,
+          extractedTransportType
+        }, 'Extracted transport_type from claude_desktop_config');
+      }
+
       request.log.info({
         operation: 'update_global_mcp_server',
         step: 'calling_service',
@@ -200,7 +216,7 @@ export default async function updateGlobalServer(server: FastifyInstance) {
         serverId,
         request.user!.id,
         'global_admin', // We know user is global admin due to middleware
-        updateData
+        finalUpdateData
       );
       
       request.log.info({
@@ -222,7 +238,7 @@ export default async function updateGlobalServer(server: FastifyInstance) {
         userId: request.user?.id,
         serverId,
         serverName: updatedServer.name,
-        updatedFields: Object.keys(updateData)
+        updatedFields: Object.keys(finalUpdateData)
       }, 'Global MCP server updated successfully');
 
       // Safe JSON parsing helper function
diff --git a/services/backend/src/utils/mcpConfigExtractor.ts b/services/backend/src/utils/mcpConfigExtractor.ts
@@ -0,0 +1,73 @@
+import { z } from 'zod';
+
+// Claude Desktop configuration schema (shared)
+export const claudeDesktopConfigSchema = z.object({
+  mcpServers: z.record(z.string(), z.object({
+    command: z.string().min(1, 'Command is required'),
+    args: z.array(z.string()),
+    env: z.record(z.string(), z.string()).optional()
+  }))
+}).refine(
+  (config) => Object.keys(config.mcpServers).length === 1,
+  { message: "Claude Desktop config must contain exactly one MCP server" }
+);
+
+export type ClaudeDesktopConfig = z.infer<typeof claudeDesktopConfigSchema>;
+
+/**
+ * Extract transport_type from Claude Desktop configuration
+ * @param claudeConfig - The claude desktop configuration object
+ * @returns Transport type: 'stdio' | 'http' | 'sse'
+ */
+export function extractTransportTypeFromClaudeConfig(claudeConfig: ClaudeDesktopConfig): 'stdio' | 'http' | 'sse' {
+  const serverKey = Object.keys(claudeConfig.mcpServers)[0];
+  const serverConfig = claudeConfig.mcpServers[serverKey];
+  const command = serverConfig.command?.toLowerCase() || '';
+  
+  // Standard CLI commands indicate stdio transport
+  const stdioCommands = ['npx', 'node', 'python', 'python3', 'pip', 'poetry', 'cargo', 'go', 'java', 'dotnet'];
+  if (stdioCommands.some(cmd => command.includes(cmd))) {
+    return 'stdio';
+  }
+  
+  // Future: Could add logic for http/sse detection if needed
+  // if (command.includes('http') || command.includes('serve')) {
+  //   return 'http';
+  // }
+  
+  // Default to stdio as it's the most common
+  return 'stdio';
+}
+
+/**
+ * Extract complete MCP configuration data from Claude Desktop config
+ * @param claudeConfig - The claude desktop configuration object
+ * @returns Object containing installation_methods, environment_variables, and transport_type
+ */
+export function extractMcpConfigData(claudeConfig: ClaudeDesktopConfig) {
+  const serverKey = Object.keys(claudeConfig.mcpServers)[0];
+  const serverConfig = claudeConfig.mcpServers[serverKey];
+  
+  // Extract installation_methods (Claude Desktop format)
+  const installation_methods = [{
+    client: "claude-desktop",
+    command: serverConfig.command,
+    args: serverConfig.args,
+    env: serverConfig.env || {}
+  }];
+  
+  // Extract environment_variables metadata
+  const environment_variables = Object.keys(serverConfig.env || {}).map(envKey => ({
+    name: envKey,
+    description: `${envKey} environment variable`,
+    required: true,
+    type: "password",
+    validation: "",
+    placeholder: serverConfig.env![envKey]
+  }));
+  
+  // Extract transport_type
+  const transport_type = extractTransportTypeFromClaudeConfig(claudeConfig);
+  
+  return { installation_methods, environment_variables, transport_type };
+}
