@hed-hog/core 0.0.328 → 0.0.329

package/hedhog/table/route.yaml

@@ -1,22 +1,33 @@
-columns:
-  - type: pk
-  - name: url
-  - name: method
-    type: enum
-    enum:
-      - GET
-      - POST
-      - PATCH
-      - DELETE
-      - PUT
-      - OPTIONS
-      - HEAD
-  - name: description
-    isNullable: true
-  - type: created_at
-  - type: updated_at
-indices:
-  - columns:
-      - url
-      - method
-    isUnique: true
+columns:
+  - type: pk
+  - name: type
+    type: enum
+    enum:
+      - HTTP
+      - MCP
+    default: HTTP
+  - name: name
+    isNullable: true
+  - name: url
+    isNullable: true
+  - name: method
+    type: enum
+    enum:
+      - GET
+      - POST
+      - PATCH
+      - DELETE
+      - PUT
+      - OPTIONS
+      - HEAD
+    isNullable: true
+  - name: tool_name
+    isNullable: true
+  - name: description
+    isNullable: true
+  - type: created_at
+  - type: updated_at
+indices:
+  - columns:
+      - tool_name
+    isUnique: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hed-hog/core",
-  "version": "0.0.328",
+  "version": "0.0.329",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
@@ -30,12 +30,13 @@
     "sharp": "^0.34.2",
     "speakeasy": "^2.0.0",
     "uuid": "^11.1.0",
-    "@hed-hog/api-locale": "0.0.14",
+    "@modelcontextprotocol/sdk": "^1.12.0",
     "@hed-hog/api": "0.0.8",
+    "@hed-hog/api-locale": "0.0.14",
     "@hed-hog/api-pagination": "0.0.7",
-    "@hed-hog/api-prisma": "0.0.6",
+    "@hed-hog/api-mail": "0.0.9",
     "@hed-hog/api-types": "0.0.1",
-    "@hed-hog/api-mail": "0.0.9"
+    "@hed-hog/api-prisma": "0.0.6"
   },
   "exports": {
     ".": {

package/src/core.module.ts

@@ -8,6 +8,8 @@ import { forwardRef, Global, Inject, MiddlewareConsumer, Module, NestModule, OnM
 import { ConfigModule } from '@nestjs/config';
 import { APP_INTERCEPTOR, Reflector } from '@nestjs/core';
 import { AiModule } from './ai/ai.module';
+import { McpModule } from './mcp/mcp.module';
+import { McpChatModule } from './mcp-chat/mcp-chat.module';
 import { AuthModule } from './auth/auth.module';
 import { SystemModule } from './core/system.module';
 import { DashboardModule } from './dashboard/dashboard.module';
@@ -29,8 +31,8 @@ import { SessionModule } from './session/session.module';
 import { SettingModule } from './setting/setting.module';
 import { SettingService } from './setting/setting.service';
 import { TaskModule } from './task/task.module';
-import { UserModule } from './user/user.module';
-import { WebhookIntegrationModule } from './webhook-integration/webhook-integration.module';
+import { UserModule } from './user/user.module';
+import { WebhookIntegrationModule } from './webhook-integration/webhook-integration.module';
 import { IsEmailWithSettingsConstraint } from './validators/is-email-with-settings.validator';
 import { IsPinCodeWithSettingConstraint } from './validators/is-pin-code-with-setting.validator';
 import { IsStrongPasswordWithSettingsConstraint } from './validators/is-strong-password-with-settings.validator';
@@ -64,10 +66,12 @@ import { ValidatorServiceLocator } from './validators/service-locator';
     forwardRef(() => SecurityModule),
     forwardRef(() => ProfileModule),
     forwardRef(() => SessionModule),
-    forwardRef(() => OAuthModule),
-    forwardRef(() => IntegrationModule),
-    forwardRef(() => WebhookIntegrationModule),
-  ],
+    forwardRef(() => OAuthModule),
+    forwardRef(() => IntegrationModule),
+    forwardRef(() => WebhookIntegrationModule),
+    forwardRef(() => McpModule),
+    forwardRef(() => McpChatModule),
+  ],
   exports: [
     UserModule,
     AuthModule,
@@ -81,10 +85,10 @@ import { ValidatorServiceLocator } from './validators/service-locator';
     SettingModule,
     FileModule,
     SessionModule,
-    AiModule,
-    IntegrationModule,
-    WebhookIntegrationModule,
-    IsStrongPasswordWithSettingsConstraint,
+    AiModule,
+    IntegrationModule,
+    WebhookIntegrationModule,
+    IsStrongPasswordWithSettingsConstraint,
     IsEmailWithSettingsConstraint,
     IsPinCodeWithSettingConstraint,
   ],

package/src/index.ts

@@ -29,16 +29,16 @@ export * from './file/file.service';
 export * from './setting/setting.module';
 export * from './setting/setting.service';
 
-export * from './ai/ai.module';
-export * from './ai/ai.service';
-
-export * from './webhook-integration/webhook-integration.module';
-export * from './webhook-integration/integration-event-catalog.service';
-export * from './webhook-integration/webhook-integration.service';
-export * from './webhook-integration/event-webhook.service';
-
-// Integration Module
-export * from './integration/integration.module';
+export * from './ai/ai.module';
+export * from './ai/ai.service';
+
+export * from './webhook-integration/webhook-integration.module';
+export * from './webhook-integration/integration-event-catalog.service';
+export * from './webhook-integration/webhook-integration.service';
+export * from './webhook-integration/event-webhook.service';
+
+// Integration Module
+export * from './integration/integration.module';
 export * from './integration/services/domain-event.publisher';
 export * from './integration/services/event-subscriber.registry';
 export * from './integration/services/inbox.service';
@@ -57,6 +57,13 @@ export * from './validators/is-email-with-settings.validator';
 export * from './validators/is-pin-code-with-setting.validator';
 export * from './validators/is-strong-password-with-settings.validator';
 
+// MCP Module
+export * from './mcp/mcp.module';
+export * from './mcp/mcp-registry.service';
+export * from './mcp/decorators/mcp-tool.decorator';
+export * from './mcp/interfaces/mcp-tool-definition.interface';
+export * from './mcp/types/mcp-context.type';
+
 // Utilities
 export * from './utils/locale-context';
 

package/src/mcp/decorators/mcp-tool.decorator.ts

@@ -0,0 +1,7 @@
+import { SetMetadata } from '@nestjs/common';
+import { McpToolDefinition } from '../interfaces/mcp-tool-definition.interface';
+
+export const MCP_TOOL_METADATA = 'mcp:tool';
+
+export const McpTool = (definition: McpToolDefinition): MethodDecorator =>
+  SetMetadata(MCP_TOOL_METADATA, definition);

package/src/mcp/guards/mcp-auth.guard.ts

@@ -0,0 +1,32 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { Request } from 'express';
+import { TokenService } from '../../token/token.service';
+
+@Injectable()
+export class McpAuthGuard implements CanActivate {
+  constructor(private readonly tokenService: TokenService) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest<Request>();
+    const locale =
+      request.headers['accept-language']?.split(',')[0]?.split('-')[0] ?? 'en';
+
+    const token = this.extractToken(request);
+    if (!token) {
+      throw new UnauthorizedException('MCP: Bearer token required');
+    }
+
+    request['auth'] = await this.tokenService.verify(locale, token);
+    return true;
+  }
+
+  private extractToken(request: Request): string | undefined {
+    const [type, token] = request.headers.authorization?.split(' ') ?? [];
+    return type === 'Bearer' ? token : undefined;
+  }
+}

package/src/mcp/guards/mcp-permission.guard.ts

@@ -0,0 +1,51 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+} from '@nestjs/common';
+import { Request } from 'express';
+
+@Injectable()
+export class McpPermissionGuard implements CanActivate {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest<Request>();
+
+    // Only POST requests carry tool invocations
+    if (request.method !== 'POST') return true;
+
+    const body = request.body as any;
+    const toolName: string | undefined =
+      body?.method === 'tools/call' ? body?.params?.name : undefined;
+
+    // tools/list, initialize, ping, etc. — no per-tool permission check needed
+    if (!toolName) return true;
+
+    const userId = (request as any)?.auth?.sub;
+
+    const count = await this.prisma.route.count({
+      where: {
+        type: 'MCP' as any,
+        tool_name: toolName,
+        role_route: {
+          some: {
+            role: {
+              role_user: {
+                some: { user_id: userId },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    if (count === 0) {
+      throw new ForbiddenException(`Access denied to MCP tool '${toolName}'`);
+    }
+
+    return true;
+  }
+}

package/src/mcp/interfaces/mcp-tool-definition.interface.ts

@@ -0,0 +1,6 @@
+export interface McpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema?: Record<string, any>;
+  readOnly?: boolean;
+}

package/src/mcp/mcp-audit.service.ts

@@ -0,0 +1,36 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { Injectable, Logger } from '@nestjs/common';
+
+interface AuditRecord {
+  userId: number;
+  toolName: string;
+  input: Record<string, any>;
+  success: boolean;
+  error?: string;
+  durationMs: number;
+}
+
+@Injectable()
+export class McpAuditService {
+  private readonly logger = new Logger(McpAuditService.name);
+
+  constructor(private readonly prisma: PrismaService) {}
+
+  async record(data: AuditRecord): Promise<void> {
+    const sanitized = JSON.stringify(data.input).slice(0, 1000);
+    try {
+      await this.prisma.mcp_tool_call_log.create({
+        data: {
+          user_id: data.userId || null,
+          tool_name: data.toolName,
+          input: sanitized,
+          success: data.success,
+          error: data.error ?? null,
+          duration_ms: data.durationMs,
+        },
+      });
+    } catch (e: any) {
+      this.logger.warn(`Failed to persist MCP audit record: ${e.message}`);
+    }
+  }
+}

package/src/mcp/mcp-registry.service.ts

@@ -0,0 +1,69 @@
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { DiscoveryService } from '@nestjs/core';
+import { Reflector } from '@nestjs/core';
+import { MCP_TOOL_METADATA } from './decorators/mcp-tool.decorator';
+import { McpToolDefinition } from './interfaces/mcp-tool-definition.interface';
+import { McpContext } from './types/mcp-context.type';
+
+export interface McpToolEntry {
+  definition: McpToolDefinition;
+  handler: (args: Record<string, any>, context: McpContext) => Promise<any>;
+}
+
+@Injectable()
+export class McpRegistryService implements OnModuleInit {
+  private readonly logger = new Logger(McpRegistryService.name);
+  private readonly tools = new Map<string, McpToolEntry>();
+
+  constructor(
+    private readonly discovery: DiscoveryService,
+    private readonly reflector: Reflector,
+  ) {}
+
+  onModuleInit(): void {
+    const providers = this.discovery.getProviders();
+
+    for (const wrapper of providers) {
+      const { instance } = wrapper;
+      if (!instance || typeof instance !== 'object') continue;
+
+      const prototype = Object.getPrototypeOf(instance);
+      if (!prototype) continue;
+
+      const methodNames = Object.getOwnPropertyNames(prototype).filter((key) => {
+        if (key === 'constructor') return false;
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+        return descriptor !== undefined && typeof descriptor.value === 'function';
+      });
+
+      for (const methodName of methodNames) {
+        const definition = this.reflector.get<McpToolDefinition>(
+          MCP_TOOL_METADATA,
+          prototype[methodName],
+        );
+
+        if (!definition) continue;
+
+        this.logger.log(`Registered MCP tool: ${definition.name}`);
+        this.tools.set(definition.name, {
+          definition,
+          handler: (instance as any)[methodName].bind(instance),
+        });
+      }
+    }
+
+    this.logger.log(`McpRegistryService: ${this.tools.size} tools registered`);
+  }
+
+  getAll(): McpToolEntry[] {
+    return Array.from(this.tools.values());
+  }
+
+  get(toolName: string): McpToolEntry | undefined {
+    return this.tools.get(toolName);
+  }
+
+  has(toolName: string): boolean {
+    return this.tools.has(toolName);
+  }
+}

package/src/mcp/mcp-server.service.ts

@@ -0,0 +1,87 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { Injectable } from '@nestjs/common';
+import { Request, Response } from 'express';
+import { McpAuditService } from './mcp-audit.service';
+import { McpRegistryService } from './mcp-registry.service';
+import { McpContext } from './types/mcp-context.type';
+
+@Injectable()
+export class McpServerService {
+  constructor(
+    private readonly registry: McpRegistryService,
+    private readonly audit: McpAuditService,
+  ) {}
+
+  async handleRequest(req: Request, res: Response, context: McpContext): Promise<void> {
+    const server = this.buildServer(context);
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  }
+
+  private buildServer(context: McpContext): Server {
+    const server = new Server(
+      { name: 'hedhog-mcp', version: '1.0.0' },
+      { capabilities: { tools: {} } },
+    );
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: this.registry.getAll().map((e) => ({
+        name: e.definition.name,
+        description: e.definition.description,
+        inputSchema: e.definition.inputSchema ?? {
+          type: 'object',
+          properties: {},
+        },
+      })),
+    }));
+
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const toolName = request.params.name;
+      const args = (request.params.arguments ?? {}) as Record<string, any>;
+      const entry = this.registry.get(toolName);
+
+      if (!entry) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `Tool '${toolName}' not found` }],
+        };
+      }
+
+      const start = Date.now();
+      try {
+        const result = await entry.handler(args, { ...context, toolName });
+        await this.audit.record({
+          userId: context.userId,
+          toolName,
+          input: args,
+          success: true,
+          durationMs: Date.now() - start,
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      } catch (e: any) {
+        await this.audit.record({
+          userId: context.userId,
+          toolName,
+          input: args,
+          success: false,
+          error: e.message,
+          durationMs: Date.now() - start,
+        });
+        return {
+          isError: true,
+          content: [{ type: 'text', text: e.message }],
+        };
+      }
+    });
+
+    return server;
+  }
+}

package/src/mcp/mcp.controller.ts

@@ -0,0 +1,30 @@
+import { NoRole } from '@hed-hog/api';
+import { All, Controller, Req, Res, UseGuards } from '@nestjs/common';
+import { Request, Response } from 'express';
+import { McpAuthGuard } from './guards/mcp-auth.guard';
+import { McpPermissionGuard } from './guards/mcp-permission.guard';
+import { McpServerService } from './mcp-server.service';
+
+@NoRole()
+@UseGuards(McpAuthGuard, McpPermissionGuard)
+@Controller('mcp')
+export class McpController {
+  constructor(private readonly mcpServer: McpServerService) {}
+
+  @All()
+  async handle(@Req() req: Request, @Res() res: Response): Promise<void> {
+    const auth = (req as any).auth;
+    const locale =
+      req.headers['accept-language']?.split(',')[0]?.split('-')[0] ?? 'en';
+    const body = req.body as any;
+    const toolName: string =
+      body?.method === 'tools/call' ? (body?.params?.name ?? '') : '';
+
+    await this.mcpServer.handleRequest(req, res, {
+      userId: auth.sub,
+      sessionId: String(auth.sessionId),
+      locale,
+      toolName,
+    });
+  }
+}

package/src/mcp/mcp.module.ts

@@ -0,0 +1,36 @@
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { Module, forwardRef } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
+import { SettingModule } from '../setting/setting.module';
+import { TokenModule } from '../token/token.module';
+import { UserModule } from '../user/user.module';
+import { McpAuthGuard } from './guards/mcp-auth.guard';
+import { McpPermissionGuard } from './guards/mcp-permission.guard';
+import { McpAuditService } from './mcp-audit.service';
+import { McpRegistryService } from './mcp-registry.service';
+import { McpServerService } from './mcp-server.service';
+import { McpController } from './mcp.controller';
+import { CoreSettingsMcpTools } from './tools/core-settings.mcp-tools';
+import { CoreUsersMcpTools } from './tools/core-users.mcp-tools';
+
+@Module({
+  imports: [
+    DiscoveryModule,
+    forwardRef(() => PrismaModule),
+    forwardRef(() => TokenModule),
+    forwardRef(() => SettingModule),
+    forwardRef(() => UserModule),
+  ],
+  controllers: [McpController],
+  providers: [
+    McpRegistryService,
+    McpServerService,
+    McpAuditService,
+    McpAuthGuard,
+    McpPermissionGuard,
+    CoreSettingsMcpTools,
+    CoreUsersMcpTools,
+  ],
+  exports: [McpRegistryService, McpServerService],
+})
+export class McpModule {}

package/src/mcp/tools/core-settings.mcp-tools.ts

@@ -0,0 +1,53 @@
+import { Injectable } from '@nestjs/common';
+import { SettingService } from '../../setting/setting.service';
+import { McpTool } from '../decorators/mcp-tool.decorator';
+import { McpContext } from '../types/mcp-context.type';
+
+@Injectable()
+export class CoreSettingsMcpTools {
+  constructor(private readonly settingService: SettingService) {}
+
+  @McpTool({
+    name: 'core.settings.get',
+    description: 'Returns effective settings for the authenticated user',
+    inputSchema: { type: 'object', properties: {} },
+    readOnly: true,
+  })
+  async getEffectiveSettings(
+    _args: Record<string, any>,
+    context: McpContext,
+  ): Promise<any> {
+    return this.settingService.getEffectiveSettings(context.userId);
+  }
+
+  @McpTool({
+    name: 'core.settings.set',
+    description:
+      'Updates a user-overridable setting value for the authenticated user. Only settings with user_override=true can be changed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        slug: {
+          type: 'string',
+          description: 'The slug identifier of the setting to update',
+        },
+        value: {
+          type: 'string',
+          description: 'The new value for the setting',
+        },
+      },
+      required: ['slug', 'value'],
+    },
+  })
+  async setUserSetting(
+    args: { slug: string; value: string },
+    context: McpContext,
+  ): Promise<any> {
+    return this.settingService.setSettingUserValue(
+      context.locale,
+      context.userId,
+      args.slug,
+      args.value,
+    );
+  }
+}