feat(all): Add shared types and components for configuration schema management

Author: Lasim

README.md

@@ -58,6 +58,7 @@ some-mcp configure --api-key=xxx
 {
   "mcpServers": {
     "deploystack": {
+      "type": "http",
       "url": "https://satellite.deploystack.io/mcp"
     }
   }

services/backend/src/routes/mcp/servers/schemas.ts

@@ -964,8 +964,7 @@ export const LIST_SERVERS_SUCCESS_RESPONSE_SCHEMA = {
 } as const;
 
 // Update request schema - all fields from CREATE_GLOBAL_SERVER_REQUEST_SCHEMA but optional
-export const UPDATE_GLOBAL_SERVER_REQUEST_SCHEMA = {
-  type: 'object',
+export const UPDATE_GLOBAL_SERVER_REQUEST_SCHEMA = { type: 'object',
   properties: {
     // All fields from SERVER_FIELDS but optional
     name: SERVER_FIELDS.name,
@@ -1005,7 +1004,53 @@ export const UPDATE_GLOBAL_SERVER_REQUEST_SCHEMA = {
     tags: SERVER_FIELDS.tags,
     status: SERVER_FIELDS.status,
     featured: SERVER_FIELDS.featured,
-    auto_install_new_default_team: SERVER_FIELDS.auto_install_new_default_team
+    auto_install_new_default_team: SERVER_FIELDS.auto_install_new_default_team,
+    // Three-tier configuration schema - CRITICAL FIX
+    template_args: { 
+      type: 'array',
+      items: TEMPLATE_ARG_SCHEMA,
+      description: 'Template-level arguments'
+    },
+    template_env: { 
+      type: 'array',
+      items: TEMPLATE_ENV_SCHEMA,
+      description: 'Template-level environment variables'
+    },
+    template_headers: { 
+      type: 'array',
+      items: TEMPLATE_HEADER_SCHEMA,
+      description: 'Template-level headers'
+    },
+    team_args_schema: { 
+      type: 'array',
+      items: TEAM_ARG_SCHEMA,
+      description: 'Team-level argument schema definitions'
+    },
+    team_env_schema: { 
+      type: 'array',
+      items: TEAM_ENV_SCHEMA,
+      description: 'Team-level environment variable schema definitions'
+    },
+    team_headers_schema: { 
+      type: 'array',
+      items: TEAM_HEADER_SCHEMA,
+      description: 'Team-level header schema definitions'
+    },
+    user_args_schema: { 
+      type: 'array',
+      items: USER_ARG_SCHEMA,
+      description: 'User-level argument schema definitions'
+    },
+    user_env_schema: { 
+      type: 'array',
+      items: USER_ENV_SCHEMA,
+      description: 'User-level environment variable schema definitions'
+    },
+    user_headers_schema: { 
+      type: 'array',
+      items: USER_HEADER_SCHEMA,
+      description: 'User-level header schema definitions'
+    }
   },
   additionalProperties: false
 } as const;

services/backend/src/routes/mcp/user-configurations/schemas.ts

@@ -57,6 +57,11 @@ export const CREATE_USER_CONFIG_REQUEST_SCHEMA = {
       type: 'object',
       additionalProperties: { type: 'string' },
       description: 'User-specific environment variables'
+    },
+    user_headers: {
+      type: 'object',
+      additionalProperties: { type: 'string' },
+      description: 'User-specific HTTP headers'
     }
   },
   additionalProperties: false
@@ -78,6 +83,11 @@ export const UPDATE_USER_CONFIG_REQUEST_SCHEMA = {
       type: 'object',
       additionalProperties: { type: 'string' },
       description: 'User-specific environment variables'
+    },
+    user_headers: {
+      type: 'object',
+      additionalProperties: { type: 'string' },
+      description: 'User-specific HTTP headers'
     }
   },
   additionalProperties: false
@@ -127,6 +137,11 @@ export const USER_CONFIG_RESPONSE_SCHEMA = {
       additionalProperties: { type: 'string' },
       description: 'User-specific environment variables'
     },
+    user_headers: {
+      type: 'object',
+      additionalProperties: { type: 'string' },
+      description: 'User-specific HTTP headers'
+    },
     created_at: { type: 'string', format: 'date-time', description: 'Creation timestamp' },
     updated_at: { type: 'string', format: 'date-time', description: 'Last update timestamp' },
     last_used_at: { type: 'string', format: 'date-time', description: 'Last used timestamp' }
@@ -227,12 +242,14 @@ export interface CreateUserConfigRequest {
   device_id?: string;
   user_args?: Record<string, string>;
   user_env?: Record<string, string>;
+  user_headers?: Record<string, string>;
 }
 
 export interface UpdateUserConfigRequest {
   device_id?: string;
   user_args?: Record<string, string>;
   user_env?: Record<string, string>;
+  user_headers?: Record<string, string>;
 }
 
 export interface UpdateUserArgsRequest {
@@ -250,6 +267,7 @@ export interface UserConfigData {
   device_id?: string;
   user_args?: Record<string, string>;
   user_env?: Record<string, string>;
+  user_headers?: Record<string, string>;
   created_at: string;
   updated_at: string;
   last_used_at?: string;
@@ -415,6 +433,7 @@ export function formatUserConfigResponse(config: any): UserConfigData {
     device_id: config.device_id || undefined,
     user_args: safeJsonParse(config.user_args, undefined),
     user_env: safeJsonParse(config.user_env, undefined),
+    user_headers: safeJsonParse(config.user_headers, undefined),
     created_at: config.created_at.toISOString(),
     updated_at: config.updated_at.toISOString(),
     last_used_at: config.last_used_at ? config.last_used_at.toISOString() : undefined

services/backend/src/services/mcpUserConfigurationService.ts

@@ -14,6 +14,7 @@ export interface McpUserConfiguration {
   user_id: string;
   user_args?: Record<string, string>;
   user_env?: Record<string, string>;
+  user_headers?: Record<string, string>;
   created_at: Date;
   updated_at: Date;
   last_used_at?: Date;
@@ -29,18 +30,21 @@ export interface McpUserConfiguration {
       description: string;
       user_args_schema?: any[];
       user_env_schema?: any[];
+      user_headers_schema?: any[];
     };
   };
 }
 
 export interface CreateUserConfigRequest {
   user_args?: Record<string, string>;
   user_env?: Record<string, string>;
+  user_headers?: Record<string, string>;
 }
 
 export interface UpdateUserConfigRequest {
   user_args?: Record<string, string>;
   user_env?: Record<string, string>;
+  user_headers?: Record<string, string>;
 }
 
 export class McpUserConfigurationService {
@@ -106,6 +110,7 @@ export class McpUserConfigurationService {
     for (const row of configurations) {
       const userArgsSchema = this.parseJsonField(row.server?.user_args_schema, []);
       const userEnvSchema = this.parseJsonField(row.server?.user_env_schema, []);
+      const userHeadersSchema = this.parseJsonField(row.server?.user_headers_schema, []);
 
       const userArgs = row.config.user_args 
         ? await McpArgsStorage.retrieveUserArgs(
@@ -125,10 +130,20 @@ export class McpUserConfigurationService {
           )
         : undefined;
 
+      const userHeaders = row.config.user_headers 
+        ? await McpEnvStorage.retrieveUserEnv(
+            row.config.user_headers,
+            userHeadersSchema,
+            { maskSecrets: true },
+            this.logger
+          )
+        : undefined;
+
       processedConfigurations.push({
         ...row.config,
         user_args: userArgs,
         user_env: userEnv,
+        user_headers: userHeaders,
         installation: row.installation ? {
           id: row.installation.id,
           installation_name: row.installation.installation_name,
@@ -139,7 +154,8 @@ export class McpUserConfigurationService {
             name: row.server.name,
             description: row.server.description,
             user_args_schema: userArgsSchema,
-            user_env_schema: userEnvSchema
+            user_env_schema: userEnvSchema,
+            user_headers_schema: userHeadersSchema
           } : undefined
         } : undefined
       });
@@ -192,6 +208,7 @@ export class McpUserConfigurationService {
 
     const userArgsSchema = this.parseJsonField(server?.user_args_schema, []);
     const userEnvSchema = this.parseJsonField(server?.user_env_schema, []);
+    const userHeadersSchema = this.parseJsonField(server?.user_headers_schema, []);
 
     const userArgs = config.user_args 
       ? await McpArgsStorage.retrieveUserArgs(
@@ -211,10 +228,20 @@ export class McpUserConfigurationService {
         )
       : undefined;
 
+    const userHeaders = config.user_headers 
+      ? await McpEnvStorage.retrieveUserEnv(
+          config.user_headers,
+          userHeadersSchema,
+          { maskSecrets: true },
+          this.logger
+        )
+      : undefined;
+
     return {
       ...config,
       user_args: userArgs,
       user_env: userEnv,
+      user_headers: userHeaders,
       installation: installation ? {
         id: installation.id,
         installation_name: installation.installation_name,
@@ -225,7 +252,8 @@ export class McpUserConfigurationService {
           name: server.name,
           description: server.description,
           user_args_schema: userArgsSchema,
-          user_env_schema: userEnvSchema
+          user_env_schema: userEnvSchema,
+          user_headers_schema: userHeadersSchema
         } : undefined
       } : undefined
     };
@@ -275,6 +303,9 @@ export class McpUserConfigurationService {
       if (data.user_env) {
         this.validateUserEnv(data.user_env, this.parseJsonField(serverInfo.user_env_schema, []));
       }
+      if (data.user_headers) {
+        this.validateUserHeaders(data.user_headers, this.parseJsonField(serverInfo.user_headers_schema, []));
+      }
     }
 
     const configId = nanoid();
@@ -294,6 +325,11 @@ export class McpUserConfigurationService {
         this.parseJsonField(serverInfo?.user_env_schema, []), 
         this.logger
       ) : null,
+      user_headers: data.user_headers ? await McpEnvStorage.storeUserEnv(
+        data.user_headers, 
+        this.parseJsonField(serverInfo?.user_headers_schema, []), 
+        this.logger
+      ) : null,
       created_at: now,
       updated_at: now,
       last_used_at: null
@@ -344,6 +380,9 @@ export class McpUserConfigurationService {
       if (data.user_env !== undefined) {
         this.validateUserEnv(data.user_env, existing.installation.server.user_env_schema || []);
       }
+      if (data.user_headers !== undefined) {
+        this.validateUserHeaders(data.user_headers, existing.installation.server.user_headers_schema || []);
+      }
     }
 
 
@@ -368,6 +407,14 @@ export class McpUserConfigurationService {
       ) : null;
     }
 
+    if (data.user_headers !== undefined) {
+      updateData.user_headers = data.user_headers ? await McpEnvStorage.storeUserEnv(
+        data.user_headers, 
+        existing.installation?.server?.user_headers_schema || [], 
+        this.logger
+      ) : null;
+    }
+
     await this.db
       .update(mcpUserConfigurations)
       .set(updateData)
@@ -497,6 +544,24 @@ export class McpUserConfigurationService {
     }
   }
 
+  private validateUserHeaders(userHeaders: Record<string, string>, schema: any[]): void {
+    // Validate user headers against schema
+    // Only validate the fields that are actually being sent, not all required fields
+    for (const [headerName, headerValue] of Object.entries(userHeaders)) {
+      const schemaEntry = schema.find((header: any) => header.name === headerName)
+      
+      if (schemaEntry) {
+        // If this field is required and the sent value is empty, throw error
+        if (schemaEntry.required && (!headerValue || headerValue.trim() === '')) {
+          throw new Error(`Required header '${headerName}' is missing or empty`)
+        }
+        
+        // Additional type validation can be added here in the future
+      }
+      // Note: We don't validate fields that aren't in the schema - allowing flexibility
+    }
+  }
+
   private parseJsonField(fieldValue: any, defaultValue: any): any {
     // Handle null, undefined, or empty values
     if (fieldValue === null || fieldValue === undefined || fieldValue === '') {