loopback4-mcp 0.0.1

package/package.json

@@ -0,0 +1,139 @@
+{
+  "name": "loopback4-mcp",
+  "version": "0.0.1",
+  "private": false,
+  "description": "Desktop",
+  "keywords": [
+    "loopback-extension",
+    "loopback"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "lb-tsc",
+    "build:watch": "lb-tsc --watch",
+    "lint": "npm run eslint && npm run prettier:check",
+    "lint:fix": "npm run eslint:fix && npm run prettier:fix",
+    "prettier:cli": "lb-prettier \"**/*.ts\" \"**/*.js\"",
+    "prettier:check": "npm run prettier:cli -- -l",
+    "prettier:fix": "npm run prettier:cli -- --write",
+    "eslint": "lb-eslint --report-unused-disable-directives .",
+    "eslint:fix": "npm run eslint -- --fix",
+    "pretest": "npm run rebuild",
+    "test": "lb-mocha --allow-console-logs \"dist/__tests__\"",
+    "posttest": "npm run lint",
+    "test:dev": "lb-mocha --allow-console-logs dist/__tests__/**/*.js && npm run posttest",
+    "clean": "lb-clean dist *.tsbuildinfo .eslintcache",
+    "rebuild": "npm run clean && npm run build",
+    "prepublishOnly": "npm run test",
+    "prepare": "husky install"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sourcefuse/loopback4-mcp"
+  },
+  "author": "SourceFuse",
+  "license": "MIT",
+  "files": [
+    "README.md",
+    "dist",
+    "src",
+    "!*/__tests__"
+  ],
+  "peerDependencies": {
+    "@loopback/core": "^7.0.3"
+  },
+  "dependencies": {
+    "@loopback/rest": "^15.0.7",
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "@sourceloop/core": "^20.0.0",
+    "tslib": "^2.6.2",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^17.7.1",
+    "@commitlint/config-conventional": "^17.7.0",
+    "@loopback/build": "^12.0.3",
+    "@loopback/core": "^7.0.3",
+    "@loopback/eslint-config": "^16.0.1",
+    "@loopback/testlab": "^8.0.3",
+    "@semantic-release/changelog": "^6.0.1",
+    "@semantic-release/commit-analyzer": "^9.0.2",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^13.1.3",
+    "@semantic-release/release-notes-generator": "^10.0.3",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^16.18.126",
+    "commitizen": "^4.2.4",
+    "cz-conventional-changelog": "^3.3.0",
+    "cz-customizable": "^6.3.0",
+    "cz-customizable-ghooks": "^2.0.0",
+    "eslint": "^8.57.1",
+    "husky": "^7.0.4",
+    "loopback4-authentication": "^13.0.4",
+    "loopback4-authorization": "^8.1.3",
+    "semantic-release": "^25.0.2",
+    "source-map-support": "^0.5.21",
+    "typescript": "~5.2.2"
+  },
+  "overrides": {
+    "jws": "3.2.3",
+    "node-forge": "1.3.2"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-customizable"
+    },
+    "cz-customizable": {
+      "config": "./.cz-config.js"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "release": {
+    "branches": [
+      "master"
+    ],
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "preset": "angular",
+          "releaseRules": [
+            {
+              "type": "chore",
+              "scope": "deps",
+              "release": "patch"
+            }
+          ]
+        }
+      ],
+      "@semantic-release/release-notes-generator",
+      [
+        "@semantic-release/npm",
+        {
+          "npmPublish": true,
+          "pkgRoot": ".",
+          "tarballDir": "dist"
+        }
+      ],
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "package.json",
+            "CHANGELOG.md"
+          ],
+          "message": "chore(release): ${nextRelease.version} semantic"
+        }
+      ],
+      "@semantic-release/github"
+    ],
+    "repositoryUrl": "https://github.com/sourcefuse/loopback4-mcp.git"
+  }
+}

package/src/component.ts

@@ -0,0 +1,18 @@
+import {Application, Component, CoreBindings, inject} from '@loopback/core';
+import {
+  McpSchemaGeneratorService,
+  McpServerFactory,
+  McpToolRegistry,
+} from './services';
+import {McpController} from './controllers';
+import {McpToolRegistryBootObserver} from './observers';
+
+export class McpComponent implements Component {
+  services = [McpSchemaGeneratorService, McpServerFactory, McpToolRegistry];
+  controllers = [McpController];
+  lifeCycleObservers = [McpToolRegistryBootObserver];
+  constructor(
+    @inject(CoreBindings.APPLICATION_INSTANCE)
+    private application: Application,
+  ) {}
+}

package/src/constants/index.ts

@@ -0,0 +1 @@
+export * from './mcp-tool.constant';

package/src/constants/mcp-tool.constant.ts

@@ -0,0 +1,2 @@
+// Metadata key for MCP tools
+export const MCP_TOOL_METADATA_KEY = 'mcp:tools';

package/src/controllers/README.md

@@ -0,0 +1,6 @@
+# Controllers
+
+This directory contains source files for the controllers exported by this
+extension.
+
+For more information, see <http://loopback.io/doc/en/lb4/Controllers.html>.

package/src/controllers/index.ts

@@ -0,0 +1 @@
+export * from './mcp.controller';

package/src/controllers/mcp.controller.ts

@@ -0,0 +1,112 @@
+import {inject, service} from '@loopback/core';
+import {post, Request, Response, RestBindings} from '@loopback/rest';
+import {StreamableHTTPServerTransport} from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import {CONTENT_TYPE, ILogger, LOGGER, STATUS_CODE} from '@sourceloop/core';
+import {authenticate, STRATEGY} from 'loopback4-authentication';
+import {authorize} from 'loopback4-authorization';
+import {McpServerFactory} from '../services';
+
+export class McpController {
+  constructor(
+    @inject(LOGGER.LOGGER_INJECT)
+    private readonly logger: ILogger,
+    @service(McpServerFactory)
+    private readonly serverFactory: McpServerFactory,
+  ) {}
+
+  @authenticate(STRATEGY.BEARER, {
+    passReqToCallback: true,
+  })
+  @authorize({
+    permissions: ['*'],
+  })
+  @post('/mcp', {
+    summary: 'MCP HTTP Message',
+    description: 'Handle MCP message via StreamableHTTP transport',
+    requestBody: {
+      content: {
+        [CONTENT_TYPE.JSON]: {
+          schema: {
+            type: 'object',
+            description: 'MCP message payload',
+          },
+        },
+      },
+    },
+    responses: {
+      [STATUS_CODE.OK]: {
+        description: 'MCP message processed successfully',
+        content: {
+          [CONTENT_TYPE.JSON]: {
+            schema: {
+              type: 'object',
+              description: 'MCP response message',
+            },
+          },
+        },
+      },
+      [STATUS_CODE.INTERNAL_SERVER_ERROR]: {
+        description: 'Internal server error',
+        content: {
+          [CONTENT_TYPE.JSON]: {
+            schema: {
+              type: 'object',
+              properties: {
+                jsonrpc: {type: 'string'},
+                error: {
+                  type: 'object',
+                  properties: {
+                    code: {type: 'number'},
+                    message: {type: 'string'},
+                  },
+                },
+                id: {type: 'null'},
+              },
+            },
+          },
+        },
+      },
+    },
+  })
+  async handleMCPRequest(
+    @inject(RestBindings.Http.REQUEST) req: Request,
+    @inject(RestBindings.Http.RESPONSE) res: Response,
+  ): Promise<void> {
+    try {
+      // Server creation using factory service
+      const server = this.serverFactory.createServer();
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+      });
+
+      // Set up cleanup handlers
+      /* eslint-disable @typescript-eslint/no-misused-promises */
+      res.on('close', async () => {
+        await transport.close();
+        await server.close();
+        this.logger.info('Session closed.');
+      });
+
+      res.on('error', async () => {
+        await transport.close();
+        await server.close();
+        this.logger.info('Closing Session as it errorred out.');
+      });
+
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    } catch (err) {
+      this.logger.error('Failed to establish MCP connection:', err);
+      if (!res.headersSent) {
+        res.status(STATUS_CODE.INTERNAL_SERVER_ERROR).json({
+          jsonrpc: '2.0',
+          error: {
+            code: -32603,
+            message: 'Internal server error',
+          },
+          id: null,
+        });
+      }
+    }
+  }
+}

package/src/decorators/README.md

@@ -0,0 +1,34 @@
+# Decorators
+
+## Overview
+
+Decorators provide annotations for class methods and arguments. Decorators use
+the form `@decorator` where `decorator` is the name of the function that will be
+called at runtime.
+
+## Basic Usage
+
+### txIdFromHeader
+
+This simple decorator allows you to annotate a `Controller` method argument. The
+decorator will annotate the method argument with the value of the header
+`X-Transaction-Id` from the request.
+
+**Example**
+
+```ts
+class MyController {
+  @get('/')
+  getHandler(@txIdFromHeader() txId: string) {
+    return `Your transaction id is: ${txId}`;
+  }
+}
+```
+
+## Related Resources
+
+You can check out the following resource to learn more about decorators and how
+they are used in LoopBack Next.
+
+- [TypeScript Handbook: Decorators](https://www.typescriptlang.org/docs/handbook/decorators.html)
+- [Decorators in LoopBack](http://loopback.io/doc/en/lb4/Decorators.html)

package/src/decorators/index.ts

@@ -0,0 +1 @@
+export * from './mcp-tool.decorator';

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

@@ -0,0 +1,68 @@
+import {BindingKey, MetadataInspector} from '@loopback/core';
+import {MCP_TOOL_METADATA_KEY} from '../constants';
+import {McpHookFunction} from '../interfaces';
+import {
+  McpHookConfig,
+  McpToolDecoratorOptions,
+  McpToolMetadata,
+} from '../types';
+
+/**
+ * Process hook config to normalize binding keys
+ */
+function processHookConfig(
+  hookConfig?: McpHookConfig,
+): McpHookConfig | undefined {
+  if (!hookConfig) return undefined;
+
+  const binding =
+    typeof hookConfig.binding === 'string'
+      ? BindingKey.create<McpHookFunction>(hookConfig.binding)
+      : hookConfig.binding;
+
+  return {
+    binding,
+    config: hookConfig.config,
+  };
+}
+
+export function mcpTool(options: McpToolDecoratorOptions) {
+  return function (
+    target: Object,
+    propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ) {
+    // Create basic schema - parameter extraction happens in the service
+    const basicSchema = options.schema ?? {};
+
+    const metadata: McpToolMetadata = {
+      name: options.name,
+      description: options.description,
+      schema: basicSchema,
+      controllerFunction: descriptor.value,
+      preHook: processHookConfig(options.preHook),
+      postHook: processHookConfig(options.postHook),
+      parameterNames: [], // Will be populated by service
+    };
+
+    // Store metadata using LoopBack's metadata system
+    // Get existing metadata for the class
+    const existingMethodsMetadata =
+      MetadataInspector.getAllMethodMetadata<McpToolMetadata>(
+        MCP_TOOL_METADATA_KEY,
+        target,
+      ) ?? {};
+
+    // Add this method's metadata
+    existingMethodsMetadata[propertyKey] = metadata;
+
+    // Store the complete metadata map back
+    MetadataInspector.defineMetadata(
+      MCP_TOOL_METADATA_KEY,
+      existingMethodsMetadata,
+      target,
+    );
+
+    return descriptor;
+  };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './component';
+export * from './types';
+export * from './decorators';
+export * from './observers';
+export * from './keys';

package/src/interfaces/index.ts

@@ -0,0 +1 @@
+export * from './mcp-hook-provider.interface';

package/src/interfaces/mcp-hook-provider.interface.ts

@@ -0,0 +1,11 @@
+export interface McpHookContext {
+  toolName: string;
+  args: {[key: string]: unknown};
+  result?: unknown;
+  error?: Error;
+  metadata?: {[key: string]: unknown};
+}
+
+export type McpHookFunction = (
+  context: McpHookContext,
+) => Promise<McpHookContext | void> | McpHookContext | void;

package/src/keys.ts

@@ -0,0 +1 @@
+export namespace McpBindings {}

package/src/mixins/README.md

@@ -0,0 +1,216 @@
+# Mixins
+
+This directory contains source files for the mixins exported by this extension.
+
+## Overview
+
+Sometimes it's helpful to write partial classes and then combining them together
+to build more powerful classes. This pattern is called Mixins (mixing in partial
+classes) and is supported by LoopBack 4.
+
+LoopBack 4 supports mixins at an `Application` level. Your partial class can
+then be mixed into the `Application` class. A mixin class can modify or override
+existing methods of the class or add new ones! It is also possible to mixin
+multiple classes together as needed.
+
+### High level example
+
+```ts
+class MyApplication extends MyMixinClass(Application) {
+  // Your code
+}
+
+// Multiple Classes mixed together
+class MyApp extends MyMixinClass(MyMixinClass2(Application)) {
+  // Your code
+}
+```
+
+## Getting Started
+
+For hello-extensions we write a simple Mixin that allows the `Application` class
+to bind a `Logger` class from ApplicationOptions, Components, or `.logger()`
+method that is mixed in. `Logger` instances are bound to the key
+`loggers.${Logger.name}`. Once a Logger has been bound, the user can retrieve it
+by using
+[Dependency Injection](http://loopback.io/doc/en/lb4/Dependency-injection.html)
+and the key for the `Logger`.
+
+### What is a Logger?
+
+> A Logger class is provides a mechanism for logging messages of varying
+> priority by providing an implementation for `Logger.info()` &
+> `Logger.error()`. An example of a Logger is `console` which has
+> `console.log()` and `console.error()`.
+
+#### An example Logger
+
+```ts
+class ColorLogger implements Logger {
+  log(...args: LogArgs) {
+    console.log('log  :', ...args);
+  }
+
+  error(...args: LogArgs) {
+    // log in red color
+    console.log('\x1b[31m error: ', ...args, '\x1b[0m');
+  }
+}
+```
+
+## LoggerMixin
+
+A complete & functional implementation can be found in `logger.mixin.ts`. _Here
+are some key things to keep in mind when writing your own Mixin_.
+
+### constructor()
+
+A Mixin constructor must take an array of any type as it's argument. This would
+represent `ApplicationOptions` for our base class `Application` as well as any
+properties we would like for our Mixin.
+
+It is also important for the constructor to call `super(args)` so `Application`
+continues to work as expected.
+
+```ts
+constructor(...args: any[]) {
+  super(args);
+}
+```
+
+### Binding via `ApplicationOptions`
+
+As mentioned earlier, since our `args` represents `ApplicationOptions`, we can
+make it possible for users to pass in their `Logger` implementations in a
+`loggers` array on `ApplicationOptions`. We can then read the array and
+automatically bind these for the user.
+
+#### Example user experience
+
+```ts
+class MyApp extends LoggerMixin(Application) {
+  constructor(...args: any[]) {
+    super(...args);
+  }
+}
+
+const app = new MyApp({
+  loggers: [ColorLogger],
+});
+```
+
+#### Example Implementation
+
+To implement this, we would check `this.options` to see if it has a `loggers`
+array and if so, bind it by calling the `.logger()` method. (More on that
+below).
+
+```ts
+if (this.options.loggers) {
+  for (const logger of this.options.loggers) {
+    this.logger(logger);
+  }
+}
+```
+
+### Binding via `.logger()`
+
+As mentioned earlier, we can add a new function to our `Application` class
+called `.logger()` into which a user would pass in their `Logger` implementation
+so we can bind it to the `loggers.*` key for them. We just add this new method
+on our partial Mixin class.
+
+```ts
+logger(logClass: Logger) {
+  const loggerKey = `loggers.${logClass.name}`;
+  this.bind(loggerKey).toClass(logClass);
+}
+```
+
+### Binding a `Logger` from a `Component`
+
+Our base class of `Application` already has a method that binds components. We
+can modify this method to continue binding a `Component` as usual but also
+binding any `Logger` instances provided by that `Component`. When modifying
+behavior of an existing method, we can ensure existing behavior by calling the
+`super.method()`. In our case the method is `.component()`.
+
+```ts
+component(component: Constructor<any>) {
+  super.component(component); // ensures existing behavior from Application
+  this.mountComponentLoggers(component);
+}
+```
+
+We have now modified `.component()` to do it's thing and then call our method
+`mountComponentLoggers()`. In this method is where we check for `Logger`
+implementations declared by the component in a `loggers` array by retrieving the
+instance of the `Component`. Then if `loggers` array exists, we bind the
+`Logger` instances as normal (by leveraging our `.logger()` method).
+
+```ts
+mountComponentLoggers(component: Constructor<any>) {
+  const componentKey = `components.${component.name}`;
+  const compInstance = this.getSync(componentKey);
+
+  if (compInstance.loggers) {
+    for (const logger of compInstance.loggers) {
+      this.logger(logger);
+    }
+  }
+}
+```
+
+## Retrieving the Logger instance
+
+Now that we have bound a Logger to our Application via one of the many ways made
+possible by `LoggerMixin`, we need to be able to retrieve it so we can use it.
+Let's say we want to use it in a controller. Here's an example to retrieving it
+so we can use it.
+
+```ts
+class MyController {
+  constructor(@inject('loggers.ColorLogger') protected log: Logger) {}
+
+  helloWorld() {
+    this.log.log('hello log');
+    this.log.error('hello error');
+  }
+}
+```
+
+## Examples for using LoggerMixin
+
+### Using the app's `.logger()` method
+
+```ts
+class LoggingApplication extends LoggerMixin(Application) {
+  constructor(...args: any[]) {
+    super(...args);
+    this.logger(ColorLogger);
+  }
+}
+```
+
+### Using the app's constructor
+
+```ts
+class LoggerApplication extends LoggerMixin(Application) {
+  constructor() {
+    super({
+      loggers: [ColorLogger],
+    });
+  }
+}
+```
+
+### Binding a Logger provided by a component
+
+```ts
+class LoggingComponent implements Component {
+  loggers: [ColorLogger];
+}
+
+const app = new LoggingApplication();
+app.component(LoggingComponent); // Logger from MyComponent will be bound to loggers.ColorLogger
+```

package/src/observers/index.ts

@@ -0,0 +1 @@
+export * from './mcp-tool-registry-boot.observer';

package/src/observers/mcp-tool-registry-boot.observer.ts

@@ -0,0 +1,40 @@
+import {
+  inject,
+  lifeCycleObserver,
+  LifeCycleObserver,
+  service,
+} from '@loopback/core';
+import {ILogger, LOGGER} from '@sourceloop/core';
+import {McpToolRegistry} from '../services';
+
+/**
+ * Lifecycle observer to initialize MCP tool registry after application boot
+ */
+@lifeCycleObserver('mcpToolRegistryInit')
+export class McpToolRegistryBootObserver implements LifeCycleObserver {
+  constructor(
+    @service(McpToolRegistry)
+    private readonly mcpToolRegistry: McpToolRegistry,
+    @inject(LOGGER.LOGGER_INJECT)
+    private readonly logger: ILogger,
+  ) {}
+
+  /**
+   * Initialize MCP tool registry after application starts
+   */
+  async start(): Promise<void> {
+    try {
+      await this.mcpToolRegistry.initialize();
+    } catch (error) {
+      this.logger.error('Failed to initialize MCP tool registry:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Called when application stops
+   */
+  async stop(): Promise<void> {
+    this.logger.info('MCP tool registry stopping...');
+  }
+}