apcore-mcp 0.2.0 → 0.4.0

package/dist/server/factory.js

@@ -7,7 +7,7 @@
  * - Registering tools/list and tools/call request handlers
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { SchemaConverter } from "../adapters/schema.js";
 import { AnnotationMapper } from "../adapters/annotations.js";
 export class MCPServerFactory {
@@ -25,7 +25,7 @@ export class MCPServerFactory {
      * @returns A configured Server instance with tools capability
      */
     createServer(name = "apcore-mcp", version = "0.1.0") {
-        return new Server({ name, version }, { capabilities: { tools: {} } });
+        return new Server({ name, version }, { capabilities: { tools: {}, resources: {} } });
     }
     /**
      * Build an MCP Tool object from an apcore module descriptor.
@@ -40,9 +40,12 @@ export class MCPServerFactory {
         if (!descriptor.moduleId || typeof descriptor.moduleId !== "string") {
             throw new Error("ModuleDescriptor.moduleId is required and must be a string");
         }
-        if (!descriptor.description || typeof descriptor.description !== "string") {
-            throw new Error("ModuleDescriptor.description is required and must be a string");
+        if (descriptor.description !== undefined && descriptor.description !== null && typeof descriptor.description !== "string") {
+            throw new Error("ModuleDescriptor.description must be a string");
         }
+        // NOTE: TypeScript uses AnnotationMapper.toMcpAnnotations() directly,
+        // while Python uses SchemaExporter.export_mcp() for the same mapping.
+        // Both produce identical output. If annotation logic changes, update both paths.
         const mcpAnnotations = this._annotationMapper.toMcpAnnotations(descriptor.annotations);
         const convertedSchema = this._schemaConverter.convertInputSchema(descriptor);
         const hasApproval = this._annotationMapper.hasRequiresApproval(descriptor.annotations);
@@ -57,10 +60,16 @@ export class MCPServerFactory {
                 openWorldHint: mcpAnnotations.openWorldHint,
             },
         };
-        if (hasApproval) {
-            tool._meta = {
-                requiresApproval: true,
-            };
+        const hasStreaming = descriptor.annotations?.streaming === true;
+        if (hasApproval || hasStreaming) {
+            const meta = {};
+            if (hasApproval) {
+                meta.requiresApproval = true;
+            }
+            if (hasStreaming) {
+                meta.streaming = true;
+            }
+            tool._meta = meta;
         }
         return tool;
     }
@@ -91,6 +100,68 @@ export class MCPServerFactory {
         }
         return tools;
     }
+    /**
+     * Register resources/list and resources/read handlers for modules with documentation.
+     *
+     * Iterates over registry.list(), gets each definition, and filters for
+     * descriptors that have a non-null `documentation` field. Registers:
+     * - resources/list: returns Resource objects with URI docs://{module_id}
+     * - resources/read: returns documentation text for the requested module
+     *
+     * @param server - The MCP Server to register handlers on
+     * @param registry - Registry to discover modules with documentation
+     */
+    registerResourceHandlers(server, registry) {
+        // Build a map of module_id -> documentation for modules with docs
+        const docsMap = new Map();
+        const moduleIds = registry.list();
+        for (const moduleId of moduleIds) {
+            try {
+                const descriptor = registry.getDefinition(moduleId);
+                if (descriptor?.documentation) {
+                    docsMap.set(moduleId, descriptor.documentation);
+                }
+            }
+            catch {
+                // Skip modules that throw errors
+            }
+        }
+        // Handle resources/list requests
+        server.setRequestHandler(ListResourcesRequestSchema, async () => {
+            const resources = [];
+            for (const [moduleId, _doc] of docsMap) {
+                resources.push({
+                    uri: `docs://${moduleId}`,
+                    name: `${moduleId} documentation`,
+                    mimeType: "text/plain",
+                });
+            }
+            return { resources };
+        });
+        // Handle resources/read requests
+        server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+            const uri = request.params.uri;
+            const prefix = "docs://";
+            if (!uri.startsWith(prefix)) {
+                throw new Error(`Unsupported URI scheme: ${uri}`);
+            }
+            const moduleId = uri.slice(prefix.length);
+            const documentation = docsMap.get(moduleId);
+            if (documentation === undefined) {
+                throw new Error(`Resource not found: ${uri}`);
+            }
+            const result = {
+                contents: [
+                    {
+                        uri,
+                        text: documentation,
+                        mimeType: "text/plain",
+                    },
+                ],
+            };
+            return result;
+        });
+    }
     /**
      * Register tools/list and tools/call request handlers on a Server instance.
      *
@@ -104,16 +175,27 @@ export class MCPServerFactory {
             return { tools };
         });
         // Handle tools/call requests
-        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
             const { name, arguments: args } = request.params;
             const toolArgs = (args ?? {});
-            const [content, isError] = await router.handleCall(name, toolArgs);
-            if (isError) {
-                throw new Error(content[0].text);
-            }
+            // Build HandleCallExtra from MCP SDK extra
+            const handleCallExtra = {
+                sendNotification: extra?.sendNotification
+                    ? (notification) => extra.sendNotification(notification)
+                    : undefined,
+                sendRequest: extra?.sendRequest
+                    ? (request, resultSchema) => extra.sendRequest(request, resultSchema)
+                    : undefined,
+                _meta: extra?._meta
+                    ? { progressToken: extra._meta.progressToken }
+                    : undefined,
+            };
+            const [content, isError] = await router.handleCall(name, toolArgs, handleCallExtra);
+            // Return tool errors as MCP CallToolResult with isError flag
+            // rather than throwing protocol-level errors
             const result = {
-                content: content,
-                isError: false,
+                content: content.map(c => ({ type: "text", text: c.text })),
+                isError,
             };
             return result;
         });

package/dist/server/factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/server/factory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/server/factory.ts"],"names":[],"mappings":"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"}

package/dist/server/router.d.ts

@@ -3,28 +3,60 @@
  *
  * Bridges the MCP tools/call protocol with apcore's Executor.call() or callAsync(),
  * handling success/error formatting for MCP text content responses.
+ *
+ * When the executor supports stream() and the caller provides a progressToken,
+ * chunks are forwarded as MCP notifications/progress before returning the
+ * accumulated result.
  */
 import type { Executor, TextContentDict } from "../types.js";
 /** Tuple of [content array, isError flag] returned from handleCall. */
 export type CallResult = [TextContentDict[], boolean];
+/**
+ * Extra context passed from the MCP SDK request handler.
+ *
+ * Mirrors the relevant subset of the SDK's `RequestHandlerExtra`:
+ * - `sendNotification` — sends an out-of-band notification on the current session
+ * - `sendRequest` — sends a request to the client (used for elicitation)
+ * - `_meta.progressToken` — opaque token the client attached to the request
+ */
+export interface HandleCallExtra {
+    sendNotification?: (notification: Record<string, unknown>) => Promise<void>;
+    sendRequest?: (request: Record<string, unknown>, resultSchema: unknown) => Promise<unknown>;
+    _meta?: {
+        progressToken?: string | number;
+    };
+}
+/** Options for the ExecutionRouter constructor. */
+export interface ExecutionRouterOptions {
+    validateInputs?: boolean;
+}
 export declare class ExecutionRouter {
     private readonly _executor;
     private readonly _errorMapper;
+    private readonly _validateInputs;
     /**
      * Create an ExecutionRouter.
      *
      * @param executor - Duck-typed executor with call(moduleId, inputs) or callAsync(moduleId, inputs)
+     * @param options - Optional configuration including validateInputs
      */
-    constructor(executor: Executor);
+    constructor(executor: Executor, options?: ExecutionRouterOptions);
     /**
      * Handle an MCP tools/call request by routing to the executor.
      *
-     * Tries executor.call() first, then falls back to executor.callAsync().
+     * Streaming path: if the executor has stream(), a progressToken is present,
+     * and sendNotification is available, each chunk from stream() is forwarded as
+     * a `notifications/progress` notification. The chunks are shallow-merged into
+     * an accumulated result which is returned as the final response.
+     *
+     * Non-streaming path: tries executor.call() first, then falls back to
+     * executor.callAsync().
      *
      * @param toolName - The MCP tool name (maps to apcore moduleId)
      * @param args - The tool call arguments
+     * @param extra - Optional MCP SDK extra context with sendNotification and _meta
      * @returns Tuple of [content, isError] where content is an array of text content dicts
      */
-    handleCall(toolName: string, args: Record<string, unknown>): Promise<CallResult>;
+    handleCall(toolName: string, args: Record<string, unknown>, extra?: HandleCallExtra): Promise<CallResult>;
 }
 //# sourceMappingURL=router.d.ts.map

package/dist/server/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/server/router.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE7D,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAAG,CAAC,eAAe,EAAE,EAAE,OAAO,CAAC,CAAC;AAEtD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAE3C;;;;OAIG;gBACS,QAAQ,EAAE,QAAQ;IAK9B;;;;;;;;OAQG;IACG,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC;CA+BvB"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/server/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAK7D,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAAG,CAAC,eAAe,EAAE,EAAE,OAAO,CAAC,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,gBAAgB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5F,KAAK,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACrC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAE1C;;;;;OAKG;gBACS,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,sBAAsB;IAMhE;;;;;;;;;;;;;;;OAeG;IACG,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,CAAC,EAAE,eAAe,GACtB,OAAO,CAAC,UAAU,CAAC;CAkLvB"}

package/dist/server/router.js

@@ -3,47 +3,187 @@
  *
  * Bridges the MCP tools/call protocol with apcore's Executor.call() or callAsync(),
  * handling success/error formatting for MCP text content responses.
+ *
+ * When the executor supports stream() and the caller provides a progressToken,
+ * chunks are forwarded as MCP notifications/progress before returning the
+ * accumulated result.
  */
 import { ErrorMapper } from "../adapters/errors.js";
+import { createBridgeContext } from "./context.js";
+import { MCP_PROGRESS_KEY, MCP_ELICIT_KEY } from "../helpers.js";
 export class ExecutionRouter {
     _executor;
     _errorMapper;
+    _validateInputs;
     /**
      * Create an ExecutionRouter.
      *
      * @param executor - Duck-typed executor with call(moduleId, inputs) or callAsync(moduleId, inputs)
+     * @param options - Optional configuration including validateInputs
      */
-    constructor(executor) {
+    constructor(executor, options) {
         this._executor = executor;
         this._errorMapper = new ErrorMapper();
+        this._validateInputs = options?.validateInputs ?? false;
     }
     /**
      * Handle an MCP tools/call request by routing to the executor.
      *
-     * Tries executor.call() first, then falls back to executor.callAsync().
+     * Streaming path: if the executor has stream(), a progressToken is present,
+     * and sendNotification is available, each chunk from stream() is forwarded as
+     * a `notifications/progress` notification. The chunks are shallow-merged into
+     * an accumulated result which is returned as the final response.
+     *
+     * Non-streaming path: tries executor.call() first, then falls back to
+     * executor.callAsync().
      *
      * @param toolName - The MCP tool name (maps to apcore moduleId)
      * @param args - The tool call arguments
+     * @param extra - Optional MCP SDK extra context with sendNotification and _meta
      * @returns Tuple of [content, isError] where content is an array of text content dicts
      */
-    async handleCall(toolName, args) {
+    async handleCall(toolName, args, extra) {
         try {
-            const callFn = this._executor.call
+            // ── Build context with MCP callbacks ──────────────────────────────
+            const progressToken = extra?._meta?.progressToken;
+            const sendNotification = extra?.sendNotification;
+            const sendRequest = extra?.sendRequest;
+            const contextData = {};
+            let hasCallbacks = false;
+            // Inject progress callback if progressToken + sendNotification available
+            if (progressToken !== undefined && sendNotification) {
+                hasCallbacks = true;
+                contextData[MCP_PROGRESS_KEY] = async (progress, total, message) => {
+                    await sendNotification({
+                        method: "notifications/progress",
+                        params: {
+                            progressToken,
+                            progress,
+                            total: total ?? 0,
+                            ...(message !== undefined ? { message } : {}),
+                        },
+                    });
+                };
+            }
+            // Inject elicitation callback if sendRequest available
+            if (sendRequest) {
+                hasCallbacks = true;
+                contextData[MCP_ELICIT_KEY] = async (message, requestedSchema) => {
+                    const result = await sendRequest({
+                        method: "elicitation/create",
+                        params: {
+                            message,
+                            ...(requestedSchema ? { requestedSchema } : {}),
+                        },
+                    }, {});
+                    return result ?? null;
+                };
+            }
+            const context = hasCallbacks
+                ? createBridgeContext(contextData)
+                : undefined;
+            // ── Pre-execution validation ────────────────────────────────────
+            if (this._validateInputs && this._executor.validate) {
+                try {
+                    const rawErrors = await this._executor.validate(toolName, args);
+                    let errorMessages = [];
+                    if (Array.isArray(rawErrors)) {
+                        // Handle both string[] and ValidationResult.errors (array of objects)
+                        errorMessages = rawErrors.map((e) => {
+                            if (typeof e === 'string')
+                                return e;
+                            if (typeof e === 'object' && e !== null) {
+                                const obj = e;
+                                const field = obj.field ?? obj.path ?? '?';
+                                const msg = obj.message ?? 'invalid';
+                                return `${field}: ${msg}`;
+                            }
+                            return String(e);
+                        });
+                    }
+                    else if (rawErrors && typeof rawErrors === 'object' && 'valid' in rawErrors) {
+                        // Handle ValidationResult object
+                        const vr = rawErrors;
+                        if (!vr.valid) {
+                            errorMessages = vr.errors.map(e => `${e.field ?? '?'}: ${e.message ?? 'invalid'}`);
+                        }
+                    }
+                    if (errorMessages.length > 0) {
+                        const detail = errorMessages.join("; ");
+                        const content = [
+                            { type: "text", text: `Validation failed: ${detail}` },
+                        ];
+                        return [content, true];
+                    }
+                }
+                catch (valError) {
+                    const errorInfo = this._errorMapper.toMcpError(valError);
+                    const content = [
+                        { type: "text", text: errorInfo.message },
+                    ];
+                    return [content, true];
+                }
+            }
+            // ── Streaming path ────────────────────────────────────────────────
+            if (this._executor.stream &&
+                progressToken !== undefined &&
+                sendNotification) {
+                let accumulated = {};
+                let chunkIndex = 0;
+                for await (const chunk of this._executor.stream(toolName, args, context)) {
+                    // Shallow-merge each chunk into the accumulated result
+                    accumulated = { ...accumulated, ...chunk };
+                    // Send progress notification for each chunk
+                    await sendNotification({
+                        method: "notifications/progress",
+                        params: {
+                            progressToken,
+                            progress: chunkIndex + 1,
+                            message: JSON.stringify(chunk),
+                        },
+                    });
+                    chunkIndex++;
+                }
+                const content = [
+                    {
+                        type: "text",
+                        text: JSON.stringify(accumulated),
+                    },
+                ];
+                if (context) {
+                    content.push({
+                        type: "text",
+                        text: JSON.stringify({ _trace_id: context.traceId }),
+                    });
+                }
+                return [content, false];
+            }
+            // ── Non-streaming path ────────────────────────────────────────────
+            const callFn = typeof this._executor.call === 'function'
                 ? this._executor.call.bind(this._executor)
-                : this._executor.callAsync?.bind(this._executor);
+                : typeof this._executor.callAsync === 'function'
+                    ? this._executor.callAsync.bind(this._executor)
+                    : null;
             if (!callFn) {
-                throw new Error("Executor must implement call() or callAsync()");
+                throw new Error('Executor must implement call() or callAsync()');
             }
-            const result = await callFn(toolName, args);
+            const result = await callFn(toolName, args, context);
             const content = [
                 {
                     type: "text",
                     text: JSON.stringify(result),
                 },
             ];
+            if (context) {
+                content.push({
+                    type: "text",
+                    text: JSON.stringify({ _trace_id: context.traceId }),
+                });
+            }
             return [content, false];
         }
         catch (error) {
+            console.error(`handleCall error for ${toolName}:`, error);
             const errorInfo = this._errorMapper.toMcpError(error);
             const content = [
                 {

package/dist/server/router.js.map

@@ -1 +1 @@
-{"version":3,"file":"router.js","sourceRoot":"","sources":["../../src/server/router.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAMpD,MAAM,OAAO,eAAe;IACT,SAAS,CAAW;IACpB,YAAY,CAAc;IAE3C;;;;OAIG;IACH,YAAY,QAAkB;QAC5B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,YAAY,GAAG,IAAI,WAAW,EAAE,CAAC;IACxC,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,UAAU,CACd,QAAgB,EAChB,IAA6B;QAE7B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI;gBAChC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;gBAC1C,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACnD,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;YACnE,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAE5C,MAAM,OAAO,GAAsB;gBACjC;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;iBAC7B;aACF,CAAC;YAEF,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YAEtD,MAAM,OAAO,GAAsB;gBACjC;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,SAAS,CAAC,OAAO;iBACxB;aACF,CAAC;YAEF,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../src/server/router.ts"],"names":[],"mappings":"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"}

package/dist/server/transport.d.ts

@@ -14,9 +14,46 @@ export interface HttpTransportOptions {
     port: number;
     endpoint?: string;
 }
+/** Duck-typed interface for a metrics collector that can export Prometheus text. */
+export interface MetricsExporter {
+    exportPrometheus(): string;
+}
 export declare class TransportManager {
     /** The underlying HTTP server, if an HTTP-based transport is active. */
     httpServer?: HttpServer;
+    /** Timestamp (ms) when this manager was created, used for uptime calculation. */
+    private _startTime;
+    /** Number of registered modules/tools. */
+    private _moduleCount;
+    /** Optional metrics collector for Prometheus /metrics endpoint. */
+    private _metricsCollector?;
+    /**
+     * Set the number of registered modules/tools.
+     *
+     * @param count - The number of modules
+     */
+    setModuleCount(count: number): void;
+    /**
+     * Set the metrics collector for Prometheus /metrics endpoint.
+     *
+     * @param collector - A MetricsExporter instance (e.g. MetricsCollector from apcore)
+     */
+    setMetricsCollector(collector: MetricsExporter): void;
+    /**
+     * Build the health check response payload.
+     *
+     * @returns Health status object with uptime and module count
+     */
+    private _buildHealthResponse;
+    /**
+     * Handle built-in routes (/health and /metrics).
+     *
+     * @param req - The incoming HTTP request
+     * @param res - The server response
+     * @param url - The parsed URL
+     * @returns true if the request was handled, false otherwise
+     */
+    private _handleBuiltinRoute;
     /**
      * Run the server using stdio transport.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/server/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsC,KAAK,MAAM,IAAI,UAAU,EAAuB,MAAM,WAAW,CAAC;AAC/G,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKxE,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA+CD,qBAAa,gBAAgB;IAC3B,wEAAwE;IACxE,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB;;;;;;;OAOG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7C;;;;;;;;OAQG;IACG,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC;IAuDhB;;;;;;;;;OASG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC;IAuEhB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;;;;;OAMG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;CAcpD"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/server/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsC,KAAK,MAAM,IAAI,UAAU,EAAuB,MAAM,WAAW,CAAC;AAC/G,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKxE,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC9B,gBAAgB,IAAI,MAAM,CAAC;CAC5B;AAkDD,qBAAa,gBAAgB;IAC3B,wEAAwE;IACxE,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB,iFAAiF;IACjF,OAAO,CAAC,UAAU,CAAsB;IAExC,0CAA0C;IAC1C,OAAO,CAAC,YAAY,CAAa;IAEjC,mEAAmE;IACnE,OAAO,CAAC,iBAAiB,CAAC,CAAkB;IAE5C;;;;OAIG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAInC;;;;OAIG;IACH,mBAAmB,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI;IAIrD;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAQ5B;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAyB3B;;;;;;;OAOG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7C;;;;;;;;OAQG;IACG,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC;IAyDhB;;;;;;;;;OASG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC;IAyEhB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;;;;;OAMG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;CAcpD"}

package/dist/server/transport.js

@@ -12,6 +12,8 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 /** Default maximum request body size in bytes (4MB). */
 const DEFAULT_MAX_BODY_BYTES = 4 * 1024 * 1024;
+/** Prometheus exposition format content-type. */
+const PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
 /** Maximum request body size in bytes. Configurable via APCORE_MAX_BODY_BYTES env var. */
 const MAX_BODY_BYTES = (() => {
     const env = process.env.APCORE_MAX_BODY_BYTES;
@@ -60,6 +62,73 @@ function readBody(req, maxBytes = MAX_BODY_BYTES) {
 export class TransportManager {
     /** The underlying HTTP server, if an HTTP-based transport is active. */
     httpServer;
+    /** Timestamp (ms) when this manager was created, used for uptime calculation. */
+    _startTime = Date.now();
+    /** Number of registered modules/tools. */
+    _moduleCount = 0;
+    /** Optional metrics collector for Prometheus /metrics endpoint. */
+    _metricsCollector;
+    /**
+     * Set the number of registered modules/tools.
+     *
+     * @param count - The number of modules
+     */
+    setModuleCount(count) {
+        this._moduleCount = count;
+    }
+    /**
+     * Set the metrics collector for Prometheus /metrics endpoint.
+     *
+     * @param collector - A MetricsExporter instance (e.g. MetricsCollector from apcore)
+     */
+    setMetricsCollector(collector) {
+        this._metricsCollector = collector;
+    }
+    /**
+     * Build the health check response payload.
+     *
+     * @returns Health status object with uptime and module count
+     */
+    _buildHealthResponse() {
+        return {
+            status: "ok",
+            uptime_seconds: Math.round((Date.now() - this._startTime) / 100) / 10,
+            module_count: this._moduleCount,
+        };
+    }
+    /**
+     * Handle built-in routes (/health and /metrics).
+     *
+     * @param req - The incoming HTTP request
+     * @param res - The server response
+     * @param url - The parsed URL
+     * @returns true if the request was handled, false otherwise
+     */
+    _handleBuiltinRoute(req, res, url) {
+        if (url.pathname === "/health" && req.method === "GET") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(this._buildHealthResponse()));
+            return true;
+        }
+        if (url.pathname === "/metrics" && req.method === "GET") {
+            if (!this._metricsCollector) {
+                res.writeHead(404);
+                res.end();
+                return true;
+            }
+            try {
+                const body = this._metricsCollector.exportPrometheus();
+                res.writeHead(200, { "Content-Type": PROMETHEUS_CONTENT_TYPE });
+                res.end(body);
+            }
+            catch {
+                res.writeHead(500);
+                res.end();
+            }
+            return true;
+        }
+        return false;
+    }
     /**
      * Run the server using stdio transport.
      *
@@ -90,6 +159,8 @@ export class TransportManager {
         await server.connect(transport);
         const httpServer = createServer(async (req, res) => {
             const url = new URL(req.url ?? "/", `http://${options.host}:${options.port}`);
+            if (this._handleBuiltinRoute(req, res, url))
+                return;
             if (url.pathname !== endpoint) {
                 res.writeHead(404).end("Not Found");
                 return;
@@ -146,6 +217,8 @@ export class TransportManager {
         const transports = new Map();
         const httpServer = createServer(async (req, res) => {
             const url = new URL(req.url ?? "/", `http://${options.host}:${options.port}`);
+            if (this._handleBuiltinRoute(req, res, url))
+                return;
             if (url.pathname === endpoint && req.method === "GET") {
                 // Establish SSE connection
                 const transport = new SSEServerTransport(messagesEndpoint, res);