@malek0512/loopback4-mcp 1.0.0

package/src/protocol/json-rpc.handler.ts

@@ -0,0 +1,77 @@
+import {bind, BindingScope} from '@loopback/core';
+import {
+  JsonRpcRequest,
+  JsonRpcResponse,
+  JsonRpcError,
+  McpErrorCode,
+} from './types';
+
+@bind({scope: BindingScope.SINGLETON})
+export class JsonRpcHandler {
+  createResponse(id: string | number, result: unknown): JsonRpcResponse {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result,
+    };
+  }
+
+  createErrorResponse(
+    id: string | number | undefined,
+    code: McpErrorCode,
+    message: string,
+    data?: unknown,
+  ): JsonRpcResponse {
+    return {
+      jsonrpc: '2.0',
+      id: id ?? (null as any),
+      error: {
+        code,
+        message,
+        data,
+      },
+    };
+  }
+
+  validateRequest(request: unknown): JsonRpcRequest {
+    if (!this.isValidRequest(request)) {
+      throw this.createError(
+        McpErrorCode.INVALID_REQUEST,
+        'Invalid JSON-RPC request',
+      );
+    }
+    return request as JsonRpcRequest;
+  }
+
+  private isValidRequest(request: unknown): boolean {
+    if (typeof request !== 'object' || request === null) {
+      return false;
+    }
+
+    const req = request as any;
+
+    return (
+      req.jsonrpc === '2.0' &&
+      typeof req.method === 'string' &&
+      (req.id === undefined ||
+        typeof req.id === 'string' ||
+        typeof req.id === 'number')
+    );
+  }
+
+  createError(
+    code: McpErrorCode,
+    message: string,
+    data?: unknown,
+  ): JsonRpcError {
+    return {
+      code,
+      message,
+      data,
+    };
+  }
+
+  isNotification(request: JsonRpcRequest): boolean {
+    return request.id === undefined;
+  }
+}

package/src/protocol/message-router.ts

@@ -0,0 +1,125 @@
+import {bind, BindingScope, inject} from '@loopback/core';
+import {
+  JsonRpcRequest,
+  JsonRpcResponse,
+  McpMethod,
+  McpErrorCode,
+  InitializeRequest,
+  InitializeResult,
+  ToolsListRequest,
+  ToolsListResult,
+  ToolCallRequest,
+  ToolCallResult,
+} from './types';
+import {JsonRpcHandler} from './json-rpc.handler';
+import {ToolRegistry} from '../registry/tool-registry';
+import {ToolExecutor} from '../execution/tool-executor';
+
+@bind({scope: BindingScope.SINGLETON})
+export class MessageRouter {
+  private initialized = false;
+  private serverInfo = {
+    name: 'LoopBack MCP Server',
+    version: '1.0.0',
+  };
+
+  constructor(
+    @inject('mcp.jsonRpcHandler')
+    private jsonRpcHandler: JsonRpcHandler,
+    @inject('mcp.toolRegistry')
+    private toolRegistry: ToolRegistry,
+    @inject('mcp.toolExecutor')
+    private toolExecutor: ToolExecutor,
+  ) {}
+
+  async route(request: JsonRpcRequest): Promise<JsonRpcResponse> {
+    try {
+      this.jsonRpcHandler.validateRequest(request);
+
+      // Handle initialization separately
+      if (request.method === McpMethod.INITIALIZE) {
+        return await this.handleInitialize(request as InitializeRequest);
+      }
+
+      // Route to appropriate handler
+      switch (request.method) {
+        case McpMethod.TOOLS_LIST:
+          return await this.handleToolsList(request as ToolsListRequest);
+
+        case McpMethod.TOOLS_CALL:
+          return await this.handleToolCall(request as ToolCallRequest);
+
+        default:
+          return this.jsonRpcHandler.createErrorResponse(
+            request.id!,
+            McpErrorCode.METHOD_NOT_FOUND,
+            `Method '${request.method}' not found`,
+          );
+      }
+    } catch (error) {
+      return this.handleError(request.id, error);
+    }
+  }
+
+  private async handleInitialize(
+    request: InitializeRequest,
+  ): Promise<JsonRpcResponse> {
+    const result: InitializeResult = {
+      protocolVersion: '2024-11-05',
+      capabilities: {
+        tools: {
+          listChanged: true,
+        },
+      },
+      serverInfo: this.serverInfo,
+    };
+
+    this.initialized = true;
+
+    return this.jsonRpcHandler.createResponse(request.id!, result);
+  }
+
+  private async handleToolsList(
+    request: ToolsListRequest,
+  ): Promise<JsonRpcResponse> {
+    const tools = this.toolRegistry.list();
+
+    const result: ToolsListResult = {
+      tools,
+    };
+
+    return this.jsonRpcHandler.createResponse(request.id!, result);
+  }
+
+  private async handleToolCall(
+    request: ToolCallRequest,
+  ): Promise<JsonRpcResponse> {
+    const {name, arguments: args} = request.params;
+
+    const result = await this.toolExecutor.execute(name, args || {});
+
+    return this.jsonRpcHandler.createResponse(request.id!, result);
+  }
+
+  private handleError(
+    id: string | number | undefined,
+    error: any,
+  ): JsonRpcResponse {
+    let code = McpErrorCode.INTERNAL_ERROR;
+    let message = 'Internal server error';
+    let data: unknown;
+
+    if (error.code && typeof error.code === 'number') {
+      code = error.code;
+      message = error.message || message;
+      data = error.data;
+    } else if (error instanceof Error) {
+      message = error.message;
+      data = {
+        stack: error.stack,
+      };
+    }
+
+    return this.jsonRpcHandler.createErrorResponse(id, code, message, data);
+  }
+}

package/src/protocol/types.ts

@@ -0,0 +1,309 @@
+// ============================================================================
+// JSON-RPC 2.0 Base Types
+// ============================================================================
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id?: string | number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: string | number;
+  result?: unknown;
+  error?: JsonRpcError;
+}
+
+export interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+export interface JsonRpcNotification {
+  jsonrpc: '2.0';
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+// ============================================================================
+// MCP Protocol Messages
+// ============================================================================
+
+export enum McpMethod {
+  // Initialization
+  INITIALIZE = 'initialize',
+  INITIALIZED = 'initialized',
+
+  // Tools
+  TOOLS_LIST = 'tools/list',
+  TOOLS_CALL = 'tools/call',
+
+  // Resources
+  RESOURCES_LIST = 'resources/list',
+  RESOURCES_READ = 'resources/read',
+  RESOURCES_SUBSCRIBE = 'resources/subscribe',
+  RESOURCES_UNSUBSCRIBE = 'resources/unsubscribe',
+
+  // Prompts
+  PROMPTS_LIST = 'prompts/list',
+  PROMPTS_GET = 'prompts/get',
+
+  // Logging
+  LOGGING_SET_LEVEL = 'logging/setLevel',
+
+  // Notifications
+  NOTIFICATION_CANCELLED = 'notifications/cancelled',
+  NOTIFICATION_PROGRESS = 'notifications/progress',
+  NOTIFICATION_MESSAGE = 'notifications/message',
+  NOTIFICATION_RESOURCES_UPDATED = 'notifications/resources/updated',
+  NOTIFICATION_RESOURCES_LIST_CHANGED = 'notifications/resources/list_changed',
+  NOTIFICATION_TOOLS_LIST_CHANGED = 'notifications/tools/list_changed',
+  NOTIFICATION_PROMPTS_LIST_CHANGED = 'notifications/prompts/list_changed',
+}
+
+// ============================================================================
+// Initialize
+// ============================================================================
+
+export interface InitializeRequest extends JsonRpcRequest {
+  method: McpMethod.INITIALIZE;
+  params: {
+    protocolVersion: string;
+    capabilities: ClientCapabilities;
+    clientInfo: Implementation;
+  };
+}
+
+export interface InitializeResult {
+  protocolVersion: string;
+  capabilities: ServerCapabilities;
+  serverInfo: Implementation;
+}
+
+export interface Implementation {
+  name: string;
+  version: string;
+}
+
+export interface ClientCapabilities {
+  experimental?: Record<string, unknown>;
+  sampling?: Record<string, unknown>;
+  roots?: {
+    listChanged?: boolean;
+  };
+}
+
+export interface ServerCapabilities {
+  experimental?: Record<string, unknown>;
+  logging?: Record<string, unknown>;
+  prompts?: {
+    listChanged?: boolean;
+  };
+  resources?: {
+    subscribe?: boolean;
+    listChanged?: boolean;
+  };
+  tools?: {
+    listChanged?: boolean;
+  };
+}
+
+// ============================================================================
+// Tools
+// ============================================================================
+
+export interface Tool {
+  name: string;
+  description?: string;
+  inputSchema: {
+    type: 'object';
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+  };
+}
+
+export interface ToolsListRequest extends JsonRpcRequest {
+  method: McpMethod.TOOLS_LIST;
+  params?: {
+    cursor?: string;
+  };
+}
+
+export interface ToolsListResult {
+  tools: Tool[];
+  nextCursor?: string;
+}
+
+export interface ToolCallRequest extends JsonRpcRequest {
+  method: McpMethod.TOOLS_CALL;
+  params: {
+    name: string;
+    arguments?: Record<string, unknown>;
+  };
+}
+
+export interface ToolCallResult {
+  content: Content[];
+  isError?: boolean;
+}
+
+// ============================================================================
+// Content Types
+// ============================================================================
+
+export type Content = TextContent | ImageContent | EmbeddedResource;
+
+export interface TextContent {
+  type: 'text';
+  text: string;
+}
+
+export interface ImageContent {
+  type: 'image';
+  data: string; // base64
+  mimeType: string;
+}
+
+export interface EmbeddedResource {
+  type: 'resource';
+  resource: ResourceContents;
+}
+
+// ============================================================================
+// Resources
+// ============================================================================
+
+export interface Resource {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+export interface ResourcesListRequest extends JsonRpcRequest {
+  method: McpMethod.RESOURCES_LIST;
+  params?: {
+    cursor?: string;
+  };
+}
+
+export interface ResourcesListResult {
+  resources: Resource[];
+  nextCursor?: string;
+}
+
+export interface ResourceReadRequest extends JsonRpcRequest {
+  method: McpMethod.RESOURCES_READ;
+  params: {
+    uri: string;
+  };
+}
+
+export interface ResourceContents {
+  uri: string;
+  mimeType?: string;
+  text?: string;
+  blob?: string; // base64
+}
+
+export interface ResourceReadResult {
+  contents: ResourceContents[];
+}
+
+// ============================================================================
+// Prompts
+// ============================================================================
+
+export interface Prompt {
+  name: string;
+  description?: string;
+  arguments?: PromptArgument[];
+}
+
+export interface PromptArgument {
+  name: string;
+  description?: string;
+  required?: boolean;
+}
+
+export interface PromptsListRequest extends JsonRpcRequest {
+  method: McpMethod.PROMPTS_LIST;
+  params?: {
+    cursor?: string;
+  };
+}
+
+export interface PromptsListResult {
+  prompts: Prompt[];
+  nextCursor?: string;
+}
+
+export interface PromptGetRequest extends JsonRpcRequest {
+  method: McpMethod.PROMPTS_GET;
+  params: {
+    name: string;
+    arguments?: Record<string, string>;
+  };
+}
+
+export interface PromptMessage {
+  role: 'user' | 'assistant';
+  content: Content;
+}
+
+export interface PromptGetResult {
+  description?: string;
+  messages: PromptMessage[];
+}
+
+// ============================================================================
+// JSON Schema
+// ============================================================================
+
+export interface JsonSchema {
+  type?: string | string[];
+  properties?: Record<string, JsonSchema>;
+  items?: JsonSchema | JsonSchema[];
+  required?: string[];
+  enum?: unknown[];
+  const?: unknown;
+  description?: string;
+  default?: unknown;
+  examples?: unknown[];
+  format?: string;
+  pattern?: string;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+  additionalProperties?: boolean | JsonSchema;
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// Error Codes
+// ============================================================================
+
+export enum McpErrorCode {
+  // Standard JSON-RPC errors
+  PARSE_ERROR = -32700,
+  INVALID_REQUEST = -32600,
+  METHOD_NOT_FOUND = -32601,
+  INVALID_PARAMS = -32602,
+  INTERNAL_ERROR = -32603,
+
+  // MCP-specific errors
+  TOOL_NOT_FOUND = -32001,
+  TOOL_EXECUTION_ERROR = -32002,
+  RESOURCE_NOT_FOUND = -32003,
+  RESOURCE_ACCESS_DENIED = -32004,
+  PROMPT_NOT_FOUND = -32005,
+  INVALID_TOOL_ARGUMENTS = -32006,
+}

package/src/registry/index.ts

@@ -0,0 +1,3 @@
+export * from './tool-registry';
+export * from './metadata-scanner';
+export * from './schema-generator';

package/src/registry/metadata-scanner.ts

@@ -0,0 +1,105 @@
+import {bind, BindingScope, inject, Application} from '@loopback/core';
+import {ToolRegistry, ToolDescriptor} from './tool-registry';
+import {McpToolMetadata, MCP_TOOL_METADATA_KEY} from '../decorators';
+import {SchemaGenerator} from './schema-generator';
+import {MetadataInspector} from '@loopback/core';
+
+@bind({scope: BindingScope.SINGLETON})
+export class MetadataScanner {
+  constructor(
+    @inject('mcp.toolRegistry')
+    private toolRegistry: ToolRegistry,
+    @inject('mcp.schemaGenerator')
+    private schemaGenerator: SchemaGenerator,
+    @inject.context()
+    private app: Application,
+  ) {}
+
+  async scan(): Promise<void> {
+    const controllerBindings = this.app.findByTag('controller');
+    for (const binding of controllerBindings) {
+      const controllerClass = binding.valueConstructor;
+      if (controllerClass) {
+        await this.scanControllerClass(controllerClass);
+      }
+    }
+  }
+
+  private async scanControllerClass(controllerClass: Function): Promise<void> {
+    try {
+      const proto = controllerClass.prototype;
+      const methodNames = Object.getOwnPropertyNames(proto).filter(
+        name => typeof proto[name] === 'function' && name !== 'constructor',
+      );
+
+      for (const methodName of methodNames) {
+        const metadata = MetadataInspector.getMethodMetadata<McpToolMetadata>(
+          MCP_TOOL_METADATA_KEY,
+          proto,
+          methodName,
+        );
+        if (metadata) {
+          await this.registerTool(controllerClass, methodName, metadata);
+        }
+      }
+    } catch (error) {
+      console.warn(`[MCP] Skipping controller during scan:`, error);
+    }
+  }
+
+  private async registerTool(
+    controllerClass: Function,
+    methodName: string,
+    metadata: McpToolMetadata,
+  ): Promise<void> {
+    // Schema: use LoopBack's own spec generation (resolves $ref, always correct)
+    const inputSchema = metadata.inputSchema ?? this.schemaGenerator.generateForMethod(controllerClass, methodName);
+
+    // Handler arg mapping: read raw LoopBack parameter metadata set at class-definition time
+    const proto = controllerClass.prototype;
+    const allParamsMeta: Record<string, Array<{name: string; in: string} | null>> =
+      Reflect.getMetadata('loopback:openapi-v3:parameters', proto) ?? {};
+    const allReqBodyMeta: Record<string, Array<object | null>> =
+      Reflect.getMetadata('loopback:openapi-v3:request-body', proto) ?? {};
+
+    const methodParams = allParamsMeta[methodName] ?? [];
+    const methodReqBodies = allReqBodyMeta[methodName] ?? [];
+    const maxArgs = Math.max(methodParams.length, methodReqBodies.length);
+
+    const descriptor: ToolDescriptor = {
+      name: metadata.name,
+      description: metadata.description,
+      inputSchema,
+      controller: proto,
+      methodName,
+      handler: async (args: Record<string, unknown>) => {
+        const controller = await this.app.get(`controllers.${controllerClass.name}`);
+
+        if (maxArgs === 0) {
+          return (controller as any)[methodName](args);
+        }
+
+        const positionalArgs: unknown[] = [];
+        const usedKeys = new Set<string>();
+
+        for (let i = 0; i < maxArgs; i++) {
+          const param = methodParams[i];
+          const reqBody = methodReqBodies[i];
+
+          if (param) {
+            positionalArgs[i] = args[param.name];
+            usedKeys.add(param.name);
+          } else if (reqBody) {
+            positionalArgs[i] = Object.fromEntries(
+              Object.entries(args).filter(([k]) => !usedKeys.has(k)),
+            );
+          }
+        }
+
+        return (controller as any)[methodName](...positionalArgs);
+      },
+    };
+
+    this.toolRegistry.register(descriptor);
+  }
+}

package/src/registry/schema-generator.ts

@@ -0,0 +1,82 @@
+import {bind, BindingScope} from '@loopback/core';
+import {getControllerSpec} from '@loopback/openapi-v3';
+import {JsonSchema} from '../protocol/types';
+
+@bind({scope: BindingScope.SINGLETON})
+export class SchemaGenerator {
+  /**
+   * Build the MCP inputSchema for a controller method using LoopBack's
+   * own getControllerSpec(), so $ref resolution and parameter ordering
+   * are always correct regardless of decorator evaluation timing.
+   *
+   * Path params become required top-level properties.
+   * Request body properties are spread into the top-level object.
+   * Optional query params (filter, where…) are omitted — MCP tools
+   * accept them as part of the body object when passed.
+   */
+  generateForMethod(controllerClass: Function, methodName: string): JsonSchema {
+    const spec = getControllerSpec(controllerClass as any);
+    const components: Record<string, any> = spec.components?.schemas ?? {};
+
+    const operation = this.findOperation(spec, methodName);
+    if (!operation) {
+      return {type: 'object', properties: {}, additionalProperties: false};
+    }
+
+    const properties: Record<string, JsonSchema> = {};
+    const required: string[] = [];
+    const usedKeys = new Set<string>();
+
+    // Path parameters (required, strongly typed)
+    for (const param of (operation.parameters ?? []) as any[]) {
+      if (param.in !== 'path') continue;
+      const schema = this.resolveRef(param.schema ?? {type: 'string'}, components);
+      properties[param.name] = schema;
+      usedKeys.add(param.name);
+      required.push(param.name);
+    }
+
+    // Request body: spread its resolved properties into the top-level schema
+    const bodyContent = operation.requestBody?.content?.['application/json'];
+    if (bodyContent?.schema) {
+      const bodySchema = this.resolveRef(bodyContent.schema, components);
+      if (bodySchema.properties) {
+        for (const [key, val] of Object.entries(bodySchema.properties)) {
+          if (!usedKeys.has(key)) {
+            properties[key] = this.resolveRef(val as any, components);
+          }
+        }
+        for (const r of bodySchema.required ?? []) {
+          if (!required.includes(r)) required.push(r);
+        }
+      }
+    }
+
+    return {
+      type: 'object',
+      properties,
+      required: required.length > 0 ? required : undefined,
+      additionalProperties: false,
+    };
+  }
+
+  /** Resolve a $ref schema from components.schemas, or return it as-is. */
+  private resolveRef(schema: any, components: Record<string, any>): any {
+    if (!schema || typeof schema !== 'object') return schema;
+    if (!schema['$ref']) return schema;
+    const refName = (schema['$ref'] as string).split('/').pop()!;
+    return components[refName] ?? schema;
+  }
+
+  /** Find the OpenAPI operation matching a controller method by x-operation-name. */
+  private findOperation(spec: any, methodName: string): any {
+    for (const pathItem of Object.values(spec.paths ?? {})) {
+      for (const op of Object.values(pathItem as object)) {
+        if (op && (op as any)['x-operation-name'] === methodName) {
+          return op;
+        }
+      }
+    }
+    return null;
+  }
+}