easy-mcp-nest 0.2.0 → 0.3.0

package/README.md

@@ -29,12 +29,26 @@ EasyMCP requires the following peer dependencies to be installed:
 - `@nestjs/core` ^11.0.1
 - `@nestjs/platform-express` ^11.0.1
 
-Install them with:
+**Optional peer dependencies** (for specific features):
+- `express` ^4.18.0 (for Express adapter)
+- `zod` ^3.22.0 (for TypeScript-first validation)
+
+Install required dependencies with:
 
 ```bash
 npm install @nestjs/common@^11.0.1 @nestjs/core@^11.0.1 @nestjs/platform-express@^11.0.1
 ```
 
+Install optional dependencies as needed:
+
+```bash
+# For Express adapter
+npm install express@^4.18.0
+
+# For Zod validation
+npm install zod@^3.22.0
+```
+
 ## Quick Start
 
 ```typescript
@@ -193,6 +207,7 @@ process.on('SIGINT', async () => {
 
 ### Types
 
+**Core Types:**
 - `McpConfig` - Main configuration interface
 - `ToolRegistrationInput` - Tool definition interface
 - `ServerInfo` - Optional server information
@@ -207,6 +222,13 @@ process.on('SIGINT', async () => {
 - `VERSION`, `PACKAGE_NAME`, `getVersion()`, `getPackageName()` - Version information utilities
 - `INTERFACE_LAYER_TOKEN` - Token for accessing the interface layer (advanced use cases)
 
+**New Feature Types:**
+- `McpContext` - Context interface for user information
+- `CreateMcpExpressRouterOptions` - Express adapter options
+- `OAuthProviderConfig`, `OAuthConfig` - OAuth configuration
+- `CreateMcpServerOptions` - Standalone server options
+- `StandaloneTransport` - Transport type ('stdio' | 'http')
+
 ## Architecture
 
 EasyMCP uses a simplified architecture for standard MCP servers:
@@ -245,11 +267,11 @@ EasyMCP implements the following MCP protocol methods:
   - Validates client protocol version
   - Returns server capabilities (currently supports tools)
   - Returns server information (name and version)
-  
+
 - **`tools/list`** - Returns all registered tools with their JSON Schema 2020-12 definitions
   - Returns array of tool definitions in MCP format
   - Each tool includes name, description, inputSchema, and optional icon
-  
+
 - **`tools/call`** - Executes a tool with provided arguments and returns the result
   - Validates tool arguments against JSON Schema 2020-12
   - Executes tool function
@@ -310,7 +332,7 @@ This enables the MCP-specified Content-Length header format, which some clients
 
 ### Limitations
 
-- **Transport**: Currently only stdio transport is supported. WebSocket and HTTP transports are not available.
+- **Transport**: stdio transport is fully supported. HTTP transport is available via Express adapter. WebSocket transport is not available.
 - **Protocol Version**: Only protocol version 2025-11-25 is supported. Older or newer versions will be rejected.
 - **Resources Subscribe/Unsubscribe**: Basic resource subscription is not yet implemented (resources/list and resources/read are supported)
 
@@ -330,10 +352,10 @@ EasyMCP provides comprehensive error handling with custom error classes and clea
 ### Error Handling Examples
 
 ```typescript
-import { 
-  EasyMCP, 
-  ConfigurationError, 
-  ToolExecutionError, 
+import {
+  EasyMCP,
+  ConfigurationError,
+  ToolExecutionError,
   ToolNotFoundError
 } from 'easy-mcp-nest';
 
@@ -438,6 +460,142 @@ Debug mode provides detailed information about:
 
 **Note**: The `DEBUG` environment variable accepts either `'1'` or `'true'` (case-sensitive) to enable debug logging.
 
+## New Features
+
+### Express Adapter
+
+Use EasyMCP in Express applications without requiring NestJS for the HTTP layer:
+
+```typescript
+import express from 'express';
+import { createMcpExpressRouter } from 'easy-mcp-nest';
+
+const app = express();
+app.use(express.json());
+
+const mcpRouter = createMcpExpressRouter({
+  tools: [BuildingTools, PaymentTools],
+  resources: [BuildingResources],
+  auth: mcpAuthMiddleware, // Optional
+});
+
+app.use('/mcp', mcpRouter);
+app.listen(3000);
+```
+
+### Context Injection
+
+Inject user context into tools using the `@McpContext()` decorator:
+
+```typescript
+import { McpContext, McpContextDecorator } from 'easy-mcp-nest';
+
+@McpTool({ name: 'create_building' })
+async createBuilding(
+  @McpParam() params: CreateBuildingDto,
+  @McpContextDecorator() context: McpContext
+) {
+  return this.service.createBuilding(context.userId, params);
+}
+```
+
+### Factory Pattern Support
+
+Use factory functions instead of dependency injection:
+
+```typescript
+import { McpService } from 'easy-mcp-nest';
+
+@McpTool({ name: 'create_building' })
+export class BuildingTools {
+  constructor(
+    @McpService(() => getBuildingService())
+    private buildingService: BuildingService
+  ) {}
+}
+```
+
+### OAuth Integration
+
+Standardize OAuth integration across MCP servers:
+
+```typescript
+import { createOAuthMiddleware, OAuthProviderConfig } from 'easy-mcp-nest';
+
+const oauthConfig: OAuthProviderConfig = {
+  provider: 'custom',
+  validateToken: async (token) => {
+    // Validate token and return payload
+    return jwt.verify(token, secret);
+  },
+  extractContext: (payload) => ({
+    userId: payload.sub,
+    scopes: payload.scopes,
+    buildingIds: payload.buildingIds,
+  }),
+};
+
+const oauthMiddleware = createOAuthMiddleware(oauthProviderService);
+app.use('/mcp', oauthMiddleware, mcpRouter);
+```
+
+### TypeScript-First Validation with Zod
+
+Use Zod schemas for type-safe validation:
+
+```typescript
+import { z } from 'zod';
+import { McpParam } from 'easy-mcp-nest';
+
+const CreateBuildingSchema = z.object({
+  name: z.string(),
+  address: z.string(),
+  floors: z.number().int().min(1).max(100),
+});
+
+@McpTool({ name: 'create_building' })
+async createBuilding(
+  @McpParam(CreateBuildingSchema) params: z.infer<typeof CreateBuildingSchema>
+) {
+  // params is fully typed and validated
+  return this.service.createBuilding(params);
+}
+```
+
+### Standalone Mode
+
+Use EasyMCP without NestJS:
+
+```typescript
+import { createMcpServer } from 'easy-mcp-nest';
+
+const server = createMcpServer({
+  tools: [BuildingTools, PaymentTools],
+  resources: [BuildingResources],
+  transport: 'http', // or 'stdio'
+  auth: validateMcpToken, // Optional
+  port: 3000,
+});
+
+await server.start();
+```
+
+### Testing Utilities
+
+Test MCP tools easily:
+
+```typescript
+import { createMcpTestApp, mockMcpContext } from 'easy-mcp-nest';
+
+const app = await createMcpTestApp([BuildingTools]);
+const context = mockMcpContext({
+  userId: '123',
+  scopes: ['read', 'write'],
+});
+const result = await app.callTool('create_building', params, context);
+await app.close();
+```
+
 ## Examples
 
 See the `examples/` directory for complete working examples.

package/dist/adapters/express/express-adapter.d.ts

@@ -0,0 +1,3 @@
+import { Router } from "express";
+import { CreateMcpExpressRouterOptions } from "./types";
+export declare function createMcpExpressRouter(options: CreateMcpExpressRouterOptions): Router;

package/dist/adapters/express/express-adapter.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMcpExpressRouter = createMcpExpressRouter;
+const express_1 = require("express");
+const constants_1 = require("../../config/constants");
+const EasyMCP_1 = require("../../EasyMCP");
+const http_gateway_service_1 = require("./http-gateway.service");
+const logger_util_1 = require("../../core/utils/logger.util");
+const sanitize_util_1 = require("../../core/utils/sanitize.util");
+const mcp_server_service_1 = require("../../core/mcp-server/mcp-server.service");
+const oauth_provider_service_1 = require("../../auth/oauth/oauth-provider.service");
+const oauth_middleware_1 = require("../../auth/oauth/oauth-middleware");
+function createMcpExpressRouter(options) {
+    const router = (0, express_1.Router)();
+    const pathPrefix = options.pathPrefix || "/mcp";
+    const tools = (options.tools || []).map((tool) => {
+        if (tool && typeof tool === "object" && "name" in tool && "function" in tool) {
+            return tool;
+        }
+        if (typeof tool === "function") {
+            throw new Error("Class-based tools are not directly supported in createMcpExpressRouter. Please convert them to ToolRegistrationInput format or register them via NestJS modules.");
+        }
+        throw new Error("Tools must be in ToolRegistrationInput format or a class constructor. Use the config-based or decorator-based approach.");
+    });
+    const config = {
+        tools,
+        resources: options.resources || [],
+        prompts: options.prompts || [],
+        serverInfo: options.serverInfo,
+    };
+    let mcpServerService = null;
+    let httpGateway = null;
+    const initPromise = (async () => {
+        await EasyMCP_1.EasyMCP.initialize(config);
+        const appContext = EasyMCP_1.EasyMCP.app;
+        mcpServerService = appContext.get(mcp_server_service_1.McpServerService);
+        httpGateway = new http_gateway_service_1.HttpGatewayService();
+        if (mcpServerService) {
+            httpGateway.setMcpServerService(mcpServerService);
+        }
+    })();
+    router.use(async (req, res, next) => {
+        try {
+            await initPromise;
+            next();
+        }
+        catch (error) {
+            logger_util_1.logger.error("ExpressAdapter", "Failed to initialize EasyMCP", {
+                error: (0, sanitize_util_1.sanitizeErrorMessage)(error),
+            });
+            res.status(500).json({
+                jsonrpc: "2.0",
+                id: null,
+                error: {
+                    code: -32603,
+                    message: "Internal error",
+                },
+            });
+        }
+    });
+    if (options.auth) {
+        router.use(options.auth);
+    }
+    else if (options.oauth) {
+        const oauthProvider = new oauth_provider_service_1.OAuthProviderService();
+        oauthProvider.setConfig(options.oauth);
+        router.use((0, oauth_middleware_1.createOAuthMiddleware)(oauthProvider));
+    }
+    const extractContext = (req) => {
+        if (req.mcpContext) {
+            return req.mcpContext;
+        }
+        if (options.auth || options.oauth) {
+            return undefined;
+        }
+        const context = {};
+        if (req.headers["x-user-id"]) {
+            context.userId = String(req.headers["x-user-id"]);
+        }
+        if (req.headers["x-scopes"]) {
+            const scopes = req.headers["x-scopes"];
+            context.scopes = Array.isArray(scopes)
+                ? scopes.map(String)
+                : String(scopes).split(",").map(s => s.trim());
+        }
+        if (req.headers["x-building-ids"]) {
+            const buildingIds = req.headers["x-building-ids"];
+            context.buildingIds = Array.isArray(buildingIds)
+                ? buildingIds.map(String)
+                : String(buildingIds).split(",").map(s => s.trim());
+        }
+        if (Object.keys(context).length > 0) {
+            logger_util_1.logger.warn("ExpressAdapter", "Using unauthenticated headers for context extraction", {
+                component: "ExpressAdapter",
+                warning: "Headers are not authenticated and can be spoofed. Use auth middleware in production.",
+            });
+            return context;
+        }
+        return undefined;
+    };
+    router.post("/", (0, express_1.json)({ limit: constants_1.MAX_MESSAGE_SIZE_BYTES }), async (req, res) => {
+        if (!httpGateway || !mcpServerService) {
+            res.status(500).json({
+                jsonrpc: "2.0",
+                id: null,
+                error: {
+                    code: -32603,
+                    message: "Internal error",
+                },
+            });
+            return;
+        }
+        const context = extractContext(req);
+        await httpGateway.handleHttpRequest(req, res, context);
+    });
+    router.get(`${pathPrefix}/health`, (req, res) => {
+        res.json({
+            status: "ok",
+            service: "mcp-server",
+            version: config.serverInfo?.version || "unknown",
+        });
+    });
+    return router;
+}
+//# sourceMappingURL=express-adapter.js.map

package/dist/adapters/express/express-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express-adapter.js","sourceRoot":"","sources":["../../../src/adapters/express/express-adapter.ts"],"names":[],"mappings":";;AAsCA,wDA2JC;AAjMD,qCAA0D;AAC1D,sDAAgE;AAIhE,2CAAwC;AAExC,iEAA4D;AAI5D,8DAAsD;AACtD,kEAAsE;AACtE,iFAA4E;AAC5E,oFAA+E;AAC/E,wEAA0E;AAuB1E,SAAgB,sBAAsB,CACpC,OAAsC;IAEtC,MAAM,MAAM,GAAG,IAAA,gBAAM,GAAE,CAAC;IACxB,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,MAAM,CAAC;IAGhD,MAAM,KAAK,GAA4B,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAExE,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,MAAM,IAAI,IAAI,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;YAC7E,OAAO,IAA6B,CAAC;QACvC,CAAC;QAID,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,kKAAkK,CAAC,CAAC;QACtL,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,yHAAyH,CAAC,CAAC;IAC7I,CAAC,CAAC,CAAC;IAGH,MAAM,MAAM,GAAc;QACxB,KAAK;QACL,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE;QAClC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE;QAC9B,UAAU,EAAE,OAAO,CAAC,UAAU;KAC/B,CAAC;IAGF,IAAI,gBAAgB,GAA4B,IAAI,CAAC;IACrD,IAAI,WAAW,GAA8B,IAAI,CAAC;IAElD,MAAM,WAAW,GAAG,CAAC,KAAK,IAAI,EAAE;QAC9B,MAAM,iBAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,UAAU,GAAI,iBAAe,CAAC,GAA8B,CAAC;QAGnE,gBAAgB,GAAG,UAAU,CAAC,GAAG,CAAC,qCAAgB,CAAC,CAAC;QAGpD,WAAW,GAAG,IAAI,yCAAkB,EAAE,CAAC;QACvC,IAAI,gBAAgB,EAAE,CAAC;YACrB,WAAW,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;QACpD,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IAGL,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,IAAI,EAAE,EAAE;QACrD,IAAI,CAAC;YACH,MAAM,WAAW,CAAC;YAClB,IAAI,EAAE,CAAC;QACT,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,oBAAM,CAAC,KAAK,CAAC,gBAAgB,EAAE,8BAA8B,EAAE;gBAC7D,KAAK,EAAE,IAAA,oCAAoB,EAAC,KAAK,CAAC;aACnC,CAAC,CAAC;YACH,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACnB,OAAO,EAAE,KAAK;gBACd,EAAE,EAAE,IAAI;gBACR,KAAK,EAAE;oBACL,IAAI,EAAE,CAAC,KAAK;oBACZ,OAAO,EAAE,gBAAgB;iBAC1B;aACF,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IAGH,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;SAAM,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAEzB,MAAM,aAAa,GAAG,IAAI,6CAAoB,EAAE,CAAC;QACjD,aAAa,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvC,MAAM,CAAC,GAAG,CAAC,IAAA,wCAAqB,EAAC,aAAa,CAAC,CAAC,CAAC;IACnD,CAAC;IAKD,MAAM,cAAc,GAAG,CAAC,GAAY,EAA0B,EAAE;QAE9D,IAAK,GAAW,CAAC,UAAU,EAAE,CAAC;YAC5B,OAAQ,GAAW,CAAC,UAAwB,CAAC;QAC/C,CAAC;QAID,IAAI,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClC,OAAO,SAAS,CAAC;QACnB,CAAC;QAMD,MAAM,OAAO,GAAwB,EAAE,CAAC;QACxC,IAAI,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;YAC7B,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;YACvC,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;gBACpC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;gBACpB,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACnD,CAAC;QACD,IAAI,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC;YAClC,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;YAClD,OAAO,CAAC,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC;gBAC9C,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC;gBACzB,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAEpC,oBAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,sDAAsD,EAAE;gBACpF,SAAS,EAAE,gBAAgB;gBAC3B,OAAO,EAAE,sFAAsF;aAChG,CAAC,CAAC;YACH,OAAO,OAAqB,CAAC;QAC/B,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IAIF,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,IAAA,cAAI,EAAC,EAAE,KAAK,EAAE,kCAAsB,EAAE,CAAC,EAAE,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;QAC9F,IAAI,CAAC,WAAW,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACtC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACnB,OAAO,EAAE,KAAK;gBACd,EAAE,EAAE,IAAI;gBACR,KAAK,EAAE;oBACL,IAAI,EAAE,CAAC,KAAK;oBACZ,OAAO,EAAE,gBAAgB;iBAC1B;aACF,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;QACpC,MAAM,WAAW,CAAC,iBAAiB,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAGH,MAAM,CAAC,GAAG,CAAC,GAAG,UAAU,SAAS,EAAE,CAAC,GAAY,EAAE,GAAa,EAAE,EAAE;QACjE,GAAG,CAAC,IAAI,CAAC;YACP,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,YAAY;YACrB,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,IAAI,SAAS;SACjD,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/adapters/express/http-gateway.service.d.ts

@@ -0,0 +1,13 @@
+import { Request, Response } from "express";
+import { IInterfaceLayer } from "../../interface/interface.interface";
+import { McpServerService } from "../../core/mcp-server/mcp-server.service";
+import { McpContext } from "../../core/context/mcp-context.interface";
+export declare class HttpGatewayService implements IInterfaceLayer {
+    private mcpServerService;
+    private requestContextMap;
+    constructor();
+    setMcpServerService(service: McpServerService): void;
+    start(): Promise<void>;
+    sendMessage(sessionId: string, output: unknown): Promise<void>;
+    handleHttpRequest(req: Request, res: Response, context?: McpContext): Promise<void>;
+}

package/dist/adapters/express/http-gateway.service.js

@@ -0,0 +1,102 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpGatewayService = void 0;
+const common_1 = require("@nestjs/common");
+const jsonrpc_interface_1 = require("../../interface/jsonrpc.interface");
+const logger_util_1 = require("../../core/utils/logger.util");
+const sanitize_util_1 = require("../../core/utils/sanitize.util");
+const constants_1 = require("../../config/constants");
+let HttpGatewayService = class HttpGatewayService {
+    mcpServerService;
+    requestContextMap = new Map();
+    constructor() {
+        logger_util_1.logger.info("HttpGatewayService", "HttpGatewayService initialized", {
+            component: "Layer 1: HTTP Interface",
+        });
+    }
+    setMcpServerService(service) {
+        this.mcpServerService = service;
+    }
+    async start() {
+        logger_util_1.logger.info("HttpGatewayService", "HTTP gateway ready (handled by Express)", {
+            component: "Layer 1: HTTP Interface",
+        });
+    }
+    async sendMessage(sessionId, output) {
+        logger_util_1.logger.debug("HttpGatewayService", "sendMessage called", {
+            component: "Layer 1: HTTP Interface",
+            sessionId,
+        });
+    }
+    async handleHttpRequest(req, res, context) {
+        const requestId = req.headers["x-request-id"] || String(Date.now());
+        if (context) {
+            this.requestContextMap.set(String(requestId), context);
+        }
+        try {
+            const contentLength = req.get("content-length");
+            if (contentLength && parseInt(contentLength, 10) > constants_1.MAX_MESSAGE_SIZE_BYTES) {
+                const errorResponse = (0, jsonrpc_interface_1.createJsonRpcError)(null, jsonrpc_interface_1.JsonRpcErrorCode.InvalidRequest, "Request body too large");
+                res.status(413).json(errorResponse);
+                return;
+            }
+            const body = req.body;
+            if (!body || typeof body !== "object") {
+                const errorResponse = (0, jsonrpc_interface_1.createJsonRpcError)(null, jsonrpc_interface_1.JsonRpcErrorCode.InvalidRequest, "Request body must be a valid JSON-RPC request");
+                res.status(400).json(errorResponse);
+                return;
+            }
+            if (!(0, jsonrpc_interface_1.isValidJsonRpcRequest)(body)) {
+                const errorResponse = (0, jsonrpc_interface_1.createJsonRpcError)(body.id || null, jsonrpc_interface_1.JsonRpcErrorCode.InvalidRequest, "Invalid JSON-RPC request structure");
+                res.status(400).json(errorResponse);
+                return;
+            }
+            const request = {
+                ...body,
+                metadata: context ? {
+                    userId: context.userId,
+                    scopes: context.scopes,
+                    buildingIds: context.buildingIds,
+                    sessionId: context.sessionId || String(requestId),
+                    metadata: {
+                        ip: req.ip || req.socket.remoteAddress,
+                        userAgent: req.get("user-agent"),
+                    },
+                } : undefined,
+            };
+            if (!this.mcpServerService) {
+                const errorResponse = (0, jsonrpc_interface_1.createJsonRpcError)(request.id, jsonrpc_interface_1.JsonRpcErrorCode.InternalError, "McpServerService not initialized");
+                res.status(500).json(errorResponse);
+                return;
+            }
+            const response = await this.mcpServerService.handleRequest(request);
+            res.status(200).json(response);
+        }
+        catch (error) {
+            logger_util_1.logger.error("HttpGatewayService", "Error handling HTTP request", {
+                component: "Layer 1: HTTP Interface",
+                error: (0, sanitize_util_1.sanitizeErrorMessage)(error),
+            });
+            const errorResponse = (0, jsonrpc_interface_1.createJsonRpcError)(req.body?.id || null, jsonrpc_interface_1.JsonRpcErrorCode.InternalError, "Internal error during request handling");
+            res.status(500).json(errorResponse);
+        }
+        finally {
+            this.requestContextMap.delete(String(requestId));
+        }
+    }
+};
+exports.HttpGatewayService = HttpGatewayService;
+exports.HttpGatewayService = HttpGatewayService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [])
+], HttpGatewayService);
+//# sourceMappingURL=http-gateway.service.js.map

package/dist/adapters/express/http-gateway.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-gateway.service.js","sourceRoot":"","sources":["../../../src/adapters/express/http-gateway.service.ts"],"names":[],"mappings":"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"}

package/dist/adapters/express/index.d.ts

@@ -0,0 +1,3 @@
+export { createMcpExpressRouter } from "./express-adapter";
+export type { CreateMcpExpressRouterOptions, McpAuthMiddleware } from "./types";
+export { HttpGatewayService } from "./http-gateway.service";

package/dist/adapters/express/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpGatewayService = exports.createMcpExpressRouter = void 0;
+var express_adapter_1 = require("./express-adapter");
+Object.defineProperty(exports, "createMcpExpressRouter", { enumerable: true, get: function () { return express_adapter_1.createMcpExpressRouter; } });
+var http_gateway_service_1 = require("./http-gateway.service");
+Object.defineProperty(exports, "HttpGatewayService", { enumerable: true, get: function () { return http_gateway_service_1.HttpGatewayService; } });
+//# sourceMappingURL=index.js.map

package/dist/adapters/express/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/express/index.ts"],"names":[],"mappings":";;;AAAA,qDAA2D;AAAlD,yHAAA,sBAAsB,OAAA;AAE/B,+DAA4D;AAAnD,0HAAA,kBAAkB,OAAA"}

package/dist/adapters/express/types.d.ts

@@ -0,0 +1,15 @@
+import { Request, Response, NextFunction } from "express";
+import { OAuthProviderConfig } from "../../auth/oauth/oauth-config.interface";
+export type McpAuthMiddleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+export interface CreateMcpExpressRouterOptions {
+    tools?: any[];
+    resources?: any[];
+    prompts?: any[];
+    auth?: McpAuthMiddleware;
+    oauth?: OAuthProviderConfig;
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+    pathPrefix?: string;
+}

package/dist/adapters/express/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/adapters/express/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/express/types.ts"],"names":[],"mappings":""}

package/dist/app.module.js

@@ -15,6 +15,7 @@ const constants_1 = require("./config/constants");
 const interface_module_1 = require("./interface/interface.module");
 const resource_module_1 = require("./resources/resource.module");
 const prompt_module_1 = require("./prompts/prompt.module");
+const context_provider_service_1 = require("./core/context/context-provider.service");
 let AppModule = class AppModule {
 };
 exports.AppModule = AppModule;
@@ -25,6 +26,7 @@ exports.AppModule = AppModule = __decorate([
             mcp_server_service_1.McpServerService,
             tool_registry_service_1.ToolRegistryService,
             config_holder_service_1.ConfigHolderService,
+            context_provider_service_1.ContextProviderService,
             {
                 provide: constants_1.CONFIG_TOKEN,
                 useExisting: config_holder_service_1.ConfigHolderService,

package/dist/app.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.module.js","sourceRoot":"","sources":["../src/app.module.ts"],"names":[],"mappings":";;;;;;;;;AAEA,2CAAwC;AACxC,6EAAwE;AACxE,yFAAoF;AACpF,0EAAqE;AACrE,kDAAkD;AAClD,mEAA+D;AAC/D,iEAA6D;AAC7D,2DAAuD;AAsBhD,IAAM,SAAS,GAAf,MAAM,SAAS;CAAG,CAAA;AAAZ,8BAAS;oBAAT,SAAS;IAhBrB,IAAA,eAAM,EAAC;QACN,OAAO,EAAE,CAAC,kCAAe,EAAE,gCAAc,EAAE,4BAAY,CAAC;QACxD,SAAS,EAAE;YAET,qCAAgB;YAEhB,2CAAmB;YACnB,2CAAmB;YAEnB;gBACE,OAAO,EAAE,wBAAY;gBACrB,WAAW,EAAE,2CAAmB;aACjC;SACF;QACD,OAAO,EAAE,CAAC,qCAAgB,CAAC;KAC5B,CAAC;GACW,SAAS,CAAG"}
+{"version":3,"file":"app.module.js","sourceRoot":"","sources":["../src/app.module.ts"],"names":[],"mappings":";;;;;;;;;AAEA,2CAAwC;AACxC,6EAAwE;AACxE,yFAAoF;AACpF,0EAAqE;AACrE,kDAAkD;AAClD,mEAA+D;AAC/D,iEAA6D;AAC7D,2DAAuD;AACvD,sFAAiF;AAwB1E,IAAM,SAAS,GAAf,MAAM,SAAS;CAAG,CAAA;AAAZ,8BAAS;oBAAT,SAAS;IAlBrB,IAAA,eAAM,EAAC;QACN,OAAO,EAAE,CAAC,kCAAe,EAAE,gCAAc,EAAE,4BAAY,CAAC;QACxD,SAAS,EAAE;YAET,qCAAgB;YAEhB,2CAAmB;YACnB,2CAAmB;YAEnB,iDAAsB;YAEtB;gBACE,OAAO,EAAE,wBAAY;gBACrB,WAAW,EAAE,2CAAmB;aACjC;SACF;QACD,OAAO,EAAE,CAAC,qCAAgB,CAAC;KAC5B,CAAC;GACW,SAAS,CAAG"}

package/dist/auth/oauth/index.d.ts

@@ -0,0 +1,3 @@
+export { OAuthProviderService } from "./oauth-provider.service";
+export { createOAuthMiddleware } from "./oauth-middleware";
+export type { OAuthProviderConfig, OAuthConfig, OAuthTokenValidator, OAuthContextExtractor, } from "./oauth-config.interface";

package/dist/auth/oauth/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOAuthMiddleware = exports.OAuthProviderService = void 0;
+var oauth_provider_service_1 = require("./oauth-provider.service");
+Object.defineProperty(exports, "OAuthProviderService", { enumerable: true, get: function () { return oauth_provider_service_1.OAuthProviderService; } });
+var oauth_middleware_1 = require("./oauth-middleware");
+Object.defineProperty(exports, "createOAuthMiddleware", { enumerable: true, get: function () { return oauth_middleware_1.createOAuthMiddleware; } });
+//# sourceMappingURL=index.js.map

package/dist/auth/oauth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/auth/oauth/index.ts"],"names":[],"mappings":";;;AAAA,mEAAgE;AAAvD,8HAAA,oBAAoB,OAAA;AAC7B,uDAA2D;AAAlD,yHAAA,qBAAqB,OAAA"}

package/dist/auth/oauth/oauth-config.interface.d.ts

@@ -0,0 +1,12 @@
+import { McpContext } from "../../core/context/mcp-context.interface";
+export type OAuthTokenValidator = (token: string) => Promise<any> | any;
+export type OAuthContextExtractor = (payload: any) => McpContext;
+export interface OAuthProviderConfig {
+    provider: string;
+    validateToken: OAuthTokenValidator;
+    extractContext: OAuthContextExtractor;
+    extractToken?: (req: any) => string | null;
+}
+export interface OAuthConfig {
+    oauth: OAuthProviderConfig;
+}

package/dist/auth/oauth/oauth-config.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=oauth-config.interface.js.map

package/dist/auth/oauth/oauth-config.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-config.interface.js","sourceRoot":"","sources":["../../../src/auth/oauth/oauth-config.interface.ts"],"names":[],"mappings":""}

package/dist/auth/oauth/oauth-middleware.d.ts

@@ -0,0 +1,3 @@
+import { Request, Response, NextFunction } from "express";
+import { OAuthProviderService } from "./oauth-provider.service";
+export declare function createOAuthMiddleware(oauthProvider: OAuthProviderService): (req: Request, res: Response, next: NextFunction) => Promise<void>;

package/dist/auth/oauth/oauth-middleware.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOAuthMiddleware = createOAuthMiddleware;
+const logger_util_1 = require("../../core/utils/logger.util");
+const sanitize_util_1 = require("../../core/utils/sanitize.util");
+function createOAuthMiddleware(oauthProvider) {
+    return async (req, res, next) => {
+        const requestId = req.headers["x-request-id"] || req.body?.id || null;
+        const clientIp = req.ip || req.socket.remoteAddress || "unknown";
+        try {
+            const token = oauthProvider.extractTokenFromRequest(req);
+            if (!token) {
+                logger_util_1.logger.audit("OAuthMiddleware", "oauth/authenticate", "failure", {
+                    reason: "No token provided",
+                    clientIp,
+                }, requestId, clientIp);
+                res.status(401).json({
+                    jsonrpc: "2.0",
+                    id: null,
+                    error: {
+                        code: -32000,
+                        message: "Unauthorized: No token provided",
+                    },
+                });
+                return;
+            }
+            const context = await oauthProvider.validateAndExtractContext(token);
+            const actorId = (0, sanitize_util_1.sanitizeActorId)(context.sessionId || context.userId || undefined);
+            logger_util_1.logger.audit("OAuthMiddleware", "oauth/authenticate", "success", {
+                clientIp,
+            }, requestId, actorId);
+            req.mcpContext = context;
+            next();
+        }
+        catch (error) {
+            logger_util_1.logger.error("OAuthMiddleware", "Token validation failed", {
+                error: (0, sanitize_util_1.sanitizeErrorMessage)(error),
+            });
+            logger_util_1.logger.audit("OAuthMiddleware", "oauth/authenticate", "failure", {
+                reason: "Token validation failed",
+                clientIp,
+            }, requestId, clientIp);
+            res.status(401).json({
+                jsonrpc: "2.0",
+                id: null,
+                error: {
+                    code: -32000,
+                    message: "Unauthorized: Invalid token",
+                },
+            });
+        }
+    };
+}
+//# sourceMappingURL=oauth-middleware.js.map