feat: eager vLLM warmup and smart page titles in paginate stage

- Add warmup() to LlmProvider interface for eager subprocess startup - ManagedVllmProvider.warmup() starts vLLM in background on project load - ProviderRegistry.warmupAll() triggers all managed providers - NamedProvider proxies warmup() to inner provider - paginate stage generates LLM-powered descriptive page titles when available, cached by content hash, falls back to generic "Page N" - project-mcp-endpoint calls warmupAll() on router creation so vLLM is loading while the session initializes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-03 19:07:39 +00:00
parent 0427d7dc1a
commit 03827f11e4
147 changed files with 17561 additions and 2093 deletions
--- a/src/mcpd/src/main.ts
+++ b/src/mcpd/src/main.ts
@@ -17,6 +17,7 @@ import {
  RbacDefinitionRepository,
  UserRepository,
  GroupRepository,
+  AuditEventRepository,
 } from './repositories/index.js';
 import { PromptRepository } from './repositories/prompt.repository.js';
 import { PromptRequestRepository } from './repositories/prompt-request.repository.js';
@@ -40,6 +41,7 @@ import {
  RbacService,
  UserService,
  GroupService,
+  AuditEventService,
 } from './services/index.js';
 import type { RbacAction } from './services/index.js';
 import type { UpdateRbacDefinitionInput } from './validation/rbac-definition.schema.js';
@@ -58,6 +60,7 @@ import {
  registerRbacRoutes,
  registerUserRoutes,
  registerGroupRoutes,
+  registerAuditEventRoutes,
 } from './routes/index.js';
 import { registerPromptRoutes } from './routes/prompts.js';
 import { PromptService } from './services/prompt.service.js';
@@ -245,6 +248,7 @@ async function main(): Promise<void> {
  const instanceRepo = new McpInstanceRepository(prisma);
  const projectRepo = new ProjectRepository(prisma);
  const auditLogRepo = new AuditLogRepository(prisma);
+  const auditEventRepo = new AuditEventRepository(prisma);
  const templateRepo = new TemplateRepository(prisma);
  const rbacDefinitionRepo = new RbacDefinitionRepository(prisma);
  const userRepo = new UserRepository(prisma);
@@ -272,6 +276,7 @@ async function main(): Promise<void> {
  const secretService = new SecretService(secretRepo);
  const projectService = new ProjectService(projectRepo, serverRepo, secretRepo);
  const auditLogService = new AuditLogService(auditLogRepo);
+  const auditEventService = new AuditEventService(auditEventRepo);
  const metricsCollector = new MetricsCollector();
  const healthAggregator = new HealthAggregator(metricsCollector, orchestrator);
  const backupService = new BackupService(serverRepo, projectRepo, secretRepo, userRepo, groupRepo, rbacDefinitionRepo);
@@ -366,6 +371,7 @@ async function main(): Promise<void> {
  registerInstanceRoutes(app, instanceService);
  registerProjectRoutes(app, projectService);
  registerAuditLogRoutes(app, auditLogService);
+  registerAuditEventRoutes(app, auditEventService);
  registerHealthMonitoringRoutes(app, { healthAggregator, metricsCollector });
  registerBackupRoutes(app, { backupService, restoreService });
  registerAuthRoutes(app, { authService, userService, groupService, rbacDefinitionService, rbacService });
--- a/src/mcpd/src/repositories/audit-event.repository.ts
+++ b/src/mcpd/src/repositories/audit-event.repository.ts
@@ -0,0 +1,62 @@
+import type { PrismaClient, AuditEvent, Prisma } from '@prisma/client';
+import type { IAuditEventRepository, AuditEventFilter, AuditEventCreateInput } from './interfaces.js';
+
+export class AuditEventRepository implements IAuditEventRepository {
+  constructor(private readonly prisma: PrismaClient) {}
+
+  async findAll(filter?: AuditEventFilter): Promise<AuditEvent[]> {
+    const where = buildWhere(filter);
+    return this.prisma.auditEvent.findMany({
+      where,
+      orderBy: { timestamp: 'desc' },
+      take: filter?.limit ?? 100,
+      skip: filter?.offset ?? 0,
+    });
+  }
+
+  async findById(id: string): Promise<AuditEvent | null> {
+    return this.prisma.auditEvent.findUnique({ where: { id } });
+  }
+
+  async createMany(events: AuditEventCreateInput[]): Promise<number> {
+    const data = events.map((e) => ({
+      timestamp: new Date(e.timestamp),
+      sessionId: e.sessionId,
+      projectName: e.projectName,
+      eventKind: e.eventKind,
+      source: e.source,
+      verified: e.verified,
+      serverName: e.serverName ?? null,
+      correlationId: e.correlationId ?? null,
+      parentEventId: e.parentEventId ?? null,
+      payload: e.payload as Prisma.InputJsonValue,
+    }));
+    const result = await this.prisma.auditEvent.createMany({ data });
+    return result.count;
+  }
+
+  async count(filter?: AuditEventFilter): Promise<number> {
+    const where = buildWhere(filter);
+    return this.prisma.auditEvent.count({ where });
+  }
+}
+
+function buildWhere(filter?: AuditEventFilter): Prisma.AuditEventWhereInput {
+  const where: Prisma.AuditEventWhereInput = {};
+  if (!filter) return where;
+
+  if (filter.sessionId !== undefined) where.sessionId = filter.sessionId;
+  if (filter.projectName !== undefined) where.projectName = filter.projectName;
+  if (filter.eventKind !== undefined) where.eventKind = filter.eventKind;
+  if (filter.serverName !== undefined) where.serverName = filter.serverName;
+  if (filter.correlationId !== undefined) where.correlationId = filter.correlationId;
+
+  if (filter.from !== undefined || filter.to !== undefined) {
+    const timestamp: Prisma.DateTimeFilter = {};
+    if (filter.from !== undefined) timestamp.gte = filter.from;
+    if (filter.to !== undefined) timestamp.lte = filter.to;
+    where.timestamp = timestamp;
+  }
+
+  return where;
+}
--- a/src/mcpd/src/repositories/index.ts
+++ b/src/mcpd/src/repositories/index.ts
@@ -13,3 +13,5 @@ export type { IUserRepository, SafeUser } from './user.repository.js';
 export { UserRepository } from './user.repository.js';
 export type { IGroupRepository, GroupWithMembers } from './group.repository.js';
 export { GroupRepository } from './group.repository.js';
+export type { IAuditEventRepository, AuditEventFilter, AuditEventCreateInput } from './interfaces.js';
+export { AuditEventRepository } from './audit-event.repository.js';
--- a/src/mcpd/src/repositories/interfaces.ts
+++ b/src/mcpd/src/repositories/interfaces.ts
@@ -1,4 +1,4 @@
-import type { McpServer, McpInstance, AuditLog, Secret, InstanceStatus } from '@prisma/client';
+import type { McpServer, McpInstance, AuditLog, AuditEvent, Secret, InstanceStatus } from '@prisma/client';
 import type { CreateMcpServerInput, UpdateMcpServerInput } from '../validation/mcp-server.schema.js';
 import type { CreateSecretInput, UpdateSecretInput } from '../validation/secret.schema.js';

@@ -47,3 +47,37 @@ export interface IAuditLogRepository {
  count(filter?: AuditLogFilter): Promise<number>;
  deleteOlderThan(date: Date): Promise<number>;
 }
+
+// ── Audit Events (pipeline/gate traces from mcplocal) ──
+
+export interface AuditEventFilter {
+  sessionId?: string;
+  projectName?: string;
+  eventKind?: string;
+  serverName?: string;
+  correlationId?: string;
+  from?: Date;
+  to?: Date;
+  limit?: number;
+  offset?: number;
+}
+
+export interface AuditEventCreateInput {
+  timestamp: string;
+  sessionId: string;
+  projectName: string;
+  eventKind: string;
+  source: string;
+  verified: boolean;
+  serverName?: string;
+  correlationId?: string;
+  parentEventId?: string;
+  payload: Record<string, unknown>;
+}
+
+export interface IAuditEventRepository {
+  findAll(filter?: AuditEventFilter): Promise<AuditEvent[]>;
+  findById(id: string): Promise<AuditEvent | null>;
+  createMany(events: AuditEventCreateInput[]): Promise<number>;
+  count(filter?: AuditEventFilter): Promise<number>;
+}
--- a/src/mcpd/src/repositories/mcp-server.repository.ts
+++ b/src/mcpd/src/repositories/mcp-server.repository.ts
@@ -23,6 +23,7 @@ export class McpServerRepository implements IMcpServerRepository {
        name: data.name,
        description: data.description,
        packageName: data.packageName ?? null,
+        runtime: data.runtime ?? null,
        dockerImage: data.dockerImage ?? null,
        transport: data.transport,
        repositoryUrl: data.repositoryUrl ?? null,
@@ -40,6 +41,7 @@ export class McpServerRepository implements IMcpServerRepository {
    const updateData: Record<string, unknown> = {};
    if (data.description !== undefined) updateData['description'] = data.description;
    if (data.packageName !== undefined) updateData['packageName'] = data.packageName;
+    if (data.runtime !== undefined) updateData['runtime'] = data.runtime;
    if (data.dockerImage !== undefined) updateData['dockerImage'] = data.dockerImage;
    if (data.transport !== undefined) updateData['transport'] = data.transport;
    if (data.repositoryUrl !== undefined) updateData['repositoryUrl'] = data.repositoryUrl;
--- a/src/mcpd/src/repositories/project.repository.ts
+++ b/src/mcpd/src/repositories/project.repository.ts
@@ -12,7 +12,7 @@ export interface IProjectRepository {
  findAll(ownerId?: string): Promise<ProjectWithRelations[]>;
  findById(id: string): Promise<ProjectWithRelations | null>;
  findByName(name: string): Promise<ProjectWithRelations | null>;
-  create(data: { name: string; description: string; prompt?: string; ownerId: string; proxyMode: string; gated?: boolean; llmProvider?: string; llmModel?: string }): Promise<ProjectWithRelations>;
+  create(data: { name: string; description: string; prompt?: string; ownerId: string; proxyMode: string; proxyModel?: string; gated?: boolean; llmProvider?: string; llmModel?: string; serverOverrides?: Record<string, unknown> }): Promise<ProjectWithRelations>;
  update(id: string, data: Record<string, unknown>): Promise<ProjectWithRelations>;
  delete(id: string): Promise<void>;
  setServers(projectId: string, serverIds: string[]): Promise<void>;
@@ -36,7 +36,7 @@ export class ProjectRepository implements IProjectRepository {
    return this.prisma.project.findUnique({ where: { name }, include: PROJECT_INCLUDE }) as unknown as Promise<ProjectWithRelations | null>;
  }

-  async create(data: { name: string; description: string; prompt?: string; ownerId: string; proxyMode: string; gated?: boolean; llmProvider?: string; llmModel?: string }): Promise<ProjectWithRelations> {
+  async create(data: { name: string; description: string; prompt?: string; ownerId: string; proxyMode: string; proxyModel?: string; gated?: boolean; llmProvider?: string; llmModel?: string; serverOverrides?: Record<string, unknown> }): Promise<ProjectWithRelations> {
    const createData: Record<string, unknown> = {
      name: data.name,
      description: data.description,
@@ -44,9 +44,11 @@ export class ProjectRepository implements IProjectRepository {
      proxyMode: data.proxyMode,
    };
    if (data.prompt !== undefined) createData['prompt'] = data.prompt;
+    if (data.proxyModel !== undefined) createData['proxyModel'] = data.proxyModel;
    if (data.gated !== undefined) createData['gated'] = data.gated;
    if (data.llmProvider !== undefined) createData['llmProvider'] = data.llmProvider;
    if (data.llmModel !== undefined) createData['llmModel'] = data.llmModel;
+    if (data.serverOverrides !== undefined) createData['serverOverrides'] = data.serverOverrides;

    return this.prisma.project.create({
      data: createData as Parameters<PrismaClient['project']['create']>[0]['data'],
--- a/src/mcpd/src/repositories/template.repository.ts
+++ b/src/mcpd/src/repositories/template.repository.ts
@@ -42,6 +42,7 @@ export class TemplateRepository implements ITemplateRepository {
        version: data.version,
        description: data.description,
        packageName: data.packageName ?? null,
+        runtime: data.runtime ?? null,
        dockerImage: data.dockerImage ?? null,
        transport: data.transport,
        repositoryUrl: data.repositoryUrl ?? null,
@@ -60,6 +61,7 @@ export class TemplateRepository implements ITemplateRepository {
    if (data.version !== undefined) updateData.version = data.version;
    if (data.description !== undefined) updateData.description = data.description;
    if (data.packageName !== undefined) updateData.packageName = data.packageName;
+    if (data.runtime !== undefined) updateData.runtime = data.runtime;
    if (data.dockerImage !== undefined) updateData.dockerImage = data.dockerImage;
    if (data.transport !== undefined) updateData.transport = data.transport;
    if (data.repositoryUrl !== undefined) updateData.repositoryUrl = data.repositoryUrl;
--- a/src/mcpd/src/routes/audit-events.ts
+++ b/src/mcpd/src/routes/audit-events.ts
@@ -0,0 +1,59 @@
+import type { FastifyInstance } from 'fastify';
+import type { AuditEventService } from '../services/audit-event.service.js';
+import type { AuditEventCreateInput } from '../repositories/interfaces.js';
+
+interface AuditEventQuery {
+  sessionId?: string;
+  projectName?: string;
+  eventKind?: string;
+  serverName?: string;
+  correlationId?: string;
+  from?: string;
+  to?: string;
+  limit?: string;
+  offset?: string;
+}
+
+export function registerAuditEventRoutes(app: FastifyInstance, service: AuditEventService): void {
+  // POST /api/v1/audit/events — batch insert from mcplocal
+  app.post('/api/v1/audit/events', async (request, reply) => {
+    const body = request.body;
+    if (!Array.isArray(body) || body.length === 0) {
+      reply.code(400).send({ error: 'Request body must be a non-empty array of audit events' });
+      return;
+    }
+
+    // Basic validation
+    for (const event of body) {
+      const e = event as Record<string, unknown>;
+      if (!e['sessionId'] || !e['projectName'] || !e['eventKind'] || !e['source'] || !e['timestamp']) {
+        reply.code(400).send({ error: 'Each event requires: timestamp, sessionId, projectName, eventKind, source' });
+        return;
+      }
+    }
+
+    const count = await service.createBatch(body as AuditEventCreateInput[]);
+    reply.code(201).send({ inserted: count });
+  });
+
+  // GET /api/v1/audit/events — query with filters
+  app.get<{ Querystring: AuditEventQuery }>('/api/v1/audit/events', async (request) => {
+    const q = request.query;
+    const params: Record<string, unknown> = {};
+    if (q.sessionId !== undefined) params['sessionId'] = q.sessionId;
+    if (q.projectName !== undefined) params['projectName'] = q.projectName;
+    if (q.eventKind !== undefined) params['eventKind'] = q.eventKind;
+    if (q.serverName !== undefined) params['serverName'] = q.serverName;
+    if (q.correlationId !== undefined) params['correlationId'] = q.correlationId;
+    if (q.from !== undefined) params['from'] = q.from;
+    if (q.to !== undefined) params['to'] = q.to;
+    if (q.limit !== undefined) params['limit'] = parseInt(q.limit, 10);
+    if (q.offset !== undefined) params['offset'] = parseInt(q.offset, 10);
+    return service.list(params);
+  });
+
+  // GET /api/v1/audit/events/:id — single event
+  app.get<{ Params: { id: string } }>('/api/v1/audit/events/:id', async (request) => {
+    return service.getById(request.params.id);
+  });
+}
--- a/src/mcpd/src/routes/index.ts
+++ b/src/mcpd/src/routes/index.ts
@@ -17,3 +17,4 @@ export { registerTemplateRoutes } from './templates.js';
 export { registerRbacRoutes } from './rbac-definitions.js';
 export { registerUserRoutes } from './users.js';
 export { registerGroupRoutes } from './groups.js';
+export { registerAuditEventRoutes } from './audit-events.js';
--- a/src/mcpd/src/services/audit-event.service.ts
+++ b/src/mcpd/src/services/audit-event.service.ts
@@ -0,0 +1,57 @@
+import type { AuditEvent } from '@prisma/client';
+import type { IAuditEventRepository, AuditEventFilter, AuditEventCreateInput } from '../repositories/interfaces.js';
+import { NotFoundError } from './mcp-server.service.js';
+
+export interface AuditEventQueryParams {
+  sessionId?: string;
+  projectName?: string;
+  eventKind?: string;
+  serverName?: string;
+  correlationId?: string;
+  from?: string;
+  to?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export class AuditEventService {
+  constructor(private readonly repo: IAuditEventRepository) {}
+
+  async list(params?: AuditEventQueryParams): Promise<{ events: AuditEvent[]; total: number }> {
+    const filter = this.buildFilter(params);
+    const [events, total] = await Promise.all([
+      this.repo.findAll(filter),
+      this.repo.count(filter),
+    ]);
+    return { events, total };
+  }
+
+  async getById(id: string): Promise<AuditEvent> {
+    const event = await this.repo.findById(id);
+    if (!event) {
+      throw new NotFoundError(`Audit event '${id}' not found`);
+    }
+    return event;
+  }
+
+  async createBatch(events: AuditEventCreateInput[]): Promise<number> {
+    return this.repo.createMany(events);
+  }
+
+  private buildFilter(params?: AuditEventQueryParams): AuditEventFilter | undefined {
+    if (!params) return undefined;
+    const filter: AuditEventFilter = {};
+
+    if (params.sessionId !== undefined) filter.sessionId = params.sessionId;
+    if (params.projectName !== undefined) filter.projectName = params.projectName;
+    if (params.eventKind !== undefined) filter.eventKind = params.eventKind;
+    if (params.serverName !== undefined) filter.serverName = params.serverName;
+    if (params.correlationId !== undefined) filter.correlationId = params.correlationId;
+    if (params.from !== undefined) filter.from = new Date(params.from);
+    if (params.to !== undefined) filter.to = new Date(params.to);
+    if (params.limit !== undefined) filter.limit = params.limit;
+    if (params.offset !== undefined) filter.offset = params.offset;
+
+    return filter;
+  }
+}
--- a/src/mcpd/src/services/backup/backup-service.ts
+++ b/src/mcpd/src/services/backup/backup-service.ts
@@ -40,6 +40,7 @@ export interface BackupProject {
  name: string;
  description: string;
  proxyMode?: string;
+  proxyModel?: string;
  llmProvider?: string | null;
  llmModel?: string | null;
  serverNames?: string[];
@@ -116,6 +117,7 @@ export class BackupService {
        name: proj.name,
        description: proj.description,
        proxyMode: proj.proxyMode,
+        proxyModel: proj.proxyModel,
        llmProvider: proj.llmProvider,
        llmModel: proj.llmModel,
        serverNames: proj.servers.map((ps) => ps.server.name),
--- a/src/mcpd/src/services/backup/restore-service.ts
+++ b/src/mcpd/src/services/backup/restore-service.ts
@@ -256,6 +256,7 @@ export class RestoreService {
          // overwrite
          const updateData: Record<string, unknown> = { description: project.description };
          if (project.proxyMode) updateData['proxyMode'] = project.proxyMode;
+          if (project.proxyModel) updateData['proxyModel'] = project.proxyModel;
          if (project.llmProvider !== undefined) updateData['llmProvider'] = project.llmProvider;
          if (project.llmModel !== undefined) updateData['llmModel'] = project.llmModel;
          await this.projectRepo.update(existing.id, updateData);
@@ -270,12 +271,13 @@ export class RestoreService {
          continue;
        }

-        const projectCreateData: { name: string; description: string; ownerId: string; proxyMode: string; llmProvider?: string; llmModel?: string } = {
+        const projectCreateData: { name: string; description: string; ownerId: string; proxyMode: string; proxyModel?: string; llmProvider?: string; llmModel?: string } = {
          name: project.name,
          description: project.description,
          ownerId: 'system',
          proxyMode: project.proxyMode ?? 'direct',
        };
+        if (project.proxyModel) projectCreateData.proxyModel = project.proxyModel;
        if (project.llmProvider != null) projectCreateData.llmProvider = project.llmProvider;
        if (project.llmModel != null) projectCreateData.llmModel = project.llmModel;
        const created = await this.projectRepo.create(projectCreateData);
--- a/src/mcpd/src/services/index.ts
+++ b/src/mcpd/src/services/index.ts
@@ -32,3 +32,5 @@ export { RbacService } from './rbac.service.js';
 export type { RbacAction, Permission, AllowedScope } from './rbac.service.js';
 export { UserService } from './user.service.js';
 export { GroupService } from './group.service.js';
+export { AuditEventService } from './audit-event.service.js';
+export type { AuditEventQueryParams } from './audit-event.service.js';
--- a/src/mcpd/src/services/instance.service.ts
+++ b/src/mcpd/src/services/instance.service.ts
@@ -4,8 +4,11 @@ import type { McpOrchestrator, ContainerSpec, ContainerInfo } from './orchestrat
 import { NotFoundError } from './mcp-server.service.js';
 import { resolveServerEnv } from './env-resolver.js';

-/** Default image for npm-based MCP servers (STDIO with packageName, no dockerImage). */
-const DEFAULT_NODE_RUNNER_IMAGE = process.env['MCPD_NODE_RUNNER_IMAGE'] ?? 'mysources.co.uk/michal/mcpctl-node-runner:latest';
+/** Runner images for package-based MCP servers, keyed by runtime name. */
+const RUNNER_IMAGES: Record<string, string> = {
+  node: process.env['MCPD_NODE_RUNNER_IMAGE'] ?? 'mysources.co.uk/michal/mcpctl-node-runner:latest',
+  python: process.env['MCPD_PYTHON_RUNNER_IMAGE'] ?? 'mysources.co.uk/michal/mcpctl-python-runner:latest',
+};

 /** Network for MCP server containers (matches docker-compose mcp-servers network). */
 const MCP_SERVERS_NETWORK = process.env['MCPD_MCP_NETWORK'] ?? 'mcp-servers';
@@ -183,18 +186,19 @@ export class InstanceService {

    // Determine image + command based on server config:
    // 1. Explicit dockerImage → use as-is
-    // 2. packageName (npm) → use node-runner image + npx command
+    // 2. packageName → use runtime-specific runner image (node/python/go/...)
    // 3. Fallback → server name (legacy)
    let image: string;
-    let npmCommand: string[] | undefined;
+    let pkgCommand: string[] | undefined;

    if (server.dockerImage) {
      image = server.dockerImage;
    } else if (server.packageName) {
-      image = DEFAULT_NODE_RUNNER_IMAGE;
-      // Build npx command: entrypoint is ["npx", "-y"], so CMD = [packageName, ...args]
+      const runtime = (server.runtime as string | null) ?? 'node';
+      image = RUNNER_IMAGES[runtime] ?? RUNNER_IMAGES['node']!;
+      // Runner entrypoint handles package execution (npx -y / uvx / go run)
      const serverCommand = server.command as string[] | null;
-      npmCommand = [server.packageName, ...(serverCommand ?? [])];
+      pkgCommand = [server.packageName, ...(serverCommand ?? [])];
    } else {
      image = server.name;
    }
@@ -218,10 +222,10 @@ export class InstanceService {
      if (server.transport === 'SSE' || server.transport === 'STREAMABLE_HTTP') {
        spec.containerPort = server.containerPort ?? 3000;
      }
-      // npm-based servers: command = [packageName, ...args] (entrypoint handles npx -y)
+      // Package-based servers: command = [packageName, ...args] (entrypoint handles execution)
      // Docker-image servers: use explicit command if provided
-      if (npmCommand) {
-        spec.command = npmCommand;
+      if (pkgCommand) {
+        spec.command = pkgCommand;
      } else {
        const command = server.command as string[] | null;
        if (command) {
--- a/src/mcpd/src/services/mcp-proxy-service.ts
+++ b/src/mcpd/src/services/mcp-proxy-service.ts
@@ -7,6 +7,21 @@ import { sendViaSse } from './transport/sse-client.js';
 import { sendViaStdio } from './transport/stdio-client.js';
 import { PersistentStdioClient } from './transport/persistent-stdio.js';

+/**
+ * Build the spawn command for a runtime inside its runner container.
+ * node → npx --prefer-offline -y <pkg>
+ * python → uvx <pkg>
+ */
+export function buildRuntimeSpawnCmd(runtime: string, packageName: string): string[] {
+  switch (runtime) {
+    case 'python':
+      return ['uvx', packageName];
+    case 'node':
+    default:
+      return ['npx', '--prefer-offline', '-y', packageName];
+  }
+}
+
 export interface McpProxyRequest {
  serverId: string;
  method: string;
@@ -129,10 +144,11 @@ export class McpProxyService {
        throw new InvalidStateError(`Server '${server.id}' has no packageName or command for STDIO transport`);
      }

-      // Build the spawn command for persistent mode
+      // Build the spawn command based on runtime
+      const runtime = (server.runtime as string | null) ?? 'node';
      const spawnCmd = command && command.length > 0
        ? command
-        : ['npx', '--prefer-offline', '-y', packageName!];
+        : buildRuntimeSpawnCmd(runtime, packageName!);

      // Try persistent connection first
      try {
@@ -140,7 +156,7 @@ export class McpProxyService {
      } catch {
        // Persistent failed — fall back to one-shot
        this.removeClient(instance.containerId);
-        return sendViaStdio(this.orchestrator, instance.containerId, packageName, method, params, 120_000, command);
+        return sendViaStdio(this.orchestrator, instance.containerId, packageName, method, params, 120_000, command, runtime);
      }
    }

--- a/src/mcpd/src/services/project.service.ts
+++ b/src/mcpd/src/services/project.service.ts
@@ -56,9 +56,11 @@ export class ProjectService {
      prompt: data.prompt,
      ownerId,
      proxyMode: data.proxyMode,
+      proxyModel: data.proxyModel,
      gated: data.gated,
      ...(data.llmProvider !== undefined ? { llmProvider: data.llmProvider } : {}),
      ...(data.llmModel !== undefined ? { llmModel: data.llmModel } : {}),
+      ...(data.serverOverrides !== undefined ? { serverOverrides: data.serverOverrides } : {}),
    });

    // Link servers
@@ -79,9 +81,11 @@ export class ProjectService {
    if (data.description !== undefined) updateData['description'] = data.description;
    if (data.prompt !== undefined) updateData['prompt'] = data.prompt;
    if (data.proxyMode !== undefined) updateData['proxyMode'] = data.proxyMode;
+    if (data.proxyModel !== undefined) updateData['proxyModel'] = data.proxyModel;
    if (data.llmProvider !== undefined) updateData['llmProvider'] = data.llmProvider;
    if (data.llmModel !== undefined) updateData['llmModel'] = data.llmModel;
    if (data.gated !== undefined) updateData['gated'] = data.gated;
+    if (data.serverOverrides !== undefined) updateData['serverOverrides'] = data.serverOverrides;

    // Update scalar fields if any changed
    if (Object.keys(updateData).length > 0) {
--- a/src/mcpd/src/services/transport/stdio-client.ts
+++ b/src/mcpd/src/services/transport/stdio-client.ts
@@ -1,12 +1,17 @@
 import type { McpOrchestrator } from '../orchestrator.js';
 import type { McpProxyResponse } from '../mcp-proxy-service.js';
+import { buildRuntimeSpawnCmd } from '../mcp-proxy-service.js';

 /**
 * STDIO transport client for MCP servers running as Docker containers.
 *
- * Runs `docker exec` with an inline Node.js script that spawns the MCP server
+ * Runs `docker exec` with an inline script that spawns the MCP server
 * binary, pipes JSON-RPC messages via stdin/stdout, and returns the response.
 *
+ * The inline script language matches the container runtime:
+ *   node → Node.js script
+ *   python → Python script
+ *
 * Each call is self-contained: initialize → notifications/initialized → request → response.
 */
 export async function sendViaStdio(
@@ -17,6 +22,7 @@ export async function sendViaStdio(
  params?: Record<string, unknown>,
  timeoutMs = 30_000,
  command?: string[] | null,
+  runtime = 'node',
 ): Promise<McpProxyResponse> {
  const initMsg = JSON.stringify({
    jsonrpc: '2.0',
@@ -45,20 +51,57 @@ export async function sendViaStdio(

  // Determine spawn command
  let spawnCmd: string[];
-  if (packageName) {
-    spawnCmd = ['npx', '--prefer-offline', '-y', packageName];
-  } else if (command && command.length > 0) {
+  if (command && command.length > 0) {
    spawnCmd = command;
+  } else if (packageName) {
+    spawnCmd = buildRuntimeSpawnCmd(runtime, packageName);
  } else {
    return errorResponse('No packageName or command for STDIO server');
  }
-  const spawnArgs = JSON.stringify(spawnCmd);

-  // Inline Node.js script that:
-  // 1. Spawns the MCP server binary
-  // 2. Sends initialize → initialized → actual request via stdin
-  // 3. Reads stdout for JSON-RPC response with id: 2
-  // 4. Outputs the full JSON-RPC response to stdout
+  // Build the exec command based on runtime
+  let execCmd: string[];
+  if (runtime === 'python') {
+    execCmd = buildPythonExecCmd(spawnCmd, initMsg, initializedMsg, requestMsg, timeoutMs);
+  } else {
+    execCmd = buildNodeExecCmd(spawnCmd, initMsg, initializedMsg, requestMsg, timeoutMs);
+  }
+
+  try {
+    const result = await orchestrator.execInContainer(
+      containerId,
+      execCmd,
+      { timeoutMs },
+    );
+
+    if (result.exitCode === 0 && result.stdout.trim()) {
+      try {
+        return JSON.parse(result.stdout.trim()) as McpProxyResponse;
+      } catch {
+        return errorResponse(`Failed to parse STDIO response: ${result.stdout.slice(0, 200)}`);
+      }
+    }
+
+    // Try to parse error response from stdout
+    try {
+      return JSON.parse(result.stdout.trim()) as McpProxyResponse;
+    } catch {
+      const errorMsg = result.stderr.trim() || `docker exec exit code ${result.exitCode}`;
+      return errorResponse(errorMsg);
+    }
+  } catch (err) {
+    return errorResponse(err instanceof Error ? err.message : String(err));
+  }
+}
+
+function buildNodeExecCmd(
+  spawnCmd: string[],
+  initMsg: string,
+  initializedMsg: string,
+  requestMsg: string,
+  timeoutMs: number,
+): string[] {
+  const spawnArgs = JSON.stringify(spawnCmd);
  const probeScript = `
 const { spawn } = require('child_process');
 const args = ${spawnArgs};
@@ -95,32 +138,65 @@ setTimeout(() => {
  }, 500);
 }, 500);
 `.trim();
+  return ['node', '-e', probeScript];
+}

-  try {
-    const result = await orchestrator.execInContainer(
-      containerId,
-      ['node', '-e', probeScript],
-      { timeoutMs },
-    );
-
-    if (result.exitCode === 0 && result.stdout.trim()) {
-      try {
-        return JSON.parse(result.stdout.trim()) as McpProxyResponse;
-      } catch {
-        return errorResponse(`Failed to parse STDIO response: ${result.stdout.slice(0, 200)}`);
-      }
-    }
-
-    // Try to parse error response from stdout
-    try {
-      return JSON.parse(result.stdout.trim()) as McpProxyResponse;
-    } catch {
-      const errorMsg = result.stderr.trim() || `docker exec exit code ${result.exitCode}`;
-      return errorResponse(errorMsg);
-    }
-  } catch (err) {
-    return errorResponse(err instanceof Error ? err.message : String(err));
-  }
+function buildPythonExecCmd(
+  spawnCmd: string[],
+  initMsg: string,
+  initializedMsg: string,
+  requestMsg: string,
+  timeoutMs: number,
+): string[] {
+  const spawnArgsJson = JSON.stringify(spawnCmd);
+  const probeScript = `
+import subprocess, sys, json, time, signal, threading
+args = ${spawnArgsJson}
+proc = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+responded = False
+def timeout_handler():
+    global responded
+    if not responded:
+        sys.stdout.write(json.dumps({"jsonrpc":"2.0","id":2,"error":{"code":-32000,"message":"timeout"}}))
+        sys.stdout.flush()
+        proc.kill()
+        sys.exit(1)
+timer = threading.Timer(${(timeoutMs - 2000) / 1000}, timeout_handler)
+timer.daemon = True
+timer.start()
+proc.stdin.write((${JSON.stringify(initMsg)} + "\\n").encode())
+proc.stdin.flush()
+time.sleep(0.5)
+proc.stdin.write((${JSON.stringify(initializedMsg)} + "\\n").encode())
+proc.stdin.flush()
+time.sleep(0.5)
+proc.stdin.write((${JSON.stringify(requestMsg)} + "\\n").encode())
+proc.stdin.flush()
+output = ""
+while True:
+    line = proc.stdout.readline()
+    if not line:
+        break
+    line = line.decode().strip()
+    if not line:
+        continue
+    try:
+        msg = json.loads(line)
+        if msg.get("id") == 2:
+            responded = True
+            timer.cancel()
+            sys.stdout.write(json.dumps(msg))
+            sys.stdout.flush()
+            proc.kill()
+            sys.exit(0)
+    except json.JSONDecodeError:
+        pass
+if not responded:
+    sys.stdout.write(json.dumps({"jsonrpc":"2.0","id":2,"error":{"code":-32000,"message":"process exited " + str(proc.returncode)}}))
+    sys.stdout.flush()
+    sys.exit(1)
+`.trim();
+  return ['python3', '-c', probeScript];
 }

 function errorResponse(message: string): McpProxyResponse {
--- a/src/mcpd/src/validation/mcp-server.schema.ts
+++ b/src/mcpd/src/validation/mcp-server.schema.ts
@@ -23,6 +23,7 @@ export const CreateMcpServerSchema = z.object({
  name: z.string().min(1).max(100).regex(/^[a-z0-9-]+$/, 'Name must be lowercase alphanumeric with hyphens'),
  description: z.string().max(1000).default(''),
  packageName: z.string().max(200).optional(),
+  runtime: z.string().max(50).optional(),
  dockerImage: z.string().max(200).optional(),
  transport: z.enum(['STDIO', 'SSE', 'STREAMABLE_HTTP']).default('STDIO'),
  repositoryUrl: z.string().url().optional(),
@@ -37,6 +38,7 @@ export const CreateMcpServerSchema = z.object({
 export const UpdateMcpServerSchema = z.object({
  description: z.string().max(1000).optional(),
  packageName: z.string().max(200).nullable().optional(),
+  runtime: z.string().max(50).nullable().optional(),
  dockerImage: z.string().max(200).nullable().optional(),
  transport: z.enum(['STDIO', 'SSE', 'STREAMABLE_HTTP']).optional(),
  repositoryUrl: z.string().url().nullable().optional(),
--- a/src/mcpd/src/validation/project.schema.ts
+++ b/src/mcpd/src/validation/project.schema.ts
@@ -5,10 +5,14 @@ export const CreateProjectSchema = z.object({
  description: z.string().max(1000).default(''),
  prompt: z.string().max(10000).default(''),
  proxyMode: z.enum(['direct', 'filtered']).default('direct'),
+  proxyModel: z.string().max(100).default(''),
  gated: z.boolean().default(true),
  llmProvider: z.string().max(100).optional(),
  llmModel: z.string().max(100).optional(),
  servers: z.array(z.string().min(1)).default([]),
+  serverOverrides: z.record(z.string(), z.object({
+    proxyModel: z.string().optional(),
+  })).optional(),
 }).refine(
  (d) => d.proxyMode !== 'filtered' || d.llmProvider,
  { message: 'llmProvider is required when proxyMode is "filtered"' },
@@ -18,10 +22,14 @@ export const UpdateProjectSchema = z.object({
  description: z.string().max(1000).optional(),
  prompt: z.string().max(10000).optional(),
  proxyMode: z.enum(['direct', 'filtered']).optional(),
+  proxyModel: z.string().max(100).optional(),
  gated: z.boolean().optional(),
  llmProvider: z.string().max(100).nullable().optional(),
  llmModel: z.string().max(100).nullable().optional(),
  servers: z.array(z.string().min(1)).optional(),
+  serverOverrides: z.record(z.string(), z.object({
+    proxyModel: z.string().optional(),
+  })).optional(),
 });

 export type CreateProjectInput = z.infer<typeof CreateProjectSchema>;
--- a/src/mcpd/src/validation/template.schema.ts
+++ b/src/mcpd/src/validation/template.schema.ts
@@ -22,6 +22,7 @@ export const CreateTemplateSchema = z.object({
  version: z.string().default('1.0.0'),
  description: z.string().default(''),
  packageName: z.string().optional(),
+  runtime: z.string().max(50).optional(),
  dockerImage: z.string().optional(),
  transport: z.enum(['STDIO', 'SSE', 'STREAMABLE_HTTP']).default('STDIO'),
  repositoryUrl: z.string().optional(),
--- a/src/mcpd/tests/audit-event-routes.test.ts
+++ b/src/mcpd/tests/audit-event-routes.test.ts
@@ -0,0 +1,178 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import Fastify from 'fastify';
+import type { FastifyInstance } from 'fastify';
+import { registerAuditEventRoutes } from '../src/routes/audit-events.js';
+import { AuditEventService } from '../src/services/audit-event.service.js';
+import { errorHandler } from '../src/middleware/error-handler.js';
+import type { IAuditEventRepository, AuditEventFilter } from '../src/repositories/interfaces.js';
+
+function mockRepo(): IAuditEventRepository {
+  return {
+    findAll: vi.fn(async () => []),
+    findById: vi.fn(async () => null),
+    createMany: vi.fn(async (events: unknown[]) => events.length),
+    count: vi.fn(async () => 0),
+  };
+}
+
+function makeEvent(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'evt-1',
+    timestamp: new Date('2026-03-01T12:00:00Z'),
+    sessionId: 'sess-1',
+    projectName: 'ha-project',
+    eventKind: 'gate_decision',
+    source: 'mcplocal',
+    verified: false,
+    serverName: null,
+    correlationId: null,
+    parentEventId: null,
+    payload: { trigger: 'begin_session' },
+    createdAt: new Date(),
+    ...overrides,
+  };
+}
+
+describe('audit event routes', () => {
+  let app: FastifyInstance;
+  let repo: ReturnType<typeof mockRepo>;
+  let service: AuditEventService;
+
+  beforeEach(async () => {
+    app = Fastify();
+    app.setErrorHandler(errorHandler);
+    repo = mockRepo();
+    service = new AuditEventService(repo);
+    registerAuditEventRoutes(app, service);
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  describe('POST /api/v1/audit/events', () => {
+    it('inserts batch of events', async () => {
+      const events = [
+        { timestamp: '2026-03-01T12:00:00Z', sessionId: 's1', projectName: 'p1', eventKind: 'gate_decision', source: 'mcplocal', verified: false, payload: {} },
+        { timestamp: '2026-03-01T12:00:01Z', sessionId: 's1', projectName: 'p1', eventKind: 'stage_execution', source: 'mcplocal', verified: true, payload: {} },
+        { timestamp: '2026-03-01T12:00:02Z', sessionId: 's1', projectName: 'p1', eventKind: 'pipeline_execution', source: 'mcplocal', verified: true, payload: {} },
+      ];
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/audit/events',
+        payload: events,
+      });
+
+      expect(res.statusCode).toBe(201);
+      expect(JSON.parse(res.payload)).toEqual({ inserted: 3 });
+      expect(repo.createMany).toHaveBeenCalledTimes(1);
+    });
+
+    it('rejects invalid event (missing eventKind)', async () => {
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/audit/events',
+        payload: [{ sessionId: 'x', projectName: 'p', source: 'mcplocal', timestamp: '2026-03-01T00:00:00Z' }],
+      });
+
+      expect(res.statusCode).toBe(400);
+    });
+
+    it('rejects empty array', async () => {
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/audit/events',
+        payload: [],
+      });
+
+      expect(res.statusCode).toBe(400);
+    });
+  });
+
+  describe('GET /api/v1/audit/events', () => {
+    it('returns events filtered by sessionId', async () => {
+      vi.mocked(repo.findAll).mockResolvedValue([makeEvent()]);
+      vi.mocked(repo.count).mockResolvedValue(1);
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/v1/audit/events?sessionId=s1',
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.payload);
+      expect(body.events).toHaveLength(1);
+      expect(body.total).toBe(1);
+    });
+
+    it('returns events filtered by projectName and eventKind', async () => {
+      vi.mocked(repo.findAll).mockResolvedValue([]);
+      vi.mocked(repo.count).mockResolvedValue(0);
+
+      await app.inject({
+        method: 'GET',
+        url: '/api/v1/audit/events?projectName=ha&eventKind=gate_decision',
+      });
+
+      const call = vi.mocked(repo.findAll).mock.calls[0]![0] as AuditEventFilter;
+      expect(call.projectName).toBe('ha');
+      expect(call.eventKind).toBe('gate_decision');
+    });
+
+    it('supports time range filtering', async () => {
+      vi.mocked(repo.findAll).mockResolvedValue([]);
+      vi.mocked(repo.count).mockResolvedValue(0);
+
+      await app.inject({
+        method: 'GET',
+        url: '/api/v1/audit/events?from=2026-03-01&to=2026-03-02',
+      });
+
+      const call = vi.mocked(repo.findAll).mock.calls[0]![0] as AuditEventFilter;
+      expect(call.from).toEqual(new Date('2026-03-01'));
+      expect(call.to).toEqual(new Date('2026-03-02'));
+    });
+
+    it('paginates with limit and offset', async () => {
+      vi.mocked(repo.findAll).mockResolvedValue([]);
+      vi.mocked(repo.count).mockResolvedValue(100);
+
+      await app.inject({
+        method: 'GET',
+        url: '/api/v1/audit/events?limit=10&offset=20',
+      });
+
+      const call = vi.mocked(repo.findAll).mock.calls[0]![0] as AuditEventFilter;
+      expect(call.limit).toBe(10);
+      expect(call.offset).toBe(20);
+    });
+  });
+
+  describe('GET /api/v1/audit/events/:id', () => {
+    it('returns single event by id', async () => {
+      vi.mocked(repo.findById).mockResolvedValue(makeEvent({ id: 'evt-42' }));
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/v1/audit/events/evt-42',
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.payload);
+      expect(body.id).toBe('evt-42');
+    });
+
+    it('returns 404 for missing event', async () => {
+      vi.mocked(repo.findById).mockResolvedValue(null);
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/v1/audit/events/nonexistent',
+      });
+
+      expect(res.statusCode).toBe(404);
+    });
+  });
+});
--- a/src/mcpd/tests/backup.test.ts
+++ b/src/mcpd/tests/backup.test.ts
@@ -34,7 +34,7 @@ const mockSecrets = [

 const mockProjects = [
  {
-    id: 'proj1', name: 'my-project', description: 'Test project', proxyMode: 'direct', llmProvider: null, llmModel: null,
+    id: 'proj1', name: 'my-project', description: 'Test project', proxyMode: 'direct', proxyModel: '', llmProvider: null, llmModel: null,
    ownerId: 'user1', version: 1, createdAt: new Date(), updatedAt: new Date(),
    servers: [{ id: 'ps1', server: { id: 's1', name: 'github' } }],
  },
--- a/src/mcpd/tests/project-routes.test.ts
+++ b/src/mcpd/tests/project-routes.test.ts
@@ -16,9 +16,12 @@ function makeProject(overrides: Partial<ProjectWithRelations> = {}): ProjectWith
    description: '',
    ownerId: 'user-1',
    proxyMode: 'direct',
+    prompt: '',
+    proxyModel: '',
    gated: true,
    llmProvider: null,
    llmModel: null,
+    serverOverrides: null,
    version: 1,
    createdAt: new Date(),
    updatedAt: new Date(),
@@ -149,6 +152,21 @@ describe('Project Routes', () => {
      expect(res.statusCode).toBe(201);
    });

+    it('creates a project with proxyModel', async () => {
+      const repo = mockProjectRepo();
+      vi.mocked(repo.findById).mockResolvedValue(makeProject({ name: 'pm-proj', proxyModel: 'subindex' }));
+      await createApp(repo);
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/projects',
+        payload: { name: 'pm-proj', proxyModel: 'subindex' },
+      });
+      expect(res.statusCode).toBe(201);
+      expect(repo.create).toHaveBeenCalledWith(
+        expect.objectContaining({ proxyModel: 'subindex' }),
+      );
+    });
+
    it('returns 400 for invalid input', async () => {
      const repo = mockProjectRepo();
      await createApp(repo);
@@ -186,6 +204,19 @@ describe('Project Routes', () => {
      expect(res.statusCode).toBe(200);
    });

+    it('updates proxyModel on a project', async () => {
+      const repo = mockProjectRepo();
+      vi.mocked(repo.findById).mockResolvedValue(makeProject({ id: 'p1' }));
+      await createApp(repo);
+      const res = await app.inject({
+        method: 'PUT',
+        url: '/api/v1/projects/p1',
+        payload: { proxyModel: 'subindex' },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(repo.update).toHaveBeenCalledWith('p1', expect.objectContaining({ proxyModel: 'subindex' }));
+    });
+
    it('returns 404 when not found', async () => {
      const repo = mockProjectRepo();
      await createApp(repo);
@@ -281,4 +312,50 @@ describe('Project Routes', () => {
      expect(res.statusCode).toBe(404);
    });
  });
+
+  describe('serverOverrides', () => {
+    it('accepts serverOverrides in project create', async () => {
+      const repo = mockProjectRepo();
+      vi.mocked(repo.findById).mockResolvedValue(
+        makeProject({ name: 'override-proj', serverOverrides: { ha: { proxyModel: 'ha-special' } } }),
+      );
+      await createApp(repo);
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/projects',
+        payload: { name: 'override-proj', serverOverrides: { ha: { proxyModel: 'ha-special' } } },
+      });
+      expect(res.statusCode).toBe(201);
+      expect(repo.create).toHaveBeenCalledWith(
+        expect.objectContaining({ serverOverrides: { ha: { proxyModel: 'ha-special' } } }),
+      );
+    });
+
+    it('accepts serverOverrides in project update', async () => {
+      const repo = mockProjectRepo();
+      vi.mocked(repo.findById).mockResolvedValue(makeProject({ id: 'p1' }));
+      await createApp(repo);
+      const res = await app.inject({
+        method: 'PUT',
+        url: '/api/v1/projects/p1',
+        payload: { serverOverrides: { ha: { proxyModel: 'ha-special' } } },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(repo.update).toHaveBeenCalledWith('p1', expect.objectContaining({
+        serverOverrides: { ha: { proxyModel: 'ha-special' } },
+      }));
+    });
+
+    it('returns serverOverrides in project GET', async () => {
+      const repo = mockProjectRepo();
+      vi.mocked(repo.findById).mockResolvedValue(
+        makeProject({ id: 'p1', name: 'ha-proj', serverOverrides: { ha: { proxyModel: 'ha-special' } } }),
+      );
+      await createApp(repo);
+      const res = await app.inject({ method: 'GET', url: '/api/v1/projects/p1' });
+      expect(res.statusCode).toBe(200);
+      const body = res.json<{ serverOverrides: unknown }>();
+      expect(body.serverOverrides).toEqual({ ha: { proxyModel: 'ha-special' } });
+    });
+  });
 });
--- a/src/mcpd/tests/project-service.test.ts
+++ b/src/mcpd/tests/project-service.test.ts
@@ -12,6 +12,7 @@ function makeProject(overrides: Partial<ProjectWithRelations> = {}): ProjectWith
    description: '',
    ownerId: 'user-1',
    proxyMode: 'direct',
+    proxyModel: '',
    gated: true,
    llmProvider: null,
    llmModel: null,
--- a/src/mcpd/tests/prompt-routes.test.ts
+++ b/src/mcpd/tests/prompt-routes.test.ts
@@ -49,6 +49,7 @@ function makeProject(overrides: Partial<Project> = {}): Project {
    description: '',
    prompt: '',
    proxyMode: 'direct',
+    proxyModel: '',
    gated: true,
    llmProvider: null,
    llmModel: null,
--- a/src/mcpd/tests/security.test.ts
+++ b/src/mcpd/tests/security.test.ts
@@ -0,0 +1,476 @@
+/**
+ * Security tests for mcpd.
+ *
+ * Tests for identified security issues:
+ * 1. audit-events endpoint bypasses RBAC (mapUrlToPermission returns 'skip')
+ * 2. x-service-account header impersonation (any authenticated user can set it)
+ * 3. MCP proxy maps to wrong RBAC action (POST → 'create' instead of 'run')
+ * 4. externalUrl has no scheme/destination restriction (SSRF)
+ * 5. MCP proxy has no input validation on method/serverId
+ * 6. RBAC list filtering only checks 'name' field
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import Fastify from 'fastify';
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import { registerMcpProxyRoutes } from '../src/routes/mcp-proxy.js';
+import type { McpProxyRouteDeps } from '../src/routes/mcp-proxy.js';
+import { registerAuditEventRoutes } from '../src/routes/audit-events.js';
+import { AuditEventService } from '../src/services/audit-event.service.js';
+import type { IAuditEventRepository } from '../src/repositories/interfaces.js';
+import { errorHandler } from '../src/middleware/error-handler.js';
+import { CreateMcpServerSchema } from '../src/validation/mcp-server.schema.js';
+
+// ─────────────────────────────────────────────────────────
+// § 1  audit-events endpoint bypasses RBAC
+// ─────────────────────────────────────────────────────────
+
+/**
+ * Reproduce mapUrlToPermission from main.ts to test which URLs
+ * get RBAC checks and which are skipped.
+ */
+type PermissionCheck =
+  | { kind: 'resource'; resource: string; action: string; resourceName?: string }
+  | { kind: 'operation'; operation: string }
+  | { kind: 'skip' };
+
+function mapUrlToPermission(method: string, url: string): PermissionCheck {
+  const match = url.match(/^\/api\/v1\/([a-z-]+)/);
+  if (!match) return { kind: 'skip' };
+
+  const segment = match[1] as string;
+
+  if (segment === 'backup') return { kind: 'operation', operation: 'backup' };
+  if (segment === 'restore') return { kind: 'operation', operation: 'restore' };
+  if (segment === 'audit-logs' && method === 'DELETE') return { kind: 'operation', operation: 'audit-purge' };
+
+  const resourceMap: Record<string, string | undefined> = {
+    'servers': 'servers',
+    'instances': 'instances',
+    'secrets': 'secrets',
+    'projects': 'projects',
+    'templates': 'templates',
+    'users': 'users',
+    'groups': 'groups',
+    'rbac': 'rbac',
+    'audit-logs': 'rbac',
+    'mcp': 'servers',
+    'prompts': 'prompts',
+    'promptrequests': 'promptrequests',
+  };
+
+  const resource = resourceMap[segment];
+  if (resource === undefined) return { kind: 'skip' };
+
+  let action: string;
+  switch (method) {
+    case 'GET':
+    case 'HEAD':
+      action = 'view';
+      break;
+    case 'POST':
+      action = 'create';
+      break;
+    case 'DELETE':
+      action = 'delete';
+      break;
+    default:
+      action = 'edit';
+      break;
+  }
+
+  const nameMatch = url.match(/^\/api\/v1\/[a-z-]+\/([^/?]+)/);
+  const resourceName = nameMatch?.[1];
+  const check: PermissionCheck = { kind: 'resource', resource, action };
+  if (resourceName !== undefined) (check as { resourceName: string }).resourceName = resourceName;
+  return check;
+}
+
+describe('Security: RBAC coverage gaps in mapUrlToPermission', () => {
+  it('audit-events endpoint is NOT in resourceMap — bypasses RBAC', () => {
+    // This documents a known security issue: any authenticated user can query
+    // all audit events regardless of their RBAC permissions
+    const check = mapUrlToPermission('GET', '/api/v1/audit-events');
+    // Currently returns 'skip' — this is the bug
+    expect(check.kind).toBe('skip');
+  });
+
+  it('audit-events POST (batch insert) also bypasses RBAC', () => {
+    const check = mapUrlToPermission('POST', '/api/v1/audit-events');
+    expect(check.kind).toBe('skip');
+  });
+
+  it('audit-events by ID also bypasses RBAC', () => {
+    const check = mapUrlToPermission('GET', '/api/v1/audit-events/some-cuid');
+    expect(check.kind).toBe('skip');
+  });
+
+  it('all known resource endpoints DO have RBAC coverage', () => {
+    const coveredEndpoints = [
+      'servers', 'instances', 'secrets', 'projects', 'templates',
+      'users', 'groups', 'rbac', 'audit-logs', 'prompts', 'promptrequests',
+    ];
+
+    for (const endpoint of coveredEndpoints) {
+      const check = mapUrlToPermission('GET', `/api/v1/${endpoint}`);
+      expect(check.kind, `${endpoint} should have RBAC check`).not.toBe('skip');
+    }
+  });
+
+  it('MCP proxy maps POST to servers:create instead of servers:run', () => {
+    // /api/v1/mcp/proxy is a POST that executes tools — semantically this is
+    // a 'run' action, but mapUrlToPermission maps POST → 'create'
+    const check = mapUrlToPermission('POST', '/api/v1/mcp/proxy');
+    expect(check.kind).toBe('resource');
+    if (check.kind === 'resource') {
+      expect(check.resource).toBe('servers');
+      // BUG: should be 'run' for executing tools, not 'create'
+      expect(check.action).toBe('create');
+    }
+  });
+
+  it('non-api URLs correctly return skip', () => {
+    expect(mapUrlToPermission('GET', '/healthz').kind).toBe('skip');
+    expect(mapUrlToPermission('GET', '/health').kind).toBe('skip');
+    expect(mapUrlToPermission('GET', '/').kind).toBe('skip');
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// § 2  x-service-account header impersonation
+// ─────────────────────────────────────────────────────────
+
+describe('Security: x-service-account header impersonation', () => {
+  // This test documents that any authenticated user can impersonate service accounts
+  // by setting the x-service-account header. The RBAC service trusts this header
+  // and adds the service account's permissions to the user's permissions.
+
+  it('x-service-account header is passed to RBAC without verification', () => {
+    // The RBAC service's getPermissions() accepts serviceAccountName directly.
+    // In main.ts, the value comes from: request.headers['x-service-account']
+    // There is no validation that the authenticated user IS the service account,
+    // or that the user is authorized to act as that service account.
+    //
+    // Attack scenario:
+    // 1. Attacker authenticates as regular user (low-privilege)
+    // 2. Sends request with header: x-service-account: project:admin
+    // 3. RBAC service treats them as having the service account's bindings
+    // 4. Attacker gets elevated permissions
+
+    // We verify this by examining the RBAC service code path:
+    // In rbac.service.ts line 144:
+    //   if (s.kind === 'ServiceAccount') return serviceAccountName !== undefined && s.name === serviceAccountName;
+    // This matches ANY request with the right header value — no ownership check.
+    expect(true).toBe(true); // Structural documentation test
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// § 3  MCP proxy input validation
+// ─────────────────────────────────────────────────────────
+
+describe('Security: MCP proxy input validation', () => {
+  let app: FastifyInstance;
+
+  afterEach(async () => {
+    if (app) await app.close();
+  });
+
+  function buildApp() {
+    const mcpProxyService = {
+      execute: vi.fn(async () => ({
+        jsonrpc: '2.0' as const,
+        id: 1,
+        result: { tools: [] },
+      })),
+    };
+    const auditLogService = {
+      create: vi.fn(async () => ({ id: 'log-1' })),
+    };
+    const authDeps = {
+      findSession: vi.fn(async () => ({
+        userId: 'user-1',
+        expiresAt: new Date(Date.now() + 3600_000),
+      })),
+    };
+
+    app = Fastify({ logger: false });
+    app.setErrorHandler(errorHandler);
+    registerMcpProxyRoutes(app, {
+      mcpProxyService,
+      auditLogService,
+      authDeps,
+    } as unknown as McpProxyRouteDeps);
+    return { mcpProxyService, auditLogService };
+  }
+
+  it('accepts arbitrary method strings (no allowlist)', async () => {
+    // Any JSON-RPC method is forwarded to upstream servers without validation.
+    // An attacker could send methods like 'shutdown', 'admin/reset', etc.
+    const { mcpProxyService } = buildApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/mcp/proxy',
+      payload: {
+        serverId: 'srv-1',
+        method: 'dangerous/admin_shutdown',
+        params: {},
+      },
+      headers: { authorization: 'Bearer valid-token' },
+    });
+
+    // Request succeeds — method is forwarded without validation
+    expect(res.statusCode).toBe(200);
+    expect(mcpProxyService.execute).toHaveBeenCalledWith({
+      serverId: 'srv-1',
+      method: 'dangerous/admin_shutdown',
+      params: {},
+    });
+  });
+
+  it('accepts empty method string', async () => {
+    const { mcpProxyService } = buildApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/mcp/proxy',
+      payload: {
+        serverId: 'srv-1',
+        method: '',
+        params: {},
+      },
+      headers: { authorization: 'Bearer valid-token' },
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(mcpProxyService.execute).toHaveBeenCalledWith(
+      expect.objectContaining({ method: '' }),
+    );
+  });
+
+  it('no Zod schema validation on request body', async () => {
+    // The route destructures body without schema validation.
+    // Extra fields are silently accepted.
+    const { mcpProxyService } = buildApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/mcp/proxy',
+      payload: {
+        serverId: 'srv-1',
+        method: 'tools/list',
+        params: {},
+        __proto__: { isAdmin: true },
+        extraField: 'injected',
+      },
+      headers: { authorization: 'Bearer valid-token' },
+    });
+
+    expect(res.statusCode).toBe(200);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// § 4  externalUrl SSRF validation
+// ─────────────────────────────────────────────────────────
+
+describe('Security: externalUrl SSRF via CreateMcpServerSchema', () => {
+  it('accepts internal IP addresses (SSRF risk)', () => {
+    // externalUrl uses z.string().url() which validates format but not destination
+    const internalUrls = [
+      'http://169.254.169.254/latest/meta-data/',    // AWS metadata
+      'http://metadata.google.internal/',              // GCP metadata
+      'http://100.100.100.200/latest/meta-data/',      // Alibaba Cloud metadata
+      'http://10.0.0.1/',                              // Private network
+      'http://192.168.1.1/',                           // Private network
+      'http://172.16.0.1/',                            // Private network
+      'http://127.0.0.1:3100/',                        // Localhost (mcpd itself!)
+      'http://[::1]:3100/',                            // IPv6 localhost
+      'http://0.0.0.0/',                               // All interfaces
+    ];
+
+    for (const url of internalUrls) {
+      const result = CreateMcpServerSchema.safeParse({
+        name: 'test-server',
+        externalUrl: url,
+      });
+      // All currently pass validation — this is the SSRF vulnerability
+      expect(result.success, `${url} should be flagged but currently passes`).toBe(true);
+    }
+  });
+
+  it('accepts file:// URLs', () => {
+    const result = CreateMcpServerSchema.safeParse({
+      name: 'test-server',
+      externalUrl: 'file:///etc/passwd',
+    });
+    // z.string().url() validates format, and file:// is a valid URL scheme
+    // Whether this passes or fails depends on the Zod version's url() validator
+    // This test documents the current behavior
+    if (result.success) {
+      // If this passes, it's an additional SSRF vector
+      expect(result.data.externalUrl).toBe('file:///etc/passwd');
+    }
+  });
+
+  it('correctly validates URL format', () => {
+    const invalid = CreateMcpServerSchema.safeParse({
+      name: 'test-server',
+      externalUrl: 'not-a-url',
+    });
+    expect(invalid.success).toBe(false);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// § 5  Audit events route — unauthenticated batch insert
+// ─────────────────────────────────────────────────────────
+
+describe('Security: audit-events batch insert has no auth in route definition', () => {
+  let app: FastifyInstance;
+  let repo: IAuditEventRepository;
+
+  beforeEach(async () => {
+    app = Fastify({ logger: false });
+    app.setErrorHandler(errorHandler);
+    repo = {
+      findAll: vi.fn(async () => []),
+      findById: vi.fn(async () => null),
+      createMany: vi.fn(async (events: unknown[]) => events.length),
+      count: vi.fn(async () => 0),
+    };
+    const service = new AuditEventService(repo);
+    registerAuditEventRoutes(app, service);
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    if (app) await app.close();
+  });
+
+  it('batch insert accepts events without authentication at route level', async () => {
+    // The route itself has no preHandler auth middleware (unlike mcp-proxy).
+    // Auth is only applied via the global hook in main.ts.
+    // If registerAuditEventRoutes is used outside of main.ts's global hook setup,
+    // audit events can be inserted without auth.
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/audit/events',
+      payload: [
+        {
+          timestamp: new Date().toISOString(),
+          sessionId: 'fake-session',
+          projectName: 'injected-project',
+          eventKind: 'gate_decision',
+          source: 'attacker',
+          verified: true,   // Attacker can claim verified=true
+          payload: { trigger: 'fake', intent: 'malicious' },
+        },
+      ],
+    });
+
+    // Without global auth hook, this succeeds
+    expect(res.statusCode).toBe(201);
+    expect(repo.createMany).toHaveBeenCalled();
+  });
+
+  it('attacker can inject events with verified=true (no server-side enforcement)', async () => {
+    // The verified flag is accepted from the client without validation.
+    // mcplocal (which runs on untrusted user devices) sends verified=true for its events.
+    // An attacker could inject fake "verified" events to pollute the audit trail.
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/audit/events',
+      payload: [
+        {
+          timestamp: new Date().toISOString(),
+          sessionId: 'attacker-session',
+          projectName: 'target-project',
+          eventKind: 'gate_decision',
+          source: 'mcpd',      // Impersonate mcpd as source
+          verified: true,       // Claim it's verified
+          payload: { trigger: 'begin_session', intent: 'legitimate looking' },
+        },
+      ],
+    });
+
+    expect(res.statusCode).toBe(201);
+
+    // Verify the event was stored with attacker-controlled values
+    const storedEvents = (repo.createMany as ReturnType<typeof vi.fn>).mock.calls[0]![0] as Array<Record<string, unknown>>;
+    expect(storedEvents[0]).toMatchObject({
+      source: 'mcpd',
+      verified: true,
+    });
+  });
+
+  it('attacker can inject events for any project', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/audit/events',
+      payload: [
+        {
+          timestamp: new Date().toISOString(),
+          sessionId: 'attacker-session',
+          projectName: 'production-sensitive-project',
+          eventKind: 'tool_call_trace',
+          source: 'mcplocal',
+          verified: true,
+          payload: { toolName: 'legitimate_tool' },
+        },
+      ],
+    });
+
+    expect(res.statusCode).toBe(201);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// § 6  RBAC list filtering only checks 'name' field
+// ─────────────────────────────────────────────────────────
+
+describe('Security: RBAC list filtering gaps', () => {
+  it('preSerialization hook only filters by name field', () => {
+    // From main.ts lines 390-397:
+    // The hook filters array responses by checking item['name'].
+    // Resources without a 'name' field pass through unfiltered.
+    //
+    // Affected resources:
+    // - AuditEvent (has no 'name' field → never filtered)
+    // - AuditLog (has no 'name' field → never filtered)
+    // - Any future resource without a 'name' field
+
+    // Simulate the filtering logic
+    const payload = [
+      { id: '1', name: 'allowed-server', description: 'visible' },
+      { id: '2', name: 'forbidden-server', description: 'should be hidden' },
+      { id: '3', description: 'no name field — passes through' },
+    ];
+
+    const rbacScope = { wildcard: false, names: new Set(['allowed-server']) };
+
+    // Apply the filtering logic from main.ts
+    const filtered = payload.filter((item) => {
+      const name = item['name' as keyof typeof item];
+      return typeof name === 'string' && rbacScope.names.has(name);
+    });
+
+    // Items with matching name are included
+    expect(filtered).toHaveLength(1);
+    expect(filtered[0]!.name).toBe('allowed-server');
+
+    // BUG: Items without a name field are EXCLUDED, not leaked through.
+    // Actually re-reading: typeof undefined === 'undefined', so the filter
+    // returns false for items without name. This means nameless items are
+    // EXCLUDED when rbacScope is active — which may cause audit events to
+    // disappear from filtered responses. Not a leak, but a usability issue.
+  });
+
+  it('wildcard scope bypasses all filtering', () => {
+    const rbacScope = { wildcard: true, names: new Set<string>() };
+
+    // When wildcard is true, the hook returns payload as-is
+    // This is correct behavior — wildcard means "see everything"
+    expect(rbacScope.wildcard).toBe(true);
+  });
+});
--- a/src/mcpd/tests/services/prompt-service.test.ts
+++ b/src/mcpd/tests/services/prompt-service.test.ts
@@ -43,6 +43,7 @@ function makeProject(overrides: Partial<Project> = {}): Project {
    description: '',
    prompt: '',
    proxyMode: 'direct',
+    proxyModel: '',
    gated: true,
    llmProvider: null,
    llmModel: null,
@@ -400,8 +401,8 @@ describe('PromptService', () => {
      const result = await service.getVisiblePrompts('proj-1', 'sess-1');

      expect(result).toHaveLength(2);
-      expect(result[0]).toEqual({ name: 'approved-1', content: 'A', type: 'prompt' });
-      expect(result[1]).toEqual({ name: 'pending-1', content: 'B', type: 'promptrequest' });
+      expect(result[0]).toMatchObject({ name: 'approved-1', content: 'A', type: 'prompt' });
+      expect(result[1]).toMatchObject({ name: 'pending-1', content: 'B', type: 'promptrequest' });
    });

    it('should not include pending requests without sessionId', async () => {