@malek0512/loopback4-mcp 1.0.0

package/dist/registry/tool-registry.js

@@ -0,0 +1,58 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolRegistry = void 0;
+const core_1 = require("@loopback/core");
+const schema_generator_1 = require("./schema-generator");
+let ToolRegistry = class ToolRegistry {
+    constructor(schemaGenerator) {
+        this.schemaGenerator = schemaGenerator;
+        this.tools = new Map();
+    }
+    register(descriptor) {
+        if (this.tools.has(descriptor.name)) {
+            throw new Error(`Tool '${descriptor.name}' is already registered`);
+        }
+        this.tools.set(descriptor.name, descriptor);
+    }
+    unregister(name) {
+        return this.tools.delete(name);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    list() {
+        return Array.from(this.tools.values()).map(descriptor => ({
+            name: descriptor.name,
+            description: descriptor.description,
+            inputSchema: descriptor.inputSchema,
+        }));
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    clear() {
+        this.tools.clear();
+    }
+    get size() {
+        return this.tools.size;
+    }
+};
+exports.ToolRegistry = ToolRegistry;
+exports.ToolRegistry = ToolRegistry = __decorate([
+    (0, core_1.bind)({ scope: core_1.BindingScope.SINGLETON }),
+    __param(0, (0, core_1.inject)('mcp.schemaGenerator')),
+    __metadata("design:paramtypes", [schema_generator_1.SchemaGenerator])
+], ToolRegistry);
+//# sourceMappingURL=tool-registry.js.map

package/dist/registry/tool-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../../src/registry/tool-registry.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,yCAA0D;AAE1D,yDAAmD;AAY5C,IAAM,YAAY,GAAlB,MAAM,YAAY;IAGvB,YAEE,eAAwC;QAAhC,oBAAe,GAAf,eAAe,CAAiB;QAJlC,UAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;IAK/C,CAAC;IAEJ,QAAQ,CAAC,UAA0B;QACjC,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,SAAS,UAAU,CAAC,IAAI,yBAAyB,CAAC,CAAC;QACrE,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAC9C,CAAC;IAED,UAAU,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YACxD,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,WAAW,EAAE,UAAU,CAAC,WAAW;YACnC,WAAW,EAAE,UAAU,CAAC,WAAkB;SAC3C,CAAC,CAAC,CAAC;IACN,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF,CAAA;AA1CY,oCAAY;uBAAZ,YAAY;IADxB,IAAA,WAAI,EAAC,EAAC,KAAK,EAAE,mBAAY,CAAC,SAAS,EAAC,CAAC;IAKjC,WAAA,IAAA,aAAM,EAAC,qBAAqB,CAAC,CAAA;qCACL,kCAAe;GAL/B,YAAY,CA0CxB"}

package/dist/transport/index.d.ts

@@ -0,0 +1,2 @@
+export * from './sse.transport';
+//# sourceMappingURL=index.d.ts.map

package/dist/transport/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transport/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/transport/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./sse.transport"), exports);
+//# sourceMappingURL=index.js.map

package/dist/transport/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/transport/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kDAAgC"}

package/dist/transport/sse.transport.d.ts

@@ -0,0 +1,9 @@
+import { Request, Response } from '@loopback/rest';
+import { MessageRouter } from '../protocol/message-router';
+export declare class SseTransport {
+    private messageRouter;
+    constructor(messageRouter: MessageRouter);
+    handleConnection(req: Request, res: Response): Promise<void>;
+    private sendEvent;
+}
+//# sourceMappingURL=sse.transport.d.ts.map

package/dist/transport/sse.transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.transport.d.ts","sourceRoot":"","sources":["../../src/transport/sse.transport.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAC,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AAGzD,qBACa,YAAY;IAGrB,OAAO,CAAC,aAAa;gBAAb,aAAa,EAAE,aAAa;IAGhC,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAuClE,OAAO,CAAC,SAAS;CAIlB"}

package/dist/transport/sse.transport.js

@@ -0,0 +1,67 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SseTransport = void 0;
+const core_1 = require("@loopback/core");
+const message_router_1 = require("../protocol/message-router");
+let SseTransport = class SseTransport {
+    constructor(messageRouter) {
+        this.messageRouter = messageRouter;
+    }
+    async handleConnection(req, res) {
+        // Set SSE headers
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.setHeader('Connection', 'keep-alive');
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        // Send initial connection event
+        this.sendEvent(res, 'connected', { message: 'MCP Server connected' });
+        // Handle incoming messages
+        req.on('data', async (chunk) => {
+            try {
+                const message = JSON.parse(chunk.toString());
+                const response = await this.messageRouter.route(message);
+                this.sendEvent(res, 'message', response);
+            }
+            catch (error) {
+                this.sendEvent(res, 'error', {
+                    message: 'Failed to process message',
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        });
+        // Handle connection close
+        req.on('close', () => {
+            console.log('SSE connection closed');
+        });
+        // Keep connection alive
+        const keepAliveInterval = setInterval(() => {
+            this.sendEvent(res, 'ping', { timestamp: Date.now() });
+        }, 30000);
+        req.on('close', () => {
+            clearInterval(keepAliveInterval);
+        });
+    }
+    sendEvent(res, event, data) {
+        res.write(`event: ${event}\n`);
+        res.write(`data: ${JSON.stringify(data)}\n\n`);
+    }
+};
+exports.SseTransport = SseTransport;
+exports.SseTransport = SseTransport = __decorate([
+    (0, core_1.bind)({ scope: core_1.BindingScope.SINGLETON }),
+    __param(0, (0, core_1.inject)('mcp.messageRouter')),
+    __metadata("design:paramtypes", [message_router_1.MessageRouter])
+], SseTransport);
+//# sourceMappingURL=sse.transport.js.map

package/dist/transport/sse.transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.transport.js","sourceRoot":"","sources":["../../src/transport/sse.transport.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,yCAA0D;AAE1D,+DAAyD;AAIlD,IAAM,YAAY,GAAlB,MAAM,YAAY;IACvB,YAEU,aAA4B;QAA5B,kBAAa,GAAb,aAAa,CAAe;IACnC,CAAC;IAEJ,KAAK,CAAC,gBAAgB,CAAC,GAAY,EAAE,GAAa;QAChD,kBAAkB;QAClB,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,mBAAmB,CAAC,CAAC;QACnD,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;QAC3C,GAAG,CAAC,SAAS,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QAC1C,GAAG,CAAC,SAAS,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;QAElD,gCAAgC;QAChC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,WAAW,EAAE,EAAC,OAAO,EAAE,sBAAsB,EAAC,CAAC,CAAC;QAEpE,2BAA2B;QAC3B,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAa,EAAE,EAAE;YACrC,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAmB,CAAC;gBAC/D,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBACzD,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC3C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE;oBAC3B,OAAO,EAAE,2BAA2B;oBACpC,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;iBAC9D,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,0BAA0B;QAC1B,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACnB,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QAEH,wBAAwB;QACxB,MAAM,iBAAiB,GAAG,WAAW,CAAC,GAAG,EAAE;YACzC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,EAAC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAC,CAAC,CAAC;QACvD,CAAC,EAAE,KAAK,CAAC,CAAC;QAEV,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACnB,aAAa,CAAC,iBAAiB,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,SAAS,CAAC,GAAa,EAAE,KAAa,EAAE,IAAa;QAC3D,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC;QAC/B,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACjD,CAAC;CACF,CAAA;AAjDY,oCAAY;uBAAZ,YAAY;IADxB,IAAA,WAAI,EAAC,EAAC,KAAK,EAAE,mBAAY,CAAC,SAAS,EAAC,CAAC;IAGjC,WAAA,IAAA,aAAM,EAAC,mBAAmB,CAAC,CAAA;qCACL,8BAAa;GAH3B,YAAY,CAiDxB"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@malek0512/loopback4-mcp",
+  "version": "1.0.0",
+  "description": "MCP (Model Context Protocol) component for LoopBack 4 — exposes your controllers as AI-callable tools via JSON-RPC 2.0 + SSE",
+  "keywords": ["loopback", "loopback4", "mcp", "model-context-protocol", "ai", "llm", "tools"],
+  "license": "MIT",
+  "author": "malek0512",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@loopback/core": ">=4.0.0",
+    "@loopback/rest": ">=12.0.0",
+    "@loopback/openapi-v3": ">=9.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@loopback/core": "^6.1.7",
+    "@loopback/rest": "^14.0.10",
+    "@loopback/openapi-v3": "^10.0.10"
+  }
+}

package/src/component.ts

@@ -0,0 +1,58 @@
+import {
+  Component,
+  ContextTags,
+  injectable,
+  CoreBindings,
+  inject,
+  Application,
+  BindingScope,
+} from '@loopback/core';
+import {McpController} from './controllers/mcp.controller';
+import {ToolRegistry} from './registry/tool-registry';
+import {MetadataScanner} from './registry/metadata-scanner';
+import {SchemaGenerator} from './registry/schema-generator';
+import {JsonRpcHandler} from './protocol/json-rpc.handler';
+import {MessageRouter} from './protocol/message-router';
+import {ToolExecutor} from './execution/tool-executor';
+import {ContextManager} from './execution/context-manager';
+import {ResultFormatter} from './execution/result-formatter';
+import {SseTransport} from './transport/sse.transport';
+
+@injectable({
+  tags: {[ContextTags.KEY]: 'components.McpComponent'},
+})
+export class McpComponent implements Component {
+  controllers = [McpController];
+
+  constructor(
+    @inject(CoreBindings.APPLICATION_INSTANCE)
+    private app: Application,
+  ) {
+    // Bind all MCP services as singletons so state (tool registry, initialized flag) persists across requests
+    this.app.bind('mcp.toolRegistry').toClass(ToolRegistry).inScope(BindingScope.SINGLETON);
+    this.app.bind('mcp.metadataScanner').toClass(MetadataScanner).inScope(BindingScope.SINGLETON);
+    this.app.bind('mcp.schemaGenerator').toClass(SchemaGenerator).inScope(BindingScope.SINGLETON);
+    this.app.bind('mcp.jsonRpcHandler').toClass(JsonRpcHandler).inScope(BindingScope.SINGLETON);
+    this.app.bind('mcp.messageRouter').toClass(MessageRouter).inScope(BindingScope.SINGLETON);
+    this.app.bind('mcp.toolExecutor').toClass(ToolExecutor).inScope(BindingScope.SINGLETON);
+    this.app.bind('mcp.contextManager').toClass(ContextManager).inScope(BindingScope.SINGLETON);
+    this.app.bind('mcp.resultFormatter').toClass(ResultFormatter).inScope(BindingScope.SINGLETON);
+    this.app.bind('mcp.sseTransport').toClass(SseTransport).inScope(BindingScope.SINGLETON);
+
+    // Scan for MCP tools after application starts
+    this.app.on('started', async () => {
+      // Delay scanning to ensure all controllers are fully initialized
+      setTimeout(async () => {
+        try {
+          console.log('[MCP] Scanning for MCP tools...');
+          const scanner = await this.app.get<MetadataScanner>('mcp.metadataScanner');
+          await scanner.scan();
+          const registry = await this.app.get<ToolRegistry>('mcp.toolRegistry');
+          console.log(`[MCP] Tool scanning complete. Found ${registry.size} tools.`);
+        } catch (error) {
+          console.error('[MCP] Error scanning tools:', error);
+        }
+      }, 100);
+    });
+  }
+}

package/src/controllers/index.ts

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

package/src/controllers/mcp.controller.ts

@@ -0,0 +1,42 @@
+import {inject} from '@loopback/core';
+import {
+  post,
+  get,
+  Request,
+  Response,
+  RestBindings,
+  requestBody,
+} from '@loopback/rest';
+import {MessageRouter} from '../protocol/message-router';
+import {SseTransport} from '../transport/sse.transport';
+import {JsonRpcRequest} from '../protocol/types';
+
+export class McpController {
+  constructor(
+    @inject('mcp.messageRouter')
+    private messageRouter: MessageRouter,
+    @inject('mcp.sseTransport')
+    private sseTransport: SseTransport,
+  ) {}
+
+  @post('/mcp')
+  async handleMessage(@requestBody() request: JsonRpcRequest): Promise<unknown> {
+    return this.messageRouter.route(request);
+  }
+
+  @get('/mcp/sse')
+  async handleSse(
+    @inject(RestBindings.Http.REQUEST) req: Request,
+    @inject(RestBindings.Http.RESPONSE) res: Response,
+  ): Promise<void> {
+    return this.sseTransport.handleConnection(req, res);
+  }
+
+  @get('/mcp/health')
+  async health(): Promise<{status: string; timestamp: number}> {
+    return {
+      status: 'ok',
+      timestamp: Date.now(),
+    };
+  }
+}

package/src/decorators/index.ts

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

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

@@ -0,0 +1,57 @@
+import {MetadataInspector, MethodDecoratorFactory} from '@loopback/core';
+import {JsonSchema} from '../protocol/types';
+
+export const MCP_TOOL_METADATA_KEY = 'mcp:tool';
+
+export interface McpToolMetadata {
+  name: string;
+  description?: string;
+  inputSchema?: JsonSchema;
+  preHook?: {
+    binding?: string;
+    function?: Function;
+  };
+  postHook?: {
+    binding?: string;
+    function?: Function;
+  };
+}
+
+export function mcpTool(metadata: McpToolMetadata): MethodDecorator {
+  return MethodDecoratorFactory.createDecorator<McpToolMetadata>(
+    MCP_TOOL_METADATA_KEY,
+    metadata,
+    {decoratorName: '@mcpTool'},
+  );
+}
+
+export namespace McpToolMetadata {
+  export function getMetadata(
+    target: Object,
+    methodName: string,
+  ): McpToolMetadata | undefined {
+    return MetadataInspector.getMethodMetadata<McpToolMetadata>(
+      MCP_TOOL_METADATA_KEY,
+      target,
+      methodName,
+    );
+  }
+
+  export function getAllMetadata(target: Object): Map<string, McpToolMetadata> {
+    const metadata = new Map<string, McpToolMetadata>();
+    const proto = Object.getPrototypeOf(target);
+
+    const methodNames = Object.getOwnPropertyNames(proto).filter(
+      name => typeof proto[name] === 'function' && name !== 'constructor',
+    );
+
+    for (const methodName of methodNames) {
+      const toolMetadata = getMetadata(target, methodName);
+      if (toolMetadata) {
+        metadata.set(methodName, toolMetadata);
+      }
+    }
+
+    return metadata;
+  }
+}

package/src/execution/context-manager.ts

@@ -0,0 +1,44 @@
+import {bind, BindingScope} from '@loopback/core';
+
+export interface ExecutionContext {
+  toolName: string;
+  arguments: Record<string, unknown>;
+  timestamp: number;
+  requestId?: string;
+}
+
+@bind({scope: BindingScope.SINGLETON})
+export class ContextManager {
+  private contexts = new Map<string, ExecutionContext>();
+
+  createContext(
+    toolName: string,
+    args: Record<string, unknown>,
+    requestId?: string,
+  ): ExecutionContext {
+    const context: ExecutionContext = {
+      toolName,
+      arguments: args,
+      timestamp: Date.now(),
+      requestId,
+    };
+
+    if (requestId) {
+      this.contexts.set(requestId, context);
+    }
+
+    return context;
+  }
+
+  getContext(requestId: string): ExecutionContext | undefined {
+    return this.contexts.get(requestId);
+  }
+
+  clearContext(requestId: string): boolean {
+    return this.contexts.delete(requestId);
+  }
+
+  clearAll(): void {
+    this.contexts.clear();
+  }
+}

package/src/execution/index.ts

@@ -0,0 +1,3 @@
+export * from './tool-executor';
+export * from './context-manager';
+export * from './result-formatter';

package/src/execution/result-formatter.ts

@@ -0,0 +1,104 @@
+import {bind, BindingScope} from '@loopback/core';
+import {Content, TextContent} from '../protocol/types';
+
+@bind({scope: BindingScope.SINGLETON})
+export class ResultFormatter {
+  /**
+   * Format the result of a tool execution into MCP Content format
+   */
+  format(result: unknown): Content[] {
+    // If result already has content array, use it
+    if (this.isContentArray(result)) {
+      return result as Content[];
+    }
+
+    // If result has a content property, use it
+    if (this.hasContentProperty(result)) {
+      return (result as any).content;
+    }
+
+    // Convert result to text content
+    return this.toTextContent(result);
+  }
+
+  /**
+   * Format an error into MCP Content format
+   */
+  formatError(error: unknown): Content[] {
+    let message = 'Unknown error occurred';
+    let details: string | undefined;
+
+    if (error instanceof Error) {
+      message = error.message;
+      details = error.stack;
+    } else if (typeof error === 'string') {
+      message = error;
+    } else if (error && typeof error === 'object') {
+      message = (error as any).message || JSON.stringify(error);
+    }
+
+    const content: TextContent[] = [
+      {
+        type: 'text',
+        text: `Error: ${message}`,
+      },
+    ];
+
+    if (details) {
+      content.push({
+        type: 'text',
+        text: `Details:\n${details}`,
+      });
+    }
+
+    return content;
+  }
+
+  private isContentArray(result: unknown): boolean {
+    return (
+      Array.isArray(result) &&
+      result.length > 0 &&
+      result.every(item => this.isContent(item))
+    );
+  }
+
+  private isContent(item: unknown): boolean {
+    if (!item || typeof item !== 'object') return false;
+    const content = item as any;
+    return (
+      content.type === 'text' ||
+      content.type === 'image' ||
+      content.type === 'resource'
+    );
+  }
+
+  private hasContentProperty(result: unknown): boolean {
+    return (
+      result !== null &&
+      typeof result === 'object' &&
+      'content' in result &&
+      Array.isArray((result as any).content)
+    );
+  }
+
+  private toTextContent(result: unknown): Content[] {
+    let text: string;
+
+    if (result === null || result === undefined) {
+      text = 'Operation completed successfully';
+    } else if (typeof result === 'string') {
+      text = result;
+    } else if (typeof result === 'object') {
+      text = JSON.stringify(result, null, 2);
+    } else {
+      text = String(result);
+    }
+
+    return [
+      {
+        type: 'text',
+        text,
+      },
+    ];
+  }
+}

package/src/execution/tool-executor.ts

@@ -0,0 +1,61 @@
+import {bind, BindingScope, inject} from '@loopback/core';
+import {ToolRegistry} from '../registry/tool-registry';
+import {ToolCallResult, McpErrorCode} from '../protocol/types';
+import {ContextManager} from './context-manager';
+import {ResultFormatter} from './result-formatter';
+
+@bind({scope: BindingScope.SINGLETON})
+export class ToolExecutor {
+  constructor(
+    @inject('mcp.toolRegistry')
+    private toolRegistry: ToolRegistry,
+    @inject('mcp.contextManager')
+    private contextManager: ContextManager,
+    @inject('mcp.resultFormatter')
+    private resultFormatter: ResultFormatter,
+  ) {}
+
+  async execute(
+    toolName: string,
+    args: Record<string, unknown>,
+  ): Promise<ToolCallResult> {
+    // Get tool descriptor
+    const descriptor = this.toolRegistry.get(toolName);
+    if (!descriptor) {
+      throw {
+        code: McpErrorCode.TOOL_NOT_FOUND,
+        message: `Tool '${toolName}' not found`,
+      };
+    }
+
+    try {
+      // Create execution context
+      const context = this.contextManager.createContext(toolName, args);
+
+      // Execute pre-hooks (if any)
+      // await this.executePreHooks(context);
+
+      // Execute the tool
+      const result = await descriptor.handler(args);
+
+      // Execute post-hooks (if any)
+      // await this.executePostHooks(context, result);
+
+      // Format result
+      const formattedResult = this.resultFormatter.format(result);
+
+      return {
+        content: formattedResult,
+        isError: false,
+      };
+    } catch (error) {
+      // Format error
+      const errorContent = this.resultFormatter.formatError(error);
+
+      return {
+        content: errorContent,
+        isError: true,
+      };
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export {McpComponent} from './component';
+export {mcpTool} from './decorators/mcp-tool.decorator';
+export type {McpToolMetadata} from './decorators/mcp-tool.decorator';
+export {MCP_TOOL_METADATA_KEY} from './decorators/mcp-tool.decorator';
+export * from './protocol/types';

package/src/observers/index.ts

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

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

@@ -0,0 +1,19 @@
+import {inject, lifeCycleObserver, LifeCycleObserver} from '@loopback/core';
+import {MetadataScanner} from '../registry/metadata-scanner';
+
+@lifeCycleObserver('mcp')
+export class McpBootObserver implements LifeCycleObserver {
+  constructor(
+    @inject('mcp.metadataScanner')
+    private metadataScanner: MetadataScanner,
+  ) {}
+
+  async start(): Promise<void> {
+    // Note: Actual scanning happens in component after 'started' event
+    // This observer is kept for future lifecycle hooks if needed
+  }
+
+  async stop(): Promise<void> {
+    console.log('[MCP] Shutting down MCP component');
+  }
+}

package/src/protocol/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './json-rpc.handler';
+export * from './message-router';