@forinda/kickjs-mcp 2.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Felix Orinda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @forinda/kickjs-mcp
+
+[Model Context Protocol](https://modelcontextprotocol.io) server adapter for KickJS. Expose `@Controller` endpoints as callable MCP tools for Claude Code, Cursor, Zed, and other MCP-aware clients — with zero duplicated schemas.
+
+## Status
+
+**v0 — skeleton.** The decorator and adapter surface exist and compile against the framework. The tool-discovery scan and MCP SDK wiring are still TODOs inside the adapter's lifecycle hooks. This package is part of Workstream 1 of the v3 AI plan and will reach v1 when:
+
+- [ ] Tool discovery scans every `@Controller` registered in the DI container
+- [ ] Zod body schemas are converted to JSON Schema via the shared Swagger converter
+- [ ] `stdio`, `sse`, and `http` transports are wired to `@modelcontextprotocol/sdk`
+- [ ] The `kick mcp` CLI command starts a standalone MCP server
+- [ ] Integration test: start a KickJS app, connect an MCP client, call a tool
+- [ ] Example app in `examples/mcp-server-api/`
+
+## Install
+
+```bash
+pnpm add @forinda/kickjs-mcp @modelcontextprotocol/sdk
+```
+
+## Usage (planned)
+
+```ts
+import { bootstrap } from '@forinda/kickjs'
+import { McpAdapter } from '@forinda/kickjs-mcp'
+import { modules } from './modules'
+
+export const app = await bootstrap({
+  modules,
+  adapters: [
+    new McpAdapter({
+      name: 'task-api',
+      version: '1.0.0',
+      description: 'Task management MCP server',
+      mode: 'explicit', // only @McpTool-decorated methods
+      transport: 'sse',
+    }),
+  ],
+})
+```
+
+Mark controller methods with `@McpTool` to expose them:
+
+```ts
+import { Controller, Post, type Ctx } from '@forinda/kickjs'
+import { McpTool } from '@forinda/kickjs-mcp'
+import { createTaskSchema } from './dtos/create-task.dto'
+
+@Controller('/tasks')
+export class TaskController {
+  @Post('/', { body: createTaskSchema, name: 'CreateTask' })
+  @McpTool({
+    description: 'Create a new task with title, priority, and optional assignee',
+    examples: [
+      { args: { title: 'Ship v3', priority: 'high' } },
+    ],
+  })
+  create(ctx: Ctx<KickRoutes.TaskController['create']>) {
+    return this.createTaskUseCase.execute(ctx.body)
+  }
+}
+```
+
+The input schema of each tool is derived automatically from the route's Zod `body` schema. Add a field, and both OpenAPI (via the Swagger adapter) and MCP pick it up on the next restart — no duplicated type declarations.
+
+## Exposure modes
+
+| Mode | Behavior |
+|------|----------|
+| `explicit` (default) | Only methods decorated with `@McpTool` are exposed. |
+| `auto` | Every route is exposed, subject to `include` / `exclude` filters. |
+
+Use `explicit` in production unless you've carefully reviewed every route. `auto` is convenient during development but can leak admin or internal endpoints if you forget to filter them out.
+
+## Transports
+
+| Transport | Use case |
+|-----------|----------|
+| `stdio` | CLI MCP clients (Claude Code, Cursor). Run via `kick mcp` in a separate process. |
+| `sse` | Mounted on the existing Express app. Default for long-running servers. |
+| `http` | Simpler than SSE; gives up live notifications. |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,461 @@
+
+import { AdapterContext, AppAdapter, Constructor } from "@forinda/kickjs";
+import { ZodTypeAny } from "zod";
+
+//#region src/types.d.ts
+/**
+ * Transport modes supported by the MCP adapter.
+ *
+ * - `stdio` — standard MCP transport for CLI clients (Claude Code, Cursor).
+ *   The MCP server owns stdin/stdout. Cannot be combined with a normal
+ *   Express dev server in the same process without care.
+ * - `sse` — Server-Sent Events over HTTP. Good fit when KickJS already
+ *   exposes an HTTP server — the MCP endpoints mount on the same app.
+ * - `http` — plain HTTP POST/GET streaming. Simpler than SSE for some
+ *   clients but gives up live notifications.
+ */
+type McpTransport = 'stdio' | 'sse' | 'http';
+/**
+ * How the adapter decides which endpoints become MCP tools.
+ *
+ * - `explicit` (default) — only methods decorated with `@McpTool` are
+ *   exposed. Safest default; prevents accidental exposure of internal
+ *   endpoints or admin routes.
+ * - `auto` — every route discovered at startup becomes a tool, subject
+ *   to the `include` / `exclude` filters. Use with care in production.
+ */
+type McpExposureMode = 'explicit' | 'auto';
+/**
+ * Authentication configuration for the MCP transport.
+ *
+ * For `stdio`, auth is usually not needed (client and server share a
+ * process). For `sse` and `http`, set this so the adapter refuses
+ * unauthenticated tool calls.
+ */
+interface McpAuthOptions {
+  /** Strategy to use. `bearer` reads `Authorization: Bearer <token>`. */
+  type: 'bearer' | 'custom';
+  /** Called on every tool invocation. Return true (or truthy data) to allow. */
+  validate: (token: string) => boolean | Promise<boolean>;
+}
+/**
+ * Options for the `McpAdapter` constructor.
+ *
+ * @example
+ * ```ts
+ * new McpAdapter({
+ *   name: 'task-api',
+ *   version: '1.0.0',
+ *   description: 'Task management MCP server',
+ *   mode: 'explicit',
+ *   transport: 'sse',
+ * })
+ * ```
+ */
+interface McpAdapterOptions {
+  /** MCP server name advertised to clients. Usually matches package.json name. */
+  name: string;
+  /** Server version advertised to clients. Defaults to '0.0.0' if omitted. */
+  version?: string;
+  /** Human-readable description shown in MCP client UIs. */
+  description?: string;
+  /** Exposure mode. Defaults to `'explicit'`. */
+  mode?: McpExposureMode;
+  /** Transport mode. Defaults to `'sse'`. */
+  transport?: McpTransport;
+  /** HTTP methods to include when `mode === 'auto'`. */
+  include?: Array<'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'>;
+  /** Glob-style path prefixes to exclude when `mode === 'auto'`. */
+  exclude?: string[];
+  /** Auth config for `sse` and `http` transports. */
+  auth?: McpAuthOptions;
+  /** Base path for the MCP endpoint (SSE/HTTP only). Defaults to `/_mcp`. */
+  basePath?: string;
+}
+/**
+ * Example input/output pair shown alongside a tool description.
+ *
+ * Models can use examples to learn the expected shape of arguments and
+ * what a successful call returns. Keep examples small and representative.
+ */
+interface McpToolExample {
+  /** Natural-language description of what this example does. */
+  description?: string;
+  /** Arguments to pass to the tool. Must match the Zod input schema. */
+  args: Record<string, unknown>;
+  /** Expected result shape. Used in docs only — not validated. */
+  result?: unknown;
+}
+/**
+ * Options for the `@McpTool` decorator.
+ *
+ * @example
+ * ```ts
+ * @Post('/', { body: createTaskSchema, name: 'CreateTask' })
+ * @McpTool({
+ *   description: 'Create a new task',
+ *   examples: [{ args: { title: 'Ship v3', priority: 'high' } }],
+ * })
+ * create(ctx: Ctx<KickRoutes.TaskController['create']>) {}
+ * ```
+ */
+interface McpToolOptions {
+  /**
+   * Override the tool name. Defaults to `<ControllerName>.<methodName>`.
+   * Tool names must be unique across the entire MCP server.
+   */
+  name?: string;
+  /**
+   * Human-readable description of what the tool does. Shown to the LLM
+   * when it decides whether to call this tool. Be specific: "Create a
+   * task" is less useful than "Create a new task with the given title,
+   * priority, and optional assignee".
+   */
+  description: string;
+  /**
+   * Optional input schema override. If omitted, the adapter derives
+   * the input schema from the route's `body` Zod schema (if any).
+   */
+  inputSchema?: ZodTypeAny;
+  /**
+   * Optional output schema for documentation. Not validated at runtime.
+   */
+  outputSchema?: ZodTypeAny;
+  /** Optional usage examples shown in the tool description. */
+  examples?: McpToolExample[];
+  /**
+   * When set to `true`, exclude this tool from any `auto` exposure mode
+   * filter. Useful to mark admin-only routes inside otherwise-exposed
+   * controllers.
+   */
+  hidden?: boolean;
+}
+/**
+ * Resolved tool definition after scanning decorators at startup.
+ *
+ * This is the shape the adapter hands to the MCP SDK when registering
+ * tools. Users don't construct this directly — it's derived from
+ * `@McpTool` metadata plus route metadata from `@Controller`.
+ *
+ * Both the raw Zod schema (`zodInputSchema`) and the converted JSON
+ * Schema (`inputSchema`) are kept on the definition. The MCP SDK
+ * accepts the Zod form directly, while the JSON Schema is exposed via
+ * `getTools()` for inspection, the `kick mcp --list` command, and
+ * documentation surfaces.
+ */
+interface McpToolDefinition {
+  /** Resolved tool name (either from options.name or derived). */
+  name: string;
+  /** Human-readable description. */
+  description: string;
+  /** JSON Schema for tool inputs, derived from the Zod body schema. */
+  inputSchema: Record<string, unknown>;
+  /**
+   * Original Zod schema for the tool input, when one was attached to
+   * the route via `body` (or via `@McpTool({ inputSchema })`). The MCP
+   * SDK accepts this form directly via `registerTool`. May be undefined
+   * for routes without a body schema.
+   */
+  zodInputSchema?: unknown;
+  /** Optional JSON Schema for tool outputs. */
+  outputSchema?: Record<string, unknown>;
+  /** HTTP method of the underlying route. */
+  httpMethod: string;
+  /** Full mount path of the underlying route (after apiPrefix + version). */
+  mountPath: string;
+  /** Examples for documentation. */
+  examples?: McpToolExample[];
+}
+//#endregion
+//#region src/mcp.adapter.d.ts
+/**
+ * Expose a KickJS application as a Model Context Protocol (MCP) server.
+ *
+ * The adapter implements `onRouteMount` to collect every registered
+ * controller alongside its mount path. During `beforeStart` (after all
+ * modules have finished mounting), it walks the collected controllers,
+ * reads route metadata via `getClassMeta(METADATA.ROUTES, ...)`, and
+ * builds a `McpToolDefinition[]` that the MCP SDK will register as
+ * callable tools.
+ *
+ * The input schema of each tool is the JSON Schema equivalent of the
+ * route's Zod `body` schema, converted via the package's own
+ * `zod-to-json-schema` helper. Tools with no body schema get an empty
+ * object schema so the model can still call them with no arguments.
+ *
+ * @example
+ * ```ts
+ * import { bootstrap } from '@forinda/kickjs'
+ * import { McpAdapter } from '@forinda/kickjs-mcp'
+ * import { modules } from './modules'
+ *
+ * export const app = await bootstrap({
+ *   modules,
+ *   adapters: [
+ *     new McpAdapter({
+ *       name: 'task-api',
+ *       version: '1.0.0',
+ *       description: 'Task management MCP server',
+ *       mode: 'explicit',
+ *       transport: 'sse',
+ *     }),
+ *   ],
+ * })
+ * ```
+ *
+ * @remarks
+ * Tool discovery is complete. The remaining work for v1 is wiring the
+ * generated tool definitions to `@modelcontextprotocol/sdk` in
+ * `afterStart` — see the TODO markers in that hook. Until then,
+ * `getTools()` returns the discovered definitions so tests can assert
+ * the scan produced the expected shape.
+ */
+declare class McpAdapter implements AppAdapter {
+  readonly name = "McpAdapter";
+  private readonly options;
+  /** Controllers collected during the mount phase, in insertion order. */
+  private readonly mountedControllers;
+  /** Discovered tool definitions, built during `beforeStart`. */
+  private readonly tools;
+  /** Active MCP server instance, created in `afterStart`. */
+  private mcpServer;
+  /**
+   * Active MCP transport, created in `afterStart`. Can be either a
+   * `StreamableHTTPServerTransport` (the default for HTTP-based MCP)
+   * or a `StdioServerTransport` (when running via the `kick mcp` CLI
+   * or with `KICK_MCP_STDIO=1`).
+   */
+  private transport;
+  /**
+   * Base URL of the running KickJS HTTP server, captured in `afterStart`
+   * once the server is listening. Tool dispatch makes internal HTTP
+   * requests against this base URL so calls flow through the normal
+   * Express pipeline (middleware, validation, auth, logging, error
+   * handling) rather than bypassing it.
+   *
+   * Format: `http://127.0.0.1:<port>`. Set to `null` until afterStart
+   * runs and reset to `null` on shutdown.
+   */
+  private serverBaseUrl;
+  constructor(options: McpAdapterOptions);
+  /**
+   * Called by the framework each time a module mounts a controller.
+   *
+   * We don't inspect routes here — we just record the pair and process
+   * everything in `beforeStart` once mounting is fully complete. This
+   * keeps the scan logic in one place and makes it easier to unit test.
+   */
+  onRouteMount(controller: Constructor, mountPath: string): void;
+  /**
+   * Walk collected controllers, read route metadata, and materialize
+   * `McpToolDefinition[]`.
+   *
+   * Runs after every module has mounted but before the HTTP server
+   * starts listening, so the MCP server can be initialized in
+   * `afterStart` with a complete tool list.
+   */
+  beforeStart(_ctx: AdapterContext): void;
+  /**
+   * Start the MCP server on the configured transport.
+   *
+   * - `http` (recommended): mounts a `StreamableHTTPServerTransport` on
+   *   the existing Express app at `${basePath}/messages`. This is the
+   *   modern, spec-compliant way to expose MCP over HTTP.
+   * - `sse` (deprecated): currently aliases to `http` and emits a warning.
+   *   The MCP SSE transport class is deprecated upstream in favor of
+   *   StreamableHTTP, which already supports SSE-style streaming under
+   *   the hood.
+   * - `stdio`: skipped here. The standalone `kick mcp` CLI command
+   *   instantiates the adapter directly and connects it to a stdio
+   *   transport so dev logs don't interfere.
+   */
+  afterStart(ctx: AdapterContext): Promise<void>;
+  /**
+   * Decide which transport to actually start.
+   *
+   * Precedence: an explicit `KICK_MCP_STDIO=1` environment variable
+   * always wins, because that's how the `kick mcp` CLI command tells
+   * the running process to switch to stdio mode without requiring the
+   * user to edit their bootstrap. Otherwise the constructor option is
+   * honored as-is.
+   */
+  private resolveTransportMode;
+  /**
+   * Start the MCP server bound to process stdio.
+   *
+   * Used by the `kick mcp` CLI: the parent process pipes its stdin/
+   * stdout to this adapter so MCP clients (Claude Code, Cursor) can
+   * speak the protocol over the wire. Logs MUST go to stderr in this
+   * mode — anything written to stdout corrupts the JSON-RPC stream.
+   *
+   * The HTTP server is still running (the framework called start()
+   * before afterStart), but we don't mount the MCP routes on it. Tool
+   * dispatch routes through fetch against `serverBaseUrl` exactly the
+   * same way it does in HTTP mode, so dispatch behavior is uniform
+   * across transports.
+   */
+  private startStdioTransport;
+  /**
+   * Tear down the MCP server and any open transports.
+   *
+   * Called during graceful shutdown. Idempotent — KickJS may invoke
+   * `shutdown` more than once under error conditions.
+   */
+  shutdown(): Promise<void>;
+  /**
+   * Return the list of tools discovered during startup.
+   *
+   * Primary consumers:
+   *   - the `kick mcp --list` command
+   *   - unit tests that verify a route was exposed as expected
+   */
+  getTools(): readonly McpToolDefinition[];
+  /**
+   * Build a `McpToolDefinition` for a single route, or return `null`
+   * if the route should be skipped under the current exposure mode.
+   *
+   * Scoping rules:
+   *   - `explicit` (default): only routes with `@McpTool` are exposed
+   *   - `auto`: every route is exposed, filtered by `include` /
+   *     `exclude`; a `hidden: true` on `@McpTool` still drops the route
+   */
+  private tryBuildTool;
+  /**
+   * Derive a default description for routes exposed in `auto` mode
+   * without an explicit `@McpTool` decorator. Kept intentionally
+   * generic — teams running `auto` should still add `@McpTool` with
+   * real descriptions for any tool the model is expected to call
+   * reliably.
+   */
+  private deriveDescription;
+  /**
+   * Join a module mount path with the route-level sub-path.
+   *
+   * Mount path already includes the API prefix + version (e.g.
+   * `/api/v1/tasks`); the route-level `path` is relative (e.g. `/:id`).
+   * Trailing/leading slashes are normalized so the final URL is stable.
+   */
+  private joinMountPath;
+  /**
+   * Construct the underlying `McpServer` and register every discovered
+   * tool against it. The SDK accepts Zod schemas natively, so we pass
+   * `zodInputSchema` straight through and skip the JSON Schema form
+   * here (the JSON Schema is for inspection / docs).
+   *
+   * Tool calls dispatch through the Express pipeline via internal HTTP
+   * requests against the running server's address (captured in
+   * `afterStart`). This preserves middleware, validation, auth, and
+   * logging — tool calls behave exactly like external HTTP requests
+   * to the same route.
+   */
+  private buildMcpServer;
+  /**
+   * Dispatch a tool call through the Express pipeline.
+   *
+   * Builds an HTTP request that matches the tool's underlying route
+   * (method + path + body or query string from the args) and sends it
+   * to the running server's `serverBaseUrl`. The request goes through
+   * every middleware the route normally hits — auth, validation,
+   * logging, error handling — so tool calls observe exactly the same
+   * guarantees as external HTTP clients.
+   *
+   * Path parameters (e.g. `/:id`) are substituted from `args` before
+   * the request fires; matching keys are removed from the body/query
+   * to avoid sending them twice.
+   *
+   * Returns a `CallToolResult` whose `content` contains the response
+   * body as text. Non-2xx responses are flagged with `isError: true`
+   * so the calling LLM can react.
+   */
+  private dispatchTool;
+  /**
+   * Substitute Express-style path parameters (`:id`) in `mountPath`
+   * with values from `args`. Returns the resolved path plus the args
+   * that were NOT consumed by parameters, so they can be sent as the
+   * request body or query string.
+   *
+   * If a `:param` is referenced in the path but missing from args,
+   * the placeholder is left in place — the request will hit a 404 from
+   * the underlying route, which is reported back as an MCP error.
+   */
+  private substitutePathParams;
+  /**
+   * Resolve the running server's base URL from a Node `http.Server`
+   * instance. Returns null if the server isn't listening or its
+   * address can't be determined (e.g. when the adapter is mounted
+   * standalone for testing).
+   *
+   * IPv6 addresses are wrapped in brackets per RFC 3986. The hostname
+   * `0.0.0.0` (Linux default) is rewritten to `127.0.0.1` because the
+   * former is not a valid request target on all platforms.
+   */
+  private resolveServerBaseUrl;
+  /**
+   * Mount the StreamableHTTP transport endpoints on the existing
+   * Express app. The transport handles three HTTP verbs at a single
+   * URL:
+   *   - POST: client → server messages (initialize, tool calls, etc.)
+   *   - GET:  server → client SSE stream for notifications
+   *   - DELETE: client tells the server to terminate a session
+   *
+   * We mount all three on `${basePath}/messages` so a single URL is
+   * the entire MCP surface area.
+   */
+  private mountHttpRoutes;
+}
+//#endregion
+//#region src/decorators.d.ts
+/**
+ * Mark a controller method as an MCP tool.
+ *
+ * The adapter scans for this decorator at startup and registers the
+ * method as a callable tool on the MCP server. The input schema is
+ * inferred from the route's `body` Zod schema — you don't repeat it here.
+ *
+ * @example
+ * ```ts
+ * import { Controller, Post, type Ctx } from '@forinda/kickjs'
+ * import { McpTool } from '@forinda/kickjs-mcp'
+ * import { createTaskSchema } from './dtos/create-task.dto'
+ *
+ * @Controller('/tasks')
+ * export class TaskController {
+ *   @Post('/', { body: createTaskSchema, name: 'CreateTask' })
+ *   @McpTool({ description: 'Create a new task' })
+ *   create(ctx: Ctx<KickRoutes.TaskController['create']>) {
+ *     // ... existing handler ...
+ *   }
+ * }
+ * ```
+ *
+ * In `explicit` mode (the default), only methods with this decorator
+ * are exposed as tools. In `auto` mode, it still controls the human-
+ * readable description and examples shown to the model.
+ */
+declare function McpTool(options: McpToolOptions): MethodDecorator;
+/**
+ * Read the MCP tool metadata attached to a method, if any.
+ *
+ * Returns `undefined` if the method was not decorated with `@McpTool`.
+ * The adapter uses this during the startup scan to decide whether a
+ * route should be registered as a tool.
+ */
+declare function getMcpToolMeta(target: object, method: string): McpToolOptions | undefined;
+/** Check whether a method was decorated with `@McpTool`. */
+declare function isMcpTool(target: object, method: string): boolean;
+//#endregion
+//#region src/constants.d.ts
+/**
+ * Metadata key for the `@McpTool` decorator.
+ *
+ * Using `createToken` gives a collision-safe, type-carrying identifier:
+ * the phantom type parameter flows through `getMethodMetaOrUndefined`
+ * so consumers get `McpToolOptions` back without a manual cast, and
+ * reference-equality guarantees that two separate definitions of
+ * `MCP_TOOL_METADATA` can never shadow each other even if the package
+ * is loaded more than once.
+ */
+declare const MCP_TOOL_METADATA: any;
+//#endregion
+export { MCP_TOOL_METADATA, McpAdapter, type McpAdapterOptions, type McpAuthOptions, type McpExposureMode, McpTool, type McpToolDefinition, type McpToolExample, type McpToolOptions, type McpTransport, getMcpToolMeta, isMcpTool };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/mcp.adapter.ts","../src/decorators.ts","../src/constants.ts"],"mappings":";;;;;;;;AAaA;;;;;AAWA;;;KAXY,YAAA;;AAoBZ;;;;;;;;KATY,eAAA;;AA8BZ;;;;;;UArBiB,cAAA;EAqCM;EAnCrB,IAAA;EAqBA;EAnBA,QAAA,GAAW,KAAA,uBAA4B,OAAA;AAAA;;;;;;;;;;;;;AA4CzC;;UA3BiB,iBAAA;EA+BH;EA7BZ,IAAA;EA6BA;EA3BA,OAAA;EA6BA;EA3BA,WAAA;EA2BM;EAzBN,IAAA,GAAO,eAAA;EAyCsB;EAvC7B,SAAA,GAAY,YAAA;EAwDE;EAtDd,OAAA,GAAU,KAAA;EA4DC;EA1DX,OAAA;EA0DyB;EAxDzB,IAAA,GAAO,cAAA;EA6CP;EA3CA,QAAA;AAAA;;;;;;;UASe,cAAA;EAmEA;EAjEf,WAAA;;EAEA,IAAA,EAAM,MAAA;EA8ES;EA5Ef,MAAA;AAAA;;;;;;;;;;;;;;UAgBe,cAAA;;;;ACxCjB;ED6CE,IAAA;;;;;;;EAOA,WAAA;ECkKqB;;;;ED7JrB,WAAA,GAAc,UAAA;ECxDL;;;ED4DT,YAAA,GAAe,UAAA;EC3CP;ED6CR,QAAA,GAAW,cAAA;ECzBH;;;;;ED+BR,MAAA;AAAA;;;;;;;;;;;;;;UAgBe,iBAAA;ECgJP;ED9IR,IAAA;EC+MQ;ED7MR,WAAA;ECqRc;EDnRd,WAAA,EAAa,MAAA;ECiYL;;;;;;ED1XR,cAAA;EElIc;EFoId,YAAA,GAAe,MAAA;;EAEf,UAAA;EEtI+B;EFwI/B,SAAA;EExIgD;EF0IhD,QAAA,GAAW,cAAA;AAAA;;;;;AA5Jb;;;;;AAWA;;;;;AASA;;;;;;;;;;AAqBA;;;;;;;;;;;;;;;;;;;;cCSa,UAAA,YAAsB,UAAA;EAAA,SACxB,IAAA;EAAA,iBAEQ,OAAA;EDMT;EAAA,iBCAS,kBAAA;EDSY;EAAA,iBCHZ,KAAA;EDOL;EAAA,QCJJ,SAAA;EDIR;;;;;AAkBF;EAlBE,QCIQ,SAAA;;;;;;;;;;;UAYA,aAAA;cAEI,OAAA,EAAS,iBAAA;EDuBrB;;;;;AAsBF;;EC5BE,YAAA,CAAa,UAAA,EAAY,WAAA,EAAa,SAAA;EDkCzB;;;;;;;;ECtBb,WAAA,CAAY,IAAA,EAAM,cAAA;ED6BlB;;;;;;;;;;;;AClGF;;EAkGQ,UAAA,CAAW,GAAA,EAAK,cAAA,GAAiB,OAAA;EA1DlB;;;;;;;;;EAAA,QAiHb,oBAAA;EAzJyB;;;;;;;;;;;;;;EAAA,QA8KnB,mBAAA;EAzGd;;;;;;EAyHM,QAAA,CAAA,GAAY,OAAA;EArCV;;;;;;;EA6DR,QAAA,CAAA,YAAqB,iBAAA;EAgFb;;;;;;;;;EAAA,QAjEA,YAAA;;ACrQV;;;;;;UD2TU,iBAAA;EC3TuD;;AAajE;;;;;EAbiE,QDsUvD,aAAA;ECzTsD;;;AAKhE;;;;;;;;ACpCA;ED+BgE,QD4UtD,cAAA;;;;;;;;;;;;;;;;;;;UAqDM,YAAA;;;;;;;;;;;UAoFN,oBAAA;;;;;;;;;;;UA0BA,oBAAA;;;;;;;;;;;;UAqBA,eAAA;AAAA;;;;;;ADniBV;;;;;AAWA;;;;;AASA;;;;;;;;;;AAqBA;;;;iBEvBgB,OAAA,CAAQ,OAAA,EAAS,cAAA,GAAiB,eAAA;;;;;;;;iBAalC,cAAA,CAAe,MAAA,UAAgB,MAAA,WAAiB,cAAA;;iBAKhD,SAAA,CAAU,MAAA,UAAgB,MAAA;;;;;;;AFpC1C;;;;;AAWA;cGXa,iBAAA"}

package/dist/index.mjs

@@ -0,0 +1,552 @@
+/**
+ * @forinda/kickjs-mcp v2.3.0
+ *
+ * Copyright (c) Felix Orinda
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @license MIT
+ */
+import { randomUUID } from "node:crypto";
+import { Logger, METADATA, createToken, getClassMeta, getMethodMetaOrUndefined, setMethodMeta } from "@forinda/kickjs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+//#region src/constants.ts
+/**
+* Metadata key for the `@McpTool` decorator.
+*
+* Using `createToken` gives a collision-safe, type-carrying identifier:
+* the phantom type parameter flows through `getMethodMetaOrUndefined`
+* so consumers get `McpToolOptions` back without a manual cast, and
+* reference-equality guarantees that two separate definitions of
+* `MCP_TOOL_METADATA` can never shadow each other even if the package
+* is loaded more than once.
+*/
+const MCP_TOOL_METADATA = createToken("kickjs.mcp.tool");
+//#endregion
+//#region src/decorators.ts
+/**
+* Mark a controller method as an MCP tool.
+*
+* The adapter scans for this decorator at startup and registers the
+* method as a callable tool on the MCP server. The input schema is
+* inferred from the route's `body` Zod schema — you don't repeat it here.
+*
+* @example
+* ```ts
+* import { Controller, Post, type Ctx } from '@forinda/kickjs'
+* import { McpTool } from '@forinda/kickjs-mcp'
+* import { createTaskSchema } from './dtos/create-task.dto'
+*
+* @Controller('/tasks')
+* export class TaskController {
+*   @Post('/', { body: createTaskSchema, name: 'CreateTask' })
+*   @McpTool({ description: 'Create a new task' })
+*   create(ctx: Ctx<KickRoutes.TaskController['create']>) {
+*     // ... existing handler ...
+*   }
+* }
+* ```
+*
+* In `explicit` mode (the default), only methods with this decorator
+* are exposed as tools. In `auto` mode, it still controls the human-
+* readable description and examples shown to the model.
+*/
+function McpTool(options) {
+	return (target, propertyKey) => {
+		setMethodMeta(MCP_TOOL_METADATA, options, target, propertyKey);
+	};
+}
+/**
+* Read the MCP tool metadata attached to a method, if any.
+*
+* Returns `undefined` if the method was not decorated with `@McpTool`.
+* The adapter uses this during the startup scan to decide whether a
+* route should be registered as a tool.
+*/
+function getMcpToolMeta(target, method) {
+	return getMethodMetaOrUndefined(MCP_TOOL_METADATA, target, method);
+}
+/** Check whether a method was decorated with `@McpTool`. */
+function isMcpTool(target, method) {
+	return getMcpToolMeta(target, method) !== void 0;
+}
+//#endregion
+//#region src/zod-to-json-schema.ts
+/**
+* Minimal Zod v4+ schema parser.
+*
+* Mirrors the `zodSchemaParser` in `@forinda/kickjs-swagger`. Zod v4
+* ships with a native `.toJSONSchema()` instance method, so this is
+* just a type guard + a call.
+*
+* Kept in-package (rather than importing from Swagger) so the MCP
+* adapter has no dependency on the Swagger package. If KickJS ever
+* extracts a shared `@forinda/kickjs-schema` utility, both adapters
+* can switch to it in one PR.
+*/
+/**
+* Check whether a value looks like a Zod v4+ schema.
+*
+* Uses structural duck-typing: the object has `safeParse` (all Zod
+* versions) AND `toJSONSchema` (Zod v4+). This avoids importing Zod
+* as a value, which would force it to become a runtime dep.
+*/
+function isZodSchema(schema) {
+	return schema != null && typeof schema === "object" && typeof schema.safeParse === "function" && typeof schema.toJSONSchema === "function";
+}
+/**
+* Convert a Zod v4+ schema to a JSON Schema object, stripping the
+* top-level `$schema` key so the output can be embedded inside an
+* MCP tool definition directly.
+*
+* Returns `null` if the input doesn't look like a Zod schema. Callers
+* should fall back to an empty-object input schema in that case.
+*/
+function zodToJsonSchema(schema) {
+	if (!isZodSchema(schema)) return null;
+	const { $schema: _ignored, ...rest } = schema.toJSONSchema();
+	return rest;
+}
+//#endregion
+//#region src/mcp.adapter.ts
+const log = Logger.for("McpAdapter");
+/**
+* Expose a KickJS application as a Model Context Protocol (MCP) server.
+*
+* The adapter implements `onRouteMount` to collect every registered
+* controller alongside its mount path. During `beforeStart` (after all
+* modules have finished mounting), it walks the collected controllers,
+* reads route metadata via `getClassMeta(METADATA.ROUTES, ...)`, and
+* builds a `McpToolDefinition[]` that the MCP SDK will register as
+* callable tools.
+*
+* The input schema of each tool is the JSON Schema equivalent of the
+* route's Zod `body` schema, converted via the package's own
+* `zod-to-json-schema` helper. Tools with no body schema get an empty
+* object schema so the model can still call them with no arguments.
+*
+* @example
+* ```ts
+* import { bootstrap } from '@forinda/kickjs'
+* import { McpAdapter } from '@forinda/kickjs-mcp'
+* import { modules } from './modules'
+*
+* export const app = await bootstrap({
+*   modules,
+*   adapters: [
+*     new McpAdapter({
+*       name: 'task-api',
+*       version: '1.0.0',
+*       description: 'Task management MCP server',
+*       mode: 'explicit',
+*       transport: 'sse',
+*     }),
+*   ],
+* })
+* ```
+*
+* @remarks
+* Tool discovery is complete. The remaining work for v1 is wiring the
+* generated tool definitions to `@modelcontextprotocol/sdk` in
+* `afterStart` — see the TODO markers in that hook. Until then,
+* `getTools()` returns the discovered definitions so tests can assert
+* the scan produced the expected shape.
+*/
+var McpAdapter = class {
+	name = "McpAdapter";
+	options;
+	/** Controllers collected during the mount phase, in insertion order. */
+	mountedControllers = [];
+	/** Discovered tool definitions, built during `beforeStart`. */
+	tools = [];
+	/** Active MCP server instance, created in `afterStart`. */
+	mcpServer = null;
+	/**
+	* Active MCP transport, created in `afterStart`. Can be either a
+	* `StreamableHTTPServerTransport` (the default for HTTP-based MCP)
+	* or a `StdioServerTransport` (when running via the `kick mcp` CLI
+	* or with `KICK_MCP_STDIO=1`).
+	*/
+	transport = null;
+	/**
+	* Base URL of the running KickJS HTTP server, captured in `afterStart`
+	* once the server is listening. Tool dispatch makes internal HTTP
+	* requests against this base URL so calls flow through the normal
+	* Express pipeline (middleware, validation, auth, logging, error
+	* handling) rather than bypassing it.
+	*
+	* Format: `http://127.0.0.1:<port>`. Set to `null` until afterStart
+	* runs and reset to `null` on shutdown.
+	*/
+	serverBaseUrl = null;
+	constructor(options) {
+		this.options = {
+			mode: options.mode ?? "explicit",
+			transport: options.transport ?? "sse",
+			basePath: options.basePath ?? "/_mcp",
+			version: options.version ?? "0.0.0",
+			...options
+		};
+	}
+	/**
+	* Called by the framework each time a module mounts a controller.
+	*
+	* We don't inspect routes here — we just record the pair and process
+	* everything in `beforeStart` once mounting is fully complete. This
+	* keeps the scan logic in one place and makes it easier to unit test.
+	*/
+	onRouteMount(controller, mountPath) {
+		this.mountedControllers.push({
+			controller,
+			mountPath
+		});
+	}
+	/**
+	* Walk collected controllers, read route metadata, and materialize
+	* `McpToolDefinition[]`.
+	*
+	* Runs after every module has mounted but before the HTTP server
+	* starts listening, so the MCP server can be initialized in
+	* `afterStart` with a complete tool list.
+	*/
+	beforeStart(_ctx) {
+		for (const { controller, mountPath } of this.mountedControllers) {
+			const routes = getClassMeta(METADATA.ROUTES, controller, []);
+			for (const route of routes) {
+				const tool = this.tryBuildTool(controller, mountPath, route);
+				if (tool) this.tools.push(tool);
+			}
+		}
+		log.debug(`MCP adapter discovered ${this.tools.length} tool(s) (mode=${this.options.mode}, transport=${this.options.transport})`);
+	}
+	/**
+	* Start the MCP server on the configured transport.
+	*
+	* - `http` (recommended): mounts a `StreamableHTTPServerTransport` on
+	*   the existing Express app at `${basePath}/messages`. This is the
+	*   modern, spec-compliant way to expose MCP over HTTP.
+	* - `sse` (deprecated): currently aliases to `http` and emits a warning.
+	*   The MCP SSE transport class is deprecated upstream in favor of
+	*   StreamableHTTP, which already supports SSE-style streaming under
+	*   the hood.
+	* - `stdio`: skipped here. The standalone `kick mcp` CLI command
+	*   instantiates the adapter directly and connects it to a stdio
+	*   transport so dev logs don't interfere.
+	*/
+	async afterStart(ctx) {
+		this.serverBaseUrl = this.resolveServerBaseUrl(ctx.server);
+		const effectiveTransport = this.resolveTransportMode();
+		if (effectiveTransport === "stdio") {
+			await this.startStdioTransport();
+			return;
+		}
+		if (effectiveTransport === "sse") log.warn("sse transport is deprecated upstream; using StreamableHTTP transport, which supports the same SSE wire format under the hood");
+		const expressApp = ctx.app;
+		if (!expressApp) {
+			log.warn("McpAdapter: AdapterContext.app is unavailable, cannot mount HTTP transport");
+			return;
+		}
+		this.mcpServer = this.buildMcpServer();
+		const httpTransport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
+		this.transport = httpTransport;
+		await this.mcpServer.connect(httpTransport);
+		this.mountHttpRoutes(expressApp, httpTransport);
+		log.info(`McpAdapter ready — ${this.tools.length} tool(s) registered, listening at ${this.options.basePath}/messages`);
+	}
+	/**
+	* Decide which transport to actually start.
+	*
+	* Precedence: an explicit `KICK_MCP_STDIO=1` environment variable
+	* always wins, because that's how the `kick mcp` CLI command tells
+	* the running process to switch to stdio mode without requiring the
+	* user to edit their bootstrap. Otherwise the constructor option is
+	* honored as-is.
+	*/
+	resolveTransportMode() {
+		if (process.env.KICK_MCP_STDIO === "1" || process.env.KICK_MCP_STDIO === "true") return "stdio";
+		return this.options.transport;
+	}
+	/**
+	* Start the MCP server bound to process stdio.
+	*
+	* Used by the `kick mcp` CLI: the parent process pipes its stdin/
+	* stdout to this adapter so MCP clients (Claude Code, Cursor) can
+	* speak the protocol over the wire. Logs MUST go to stderr in this
+	* mode — anything written to stdout corrupts the JSON-RPC stream.
+	*
+	* The HTTP server is still running (the framework called start()
+	* before afterStart), but we don't mount the MCP routes on it. Tool
+	* dispatch routes through fetch against `serverBaseUrl` exactly the
+	* same way it does in HTTP mode, so dispatch behavior is uniform
+	* across transports.
+	*/
+	async startStdioTransport() {
+		this.mcpServer = this.buildMcpServer();
+		this.transport = new StdioServerTransport();
+		await this.mcpServer.connect(this.transport);
+		log.info(`McpAdapter ready (stdio) — ${this.tools.length} tool(s) registered, dispatching against ${this.serverBaseUrl ?? "unknown"}`);
+	}
+	/**
+	* Tear down the MCP server and any open transports.
+	*
+	* Called during graceful shutdown. Idempotent — KickJS may invoke
+	* `shutdown` more than once under error conditions.
+	*/
+	async shutdown() {
+		try {
+			await this.transport?.close();
+		} catch (err) {
+			log.error(err, "McpAdapter: failed to close transport");
+		}
+		try {
+			await this.mcpServer?.close();
+		} catch (err) {
+			log.error(err, "McpAdapter: failed to close server");
+		}
+		this.transport = null;
+		this.mcpServer = null;
+		this.serverBaseUrl = null;
+		log.debug("McpAdapter shutdown complete");
+	}
+	/**
+	* Return the list of tools discovered during startup.
+	*
+	* Primary consumers:
+	*   - the `kick mcp --list` command
+	*   - unit tests that verify a route was exposed as expected
+	*/
+	getTools() {
+		return this.tools;
+	}
+	/**
+	* Build a `McpToolDefinition` for a single route, or return `null`
+	* if the route should be skipped under the current exposure mode.
+	*
+	* Scoping rules:
+	*   - `explicit` (default): only routes with `@McpTool` are exposed
+	*   - `auto`: every route is exposed, filtered by `include` /
+	*     `exclude`; a `hidden: true` on `@McpTool` still drops the route
+	*/
+	tryBuildTool(controller, mountPath, route) {
+		const meta = getMcpToolMeta(controller.prototype, route.handlerName);
+		if (this.options.mode === "explicit" && !meta) return null;
+		if (meta?.hidden) return null;
+		if (this.options.mode === "auto") {
+			const methodUpper = route.method.toUpperCase();
+			if (this.options.include && !this.options.include.includes(methodUpper)) return null;
+			if (this.options.exclude?.some((prefix) => mountPath.startsWith(prefix))) return null;
+		}
+		const description = meta?.description ?? this.deriveDescription(controller, route);
+		const name = meta?.name ?? `${controller.name}.${route.handlerName}`;
+		const candidateSchema = meta?.inputSchema ?? route.validation?.body ?? route.validation?.query;
+		return {
+			name,
+			description,
+			inputSchema: zodToJsonSchema(candidateSchema) ?? {
+				type: "object",
+				properties: {},
+				additionalProperties: false
+			},
+			zodInputSchema: candidateSchema,
+			outputSchema: (meta?.outputSchema ? zodToJsonSchema(meta.outputSchema) : void 0) ?? void 0,
+			httpMethod: route.method.toUpperCase(),
+			mountPath: this.joinMountPath(mountPath, route.path),
+			examples: meta?.examples
+		};
+	}
+	/**
+	* Derive a default description for routes exposed in `auto` mode
+	* without an explicit `@McpTool` decorator. Kept intentionally
+	* generic — teams running `auto` should still add `@McpTool` with
+	* real descriptions for any tool the model is expected to call
+	* reliably.
+	*/
+	deriveDescription(controller, route) {
+		return `${route.method.toUpperCase()} handler ${controller.name}.${route.handlerName}`;
+	}
+	/**
+	* Join a module mount path with the route-level sub-path.
+	*
+	* Mount path already includes the API prefix + version (e.g.
+	* `/api/v1/tasks`); the route-level `path` is relative (e.g. `/:id`).
+	* Trailing/leading slashes are normalized so the final URL is stable.
+	*/
+	joinMountPath(mountPath, routePath) {
+		const base = mountPath.endsWith("/") ? mountPath.slice(0, -1) : mountPath;
+		if (!routePath || routePath === "/") return base;
+		return `${base}${routePath.startsWith("/") ? routePath : `/${routePath}`}`;
+	}
+	/**
+	* Construct the underlying `McpServer` and register every discovered
+	* tool against it. The SDK accepts Zod schemas natively, so we pass
+	* `zodInputSchema` straight through and skip the JSON Schema form
+	* here (the JSON Schema is for inspection / docs).
+	*
+	* Tool calls dispatch through the Express pipeline via internal HTTP
+	* requests against the running server's address (captured in
+	* `afterStart`). This preserves middleware, validation, auth, and
+	* logging — tool calls behave exactly like external HTTP requests
+	* to the same route.
+	*/
+	buildMcpServer() {
+		const server = new McpServer({
+			name: this.options.name,
+			version: this.options.version,
+			...this.options.description ? { description: this.options.description } : {}
+		});
+		const registerTool = server.registerTool.bind(server);
+		for (const tool of this.tools) {
+			const config = { description: tool.description };
+			if (tool.zodInputSchema) config.inputSchema = tool.zodInputSchema;
+			registerTool(tool.name, config, async (args) => this.dispatchTool(tool, args));
+		}
+		return server;
+	}
+	/**
+	* Dispatch a tool call through the Express pipeline.
+	*
+	* Builds an HTTP request that matches the tool's underlying route
+	* (method + path + body or query string from the args) and sends it
+	* to the running server's `serverBaseUrl`. The request goes through
+	* every middleware the route normally hits — auth, validation,
+	* logging, error handling — so tool calls observe exactly the same
+	* guarantees as external HTTP clients.
+	*
+	* Path parameters (e.g. `/:id`) are substituted from `args` before
+	* the request fires; matching keys are removed from the body/query
+	* to avoid sending them twice.
+	*
+	* Returns a `CallToolResult` whose `content` contains the response
+	* body as text. Non-2xx responses are flagged with `isError: true`
+	* so the calling LLM can react.
+	*/
+	async dispatchTool(tool, rawArgs) {
+		if (!this.serverBaseUrl) return {
+			isError: true,
+			content: [{
+				type: "text",
+				text: `Cannot dispatch ${tool.name}: HTTP server address not yet captured`
+			}]
+		};
+		const args = rawArgs ?? {};
+		const { path, remainingArgs } = this.substitutePathParams(tool.mountPath, args);
+		const method = tool.httpMethod.toUpperCase();
+		const hasBody = method === "POST" || method === "PUT" || method === "PATCH";
+		let url = `${this.serverBaseUrl}${path}`;
+		const init = {
+			method,
+			headers: {
+				accept: "application/json",
+				"x-mcp-tool": tool.name
+			}
+		};
+		if (hasBody) {
+			init.headers["content-type"] = "application/json";
+			init.body = JSON.stringify(remainingArgs);
+		} else if (Object.keys(remainingArgs).length > 0) {
+			const qs = new URLSearchParams();
+			for (const [key, value] of Object.entries(remainingArgs)) {
+				if (value === void 0 || value === null) continue;
+				qs.append(key, typeof value === "string" ? value : JSON.stringify(value));
+			}
+			const sep = url.includes("?") ? "&" : "?";
+			url = `${url}${sep}${qs.toString()}`;
+		}
+		try {
+			const res = await fetch(url, init);
+			const text = await res.text();
+			return {
+				isError: res.status >= 400,
+				content: [{
+					type: "text",
+					text: text || `(${res.status} ${res.statusText})`
+				}]
+			};
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			log.error(err, `McpAdapter: dispatch failed for ${tool.name}`);
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `Tool dispatch error: ${message}`
+				}]
+			};
+		}
+	}
+	/**
+	* Substitute Express-style path parameters (`:id`) in `mountPath`
+	* with values from `args`. Returns the resolved path plus the args
+	* that were NOT consumed by parameters, so they can be sent as the
+	* request body or query string.
+	*
+	* If a `:param` is referenced in the path but missing from args,
+	* the placeholder is left in place — the request will hit a 404 from
+	* the underlying route, which is reported back as an MCP error.
+	*/
+	substitutePathParams(mountPath, args) {
+		const remaining = { ...args };
+		return {
+			path: mountPath.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_match, param) => {
+				if (param in remaining) {
+					const value = remaining[param];
+					delete remaining[param];
+					return encodeURIComponent(String(value));
+				}
+				return `:${param}`;
+			}),
+			remainingArgs: remaining
+		};
+	}
+	/**
+	* Resolve the running server's base URL from a Node `http.Server`
+	* instance. Returns null if the server isn't listening or its
+	* address can't be determined (e.g. when the adapter is mounted
+	* standalone for testing).
+	*
+	* IPv6 addresses are wrapped in brackets per RFC 3986. The hostname
+	* `0.0.0.0` (Linux default) is rewritten to `127.0.0.1` because the
+	* former is not a valid request target on all platforms.
+	*/
+	resolveServerBaseUrl(server) {
+		if (!server) return null;
+		const address = server.address();
+		if (!address || typeof address === "string") return null;
+		let host = address.address;
+		if (host === "::" || host === "0.0.0.0" || host === "") host = "127.0.0.1";
+		if (host.includes(":") && !host.startsWith("[")) host = `[${host}]`;
+		return `http://${host}:${address.port}`;
+	}
+	/**
+	* Mount the StreamableHTTP transport endpoints on the existing
+	* Express app. The transport handles three HTTP verbs at a single
+	* URL:
+	*   - POST: client → server messages (initialize, tool calls, etc.)
+	*   - GET:  server → client SSE stream for notifications
+	*   - DELETE: client tells the server to terminate a session
+	*
+	* We mount all three on `${basePath}/messages` so a single URL is
+	* the entire MCP surface area.
+	*/
+	mountHttpRoutes(app, transport) {
+		const path = `${this.options.basePath}/messages`;
+		const handleRequest = async (req, res) => {
+			try {
+				await transport.handleRequest(req, res, req.body);
+			} catch (err) {
+				log.error(err, `McpAdapter: error handling ${req.method} ${path}`);
+				if (!res.headersSent) res.status(500).json({ error: "MCP transport error" });
+			}
+		};
+		app.post(path, handleRequest);
+		app.get(path, handleRequest);
+		app.delete(path, handleRequest);
+	}
+};
+//#endregion
+export { MCP_TOOL_METADATA, McpAdapter, McpTool, getMcpToolMeta, isMcpTool };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/constants.ts","../src/decorators.ts","../src/zod-to-json-schema.ts","../src/mcp.adapter.ts"],"sourcesContent":["import { createToken } from '@forinda/kickjs'\nimport type { McpToolOptions } from './types'\n\n/**\n * Metadata key for the `@McpTool` decorator.\n *\n * Using `createToken` gives a collision-safe, type-carrying identifier:\n * the phantom type parameter flows through `getMethodMetaOrUndefined`\n * so consumers get `McpToolOptions` back without a manual cast, and\n * reference-equality guarantees that two separate definitions of\n * `MCP_TOOL_METADATA` can never shadow each other even if the package\n * is loaded more than once.\n */\nexport const MCP_TOOL_METADATA = createToken<McpToolOptions>('kickjs.mcp.tool')\n","import { setMethodMeta, getMethodMetaOrUndefined } from '@forinda/kickjs'\nimport { MCP_TOOL_METADATA } from './constants'\nimport type { McpToolOptions } from './types'\n\n/**\n * Mark a controller method as an MCP tool.\n *\n * The adapter scans for this decorator at startup and registers the\n * method as a callable tool on the MCP server. The input schema is\n * inferred from the route's `body` Zod schema — you don't repeat it here.\n *\n * @example\n * ```ts\n * import { Controller, Post, type Ctx } from '@forinda/kickjs'\n * import { McpTool } from '@forinda/kickjs-mcp'\n * import { createTaskSchema } from './dtos/create-task.dto'\n *\n * @Controller('/tasks')\n * export class TaskController {\n *   @Post('/', { body: createTaskSchema, name: 'CreateTask' })\n *   @McpTool({ description: 'Create a new task' })\n *   create(ctx: Ctx<KickRoutes.TaskController['create']>) {\n *     // ... existing handler ...\n *   }\n * }\n * ```\n *\n * In `explicit` mode (the default), only methods with this decorator\n * are exposed as tools. In `auto` mode, it still controls the human-\n * readable description and examples shown to the model.\n */\nexport function McpTool(options: McpToolOptions): MethodDecorator {\n  return (target, propertyKey) => {\n    setMethodMeta(MCP_TOOL_METADATA, options, target, propertyKey as string)\n  }\n}\n\n/**\n * Read the MCP tool metadata attached to a method, if any.\n *\n * Returns `undefined` if the method was not decorated with `@McpTool`.\n * The adapter uses this during the startup scan to decide whether a\n * route should be registered as a tool.\n */\nexport function getMcpToolMeta(target: object, method: string): McpToolOptions | undefined {\n  return getMethodMetaOrUndefined<McpToolOptions>(MCP_TOOL_METADATA, target, method)\n}\n\n/** Check whether a method was decorated with `@McpTool`. */\nexport function isMcpTool(target: object, method: string): boolean {\n  return getMcpToolMeta(target, method) !== undefined\n}\n","/**\n * Minimal Zod v4+ schema parser.\n *\n * Mirrors the `zodSchemaParser` in `@forinda/kickjs-swagger`. Zod v4\n * ships with a native `.toJSONSchema()` instance method, so this is\n * just a type guard + a call.\n *\n * Kept in-package (rather than importing from Swagger) so the MCP\n * adapter has no dependency on the Swagger package. If KickJS ever\n * extracts a shared `@forinda/kickjs-schema` utility, both adapters\n * can switch to it in one PR.\n */\n\n/**\n * Check whether a value looks like a Zod v4+ schema.\n *\n * Uses structural duck-typing: the object has `safeParse` (all Zod\n * versions) AND `toJSONSchema` (Zod v4+). This avoids importing Zod\n * as a value, which would force it to become a runtime dep.\n */\nexport function isZodSchema(schema: unknown): boolean {\n  return (\n    schema != null &&\n    typeof schema === 'object' &&\n    typeof (schema as { safeParse?: unknown }).safeParse === 'function' &&\n    typeof (schema as { toJSONSchema?: unknown }).toJSONSchema === 'function'\n  )\n}\n\n/**\n * Convert a Zod v4+ schema to a JSON Schema object, stripping the\n * top-level `$schema` key so the output can be embedded inside an\n * MCP tool definition directly.\n *\n * Returns `null` if the input doesn't look like a Zod schema. Callers\n * should fall back to an empty-object input schema in that case.\n */\nexport function zodToJsonSchema(schema: unknown): Record<string, unknown> | null {\n  if (!isZodSchema(schema)) return null\n  const { $schema: _ignored, ...rest } = (\n    schema as { toJSONSchema: () => Record<string, unknown> }\n  ).toJSONSchema() as Record<string, unknown>\n  return rest\n}\n","import { randomUUID } from 'node:crypto'\nimport {\n  Logger,\n  METADATA,\n  getClassMeta,\n  type AppAdapter,\n  type AdapterContext,\n  type Constructor,\n  type RouteDefinition,\n} from '@forinda/kickjs'\nimport type { Express } from 'express'\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'\nimport type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'\nimport { getMcpToolMeta } from './decorators'\nimport { zodToJsonSchema } from './zod-to-json-schema'\nimport type { McpAdapterOptions, McpToolDefinition, McpTransport } from './types'\n\nconst log = Logger.for('McpAdapter')\n\n/**\n * Expose a KickJS application as a Model Context Protocol (MCP) server.\n *\n * The adapter implements `onRouteMount` to collect every registered\n * controller alongside its mount path. During `beforeStart` (after all\n * modules have finished mounting), it walks the collected controllers,\n * reads route metadata via `getClassMeta(METADATA.ROUTES, ...)`, and\n * builds a `McpToolDefinition[]` that the MCP SDK will register as\n * callable tools.\n *\n * The input schema of each tool is the JSON Schema equivalent of the\n * route's Zod `body` schema, converted via the package's own\n * `zod-to-json-schema` helper. Tools with no body schema get an empty\n * object schema so the model can still call them with no arguments.\n *\n * @example\n * ```ts\n * import { bootstrap } from '@forinda/kickjs'\n * import { McpAdapter } from '@forinda/kickjs-mcp'\n * import { modules } from './modules'\n *\n * export const app = await bootstrap({\n *   modules,\n *   adapters: [\n *     new McpAdapter({\n *       name: 'task-api',\n *       version: '1.0.0',\n *       description: 'Task management MCP server',\n *       mode: 'explicit',\n *       transport: 'sse',\n *     }),\n *   ],\n * })\n * ```\n *\n * @remarks\n * Tool discovery is complete. The remaining work for v1 is wiring the\n * generated tool definitions to `@modelcontextprotocol/sdk` in\n * `afterStart` — see the TODO markers in that hook. Until then,\n * `getTools()` returns the discovered definitions so tests can assert\n * the scan produced the expected shape.\n */\nexport class McpAdapter implements AppAdapter {\n  readonly name = 'McpAdapter'\n\n  private readonly options: Required<\n    Pick<McpAdapterOptions, 'mode' | 'transport' | 'basePath' | 'version'>\n  > &\n    McpAdapterOptions\n\n  /** Controllers collected during the mount phase, in insertion order. */\n  private readonly mountedControllers: Array<{\n    controller: Constructor\n    mountPath: string\n  }> = []\n\n  /** Discovered tool definitions, built during `beforeStart`. */\n  private readonly tools: McpToolDefinition[] = []\n\n  /** Active MCP server instance, created in `afterStart`. */\n  private mcpServer: McpServer | null = null\n\n  /**\n   * Active MCP transport, created in `afterStart`. Can be either a\n   * `StreamableHTTPServerTransport` (the default for HTTP-based MCP)\n   * or a `StdioServerTransport` (when running via the `kick mcp` CLI\n   * or with `KICK_MCP_STDIO=1`).\n   */\n  private transport: Transport | null = null\n\n  /**\n   * Base URL of the running KickJS HTTP server, captured in `afterStart`\n   * once the server is listening. Tool dispatch makes internal HTTP\n   * requests against this base URL so calls flow through the normal\n   * Express pipeline (middleware, validation, auth, logging, error\n   * handling) rather than bypassing it.\n   *\n   * Format: `http://127.0.0.1:<port>`. Set to `null` until afterStart\n   * runs and reset to `null` on shutdown.\n   */\n  private serverBaseUrl: string | null = null\n\n  constructor(options: McpAdapterOptions) {\n    this.options = {\n      mode: options.mode ?? 'explicit',\n      transport: options.transport ?? 'sse',\n      basePath: options.basePath ?? '/_mcp',\n      version: options.version ?? '0.0.0',\n      ...options,\n    }\n  }\n\n  /**\n   * Called by the framework each time a module mounts a controller.\n   *\n   * We don't inspect routes here — we just record the pair and process\n   * everything in `beforeStart` once mounting is fully complete. This\n   * keeps the scan logic in one place and makes it easier to unit test.\n   */\n  onRouteMount(controller: Constructor, mountPath: string): void {\n    this.mountedControllers.push({ controller, mountPath })\n  }\n\n  /**\n   * Walk collected controllers, read route metadata, and materialize\n   * `McpToolDefinition[]`.\n   *\n   * Runs after every module has mounted but before the HTTP server\n   * starts listening, so the MCP server can be initialized in\n   * `afterStart` with a complete tool list.\n   */\n  beforeStart(_ctx: AdapterContext): void {\n    for (const { controller, mountPath } of this.mountedControllers) {\n      const routes = getClassMeta<RouteDefinition[]>(METADATA.ROUTES, controller, [])\n      for (const route of routes) {\n        const tool = this.tryBuildTool(controller, mountPath, route)\n        if (tool) this.tools.push(tool)\n      }\n    }\n\n    log.debug(\n      `MCP adapter discovered ${this.tools.length} tool(s) ` +\n        `(mode=${this.options.mode}, transport=${this.options.transport})`,\n    )\n  }\n\n  /**\n   * Start the MCP server on the configured transport.\n   *\n   * - `http` (recommended): mounts a `StreamableHTTPServerTransport` on\n   *   the existing Express app at `${basePath}/messages`. This is the\n   *   modern, spec-compliant way to expose MCP over HTTP.\n   * - `sse` (deprecated): currently aliases to `http` and emits a warning.\n   *   The MCP SSE transport class is deprecated upstream in favor of\n   *   StreamableHTTP, which already supports SSE-style streaming under\n   *   the hood.\n   * - `stdio`: skipped here. The standalone `kick mcp` CLI command\n   *   instantiates the adapter directly and connects it to a stdio\n   *   transport so dev logs don't interfere.\n   */\n  async afterStart(ctx: AdapterContext): Promise<void> {\n    // Capture the running server's address so tool dispatch can make\n    // internal HTTP requests against the actual port. The framework\n    // calls afterStart only once the server is listening, so\n    // server.address() returns a real AddressInfo at this point.\n    // We capture this regardless of transport mode because dispatch\n    // always uses the local HTTP listener — even in stdio mode it's\n    // the internal route into the Express pipeline.\n    this.serverBaseUrl = this.resolveServerBaseUrl(ctx.server)\n\n    const effectiveTransport = this.resolveTransportMode()\n\n    if (effectiveTransport === 'stdio') {\n      await this.startStdioTransport()\n      return\n    }\n\n    if (effectiveTransport === 'sse') {\n      log.warn(\n        'sse transport is deprecated upstream; using StreamableHTTP transport, which supports the same SSE wire format under the hood',\n      )\n    }\n\n    const expressApp = ctx.app as Express | undefined\n    if (!expressApp) {\n      log.warn('McpAdapter: AdapterContext.app is unavailable, cannot mount HTTP transport')\n      return\n    }\n\n    this.mcpServer = this.buildMcpServer()\n    const httpTransport = new StreamableHTTPServerTransport({\n      // Stateless mode for v0 — every request gets a fresh session. We can\n      // switch to a stateful generator (sessionIdGenerator: randomUUID) once\n      // we add session-aware tool dispatch.\n      sessionIdGenerator: () => randomUUID(),\n    })\n    this.transport = httpTransport\n\n    await this.mcpServer.connect(httpTransport)\n    this.mountHttpRoutes(expressApp, httpTransport)\n\n    log.info(\n      `McpAdapter ready — ${this.tools.length} tool(s) registered, listening at ${this.options.basePath}/messages`,\n    )\n  }\n\n  /**\n   * Decide which transport to actually start.\n   *\n   * Precedence: an explicit `KICK_MCP_STDIO=1` environment variable\n   * always wins, because that's how the `kick mcp` CLI command tells\n   * the running process to switch to stdio mode without requiring the\n   * user to edit their bootstrap. Otherwise the constructor option is\n   * honored as-is.\n   */\n  private resolveTransportMode(): McpTransport {\n    if (process.env.KICK_MCP_STDIO === '1' || process.env.KICK_MCP_STDIO === 'true') {\n      return 'stdio'\n    }\n    return this.options.transport\n  }\n\n  /**\n   * Start the MCP server bound to process stdio.\n   *\n   * Used by the `kick mcp` CLI: the parent process pipes its stdin/\n   * stdout to this adapter so MCP clients (Claude Code, Cursor) can\n   * speak the protocol over the wire. Logs MUST go to stderr in this\n   * mode — anything written to stdout corrupts the JSON-RPC stream.\n   *\n   * The HTTP server is still running (the framework called start()\n   * before afterStart), but we don't mount the MCP routes on it. Tool\n   * dispatch routes through fetch against `serverBaseUrl` exactly the\n   * same way it does in HTTP mode, so dispatch behavior is uniform\n   * across transports.\n   */\n  private async startStdioTransport(): Promise<void> {\n    this.mcpServer = this.buildMcpServer()\n    this.transport = new StdioServerTransport()\n    await this.mcpServer.connect(this.transport)\n    // Use stderr-friendly log level so we don't break the protocol\n    log.info(\n      `McpAdapter ready (stdio) — ${this.tools.length} tool(s) registered, dispatching against ${this.serverBaseUrl ?? 'unknown'}`,\n    )\n  }\n\n  /**\n   * Tear down the MCP server and any open transports.\n   *\n   * Called during graceful shutdown. Idempotent — KickJS may invoke\n   * `shutdown` more than once under error conditions.\n   */\n  async shutdown(): Promise<void> {\n    try {\n      await this.transport?.close()\n    } catch (err) {\n      log.error(err as Error, 'McpAdapter: failed to close transport')\n    }\n    try {\n      await this.mcpServer?.close()\n    } catch (err) {\n      log.error(err as Error, 'McpAdapter: failed to close server')\n    }\n    this.transport = null\n    this.mcpServer = null\n    this.serverBaseUrl = null\n    log.debug('McpAdapter shutdown complete')\n  }\n\n  /**\n   * Return the list of tools discovered during startup.\n   *\n   * Primary consumers:\n   *   - the `kick mcp --list` command\n   *   - unit tests that verify a route was exposed as expected\n   */\n  getTools(): readonly McpToolDefinition[] {\n    return this.tools\n  }\n\n  // ── Internal helpers ───────────────────────────────────────────────\n\n  /**\n   * Build a `McpToolDefinition` for a single route, or return `null`\n   * if the route should be skipped under the current exposure mode.\n   *\n   * Scoping rules:\n   *   - `explicit` (default): only routes with `@McpTool` are exposed\n   *   - `auto`: every route is exposed, filtered by `include` /\n   *     `exclude`; a `hidden: true` on `@McpTool` still drops the route\n   */\n  private tryBuildTool(\n    controller: Constructor,\n    mountPath: string,\n    route: RouteDefinition,\n  ): McpToolDefinition | null {\n    const meta = getMcpToolMeta(controller.prototype, route.handlerName)\n\n    if (this.options.mode === 'explicit' && !meta) return null\n    if (meta?.hidden) return null\n\n    if (this.options.mode === 'auto') {\n      const methodUpper = route.method.toUpperCase() as 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'\n      if (this.options.include && !this.options.include.includes(methodUpper)) return null\n      if (this.options.exclude?.some((prefix) => mountPath.startsWith(prefix))) return null\n    }\n\n    const description = meta?.description ?? this.deriveDescription(controller, route)\n    const name = meta?.name ?? `${controller.name}.${route.handlerName}`\n\n    // Prefer the body schema for POST/PUT/PATCH, query schema for GET/DELETE.\n    // In `auto` mode the decorator may be absent entirely, in which case we\n    // fall back to whatever schema the route decorator declared.\n    const candidateSchema = meta?.inputSchema ?? route.validation?.body ?? route.validation?.query\n\n    const inputSchema = zodToJsonSchema(candidateSchema) ?? {\n      type: 'object',\n      properties: {},\n      additionalProperties: false,\n    }\n\n    const outputSchema = meta?.outputSchema ? zodToJsonSchema(meta.outputSchema) : undefined\n\n    return {\n      name,\n      description,\n      inputSchema,\n      // Keep the original Zod schema alongside the JSON Schema. The MCP\n      // SDK accepts Zod directly via `registerTool`, while `inputSchema`\n      // (above) is what `getTools()` and inspection surfaces consume.\n      zodInputSchema: candidateSchema,\n      outputSchema: outputSchema ?? undefined,\n      httpMethod: route.method.toUpperCase(),\n      mountPath: this.joinMountPath(mountPath, route.path),\n      examples: meta?.examples,\n    }\n  }\n\n  /**\n   * Derive a default description for routes exposed in `auto` mode\n   * without an explicit `@McpTool` decorator. Kept intentionally\n   * generic — teams running `auto` should still add `@McpTool` with\n   * real descriptions for any tool the model is expected to call\n   * reliably.\n   */\n  private deriveDescription(controller: Constructor, route: RouteDefinition): string {\n    return `${route.method.toUpperCase()} handler ${controller.name}.${route.handlerName}`\n  }\n\n  /**\n   * Join a module mount path with the route-level sub-path.\n   *\n   * Mount path already includes the API prefix + version (e.g.\n   * `/api/v1/tasks`); the route-level `path` is relative (e.g. `/:id`).\n   * Trailing/leading slashes are normalized so the final URL is stable.\n   */\n  private joinMountPath(mountPath: string, routePath: string): string {\n    const base = mountPath.endsWith('/') ? mountPath.slice(0, -1) : mountPath\n    if (!routePath || routePath === '/') return base\n    const sub = routePath.startsWith('/') ? routePath : `/${routePath}`\n    return `${base}${sub}`\n  }\n\n  /**\n   * Construct the underlying `McpServer` and register every discovered\n   * tool against it. The SDK accepts Zod schemas natively, so we pass\n   * `zodInputSchema` straight through and skip the JSON Schema form\n   * here (the JSON Schema is for inspection / docs).\n   *\n   * Tool calls dispatch through the Express pipeline via internal HTTP\n   * requests against the running server's address (captured in\n   * `afterStart`). This preserves middleware, validation, auth, and\n   * logging — tool calls behave exactly like external HTTP requests\n   * to the same route.\n   */\n  private buildMcpServer(): McpServer {\n    const server = new McpServer({\n      name: this.options.name,\n      version: this.options.version,\n      ...(this.options.description ? { description: this.options.description } : {}),\n    })\n\n    // The SDK's `registerTool` is heavily overloaded with deep generic\n    // inference over Zod input/output shapes. The McpToolDefinition\n    // intentionally types `zodInputSchema` as `unknown` to keep our\n    // public surface free of SDK internal types, which makes the\n    // overload picker unhappy. Cast through `any` once, here, so the\n    // call sites stay clean. The SDK validates the schema at register\n    // time anyway, so the `any` is bounded to this loop.\n    /* eslint-disable @typescript-eslint/no-explicit-any */\n    const registerTool = server.registerTool.bind(server) as (\n      name: string,\n      config: { description: string; inputSchema?: unknown },\n      cb: (args: unknown) => any,\n    ) => unknown\n    /* eslint-enable @typescript-eslint/no-explicit-any */\n\n    for (const tool of this.tools) {\n      const config: { description: string; inputSchema?: unknown } = {\n        description: tool.description,\n      }\n      if (tool.zodInputSchema) {\n        config.inputSchema = tool.zodInputSchema\n      }\n      registerTool(tool.name, config, async (args) => this.dispatchTool(tool, args))\n    }\n\n    return server\n  }\n\n  /**\n   * Dispatch a tool call through the Express pipeline.\n   *\n   * Builds an HTTP request that matches the tool's underlying route\n   * (method + path + body or query string from the args) and sends it\n   * to the running server's `serverBaseUrl`. The request goes through\n   * every middleware the route normally hits — auth, validation,\n   * logging, error handling — so tool calls observe exactly the same\n   * guarantees as external HTTP clients.\n   *\n   * Path parameters (e.g. `/:id`) are substituted from `args` before\n   * the request fires; matching keys are removed from the body/query\n   * to avoid sending them twice.\n   *\n   * Returns a `CallToolResult` whose `content` contains the response\n   * body as text. Non-2xx responses are flagged with `isError: true`\n   * so the calling LLM can react.\n   */\n  private async dispatchTool(\n    tool: McpToolDefinition,\n    rawArgs: unknown,\n  ): Promise<{\n    content: Array<{ type: 'text'; text: string }>\n    isError?: boolean\n  }> {\n    if (!this.serverBaseUrl) {\n      return {\n        isError: true,\n        content: [\n          {\n            type: 'text' as const,\n            text: `Cannot dispatch ${tool.name}: HTTP server address not yet captured`,\n          },\n        ],\n      }\n    }\n\n    const args = (rawArgs ?? {}) as Record<string, unknown>\n    const { path, remainingArgs } = this.substitutePathParams(tool.mountPath, args)\n    const method = tool.httpMethod.toUpperCase()\n    const hasBody = method === 'POST' || method === 'PUT' || method === 'PATCH'\n\n    let url = `${this.serverBaseUrl}${path}`\n    const init: RequestInit = {\n      method,\n      headers: {\n        accept: 'application/json',\n        'x-mcp-tool': tool.name,\n      },\n    }\n\n    if (hasBody) {\n      ;(init.headers as Record<string, string>)['content-type'] = 'application/json'\n      init.body = JSON.stringify(remainingArgs)\n    } else if (Object.keys(remainingArgs).length > 0) {\n      // GET / DELETE: serialize args as a query string\n      const qs = new URLSearchParams()\n      for (const [key, value] of Object.entries(remainingArgs)) {\n        if (value === undefined || value === null) continue\n        qs.append(key, typeof value === 'string' ? value : JSON.stringify(value))\n      }\n      const sep = url.includes('?') ? '&' : '?'\n      url = `${url}${sep}${qs.toString()}`\n    }\n\n    try {\n      const res = await fetch(url, init)\n      const text = await res.text()\n      return {\n        isError: res.status >= 400,\n        content: [\n          {\n            type: 'text' as const,\n            text: text || `(${res.status} ${res.statusText})`,\n          },\n        ],\n      }\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err)\n      log.error(err as Error, `McpAdapter: dispatch failed for ${tool.name}`)\n      return {\n        isError: true,\n        content: [\n          {\n            type: 'text' as const,\n            text: `Tool dispatch error: ${message}`,\n          },\n        ],\n      }\n    }\n  }\n\n  /**\n   * Substitute Express-style path parameters (`:id`) in `mountPath`\n   * with values from `args`. Returns the resolved path plus the args\n   * that were NOT consumed by parameters, so they can be sent as the\n   * request body or query string.\n   *\n   * If a `:param` is referenced in the path but missing from args,\n   * the placeholder is left in place — the request will hit a 404 from\n   * the underlying route, which is reported back as an MCP error.\n   */\n  private substitutePathParams(\n    mountPath: string,\n    args: Record<string, unknown>,\n  ): { path: string; remainingArgs: Record<string, unknown> } {\n    const remaining: Record<string, unknown> = { ...args }\n    const path = mountPath.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_match, param: string) => {\n      if (param in remaining) {\n        const value = remaining[param]\n        delete remaining[param]\n        return encodeURIComponent(String(value))\n      }\n      return `:${param}`\n    })\n    return { path, remainingArgs: remaining }\n  }\n\n  /**\n   * Resolve the running server's base URL from a Node `http.Server`\n   * instance. Returns null if the server isn't listening or its\n   * address can't be determined (e.g. when the adapter is mounted\n   * standalone for testing).\n   *\n   * IPv6 addresses are wrapped in brackets per RFC 3986. The hostname\n   * `0.0.0.0` (Linux default) is rewritten to `127.0.0.1` because the\n   * former is not a valid request target on all platforms.\n   */\n  private resolveServerBaseUrl(server: AdapterContext['server']): string | null {\n    if (!server) return null\n    const address = server.address()\n    if (!address || typeof address === 'string') return null\n    let host = address.address\n    if (host === '::' || host === '0.0.0.0' || host === '') host = '127.0.0.1'\n    if (host.includes(':') && !host.startsWith('[')) host = `[${host}]`\n    return `http://${host}:${address.port}`\n  }\n\n  /**\n   * Mount the StreamableHTTP transport endpoints on the existing\n   * Express app. The transport handles three HTTP verbs at a single\n   * URL:\n   *   - POST: client → server messages (initialize, tool calls, etc.)\n   *   - GET:  server → client SSE stream for notifications\n   *   - DELETE: client tells the server to terminate a session\n   *\n   * We mount all three on `${basePath}/messages` so a single URL is\n   * the entire MCP surface area.\n   */\n  private mountHttpRoutes(app: Express, transport: StreamableHTTPServerTransport): void {\n    const path = `${this.options.basePath}/messages`\n\n    /* eslint-disable @typescript-eslint/no-explicit-any */\n    const handleRequest = async (req: any, res: any): Promise<void> => {\n      try {\n        await transport.handleRequest(req, res, req.body)\n      } catch (err) {\n        log.error(err as Error, `McpAdapter: error handling ${req.method} ${path}`)\n        if (!res.headersSent) {\n          res.status(500).json({ error: 'MCP transport error' })\n        }\n      }\n    }\n    /* eslint-enable @typescript-eslint/no-explicit-any */\n\n    app.post(path, handleRequest)\n    app.get(path, handleRequest)\n    app.delete(path, handleRequest)\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@forinda/kickjs-mcp",
+  "version": "2.3.0",
+  "description": "Model Context Protocol server adapter for KickJS — expose @Controller endpoints as MCP tools",
+  "keywords": [
+    "kickjs",
+    "nodejs",
+    "typescript",
+    "express",
+    "decorators",
+    "dependency-injection",
+    "backend",
+    "api",
+    "framework",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "claude",
+    "anthropic",
+    "tool-calling",
+    "agent",
+    "llm",
+    "@forinda/kickjs",
+    "@forinda/kickjs-cli",
+    "@forinda/kickjs-swagger"
+  ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "wireit": {
+    "build": {
+      "command": "tsdown",
+      "files": [
+        "src/**/*.ts",
+        "tsdown.config.ts",
+        "tsconfig.json",
+        "package.json"
+      ],
+      "output": [
+        "dist/**"
+      ],
+      "dependencies": [
+        "../kickjs:build"
+      ]
+    }
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "@forinda/kickjs": "2.3.0"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@swc/core": "^1.15.21",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.0",
+    "@types/supertest": "^7.2.0",
+    "express": "^5.1.0",
+    "supertest": "^7.2.2",
+    "typescript": "^5.9.2",
+    "unplugin-swc": "^1.5.9",
+    "vitest": "^4.1.2",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Felix Orinda",
+  "engines": {
+    "node": ">=20.0"
+  },
+  "homepage": "https://forinda.github.io/kick-js/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forinda/kick-js.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/forinda/kick-js/issues"
+  },
+  "scripts": {
+    "build": "wireit",
+    "dev": "tsdown --watch",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .wireit"
+  }
+}