@rekog/mcp-nest 1.9.10 → 2.0.0-alpha.0

package/src/mcp/transport/mcp-server-options.interface.ts

@@ -0,0 +1,75 @@
+import { Icon, ServerCapabilities } from '@modelcontextprotocol/sdk/types.js';
+import { HttpServer } from '@nestjs/common';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpTransport } from './mcp-transport.interface';
+
+/**
+ * Configuration for an {@link McpStrategy} — the NestJS microservice transport
+ * strategy that powers an MCP server. Pass an instance to
+ * `app.connectMicroservice({ strategy: new McpStrategy(options) })`, set the HTTP
+ * adapter for HTTP transports, and declare your `@McpController` classes in a
+ * module's `controllers` array. No `McpModule` is required.
+ */
+export interface McpServerOptions {
+  /** Server name (MCP `Implementation.name`). */
+  name: string;
+  /** Server version (MCP `Implementation.version`). */
+  version: string;
+  /**
+   * Logical server name used for multi-server isolation. Only
+   * `@McpController({ server: <name> })` classes bind to this strategy. Omit for
+   * the default server (binds to plain `@McpController()` classes).
+   */
+  server?: string;
+  /** Human-readable display name. */
+  title?: string;
+  /** Short description of what this server does. */
+  description?: string;
+  /** URL of the website associated with this server. */
+  websiteUrl?: string;
+  /** Icons representing this server. */
+  icons?: Icon[];
+  /** Extra MCP server capabilities merged with the auto-derived ones. */
+  capabilities?: ServerCapabilities;
+  /** Server instructions sent to clients on initialize. */
+  instructions?: string;
+  /** Mutate the SDK server right after creation (instrumentation, etc.). */
+  serverMutator?: (server: McpServer) => McpServer;
+
+  /**
+   * The integrations this server exposes. Provide one entry per transport,
+   * e.g. `[new StreamableHttpTransport(), new StdioTransport()]`.
+   */
+  transports: McpTransport[];
+
+  /**
+   * The Nest HTTP adapter, required for HTTP-based transports. Either pass it
+   * here (`new McpStrategy({ ..., httpAdapter: app.getHttpAdapter() })`) or set
+   * it later via `strategy.setHttpAdapter(app.getHttpAdapter())`. Not needed for
+   * stdio-only servers.
+   */
+  httpAdapter?: HttpServer;
+
+  /**
+   * Freemium mode. When `true`, anonymous (unauthenticated) sessions may reach
+   * `@PublicTool()` tools, while every other tool still requires a resolved
+   * `req.user`. When `false` (default), per-tool listing/visibility trusts the
+   * server's own authentication — `@UseGuards()` on `@McpController` classes or
+   * methods (run by the NestJS RPC pipeline at call time) and/or auth middleware
+   * on the HTTP routes.
+   *
+   * @default false
+   */
+  allowUnauthenticatedAccess?: boolean;
+  /**
+   * Logging configuration.
+   * - `false` to disable MCP logging
+   * - `{ level: [...] }` to filter levels
+   * - `undefined` (default) for standard NestJS logging
+   */
+  logging?:
+    | false
+    | {
+        level: ('log' | 'error' | 'warn' | 'debug' | 'verbose')[];
+      };
+}

package/src/mcp/transport/mcp-transport.constants.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared transport identifier for the MCP microservice strategy.
+ *
+ * Both the MCP capability decorators (`@Tool`, `@Resource`, `@ResourceTemplate`,
+ * `@Prompt`) and the {@link McpStrategy} reference this exact symbol. NestJS
+ * binds a `@MessagePattern` handler to a strategy only when the handler's
+ * declared transport is undefined OR equals the strategy's `transportId`
+ * (see `@nestjs/microservices` ListenersController). By tagging MCP handlers
+ * with this symbol and setting it as the strategy's `transportId` we get mutual
+ * exclusion: other microservice transports never bind MCP handlers, and the MCP
+ * strategy prunes any stray non-MCP handler that matched via the undefined-transport
+ * clause.
+ *
+ * Uses the global symbol registry (`Symbol.for`) so it stays stable even if the
+ * package is duplicated across `node_modules`.
+ */
+export const MCP_TRANSPORT = Symbol.for('@rekog/mcp-nest:transport');
+
+/**
+ * Transport id for a *named* MCP server, falling back to the default shared id
+ * ({@link MCP_TRANSPORT}) when no name is given.
+ *
+ * Naming a server gives it its own transport id, so NestJS's existing
+ * `transport === transportId` routing isolates each server's handlers natively:
+ * only `@McpController({ server: <name> })` classes bind to the matching
+ * `McpStrategy({ server: <name> })`. An unnamed controller + unnamed strategy
+ * keep using {@link MCP_TRANSPORT} — i.e. the original single-server behavior.
+ *
+ * Uses the global symbol registry (`Symbol.for`) so the id stays stable even if
+ * the package is duplicated across `node_modules`.
+ */
+export const mcpTransportFor = (server?: string): symbol =>
+  server ? Symbol.for(`@rekog/mcp-nest:transport:${server}`) : MCP_TRANSPORT;
+
+/**
+ * Class-metadata key recording the logical server name an `@McpController` was
+ * assigned to (via `@McpController({ server })`). Kept for diagnostics; the
+ * actual routing is driven by the per-method transport id, not this key.
+ */
+export const MCP_SERVER_NAME_METADATA_KEY = 'mcp:server-name';
+
+export type McpCapabilityType =
+  | 'tool'
+  | 'resource'
+  | 'resource-template'
+  | 'prompt';
+
+/**
+ * Structured message pattern stored for every MCP capability handler. NestJS
+ * normalizes object patterns by sorting keys and JSON-stringifying them, so the
+ * strategy can deterministically rebuild a route from a discovered capability
+ * name and look the handler up via `getHandlerByPattern`.
+ */
+export interface McpPattern {
+  mcp: McpCapabilityType;
+  name: string;
+  // Index signature keeps the pattern assignable to NestJS's MsObjectPattern.
+  [key: string]: string;
+}
+
+/**
+ * Routing + metadata identity carried in the bound handler's `extras`.
+ *
+ * `mcpMethodRef` is the original decorated method (`descriptor.value`). NestJS
+ * stores `extras` by reference on the handler, so at `listen()` time — after ALL
+ * decorators on that method have run — the strategy reads every metadata key off
+ * `mcpMethodRef` directly (`@Tool` options + `@ToolScopes`/`@ToolRoles`/etc.),
+ * with no DI discovery service.
+ */
+/** A decorated capability method reference (used to read its metadata at bind time). */
+export type McpMethodRef = (...args: any[]) => any;
+
+export interface McpHandlerExtras {
+  mcpType: McpCapabilityType;
+  mcpName: string;
+  mcpMethodKey: string;
+  mcpMethodRef: McpMethodRef;
+}
+
+export function buildMcpPattern(
+  type: McpCapabilityType,
+  name: string,
+): McpPattern {
+  return { mcp: type, name };
+}
+
+export function buildMcpHandlerExtras(
+  type: McpCapabilityType,
+  name: string,
+  methodKey: string,
+  methodRef: McpMethodRef,
+): McpHandlerExtras {
+  return {
+    mcpType: type,
+    mcpName: name,
+    mcpMethodKey: methodKey,
+    mcpMethodRef: methodRef,
+  };
+}

package/src/mcp/transport/mcp-transport.interface.ts

@@ -0,0 +1,50 @@
+import { HttpServer, Logger } from '@nestjs/common';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServerOptions } from './mcp-server-options.interface';
+import { McpSessionInfo, McpTransportKind } from './mcp-context';
+
+/**
+ * The surface a transport receives from the {@link McpStrategy} when it starts.
+ * Transports own the wire protocol; the strategy owns capability discovery,
+ * the MCP request handlers, and routing into the NestJS RPC pipeline.
+ */
+export interface McpTransportContext {
+  /**
+   * Create a bare SDK `McpServer` (capabilities derived from discovery + any
+   * `serverMutator` applied). The caller is responsible for connecting it to an
+   * SDK transport and for calling {@link bindRequestHandlers}.
+   */
+  createServer(): McpServer;
+
+  /**
+   * (Re)register the MCP request handlers (tools/resources/prompts) on a server,
+   * bound to a specific incoming request. Call this per request for session-aware
+   * transports so the per-request `rawRequest` (auth context) is current.
+   */
+  bindRequestHandlers(
+    server: McpServer,
+    session: Pick<McpSessionInfo, 'transport' | 'stateless' | 'sessionId'>,
+    rawRequest?: unknown,
+  ): void;
+
+  /** The Nest HTTP adapter. Present whenever an HTTP-based transport is used. */
+  httpAdapter?: HttpServer;
+
+  /** The resolved strategy options. */
+  options: McpServerOptions;
+
+  /** A logger scoped to the MCP server. */
+  logger: Logger;
+}
+
+/**
+ * A single MCP integration (stdio or streamable-HTTP). Implementations
+ * are plain objects the user constructs and passes via {@link McpServerOptions.transports}.
+ */
+export interface McpTransport {
+  readonly kind: McpTransportKind;
+  /** Called once from {@link McpStrategy.listen}. */
+  start(ctx: McpTransportContext): Promise<void> | void;
+  /** Called from {@link McpStrategy.close}. */
+  close(): Promise<void> | void;
+}