@dxheroes/local-mcp-backend 0.3.1

package/src/common/filters/all-exceptions.filter.ts

@@ -0,0 +1,77 @@
+/**
+ * Global Exception Filter
+ *
+ * Catches all exceptions and formats them consistently.
+ */
+
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Logger,
+} from '@nestjs/common';
+import { Request, Response } from 'express';
+
+interface ErrorResponse {
+  statusCode: number;
+  message: string;
+  error: string;
+  timestamp: string;
+  path: string;
+  requestId?: string;
+}
+
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  private readonly logger = new Logger(AllExceptionsFilter.name);
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    let status = HttpStatus.INTERNAL_SERVER_ERROR;
+    let message = 'Internal server error';
+    let error = 'Internal Server Error';
+
+    if (exception instanceof HttpException) {
+      status = exception.getStatus();
+      const exceptionResponse = exception.getResponse();
+
+      if (typeof exceptionResponse === 'string') {
+        message = exceptionResponse;
+      } else if (typeof exceptionResponse === 'object') {
+        const responseObj = exceptionResponse as Record<string, unknown>;
+        message = (responseObj.message as string) || message;
+        error = (responseObj.error as string) || exception.name;
+      }
+    } else if (exception instanceof Error) {
+      message = exception.message;
+      error = exception.name;
+    }
+
+    // Log error
+    this.logger.error(`${request.method} ${request.url} - ${status} - ${message}`, {
+      exception: exception instanceof Error ? exception.stack : String(exception),
+      requestId: request.headers['x-request-id'],
+    });
+
+    const errorResponse: ErrorResponse = {
+      statusCode: status,
+      message,
+      error,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+    };
+
+    // Add request ID if present
+    const requestId = request.headers['x-request-id'];
+    if (typeof requestId === 'string') {
+      errorResponse.requestId = requestId;
+    }
+
+    response.status(status).json(errorResponse);
+  }
+}

package/src/common/interceptors/logging.interceptor.ts

@@ -0,0 +1,45 @@
+/**
+ * Logging Interceptor
+ *
+ * Logs incoming requests and outgoing responses with timing.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { CallHandler, ExecutionContext, Injectable, Logger, NestInterceptor } from '@nestjs/common';
+import { Request, Response } from 'express';
+import { Observable } from 'rxjs';
+import { tap } from 'rxjs/operators';
+
+@Injectable()
+export class LoggingInterceptor implements NestInterceptor {
+  private readonly logger = new Logger('HTTP');
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const ctx = context.switchToHttp();
+    const request = ctx.getRequest<Request>();
+    const response = ctx.getResponse<Response>();
+
+    // Add request ID if not present
+    if (!request.headers['x-request-id']) {
+      request.headers['x-request-id'] = randomUUID();
+    }
+    const requestId = request.headers['x-request-id'];
+    response.setHeader('x-request-id', requestId);
+
+    const { method, url } = request;
+    const startTime = Date.now();
+
+    return next.handle().pipe(
+      tap({
+        next: () => {
+          const duration = Date.now() - startTime;
+          this.logger.log(`${method} ${url} ${response.statusCode} - ${duration}ms`);
+        },
+        error: () => {
+          const duration = Date.now() - startTime;
+          this.logger.warn(`${method} ${url} ERROR - ${duration}ms`);
+        },
+      })
+    );
+  }
+}

package/src/common/pipes/validation.pipe.ts

@@ -0,0 +1,31 @@
+/**
+ * Zod Validation Pipe
+ *
+ * Custom validation pipe that uses Zod schemas.
+ */
+
+import { BadRequestException, Injectable, PipeTransform } from '@nestjs/common';
+import { z } from 'zod';
+
+@Injectable()
+export class ZodValidationPipe implements PipeTransform {
+  constructor(private schema: z.ZodSchema) {}
+
+  transform(value: unknown) {
+    const result = this.schema.safeParse(value);
+
+    if (!result.success) {
+      const errors = result.error.issues.map((issue) => ({
+        path: issue.path.join('.'),
+        message: issue.message,
+      }));
+
+      throw new BadRequestException({
+        message: 'Validation failed',
+        errors,
+      });
+    }
+
+    return result.data;
+  }
+}

package/src/config/app.config.ts

@@ -0,0 +1,15 @@
+/**
+ * Application configuration
+ */
+
+import { registerAs } from '@nestjs/config';
+
+export default registerAs('app', () => ({
+  nodeEnv: process.env.NODE_ENV || 'development',
+  port: Number.parseInt(process.env.PORT || '3001', 10),
+  corsOrigins: process.env.CORS_ORIGINS?.split(',') || [
+    'http://localhost:5173',
+    'http://localhost:3000',
+  ],
+  logLevel: process.env.LOG_LEVEL || 'info',
+}));

package/src/config/database.config.ts

@@ -0,0 +1,34 @@
+/**
+ * Database configuration
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { registerAs } from '@nestjs/config';
+
+export default registerAs('database', () => {
+  // Parse DATABASE_URL for path
+  const databaseUrl = process.env.DATABASE_URL;
+
+  // Default path if not set
+  const defaultPath = join(homedir(), '.local-mcp-gateway-data', 'local-mcp-gateway.db');
+
+  // Extract path from file: URL
+  let path = defaultPath;
+  if (databaseUrl?.startsWith('file:')) {
+    const filePath = databaseUrl.replace('file:', '');
+    if (!filePath.startsWith(':memory:')) {
+      // Handle relative paths (./dev.db)
+      if (filePath.startsWith('./')) {
+        path = join(process.cwd(), filePath.slice(2));
+      } else {
+        path = filePath;
+      }
+    }
+  }
+
+  return {
+    url: databaseUrl || `file:${defaultPath}`,
+    path,
+  };
+});

package/src/main.ts

@@ -0,0 +1,66 @@
+/**
+ * NestJS Application Bootstrap
+ *
+ * Entry point for the Local MCP Gateway backend.
+ * No authentication required - immediate access to all features.
+ */
+
+import { Logger, ValidationPipe } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { NestFactory } from '@nestjs/core';
+import compression from 'compression';
+import helmet from 'helmet';
+import { AppModule } from './app.module.js';
+import { AllExceptionsFilter } from './common/filters/all-exceptions.filter.js';
+import { LoggingInterceptor } from './common/interceptors/logging.interceptor.js';
+
+async function bootstrap() {
+  const logger = new Logger('Bootstrap');
+  const app = await NestFactory.create(AppModule, {
+    logger: ['error', 'warn', 'log', 'debug', 'verbose'],
+  });
+
+  const configService = app.get(ConfigService);
+
+  // Security
+  app.use(helmet());
+  app.use(compression());
+
+  // CORS
+  const corsOrigins = configService.get<string>('CORS_ORIGINS')?.split(',') || [
+    'http://localhost:5173',
+    'http://localhost:3000',
+  ];
+  app.enableCors({
+    origin: corsOrigins,
+    credentials: true,
+    methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+  });
+
+  // Global prefix
+  app.setGlobalPrefix('api');
+
+  // Global pipes
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,
+      forbidNonWhitelisted: true,
+      transform: true,
+      transformOptions: { enableImplicitConversion: true },
+    })
+  );
+
+  // Global filters
+  app.useGlobalFilters(new AllExceptionsFilter());
+
+  // Global interceptors
+  app.useGlobalInterceptors(new LoggingInterceptor());
+
+  const port = configService.get<number>('PORT') || 3001;
+  await app.listen(port);
+
+  logger.log(`Application is running on: http://localhost:${port}`);
+  logger.log(`API available at: http://localhost:${port}/api`);
+}
+
+bootstrap();

package/src/modules/database/database.module.ts

@@ -0,0 +1,15 @@
+/**
+ * Database Module
+ *
+ * Global module providing Prisma client for database operations.
+ */
+
+import { Global, Module } from '@nestjs/common';
+import { PrismaService } from './prisma.service.js';
+
+@Global()
+@Module({
+  providers: [PrismaService],
+  exports: [PrismaService],
+})
+export class DatabaseModule {}

package/src/modules/database/prisma.service.ts

@@ -0,0 +1,110 @@
+/**
+ * Prisma Service
+ *
+ * NestJS service wrapping Prisma Client with lifecycle management.
+ */
+
+import { createPrismaAdapter } from '@dxheroes/local-mcp-database';
+import { PrismaClient } from '@dxheroes/local-mcp-database/generated/prisma';
+import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+
+@Injectable()
+export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(PrismaService.name);
+
+  constructor() {
+    super({
+      adapter: createPrismaAdapter(),
+      log:
+        process.env.NODE_ENV === 'development'
+          ? [
+              { emit: 'event', level: 'query' },
+              { emit: 'stdout', level: 'info' },
+              { emit: 'stdout', level: 'warn' },
+              { emit: 'stdout', level: 'error' },
+            ]
+          : [{ emit: 'stdout', level: 'error' }],
+    });
+  }
+
+  async onModuleInit() {
+    this.logger.log('Connecting to database...');
+    await this.$connect();
+    this.logger.log('Database connected');
+
+    // Seed default data on first run
+    await this.seedDefaultData();
+  }
+
+  /**
+   * Seed default data if database is empty (first run only)
+   * Only seeds if no profiles exist - respects user data
+   */
+  private async seedDefaultData() {
+    // Check if any profiles exist - if so, user has data, don't seed
+    const profileCount = await this.profile.count();
+    if (profileCount > 0) {
+      this.logger.debug('Database has existing data, skipping seed');
+      return;
+    }
+
+    this.logger.log('First run detected, seeding default data...');
+
+    // Create default profile
+    const defaultProfile = await this.profile.create({
+      data: {
+        name: 'default',
+        description: 'Default MCP profile for general use',
+      },
+    });
+    this.logger.log(`Created default profile: ${defaultProfile.id}`);
+
+    // Create Context7 MCP server
+    const context7 = await this.mcpServer.create({
+      data: {
+        name: 'Context7',
+        type: 'remote_http',
+        config: JSON.stringify({ url: 'https://mcp.context7.com/mcp' }),
+      },
+    });
+    this.logger.log(`Created Context7 MCP server: ${context7.id}`);
+
+    // Link Context7 to default profile
+    await this.profileMcpServer.create({
+      data: {
+        profileId: defaultProfile.id,
+        mcpServerId: context7.id,
+        order: 0,
+      },
+    });
+    this.logger.log('Linked Context7 to default profile');
+
+    this.logger.log('Default data seeding complete');
+  }
+
+  async onModuleDestroy() {
+    this.logger.log('Disconnecting from database...');
+    await this.$disconnect();
+    this.logger.log('Database disconnected');
+  }
+
+  /**
+   * Clean database (for testing only)
+   */
+  async cleanDatabase() {
+    if (process.env.NODE_ENV !== 'test') {
+      throw new Error('cleanDatabase can only be called in test environment');
+    }
+
+    const tablenames = await this.$queryRaw<Array<{ name: string }>>`
+      SELECT name FROM sqlite_master
+      WHERE type='table'
+      AND name NOT LIKE '_prisma%'
+      AND name NOT LIKE 'sqlite%'
+    `;
+
+    for (const { name } of tablenames) {
+      await this.$executeRawUnsafe(`DELETE FROM "${name}"`);
+    }
+  }
+}

package/src/modules/debug/debug.controller.ts

@@ -0,0 +1,53 @@
+/**
+ * Debug Controller
+ *
+ * REST API endpoints for debug log management.
+ */
+
+import { Controller, Delete, Get, HttpCode, HttpStatus, Query } from '@nestjs/common';
+import { DebugService } from './debug.service.js';
+
+@Controller('debug')
+export class DebugController {
+  constructor(private readonly debugService: DebugService) {}
+
+  /**
+   * Get debug logs with optional filters
+   */
+  @Get('logs')
+  async getLogs(
+    @Query('profileId') profileId?: string,
+    @Query('mcpServerId') mcpServerId?: string,
+    @Query('status') status?: 'pending' | 'success' | 'error',
+    @Query('since') since?: string,
+    @Query('until') until?: string,
+    @Query('limit') limit?: string,
+    @Query('offset') offset?: string
+  ) {
+    const filter = {
+      profileId,
+      mcpServerId,
+      status,
+      since: since ? new Date(since) : undefined,
+      until: until ? new Date(until) : undefined,
+    };
+
+    return this.debugService.getLogs(
+      filter,
+      limit ? Number.parseInt(limit, 10) : 100,
+      offset ? Number.parseInt(offset, 10) : 0
+    );
+  }
+
+  /**
+   * Clear debug logs
+   */
+  @Delete('logs')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async clearLogs(
+    @Query('profileId') profileId?: string,
+    @Query('mcpServerId') mcpServerId?: string
+  ) {
+    await this.debugService.clearLogs({ profileId, mcpServerId });
+  }
+}

package/src/modules/debug/debug.module.ts

@@ -0,0 +1,16 @@
+/**
+ * Debug Module
+ *
+ * Debug logging endpoints for MCP traffic inspection.
+ */
+
+import { Module } from '@nestjs/common';
+import { DebugController } from './debug.controller.js';
+import { DebugService } from './debug.service.js';
+
+@Module({
+  controllers: [DebugController],
+  providers: [DebugService],
+  exports: [DebugService],
+})
+export class DebugModule {}

package/src/modules/debug/debug.service.ts

@@ -0,0 +1,143 @@
+/**
+ * Debug Service
+ *
+ * Manages debug logs for MCP traffic inspection.
+ * The DebugLog model tracks MCP requests/responses, not general log levels.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { PrismaService } from '../database/prisma.service.js';
+
+interface CreateLogDto {
+  profileId?: string | null;
+  mcpServerId?: string | null;
+  requestType: string;
+  requestPayload: string;
+  responsePayload?: string | null;
+  status: 'pending' | 'success' | 'error';
+  errorMessage?: string | null;
+  durationMs?: number | null;
+}
+
+interface LogFilter {
+  profileId?: string;
+  mcpServerId?: string;
+  status?: 'pending' | 'success' | 'error';
+  since?: Date;
+  until?: Date;
+}
+
+@Injectable()
+export class DebugService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  /**
+   * Create a debug log entry for an MCP request
+   */
+  async createLog(dto: CreateLogDto) {
+    return this.prisma.debugLog.create({
+      data: {
+        profileId: dto.profileId,
+        mcpServerId: dto.mcpServerId,
+        requestType: dto.requestType,
+        requestPayload: dto.requestPayload,
+        responsePayload: dto.responsePayload,
+        status: dto.status,
+        errorMessage: dto.errorMessage,
+        durationMs: dto.durationMs,
+      },
+    });
+  }
+
+  /**
+   * Update a debug log entry with response data
+   */
+  async updateLog(
+    id: string,
+    data: {
+      responsePayload?: string;
+      status?: 'pending' | 'success' | 'error';
+      errorMessage?: string;
+      durationMs?: number;
+      mcpServerId?: string;
+    }
+  ) {
+    return this.prisma.debugLog.update({
+      where: { id },
+      data,
+    });
+  }
+
+  /**
+   * Get debug logs with optional filters
+   */
+  async getLogs(filter?: LogFilter, limit = 100, offset = 0) {
+    const where: Record<string, unknown> = {};
+
+    if (filter?.profileId) {
+      where.profileId = filter.profileId;
+    }
+
+    if (filter?.mcpServerId) {
+      where.mcpServerId = filter.mcpServerId;
+    }
+
+    if (filter?.status) {
+      where.status = filter.status;
+    }
+
+    if (filter?.since || filter?.until) {
+      where.createdAt = {};
+      if (filter.since) {
+        (where.createdAt as Record<string, Date>).gte = filter.since;
+      }
+      if (filter.until) {
+        (where.createdAt as Record<string, Date>).lte = filter.until;
+      }
+    }
+
+    const [logs, total] = await Promise.all([
+      this.prisma.debugLog.findMany({
+        where,
+        orderBy: { createdAt: 'desc' },
+        take: limit,
+        skip: offset,
+        include: {
+          profile: {
+            select: { id: true, name: true },
+          },
+          mcpServer: {
+            select: { id: true, name: true },
+          },
+        },
+      }),
+      this.prisma.debugLog.count({ where }),
+    ]);
+
+    return {
+      logs,
+      total,
+      limit,
+      offset,
+    };
+  }
+
+  /**
+   * Clear debug logs
+   */
+  async clearLogs(options?: { profileId?: string; mcpServerId?: string }) {
+    const where: Record<string, string> = {};
+
+    if (options?.profileId) {
+      where.profileId = options.profileId;
+    }
+
+    if (options?.mcpServerId) {
+      where.mcpServerId = options.mcpServerId;
+    }
+
+    await this.prisma.debugLog.deleteMany({
+      where: Object.keys(where).length > 0 ? where : undefined,
+    });
+  }
+}

package/src/modules/health/health.controller.ts

@@ -0,0 +1,48 @@
+/**
+ * Health Controller
+ *
+ * Health check endpoints for monitoring and load balancers.
+ */
+
+import { Controller, Get } from '@nestjs/common';
+import { PrismaService } from '../database/prisma.service.js';
+
+@Controller('health')
+export class HealthController {
+  constructor(private readonly prisma: PrismaService) {}
+
+  /**
+   * Basic liveness probe
+   */
+  @Get()
+  async getHealth() {
+    return {
+      status: 'ok',
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Readiness probe with database check
+   */
+  @Get('ready')
+  async getReadiness() {
+    try {
+      // Test database connectivity
+      await this.prisma.$queryRaw`SELECT 1`;
+
+      return {
+        status: 'ok',
+        timestamp: new Date().toISOString(),
+        database: 'connected',
+      };
+    } catch (error) {
+      return {
+        status: 'error',
+        timestamp: new Date().toISOString(),
+        database: 'disconnected',
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+}

package/src/modules/health/health.module.ts

@@ -0,0 +1,13 @@
+/**
+ * Health Module
+ *
+ * Health check endpoints for monitoring.
+ */
+
+import { Module } from '@nestjs/common';
+import { HealthController } from './health.controller.js';
+
+@Module({
+  controllers: [HealthController],
+})
+export class HealthModule {}