@dxheroes/local-mcp-backend 0.4.0 → 0.5.0

package/src/modules/profiles/profiles.service.ts

@@ -13,6 +13,7 @@ import {
 } from '@nestjs/common';
 import { PrismaService } from '../database/prisma.service.js';
 import { ProxyService } from '../proxy/proxy.service.js';
+import { RESERVED_PROFILE_NAMES } from '../settings/settings.constants.js';
 
 interface CreateProfileDto {
   name: string;
@@ -51,6 +52,16 @@ export class ProfilesService {
     private readonly proxyService: ProxyService
   ) {}
 
+  /**
+   * Validate profile name against reserved names
+   */
+  private validateProfileName(name: string): void {
+    const lowerName = name.toLowerCase();
+    if (RESERVED_PROFILE_NAMES.some((reserved) => reserved.toLowerCase() === lowerName)) {
+      throw new ConflictException(`Profile name "${name}" is reserved for system use`);
+    }
+  }
+
   /**
    * Get all profiles
    */
@@ -128,6 +139,9 @@ export class ProfilesService {
    * Create a new profile
    */
   async create(dto: CreateProfileDto) {
+    // Validate against reserved names
+    this.validateProfileName(dto.name);
+
     // Check for unique name
     const existing = await this.prisma.profile.findUnique({
       where: { name: dto.name },
@@ -155,6 +169,11 @@ export class ProfilesService {
       throw new NotFoundException(`Profile ${id} not found`);
     }
 
+    // Validate new name against reserved names
+    if (dto.name) {
+      this.validateProfileName(dto.name);
+    }
+
     // Check for unique name if changing
     if (dto.name && dto.name !== profile.name) {
       const existing = await this.prisma.profile.findUnique({

package/src/modules/proxy/AGENTS.md

@@ -0,0 +1,34 @@
+# Proxy Module
+
+## Description
+
+MCP proxy module that exposes profile endpoints for AI clients. Handles MCP protocol communication (HTTP/SSE) and routes requests to underlying servers.
+
+## Contents
+
+- `proxy.module.ts` - Module definition
+- `proxy.controller.ts` - MCP protocol endpoints (HTTP, SSE)
+- `proxy.service.ts` - Request routing and tool aggregation
+
+## Key Endpoints
+
+- `POST /api/mcp/:profileSlug` - HTTP MCP endpoint (Streamable HTTP)
+- `GET /api/mcp/:profileSlug/sse` - SSE MCP endpoint (legacy)
+- `POST /api/mcp/:profileSlug/message` - SSE message endpoint (legacy)
+
+## Key Concepts
+
+- **Streamable HTTP**: Modern MCP transport (single POST endpoint)
+- **SSE Transport**: Legacy Server-Sent Events transport
+- **Tool Aggregation**: Combines tools from all profile MCP servers
+- **Request Routing**: Routes tool calls to correct MCP server
+- **Debug Logging**: All traffic is logged for debugging
+
+## Proxy Flow
+
+1. AI client connects to profile endpoint
+2. Proxy aggregates tool lists from all servers
+3. Client calls a tool
+4. Proxy routes to correct MCP server
+5. Response returned to client
+6. All traffic logged to debug logs

package/src/modules/proxy/proxy.controller.ts

@@ -1,16 +1,235 @@
 /**
  * Proxy Controller
  *
- * MCP proxy endpoints for profiles.
+ * MCP proxy endpoints for profiles and gateway.
+ * Supports MCP Streamable HTTP transport (2025-11-25 spec) with SSE notifications.
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http
  */
 
-import { Body, Controller, Get, HttpCode, HttpStatus, Param, Post } from '@nestjs/common';
+import {
+  Body,
+  Controller,
+  Get,
+  HttpCode,
+  HttpStatus,
+  NotFoundException,
+  Param,
+  Post,
+  Req,
+  Res,
+} from '@nestjs/common';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import type { Request, Response } from 'express';
+import { fromEvent, map } from 'rxjs';
+import { GATEWAY_PROFILE_CHANGED, SettingsService } from '../settings/settings.service.js';
 import type { McpRequest, McpResponse } from './proxy.service.js';
 import { ProxyService } from './proxy.service.js';
 
 @Controller('mcp')
 export class ProxyController {
-  constructor(private readonly proxyService: ProxyService) {}
+  constructor(
+    private readonly proxyService: ProxyService,
+    private readonly settingsService: SettingsService,
+    private readonly eventEmitter: EventEmitter2
+  ) {}
+
+  // =========================================
+  // Gateway Endpoints (must come BEFORE :profileName routes)
+  // =========================================
+
+  /**
+   * SSE endpoint for gateway notifications (dedicated URL)
+   * Sends notifications/tools/list_changed when the active profile changes.
+   */
+  @Get('gateway/sse')
+  streamGatewaySse(@Req() req: Request, @Res() res: Response) {
+    return this.streamGatewayEvents(req, res);
+  }
+
+  /**
+   * POST handler for gateway SSE - handles JSON-RPC requests via SSE transport
+   */
+  @Post('gateway/sse')
+  @HttpCode(HttpStatus.OK)
+  async handleGatewaySseRequest(@Body() request: McpRequest): Promise<McpResponse> {
+    return this.handleGatewayRequest(request);
+  }
+
+  /**
+   * Get gateway info - proxies to default profile info
+   */
+  @Get('gateway/info')
+  async getGatewayInfo() {
+    const profileName = await this.settingsService.getDefaultGatewayProfile();
+
+    try {
+      const info = await this.proxyService.getProfileInfo(profileName);
+      return {
+        ...info,
+        gateway: {
+          activeProfile: profileName,
+        },
+      };
+    } catch (error) {
+      if (error instanceof NotFoundException) {
+        throw new NotFoundException(
+          `Default gateway profile "${profileName}" not found. Please select a valid profile in settings.`
+        );
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * GET handler for gateway endpoint
+   *
+   * Streamable HTTP content negotiation:
+   * - Accept: text/event-stream -> Returns SSE stream for notifications
+   * - Otherwise -> Returns JSON usage instructions
+   *
+   * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http
+   */
+  @Get('gateway')
+  async getGatewayEndpoint(@Req() req: Request, @Res() res: Response) {
+    // Streamable HTTP: check Accept header for content negotiation
+    const acceptHeader = req.headers.accept || '';
+    if (acceptHeader.includes('text/event-stream')) {
+      return this.streamGatewayEvents(req, res);
+    }
+
+    // Return JSON usage info
+    const profileName = await this.settingsService.getDefaultGatewayProfile();
+
+    try {
+      const info = await this.proxyService.getProfileInfo(profileName);
+      return res.json({
+        message: 'This is the MCP Gateway endpoint. Use POST for JSON-RPC requests.',
+        usage: {
+          method: 'POST',
+          contentType: 'application/json',
+          body: {
+            jsonrpc: '2.0',
+            method: 'tools/list',
+            id: 1,
+          },
+        },
+        endpoints: {
+          sse: '/api/mcp/gateway/sse',
+          http: '/api/mcp/gateway',
+        },
+        gateway: {
+          activeProfile: profileName,
+          settingsEndpoint: '/api/settings/default-gateway-profile',
+        },
+        profile: {
+          name: profileName,
+          toolCount: info.tools.length,
+          serverCount: info.serverStatus.total,
+          connectedServers: info.serverStatus.connected,
+        },
+        infoEndpoint: '/api/mcp/gateway/info',
+      });
+    } catch (error) {
+      if (error instanceof NotFoundException) {
+        throw new NotFoundException(
+          `Default gateway profile "${profileName}" not found. Please select a valid profile in settings.`
+        );
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Stream SSE events for gateway notifications.
+   * Sends notifications/tools/list_changed when the active profile changes.
+   *
+   * Follows MCP Streamable HTTP transport (2025-11-25):
+   * - No endpoint event needed (unified endpoint)
+   * - Simple data: format without event: prefix
+   *
+   * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http
+   */
+  private streamGatewayEvents(req: Request, res: Response) {
+    // Set SSE headers
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Connection', 'keep-alive');
+    res.setHeader('X-Accel-Buffering', 'no'); // For nginx
+
+    // Streamable HTTP - no endpoint event needed
+    // Just send a comment to establish connection
+    res.write(': connected\n\n');
+
+    // Subscribe to profile change events
+    const subscription = fromEvent(this.eventEmitter, GATEWAY_PROFILE_CHANGED)
+      .pipe(
+        map(() => ({
+          jsonrpc: '2.0',
+          method: 'notifications/tools/list_changed',
+        }))
+      )
+      .subscribe((notification) => {
+        // Streamable HTTP - simple data format, no event prefix
+        res.write(`data: ${JSON.stringify(notification)}\n\n`);
+      });
+
+    // Cleanup on client disconnect
+    req.on('close', () => {
+      subscription.unsubscribe();
+    });
+  }
+
+  /**
+   * MCP JSON-RPC endpoint for the gateway - proxies to default profile
+   */
+  @Post('gateway')
+  @HttpCode(HttpStatus.OK)
+  async handleGatewayRequest(@Body() request: McpRequest): Promise<McpResponse> {
+    const profileName = await this.settingsService.getDefaultGatewayProfile();
+
+    try {
+      return await this.proxyService.handleRequest(profileName, request);
+    } catch (error) {
+      if (error instanceof NotFoundException) {
+        throw new NotFoundException(
+          `Default gateway profile "${profileName}" not found. Please select a valid profile in settings.`
+        );
+      }
+      throw error;
+    }
+  }
+
+  // =========================================
+  // Profile-specific Endpoints (existing)
+  // =========================================
+
+  /**
+   * SSE endpoint for profile notifications (dedicated URL)
+   * Sends notifications/tools/list_changed when the active gateway profile changes.
+   */
+  @Get(':profileName/sse')
+  async streamProfileSse(
+    @Param('profileName') profileName: string,
+    @Req() req: Request,
+    @Res() res: Response
+  ) {
+    // Validate profile exists
+    await this.proxyService.getProfileInfo(profileName);
+    return this.streamGatewayEvents(req, res);
+  }
+
+  /**
+   * POST handler for profile SSE - handles JSON-RPC requests via SSE transport
+   */
+  @Post(':profileName/sse')
+  @HttpCode(HttpStatus.OK)
+  async handleProfileSseRequest(
+    @Param('profileName') profileName: string,
+    @Body() request: McpRequest
+  ): Promise<McpResponse> {
+    return this.handleMcpRequest(profileName, request);
+  }
 
   /**
    * Get profile info with aggregated tools and server status
@@ -21,12 +240,31 @@ export class ProxyController {
   }
 
   /**
-   * GET handler for MCP endpoint - returns usage instructions instead of 404
+   * GET handler for MCP endpoint
+   *
+   * Streamable HTTP content negotiation:
+   * - Accept: text/event-stream -> Returns SSE stream for notifications
+   * - Otherwise -> Returns JSON usage instructions
+   *
+   * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http
    */
   @Get(':profileName')
-  async getMcpEndpoint(@Param('profileName') profileName: string) {
+  async getMcpEndpoint(
+    @Param('profileName') profileName: string,
+    @Req() req: Request,
+    @Res() res: Response
+  ) {
+    // Validate profile exists first
     const info = await this.proxyService.getProfileInfo(profileName);
-    return {
+
+    // Streamable HTTP: check Accept header for content negotiation
+    const acceptHeader = req.headers.accept || '';
+    if (acceptHeader.includes('text/event-stream')) {
+      return this.streamGatewayEvents(req, res);
+    }
+
+    // Return JSON usage info
+    return res.json({
       message: 'This is an MCP (Model Context Protocol) endpoint. Use POST for JSON-RPC requests.',
       usage: {
         method: 'POST',
@@ -37,6 +275,10 @@ export class ProxyController {
           id: 1,
         },
       },
+      endpoints: {
+        sse: `/api/mcp/${profileName}/sse`,
+        http: `/api/mcp/${profileName}`,
+      },
       profile: {
         name: profileName,
         toolCount: info.tools.length,
@@ -44,7 +286,7 @@ export class ProxyController {
         connectedServers: info.serverStatus.connected,
       },
       infoEndpoint: `/api/mcp/${profileName}/info`,
-    };
+    });
   }
 
   /**

package/src/modules/proxy/proxy.module.ts

@@ -2,16 +2,18 @@
  * Proxy Module
  *
  * Handles MCP proxy endpoints for profiles.
+ * Supports SSE notifications for MCP Streamable HTTP transport.
  */
 
 import { Module } from '@nestjs/common';
 import { DebugModule } from '../debug/debug.module.js';
 import { McpModule } from '../mcp/mcp.module.js';
+import { SettingsModule } from '../settings/settings.module.js';
 import { ProxyController } from './proxy.controller.js';
 import { ProxyService } from './proxy.service.js';
 
 @Module({
-  imports: [McpModule, DebugModule],
+  imports: [McpModule, DebugModule, SettingsModule],
   controllers: [ProxyController],
   providers: [ProxyService],
   exports: [ProxyService],

package/src/modules/settings/AGENTS.md

@@ -0,0 +1,31 @@
+# Settings Module
+
+## Description
+
+Application settings module. Manages gateway-wide configuration stored in the database.
+
+## Contents
+
+- `settings.module.ts` - Module definition
+- `settings.controller.ts` - REST API for settings
+- `settings.service.ts` - Settings storage and retrieval
+- `settings.constants.ts` - Default settings values
+
+## Key Endpoints
+
+- `GET /api/settings` - Get all settings
+- `PUT /api/settings` - Update settings
+- `GET /api/settings/:key` - Get single setting
+
+## Key Settings
+
+- `mcpTransport` - Default MCP transport type (http/sse)
+- `debugLogRetention` - Debug log retention period
+- Other gateway-wide configuration
+
+## Key Concepts
+
+- **Key-Value Storage**: Settings stored as key-value pairs
+- **Defaults**: Default values defined in constants
+- **Persistence**: Settings persist across restarts
+- **Type Safety**: Settings validated against expected types

package/src/modules/settings/settings.constants.ts

@@ -0,0 +1,20 @@
+/**
+ * Settings Constants
+ *
+ * Defines setting keys, defaults, and reserved profile names.
+ */
+
+// Setting keys
+export const SETTING_KEYS = {
+  DEFAULT_GATEWAY_PROFILE: 'default_gateway_profile',
+} as const;
+
+// Default values for settings
+export const SETTING_DEFAULTS: Record<string, string> = {
+  [SETTING_KEYS.DEFAULT_GATEWAY_PROFILE]: 'default',
+};
+
+// Reserved profile names that cannot be created by users
+export const RESERVED_PROFILE_NAMES = ['gateway'] as const;
+
+export type SettingKey = (typeof SETTING_KEYS)[keyof typeof SETTING_KEYS];

package/src/modules/settings/settings.controller.ts

@@ -0,0 +1,47 @@
+/**
+ * Settings Controller
+ *
+ * REST API endpoints for gateway settings management.
+ */
+
+import { Body, Controller, Get, Put } from '@nestjs/common';
+import { IsNotEmpty, IsString, MaxLength } from 'class-validator';
+import { SettingsService } from './settings.service.js';
+
+export class UpdateDefaultGatewayProfileDto {
+  @IsString()
+  @IsNotEmpty({ message: 'Profile name cannot be empty' })
+  @MaxLength(100, { message: 'Profile name must be at most 100 characters' })
+  profileName: string;
+}
+
+@Controller('settings')
+export class SettingsController {
+  constructor(private readonly settingsService: SettingsService) {}
+
+  /**
+   * Get all gateway settings
+   */
+  @Get()
+  async getAllSettings() {
+    return this.settingsService.getAllSettings();
+  }
+
+  /**
+   * Get the default gateway profile setting
+   */
+  @Get('default-gateway-profile')
+  async getDefaultGatewayProfile() {
+    const profileName = await this.settingsService.getDefaultGatewayProfile();
+    return { profileName };
+  }
+
+  /**
+   * Set the default gateway profile
+   */
+  @Put('default-gateway-profile')
+  async setDefaultGatewayProfile(@Body() dto: UpdateDefaultGatewayProfileDto) {
+    await this.settingsService.setDefaultGatewayProfile(dto.profileName);
+    return { profileName: dto.profileName };
+  }
+}

package/src/modules/settings/settings.module.ts

@@ -0,0 +1,16 @@
+/**
+ * Settings Module
+ *
+ * Handles gateway configuration settings.
+ */
+
+import { Module } from '@nestjs/common';
+import { SettingsController } from './settings.controller.js';
+import { SettingsService } from './settings.service.js';
+
+@Module({
+  controllers: [SettingsController],
+  providers: [SettingsService],
+  exports: [SettingsService],
+})
+export class SettingsModule {}

package/src/modules/settings/settings.service.ts

@@ -0,0 +1,99 @@
+/**
+ * Settings Service
+ *
+ * Business logic for gateway settings management.
+ * Emits events when gateway settings change for SSE notifications.
+ */
+
+import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { PrismaService } from '../database/prisma.service.js';
+import { SETTING_DEFAULTS, SETTING_KEYS, type SettingKey } from './settings.constants.js';
+
+/** Event name for gateway profile changes */
+export const GATEWAY_PROFILE_CHANGED = 'gateway.profile.changed';
+
+@Injectable()
+export class SettingsService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly eventEmitter: EventEmitter2
+  ) {}
+
+  /**
+   * Get a setting value by key, returns default if not set
+   */
+  async getSetting(key: SettingKey): Promise<string> {
+    const setting = await this.prisma.gatewaySetting.findUnique({
+      where: { key },
+    });
+
+    return setting?.value ?? SETTING_DEFAULTS[key];
+  }
+
+  /**
+   * Set a setting value
+   */
+  async setSetting(key: SettingKey, value: string): Promise<{ key: string; value: string }> {
+    const setting = await this.prisma.gatewaySetting.upsert({
+      where: { key },
+      update: { value },
+      create: { key, value },
+    });
+
+    return { key: setting.key, value: setting.value };
+  }
+
+  /**
+   * Get the default gateway profile name
+   */
+  async getDefaultGatewayProfile(): Promise<string> {
+    return this.getSetting(SETTING_KEYS.DEFAULT_GATEWAY_PROFILE);
+  }
+
+  /**
+   * Set the default gateway profile
+   * Validates that the profile exists before setting.
+   * Emits GATEWAY_PROFILE_CHANGED event for SSE subscribers.
+   */
+  async setDefaultGatewayProfile(profileName: string): Promise<{ key: string; value: string }> {
+    // Input sanitization
+    const trimmedName = profileName?.trim();
+    if (!trimmedName) {
+      throw new BadRequestException('Profile name cannot be empty');
+    }
+
+    // Validate that profile exists
+    const profile = await this.prisma.profile.findUnique({
+      where: { name: trimmedName },
+    });
+
+    if (!profile) {
+      throw new NotFoundException(`Profile "${trimmedName}" not found`);
+    }
+
+    const result = await this.setSetting(SETTING_KEYS.DEFAULT_GATEWAY_PROFILE, trimmedName);
+
+    // Emit event for SSE subscribers (MCP Streamable HTTP notifications)
+    this.eventEmitter.emit(GATEWAY_PROFILE_CHANGED, { profileName: trimmedName });
+
+    return result;
+  }
+
+  /**
+   * Get all settings with their current values
+   */
+  async getAllSettings(): Promise<Record<string, string>> {
+    const settings = await this.prisma.gatewaySetting.findMany();
+
+    // Start with defaults
+    const result: Record<string, string> = { ...SETTING_DEFAULTS };
+
+    // Override with stored values
+    for (const setting of settings) {
+      result[setting.key] = setting.value;
+    }
+
+    return result;
+  }
+}