loopback4-mcp 0.0.1

package/src/providers/README.md

@@ -0,0 +1,129 @@
+# Providers
+
+This directory contains providers contributing additional bindings, for example
+custom sequence actions.
+
+## Overview
+
+A [provider](http://loopback.io/doc/en/lb4/Creating-components.html#providers)
+is a class that provides a `value()` function. This function is called `Context`
+when another entity requests a value to be injected.
+
+Here we create a provider for a logging function that can be used as a new
+action in a custom [sequence](http://loopback.io/doc/en/lb4/Sequence.html).
+
+The logger will log the URL, the parsed request parameters, and the result. The
+logger is also capable of timing the sequence if you start a timer at the start
+of the sequence using `this.logger.startTimer()`.
+
+## Basic Usage
+
+### TimerProvider
+
+TimerProvider is automatically bound to your Application's
+[Context](http://loopback.io/doc/en/lb4/Context.html) using the LogComponent
+which exports this provider with a binding key of `extension-starter.timer`. You
+can learn more about components in the
+[related resources section](#related-resources).
+
+This provider makes available to your application a timer function which given a
+start time _(given as an array [seconds, nanoseconds])_ can give you a total
+time elapsed since the start in milliseconds. The timer can also start timing if
+no start time is given. This is used by LogComponent to allow a user to time a
+Sequence.
+
+_NOTE:_ _You can get the start time in the required format by using
+`this.logger.startTimer()`._
+
+You can provide your own implementation of the elapsed time function by binding
+it to the binding key (accessible via `ExtensionStarterBindings`) as follows:
+
+```ts
+app.bind(ExtensionStarterBindings.TIMER).to(timerFn);
+```
+
+### LogProvider
+
+LogProvider can automatically be bound to your Application's Context using the
+LogComponent which exports the provider with a binding key of
+`extension-starter.actions.log`.
+
+The key can be accessed by importing `ExtensionStarterBindings` as follows:
+
+**Example: Binding Keys**
+
+```ts
+import {ExtensionStarterBindings} from 'HelloExtensions';
+// Key can be accessed as follows now
+const key = ExtensionStarterBindings.LOG_ACTION;
+```
+
+LogProvider gives us a sequence action and a `startTimer` function. In order to
+use the sequence action, you must define your own sequence as shown below.
+
+**Example: Sequence**
+
+```ts
+class LogSequence implements SequenceHandler {
+  constructor(
+    @inject(coreSequenceActions.FIND_ROUTE) protected findRoute: FindRoute,
+    @inject(coreSequenceActions.PARSE_PARAMS)
+    protected parseParams: ParseParams,
+    @inject(coreSequenceActions.INVOKE_METHOD) protected invoke: InvokeMethod,
+    @inject(coreSequenceActions.SEND) protected send: Send,
+    @inject(coreSequenceActions.REJECT) protected reject: Reject,
+    // We get the logger injected by the LogProvider here
+    @inject(ExtensionStarterBindings.LOG_ACTION) protected logger: LogFn,
+  ) {}
+
+  async handle(context: RequestContext) {
+    const {request, response} = context;
+
+    // We define these variable outside so they can be accessed by logger.
+    let args: any = [];
+    let result: any;
+
+    // Optionally start timing the sequence using the timer
+    // function available via LogFn
+    const start = this.logger.startTimer();
+
+    try {
+      const route = this.findRoute(request);
+      args = await this.parseParams(request, route);
+      result = await this.invoke(route, args);
+      this.send(response, result);
+    } catch (error) {
+      result = error; // so we can log the error message in the logger
+      this.reject(context, error);
+    }
+
+    // We call the logger function given to us by LogProvider
+    this.logger(request, args, result, start);
+  }
+}
+```
+
+Once a sequence has been written, we can just use that in our Application as
+follows:
+
+**Example: Application**
+
+```ts
+const app = new Application({
+  sequence: LogSequence,
+});
+app.component(LogComponent);
+
+// Now all requests handled by our sequence will be logged.
+```
+
+## Related Resources
+
+You can check out the following resource to learn more about providers,
+components, sequences, and binding keys.
+
+- [Providers](http://loopback.io/doc/en/lb4/Creating-components.html#providers)
+- [Creating Components](http://loopback.io/doc/en/lb4/Creating-components.html)
+- [Using Components](http://loopback.io/doc/en/lb4/Components.html)
+- [Sequence](http://loopback.io/doc/en/lb4/Sequence.html)
+- [Binding Keys](http://loopback.io/doc/en/lb4/Decorators.html)

package/src/repositories/README.md

@@ -0,0 +1,5 @@
+# Repositories
+
+This directory contains code for repositories provided by this extension.
+
+For more information, see <http://loopback.io/doc/en/lb4/Repositories.html>.

package/src/services/index.ts

@@ -0,0 +1,3 @@
+export * from './mcp-server-factory.service';
+export * from './mcp-tool-registry.service';
+export * from './mcp-schema-generator-service.service';

package/src/services/mcp-schema-generator-service.service.ts

@@ -0,0 +1,80 @@
+import {BindingScope, inject, injectable} from '@loopback/core';
+import {ILogger, LOGGER} from '@sourceloop/core';
+import {z, ZodRawShape} from 'zod';
+import {extractParameterInfo} from '../utils';
+
+@injectable({scope: BindingScope.SINGLETON})
+export class McpSchemaGeneratorService {
+  constructor(
+    @inject(LOGGER.LOGGER_INJECT)
+    private readonly logger: ILogger,
+  ) {}
+
+  /**
+   * Create Zod schema for a single parameter using LoopBack type string
+   */
+  createZodSchemaForParameterType(paramType: string) {
+    switch (paramType) {
+      case 'string':
+        return z.string();
+      case 'number':
+        return z.number();
+      case 'boolean':
+        return z.boolean();
+      case 'object':
+        return z.object({}).passthrough();
+      case 'array':
+        return z.array(z.any());
+      default:
+        return z.any();
+    }
+  }
+
+  /**
+   * Generate tool schema using LoopBack metadata
+   */
+  generateToolSchemaFromLoopBack(
+    options: {name: string; description: string; schema?: ZodRawShape},
+    target: Object,
+    methodName: string,
+  ) {
+    let schema = options.schema;
+
+    if (!schema || Object.keys(schema).length === 0) {
+      try {
+        const {parameterNames, parameterOptional, parameterTypes} =
+          extractParameterInfo(target, methodName);
+
+        if (parameterNames.length > 0) {
+          let combinedSchema = z.object({});
+
+          parameterTypes.forEach((paramType, index) => {
+            const zodSchema = this.createZodSchemaForParameterType(paramType);
+            const paramName = parameterNames[index];
+            const isOptional = parameterOptional[index];
+
+            combinedSchema = combinedSchema.merge(
+              z.object({
+                [paramName]: isOptional ? zodSchema.optional() : zodSchema,
+              }),
+            );
+          });
+
+          schema = combinedSchema.shape;
+        } else {
+          schema = {};
+        }
+      } catch (error) {
+        this.logger.warn(
+          `Failed to generate schema for tool ${options.name} from LoopBack metadata:`,
+          error,
+        );
+        schema = {};
+      }
+    } else {
+      schema = schema ?? {};
+    }
+
+    return schema;
+  }
+}

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

@@ -0,0 +1,71 @@
+import {bind, BindingScope, Context, inject, service} from '@loopback/core';
+import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
+import {McpToolRegistry} from './mcp-tool-registry.service';
+import {RequestHandlerExtra} from '@modelcontextprotocol/sdk/shared/protocol';
+import {
+  ServerNotification,
+  ServerRequest,
+} from '@modelcontextprotocol/sdk/types';
+
+@bind({scope: BindingScope.REQUEST})
+export class McpServerFactory {
+  constructor(
+    @inject.context()
+    private readonly ctx: Context,
+    @service(McpToolRegistry)
+    private readonly toolRegistry: McpToolRegistry,
+  ) {}
+
+  /**
+   * Create a new MCP server instance with tool registration
+   * Uses singleton registry with pre-computed tools and controller instances
+   */
+  createServer(): McpServer {
+    // Create fresh server instance
+    const server = new McpServer(
+      {
+        name: 'Project management MCP server',
+        version: '1.0.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      },
+    );
+
+    // Tool registration from singleton registry
+    const toolDefinitions = this.toolRegistry.getToolDefinitions();
+    for (const toolDef of toolDefinitions) {
+      // Adapt the registry handler to work with the new API signature
+      // The new API expects (parameters, extra) instead of (context, args, extras)
+      const adaptedHandler = async (
+        parameters: Record<string, unknown>,
+        extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+      ) => toolDef.handler(this.ctx, parameters, extra);
+
+      // Use the new registerTool API with type assertion to avoid deep type recursion
+      const registerTool = (
+        server as unknown as {
+          registerTool(
+            name: string,
+            config: {description: string; inputSchema: unknown},
+            handler: Function,
+          ): void;
+        }
+      ).registerTool;
+
+      registerTool.call(
+        server,
+        toolDef.name,
+        {
+          description: toolDef.description,
+          inputSchema: toolDef.schema,
+        },
+        adaptedHandler,
+      );
+    }
+
+    return server;
+  }
+}

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

@@ -0,0 +1,368 @@
+import {
+  Application,
+  bind,
+  BindingKey,
+  BindingScope,
+  Constructor,
+  Context,
+  CoreBindings,
+  inject,
+  MetadataInspector,
+  service,
+} from '@loopback/core';
+import {HttpErrors} from '@loopback/rest';
+import {RequestHandlerExtra} from '@modelcontextprotocol/sdk/shared/protocol';
+import {
+  CallToolResult,
+  ServerNotification,
+  ServerRequest,
+} from '@modelcontextprotocol/sdk/types';
+import {IAuthUserWithPermissions, ILogger, LOGGER} from '@sourceloop/core';
+import {AuthenticationBindings} from 'loopback4-authentication';
+import {
+  AUTHORIZATION_METADATA_ACCESSOR,
+  AuthorizationBindings,
+  AuthorizationMetadata,
+} from 'loopback4-authorization';
+import {McpHookContext, McpHookFunction} from '../interfaces';
+import {MCP_TOOL_METADATA_KEY} from '../constants';
+import {extractParameterInfo} from '../utils';
+import {McpSchemaGeneratorService} from './mcp-schema-generator-service.service';
+import {McpTool, McpToolMetadata} from '../types';
+
+@bind({scope: BindingScope.SINGLETON})
+export class McpToolRegistry {
+  private toolDefinitions: McpTool[] = [];
+  private isInitialized = false;
+
+  constructor(
+    @inject(CoreBindings.APPLICATION_INSTANCE)
+    private readonly app: Application,
+    @inject(LOGGER.LOGGER_INJECT)
+    private readonly logger: ILogger,
+    @service(McpSchemaGeneratorService)
+    private readonly schemaGenerator: McpSchemaGeneratorService,
+  ) {}
+
+  /**
+   * Get MCP tools from a class using LoopBack MetadataInspector
+   */
+  private getMcpToolsFromClass(targetClass: Function): McpToolMetadata[] {
+    const processedTools: McpToolMetadata[] = [];
+    const prototype = targetClass.prototype;
+
+    const allTools = MetadataInspector.getAllMethodMetadata<McpToolMetadata>(
+      MCP_TOOL_METADATA_KEY,
+      prototype,
+    );
+
+    if (!allTools || Object.keys(allTools).length === 0) {
+      return [];
+    }
+
+    for (const [methodName, tool] of Object.entries(allTools)) {
+      try {
+        const {parameterNames} = extractParameterInfo(prototype, methodName);
+
+        // Create a copy with updated parameter info
+        const processedTool: McpToolMetadata = {
+          ...tool,
+          parameterNames,
+        };
+
+        // Generate schema if needed
+        if (
+          !processedTool.schema ||
+          Object.keys(processedTool.schema).length === 0
+        ) {
+          const schema = this.schemaGenerator.generateToolSchemaFromLoopBack(
+            {
+              name: processedTool.name,
+              description: processedTool.description,
+              schema: processedTool.schema,
+            },
+            prototype,
+            methodName,
+          );
+          processedTool.schema = schema;
+        }
+
+        processedTools.push(processedTool);
+      } catch (error) {
+        // Tool doesn't have LoopBack parameter decorators
+        this.logger.warn(
+          `Tool ${methodName} missing LoopBack parameter decorators:`,
+          error,
+        );
+      }
+    }
+
+    return processedTools;
+  }
+
+  /**
+   * Initialize tool registry at startup - stores metadata without instantiating controllers
+   */
+  async initialize(): Promise<void> {
+    if (this.isInitialized) return;
+
+    const controllerBindings = this.app.findByTag('controller');
+
+    // Process all bindings and collect tool metadata without instantiating controllers
+    const toolArrays = controllerBindings.map(binding => {
+      const controllerClass = binding.valueConstructor;
+      if (!controllerClass) {
+        this.logger.info(`No constructor found for binding ${binding.key}`);
+        return [];
+      }
+
+      const tools = this.getMcpToolsFromClass(controllerClass);
+
+      if (tools.length === 0) return [];
+
+      // Create pre-bound tool definitions
+      return tools.map(tool => {
+        return {
+          ...tool,
+          controllerBinding: BindingKey.create<object>(binding.key), // Store binding key instead of instance
+          handler: async (
+            requestContext: Context,
+            args: {[key: string]: unknown},
+            extras: RequestHandlerExtra<ServerRequest, ServerNotification>,
+          ): Promise<CallToolResult> => {
+            const ctx = await this.setupAuthorizationContext(
+              requestContext,
+              tool,
+              controllerClass,
+            );
+
+            const hookContext: McpHookContext = {
+              toolName: tool.name,
+              args: args,
+              metadata: tool.postHook?.config,
+            };
+            await this.executePreHook(ctx, tool, hookContext);
+
+            let result;
+            try {
+              result = await this.executeToolMethod(
+                ctx,
+                binding.key,
+                tool,
+                hookContext,
+                extras,
+              );
+              hookContext.result = result;
+
+              await this.executePostHook(ctx, tool, hookContext);
+            } catch (err) {
+              const error = err instanceof Error ? err : new Error(String(err));
+              hookContext.error = error;
+              this.logger.error(
+                `MCP Tool '${tool.name}' execution failed:`,
+                error.message,
+              );
+              return this.errorToCallToolResult(error);
+            } finally {
+              ctx.close();
+            }
+            return (hookContext.result as CallToolResult) ?? result;
+          },
+        };
+      });
+    });
+
+    this.toolDefinitions = toolArrays.flat();
+    this.isInitialized = true;
+  }
+
+  /**
+   * Get all precomputed tool definitions (ultra-fast)
+   */
+  getToolDefinitions(): McpTool[] {
+    return this.toolDefinitions;
+  }
+
+  /**
+   * Resolve hook function from provider binding
+   */
+  private async resolveHook(
+    ctx: Context,
+    hookBinding?: BindingKey<McpHookFunction> | string,
+  ): Promise<McpHookFunction | undefined> {
+    if (!hookBinding) {
+      return undefined;
+    }
+
+    try {
+      const bindingKey =
+        typeof hookBinding === 'string'
+          ? BindingKey.create<McpHookFunction>(hookBinding)
+          : hookBinding;
+      return await ctx.get(bindingKey);
+    } catch (error) {
+      // Hook binding not found - this is not an error, just log and continue
+      this.logger.warn(
+        `Hook binding ${hookBinding.toString()} not found:`,
+        error,
+      );
+      return undefined;
+    }
+  }
+
+  /**
+   * Set up authorization context and perform authorization check
+   */
+  private async setupAuthorizationContext(
+    requestContext: Context,
+    tool: McpToolMetadata,
+    controllerClass: Constructor<object>,
+  ): Promise<Context> {
+    // Get authorization metadata from the controller method
+    const authMetadata =
+      MetadataInspector.getMethodMetadata<AuthorizationMetadata>(
+        AUTHORIZATION_METADATA_ACCESSOR,
+        controllerClass.prototype,
+        tool.controllerFunction.name,
+      );
+
+    if (!authMetadata) {
+      this.logger.warn(
+        `No authorization metadata found for MCP tool '${tool.name}'`,
+      );
+      throw new HttpErrors.Forbidden(
+        `MCP tool '${tool.name}' is missing authorization configuration.`,
+      );
+    }
+
+    // Check authorization first - get authorize function from context
+    const ctx = new Context(requestContext);
+
+    // Bind the authorization metadata so the authorize action provider can access it
+    ctx.bind(AuthorizationBindings.METADATA).to(authMetadata);
+
+    // Bind controller information for authorization
+    ctx.bind(CoreBindings.CONTROLLER_CLASS).to(controllerClass);
+    ctx
+      .bind(CoreBindings.CONTROLLER_METHOD_NAME)
+      .to(tool.controllerFunction.name);
+
+    const user = await ctx.get<IAuthUserWithPermissions>(
+      AuthenticationBindings.CURRENT_USER,
+    );
+
+    const authorizeAction = await ctx.get(
+      AuthorizationBindings.AUTHORIZE_ACTION,
+    );
+    const isAuthorized = await authorizeAction(user.permissions);
+
+    if (!isAuthorized) {
+      this.logger.warn(
+        `User ${user.id} is not authorized to access MCP tool '${tool.name}'`,
+      );
+      throw new HttpErrors.Forbidden(
+        `Access denied for MCP tool '${tool.name}'.`,
+      );
+    }
+
+    return ctx;
+  }
+
+  /**
+   * Prepare method arguments based on parameter patterns
+   */
+  private prepareMethodArguments(
+    tool: McpToolMetadata,
+    args: {[key: string]: unknown},
+  ): unknown[] {
+    // Extract individual parameter values by name
+    if (!tool.parameterNames?.length) {
+      // Fallback - pass args object directly if no parameter names
+      return [args];
+    }
+
+    // Extract individual values by parameter names
+    return tool.parameterNames.map(paramName => args?.[paramName]);
+  }
+
+  /**
+   * Execute pre-hook if configured
+   */
+  private async executePreHook(
+    ctx: Context,
+    tool: McpToolMetadata,
+    hookContext: McpHookContext,
+  ): Promise<void> {
+    const preHook = await this.resolveHook(ctx, tool.preHook?.binding);
+    if (preHook) {
+      const preHookResult = await preHook(hookContext);
+      if (preHookResult) {
+        hookContext.args = preHookResult.args;
+      }
+    }
+  }
+
+  /**
+   * Execute post-hook if configured
+   */
+  private async executePostHook(
+    ctx: Context,
+    tool: McpToolMetadata,
+    hookContext: McpHookContext,
+  ): Promise<void> {
+    const postHook = await this.resolveHook(ctx, tool.postHook?.binding);
+    if (postHook) {
+      const postHookResult = await postHook(hookContext);
+      if (postHookResult) {
+        hookContext.result = postHookResult.result;
+        hookContext.args = postHookResult.args;
+        hookContext.error = postHookResult.error;
+      }
+    }
+  }
+
+  /**
+   * Execute the tool method with proper result wrapping
+   */
+  private async executeToolMethod(
+    ctx: Context,
+    bindingKey: string,
+    tool: McpToolMetadata,
+    hookContext: McpHookContext,
+    extras: RequestHandlerExtra<ServerRequest, ServerNotification>,
+  ): Promise<CallToolResult> {
+    const controllerInstance = await ctx.get(bindingKey);
+    const methodArgs = this.prepareMethodArguments(tool, hookContext.args);
+
+    let result = await tool.controllerFunction.call(
+      controllerInstance,
+      ...methodArgs,
+      extras,
+    );
+
+    // Automatically wrap result in MCP response format if not already wrapped
+    if (result && typeof result === 'object' && !result.content) {
+      result = {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      } as CallToolResult;
+    }
+
+    return result;
+  }
+
+  private errorToCallToolResult(error: Error): CallToolResult {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: error.message || 'MCP tool execution failed',
+        },
+      ],
+    } as CallToolResult;
+  }
+}