@unbrained/pm-cli 2026.8.25 → 2026.8.26

package/dist/core/extensions/manifest-schema.d.ts

@@ -14,7 +14,27 @@ export interface ExtensionManifestSchemaInspection {
     /** Whether neither canonical pm compatibility bound is present. */
     missingVersionBounds: boolean;
 }
+/** Stable machine-readable schema finding emitted by author-time lint. */
+export interface ExtensionManifestSchemaFinding {
+    /** Schema condition an author must review. */
+    code: "manifest_unknown_key" | "no_version_bounds_declared";
+    /** JSON-style manifest location responsible for the finding. */
+    path: string;
+    /** Canonical key to use when the mistaken or missing field has one. */
+    suggested_key?: "pm_min_version" | "pm_max_version";
+    /** Actionable explanation of the ignored or missing declaration. */
+    message: string;
+}
+/** Pure schema-lint result for one raw extension manifest. */
+export interface ExtensionManifestSchemaLintResult {
+    /** False when at least one author-facing schema finding is present. */
+    ok: boolean;
+    /** Deterministically ordered schema findings. */
+    findings: ExtensionManifestSchemaFinding[];
+}
 /** Inspect raw manifest keys without parsing, loading, or mutating an extension. */
 export declare function inspectExtensionManifestSchema(manifest: Readonly<Record<string, unknown>>): ExtensionManifestSchemaInspection;
+/** Lint raw extension-manifest keys without loading code or evaluating versions. */
+export declare function lintExtensionManifestSchema(manifest: Readonly<Record<string, unknown>>): ExtensionManifestSchemaLintResult;
 /** Format runtime discovery warnings for unknown keys and absent canonical compatibility bounds. */
 export declare function formatExtensionManifestSchemaWarnings(layer: ExtensionLayer, manifest: ExtensionManifest, rawManifest: Readonly<Record<string, unknown>>): string[];

package/dist/core/extensions/manifest-schema.js

@@ -6,7 +6,7 @@
  */
 /** Canonical top-level keys accepted by an extension `manifest.json`. */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7d9d8924-3186-5aab-ac36-164fb08624a8")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="49cea84c-1d1b-523b-8c98-7ac16c69ae82")}catch(e){}}();
 export const KNOWN_EXTENSION_MANIFEST_KEYS = new Set([
     "name",
     "version",
@@ -37,16 +37,34 @@ export function inspectExtensionManifestSchema(manifest) {
             manifest.pm_max_version === undefined,
     };
 }
-/** Format runtime discovery warnings for unknown keys and absent canonical compatibility bounds. */
-export function formatExtensionManifestSchemaWarnings(layer, manifest, rawManifest) {
-    const inspection = inspectExtensionManifestSchema(rawManifest);
-    const warnings = inspection.unknownKeys.map((key) => key === "compatibility"
-        ? `extension_manifest_unknown_key:${layer}:${manifest.name}:key=compatibility:suggested=pm_min_version`
-        : `extension_manifest_unknown_key:${layer}:${manifest.name}:key=${key}`);
+/** Lint raw extension-manifest keys without loading code or evaluating versions. */
+export function lintExtensionManifestSchema(manifest) {
+    const inspection = inspectExtensionManifestSchema(manifest);
+    const findings = inspection.unknownKeys.map((key) => ({
+        code: "manifest_unknown_key",
+        path: key,
+        ...(key === "compatibility"
+            ? { suggested_key: "pm_min_version" }
+            : {}),
+        message: key === "compatibility"
+            ? 'Manifest key "compatibility" is ignored; declare the canonical pm_min_version and optional pm_max_version fields instead.'
+            : `Manifest key "${key}" is not part of the extension manifest contract and will be ignored.`,
+    }));
     if (inspection.missingVersionBounds) {
-        warnings.push(`extension_manifest_no_version_bounds:${layer}:${manifest.name}:suggested=pm_min_version`);
+        findings.push({
+            code: "no_version_bounds_declared",
+            path: "$",
+            suggested_key: "pm_min_version",
+            message: "No canonical pm version bounds are declared; add pm_min_version so compatibility intent is explicit.",
+        });
     }
-    return warnings;
+    return { ok: findings.length === 0, findings };
+}
+/** Format runtime discovery warnings for unknown keys and absent canonical compatibility bounds. */
+export function formatExtensionManifestSchemaWarnings(layer, manifest, rawManifest) {
+    return lintExtensionManifestSchema(rawManifest).findings.map((finding) => finding.code === "manifest_unknown_key"
+        ? `extension_manifest_unknown_key:${layer}:${manifest.name}:key=${finding.path}${finding.suggested_key ? `:suggested=${finding.suggested_key}` : ""}`
+        : `extension_manifest_no_version_bounds:${layer}:${manifest.name}:suggested=pm_min_version`);
 }
 //# sourceMappingURL=manifest-schema.js.map
-//# debugId=7d9d8924-3186-5aab-ac36-164fb08624a8
+//# debugId=49cea84c-1d1b-523b-8c98-7ac16c69ae82

package/dist/mcp/http-server.d.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * @module mcp/http-server
+ *
+ * Serves the pm MCP dispatcher through the sessionless 2026-07-28 Streamable
+ * HTTP POST binding with request-scoped JSON/SSE responses.
+ */
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { type PmMcpHttpAuthorizationPolicy, type PmMcpProtectedResourceMetadata } from "../sdk/mcp/authorization.js";
+import { type JsonRpcRequest } from "./server.js";
+/** Runtime options for one real Streamable HTTP server. */
+export interface PmMcpHttpServerOptions {
+    /** Local bind host. Defaults to the DNS-rebinding-safe loopback address. */
+    host?: string;
+    /** TCP port. Zero requests an ephemeral port. */
+    port?: number;
+    /** Single modern MCP POST endpoint. */
+    endpointPath?: string;
+    /** Exact browser origins permitted when an Origin header is present. */
+    allowedOrigins?: readonly string[];
+    /** Optional RFC 9728/OAuth resource-server policy. */
+    authorization?: PmMcpHttpAuthorizationPolicy;
+    /** Metadata served at RFC 9728 well-known paths. */
+    protectedResourceMetadata?: PmMcpProtectedResourceMetadata;
+    /** Maximum accepted JSON request bytes. */
+    maximumBodyBytes?: number;
+    /** SSE comment interval; zero disables keep-alives. */
+    keepAliveMs?: number;
+    /** Optional embedding dispatcher; defaults to the canonical pm MCP handler. */
+    requestHandler?: (request: JsonRpcRequest) => unknown | Promise<unknown>;
+}
+/** Write one SSE event and wait for transport backpressure to clear. */
+export declare function writePmMcpSseEvent(response: ServerResponse, payload: unknown): Promise<void>;
+declare function writeMcpHttpDispatchError(response: ServerResponse, rpcRequest: JsonRpcRequest | undefined, error: unknown): void;
+declare function destroyFailedMcpHttpResponse(response: ServerResponse, error: unknown): void;
+/** Create a configured HTTP server without binding it. */
+export declare function createPmMcpHttpServer(options?: PmMcpHttpServerOptions): Server<typeof IncomingMessage, typeof ServerResponse>;
+/** Gracefully close subscriptions before stopping a Streamable HTTP server. */
+export declare function closePmMcpHttpServer(server: Server): Promise<void>;
+/** Bind the configured Streamable HTTP server and return its actual address. */
+export declare function startPmMcpHttpServer(options?: PmMcpHttpServerOptions): Promise<ReturnType<typeof createPmMcpHttpServer>>;
+/** Resolve loopback-safe bind defaults without opening a socket. */
+export declare function resolvePmMcpHttpListenAddress(options?: Pick<PmMcpHttpServerOptions, "host" | "port">): {
+    host: string;
+    port: number;
+};
+/** Resolve and harden executable HTTP options from an environment map. */
+export declare function resolvePmMcpHttpServerOptionsFromEnvironment(processEnvironment?: NodeJS.ProcessEnv): PmMcpHttpServerOptions;
+/** Internal HTTP transport seams used only by direct integration tests. */
+export declare const _testOnly: {
+    /** Return the first active request-scoped transport key for one server. */
+    activeSubscriptionKey: (server: Server) => symbol | undefined;
+    /** Open a stream against one server runtime without a network socket. */
+    openHttpSubscription: (server: Server, request: JsonRpcRequest, response: ServerResponse) => Promise<void>;
+    /** Exercise committed-response handling without a network race. */
+    writeMcpHttpDispatchError: typeof writeMcpHttpDispatchError;
+    /** Exercise the terminal request rejection handler without a live socket. */
+    destroyFailedMcpHttpResponse: typeof destroyFailedMcpHttpResponse;
+};
+export {};

package/dist/mcp/http-server.js

@@ -0,0 +1,451 @@
+#!/usr/bin/env node
+/**
+ * @module mcp/http-server
+ *
+ * Serves the pm MCP dispatcher through the sessionless 2026-07-28 Streamable
+ * HTTP POST binding with request-scoped JSON/SSE responses.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7c5d2b34-e2ab-52a9-80a9-c5a28ce09dc7")}catch(e){}}();
+import { createServer, } from "node:http";
+import { PM_MCP_ERROR_CODES, PmMcpProtocolError } from "../sdk/mcp/protocol.js";
+import { PmMcpAuthorizationError, authorizeMcpHttpRequest, buildMcpProtectedResourceMetadata, createMcpStaticBearerVerifier, } from "../sdk/mcp/authorization.js";
+import { validateMcpHttpRequestHeaders } from "../sdk/mcp/transport.js";
+import { buildMcpToolCallErrorResult, closeMcpSubscription, handleRequest, isInvokedAsMcpMainModule, openMcpSubscription, resolveMcpToolSchemaForRequest, } from "./server.js";
+const DEFAULT_MAXIMUM_BODY_BYTES = 1024 * 1024;
+const DEFAULT_KEEP_ALIVE_MS = 15_000;
+const PM_MCP_HTTP_RUNTIMES = new WeakMap();
+/** Write one SSE event and wait for transport backpressure to clear. */
+export function writePmMcpSseEvent(response, payload) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => {
+            response.off("drain", onDrain);
+            response.off("close", onClose);
+        };
+        const onDrain = () => {
+            settled = true;
+            cleanup();
+            resolve();
+        };
+        const onClose = () => {
+            settled = true;
+            cleanup();
+            reject(new Error("MCP response stream closed during backpressure"));
+        };
+        response.once("drain", onDrain);
+        response.once("close", onClose);
+        try {
+            if (response.write(`data: ${JSON.stringify(payload)}\n\n`) && !settled) {
+                settled = true;
+                cleanup();
+                resolve();
+            }
+        }
+        catch (error) {
+            cleanup();
+            reject(error);
+        }
+    });
+}
+function writeJson(response, status, payload, headers = {}) {
+    response.writeHead(status, {
+        "Cache-Control": "no-store",
+        "Content-Type": "application/json",
+        ...headers,
+    });
+    response.end(`${JSON.stringify(payload)}\n`);
+}
+function writeJsonRpcError(response, id, error) {
+    const authorizationError = error instanceof PmMcpAuthorizationError ? error : undefined;
+    const protocolError = error instanceof PmMcpProtocolError ? error : undefined;
+    const code = protocolError?.code ?? -32603;
+    const clientErrorCodes = new Set([
+        -32700,
+        -32600,
+        PM_MCP_ERROR_CODES.headerMismatch,
+        PM_MCP_ERROR_CODES.unsupportedProtocolVersion,
+        PM_MCP_ERROR_CODES.invalidParams,
+    ]);
+    const status = authorizationError?.httpStatus ??
+        (code === -32601 ? 404 : clientErrorCodes.has(code) ? 400 : 500);
+    writeJson(response, status, {
+        jsonrpc: "2.0",
+        id: id ?? null,
+        error: {
+            code,
+            message: error instanceof Error ? error.message : "Internal MCP error",
+            ...(protocolError ? { data: protocolError.data } : {}),
+        },
+    }, authorizationError?.challenge
+        ? { "WWW-Authenticate": authorizationError.challenge }
+        : {});
+}
+function finishCommittedMcpResponse(response) {
+    if (!response.headersSent && !response.writableEnded && !response.destroyed) {
+        return false;
+    }
+    if (!response.writableEnded && !response.destroyed)
+        response.end();
+    return true;
+}
+function writeMcpHttpDispatchError(response, rpcRequest, error) {
+    if (finishCommittedMcpResponse(response))
+        return;
+    const toolError = rpcRequest
+        ? buildMcpToolCallErrorResult(rpcRequest, error)
+        : undefined;
+    if (toolError && rpcRequest) {
+        writeJson(response, 200, {
+            jsonrpc: "2.0",
+            id: rpcRequest.id ?? null,
+            result: toolError,
+        });
+        return;
+    }
+    writeJsonRpcError(response, rpcRequest?.id, error);
+}
+function destroyFailedMcpHttpResponse(response, error) {
+    response.destroy(new Error("Unhandled MCP HTTP request failure", { cause: error }));
+}
+async function readRequestBody(request, maximumBytes) {
+    const chunks = [];
+    let observed = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.from(chunk);
+        observed += buffer.length;
+        if (observed > maximumBytes) {
+            throw new PmMcpProtocolError("MCP HTTP request body exceeds the configured limit", PM_MCP_ERROR_CODES.invalidParams, { maximumBytes });
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function parseJsonRpcRequest(source) {
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        throw new PmMcpProtocolError("Invalid JSON-RPC request body", -32700);
+    }
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        ("jsonrpc" in value && value.jsonrpc !== "2.0") ||
+        ("method" in value && typeof value.method !== "string")) {
+        throw new PmMcpProtocolError("Invalid JSON-RPC request", -32600);
+    }
+    return value;
+}
+function protectedResourcePaths(endpointPath) {
+    return new Set([
+        "/.well-known/oauth-protected-resource",
+        `/.well-known/oauth-protected-resource${endpointPath}`,
+    ]);
+}
+function routeMcpHttpBoundary(request, response, requestUrl, runtime) {
+    if (runtime.options.protectedResourceMetadata &&
+        request.method === "GET" &&
+        protectedResourcePaths(runtime.endpointPath).has(requestUrl.pathname)) {
+        writeJson(response, 200, { ...runtime.options.protectedResourceMetadata });
+        return true;
+    }
+    if (requestUrl.pathname !== runtime.endpointPath) {
+        writeJson(response, 404, { error: "Not found" });
+        return true;
+    }
+    if (request.method !== "POST") {
+        response.setHeader("Allow", "POST");
+        writeJson(response, 405, { error: "Method not allowed" });
+        return true;
+    }
+    const origin = request.headers.origin;
+    if (origin !== undefined && !runtime.allowedOrigins.has(origin)) {
+        writeJson(response, 403, { error: "Origin is not allowed" });
+        return true;
+    }
+    const accept = request.headers.accept;
+    const contentType = request.headers["content-type"];
+    if (typeof accept !== "string" ||
+        !accept.includes("application/json") ||
+        !accept.includes("text/event-stream") ||
+        typeof contentType !== "string" ||
+        !contentType.startsWith("application/json")) {
+        writeJson(response, 406, {
+            error: "MCP requires JSON and SSE content negotiation",
+        });
+        return true;
+    }
+    return false;
+}
+async function openHttpSubscription(input) {
+    if (typeof input.request.id !== "string" &&
+        typeof input.request.id !== "number") {
+        throw new PmMcpProtocolError("subscriptions/listen requires a JSON-RPC id", PM_MCP_ERROR_CODES.invalidParams);
+    }
+    const subscriptionId = input.request.id;
+    const subscriptionKey = Symbol("pm-mcp-http-subscription");
+    const active = {
+        id: subscriptionId,
+        key: subscriptionKey,
+        response: input.response,
+    };
+    let disconnected = input.response.destroyed || input.response.writableEnded;
+    let subscriptionOpened = false;
+    const closeActiveSubscription = () => {
+        disconnected = true;
+        if (active.timer)
+            clearInterval(active.timer);
+        input.runtime.activeSubscriptions.delete(subscriptionKey);
+        if (subscriptionOpened) {
+            closeMcpSubscription(subscriptionId, subscriptionKey);
+        }
+    };
+    input.response.once("close", closeActiveSubscription);
+    let responseStarted = false;
+    try {
+        await openMcpSubscription({
+            request: input.request,
+            key: subscriptionKey,
+            sink: (notification) => {
+                if (input.response.destroyed || input.response.writableEnded) {
+                    throw new Error("MCP response stream closed before acknowledgment");
+                }
+                if (!responseStarted) {
+                    responseStarted = true;
+                    input.response.setHeader("Cache-Control", "no-cache, no-store");
+                    input.response.setHeader("Connection", "keep-alive");
+                    input.response.setHeader("Content-Type", "text/event-stream");
+                    input.response.setHeader("X-Accel-Buffering", "no");
+                }
+                return writePmMcpSseEvent(input.response, notification);
+            },
+        });
+        subscriptionOpened = true;
+    }
+    catch (error) {
+        input.response.off("close", closeActiveSubscription);
+        throw error;
+    }
+    if (disconnected ||
+        input.response.destroyed ||
+        input.response.writableEnded) {
+        closeActiveSubscription();
+        return;
+    }
+    if (input.runtime.keepAliveMs > 0) {
+        active.timer = setInterval(() => input.response.write(":\r\n\r\n"), input.runtime.keepAliveMs);
+        active.timer.unref();
+    }
+    input.runtime.activeSubscriptions.set(subscriptionKey, active);
+}
+async function dispatchMcpHttpRpc(input) {
+    let rpcRequest;
+    try {
+        if (input.runtime.options.authorization) {
+            await authorizeMcpHttpRequest({
+                headers: input.request.headers,
+                requestUrl: input.requestUrl.href,
+                policy: input.runtime.options.authorization,
+            });
+        }
+        rpcRequest = parseJsonRpcRequest(await readRequestBody(input.request, input.runtime.maximumBodyBytes));
+        validateMcpHttpRequestHeaders({
+            headers: input.request.headers,
+            request: rpcRequest,
+            toolSchema: await resolveMcpToolSchemaForRequest(rpcRequest),
+        });
+        if (rpcRequest.method === "subscriptions/listen") {
+            await openHttpSubscription({
+                request: rpcRequest,
+                response: input.response,
+                runtime: input.runtime,
+            });
+            return;
+        }
+        const result = await (input.runtime.options.requestHandler ?? handleRequest)(rpcRequest);
+        if (!Object.prototype.hasOwnProperty.call(rpcRequest, "id")) {
+            input.response.writeHead(202);
+            input.response.end();
+            return;
+        }
+        writeJson(input.response, 200, {
+            jsonrpc: "2.0",
+            id: rpcRequest.id ?? null,
+            result: result ?? {},
+        });
+    }
+    catch (error) {
+        writeMcpHttpDispatchError(input.response, rpcRequest, error);
+    }
+}
+async function handleMcpHttpRequest(request, response, runtime) {
+    const requestUrl = new URL(request.url, "http://localhost");
+    if (routeMcpHttpBoundary(request, response, requestUrl, runtime))
+        return;
+    await dispatchMcpHttpRpc({ request, response, requestUrl, runtime });
+}
+/** Create a configured HTTP server without binding it. */
+export function createPmMcpHttpServer(options = {}) {
+    const runtime = {
+        activeSubscriptions: new Map(),
+        allowedOrigins: new Set(options.allowedOrigins ?? []),
+        endpointPath: options.endpointPath ?? "/mcp",
+        keepAliveMs: options.keepAliveMs ?? DEFAULT_KEEP_ALIVE_MS,
+        maximumBodyBytes: options.maximumBodyBytes ?? DEFAULT_MAXIMUM_BODY_BYTES,
+        options,
+    };
+    const server = createServer((request, response) => {
+        void handleMcpHttpRequest(request, response, runtime).catch(destroyFailedMcpHttpResponse.bind(undefined, response));
+    });
+    PM_MCP_HTTP_RUNTIMES.set(server, runtime);
+    server.on("close", () => {
+        closeActiveHttpSubscriptions(runtime);
+        PM_MCP_HTTP_RUNTIMES.delete(server);
+    });
+    return server;
+}
+function closeActiveHttpSubscriptions(runtime) {
+    for (const [key, active] of runtime.activeSubscriptions) {
+        if (active.timer)
+            clearInterval(active.timer);
+        const result = closeMcpSubscription(active.id, key);
+        if (result) {
+            active.response.write(`data: ${JSON.stringify({ jsonrpc: "2.0", id: active.id, result })}\n\n`);
+        }
+        active.response.end();
+    }
+    runtime.activeSubscriptions.clear();
+}
+/** Gracefully close subscriptions before stopping a Streamable HTTP server. */
+export async function closePmMcpHttpServer(server) {
+    const runtime = PM_MCP_HTTP_RUNTIMES.get(server);
+    if (runtime)
+        closeActiveHttpSubscriptions(runtime);
+    await new Promise((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+    });
+    server.closeAllConnections();
+}
+/** Bind the configured Streamable HTTP server and return its actual address. */
+export async function startPmMcpHttpServer(options = {}) {
+    const server = createPmMcpHttpServer(options);
+    const address = resolvePmMcpHttpListenAddress(options);
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(address.port, address.host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    return server;
+}
+/** Resolve loopback-safe bind defaults without opening a socket. */
+export function resolvePmMcpHttpListenAddress(options = {}) {
+    return {
+        host: options.host ?? "127.0.0.1",
+        port: options.port ?? 3000,
+    };
+}
+function readMcpHttpEnvironment(environment) {
+    const configuredPort = environment.PM_MCP_HTTP_PORT?.trim();
+    const port = Number(configuredPort || "3000");
+    if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        throw new Error("PM_MCP_HTTP_PORT must be an integer from 0 through 65535");
+    }
+    return {
+        host: environment.PM_MCP_HTTP_HOST?.trim() || "127.0.0.1",
+        port,
+        allowedOrigins: (environment.PM_MCP_HTTP_ALLOWED_ORIGINS ?? "")
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter(Boolean),
+        token: environment.PM_MCP_HTTP_BEARER_TOKEN?.trim() || undefined,
+        issuer: environment.PM_MCP_HTTP_AUTH_ISSUER?.trim() || undefined,
+        resource: environment.PM_MCP_HTTP_RESOURCE?.trim() || undefined,
+        scopes: (environment.PM_MCP_HTTP_SCOPES ?? "pm:read pm:write")
+            .split(/\s+/u)
+            .filter(Boolean),
+    };
+}
+function buildMcpHttpAuthorizationOptions(environment) {
+    const metadata = buildMcpProtectedResourceMetadata({
+        resource: environment.resource,
+        authorizationServers: [environment.issuer],
+        scopes: environment.scopes,
+    });
+    const acceptedIssuer = environment.issuer;
+    return {
+        protectedResourceMetadata: metadata,
+        authorization: {
+            issuer: acceptedIssuer,
+            resource: metadata.resource,
+            requiredScopes: environment.scopes,
+            resourceMetadataUrl: new URL("/.well-known/oauth-protected-resource", metadata.resource).href,
+            verifyAccessToken: createMcpStaticBearerVerifier({
+                token: environment.token,
+                claims: {
+                    principal: "configured-remote-client",
+                    issuer: acceptedIssuer,
+                    audience: metadata.resource,
+                    scopes: environment.scopes,
+                },
+            }),
+        },
+    };
+}
+function hasCompleteMcpHttpAuthorization(environment) {
+    return Boolean(environment.token && environment.issuer && environment.resource);
+}
+/** Resolve and harden executable HTTP options from an environment map. */
+export function resolvePmMcpHttpServerOptionsFromEnvironment(processEnvironment = process.env) {
+    const environment = readMcpHttpEnvironment(processEnvironment);
+    const hasAuthorization = hasCompleteMcpHttpAuthorization(environment);
+    if (environment.host !== "127.0.0.1" &&
+        environment.host !== "localhost" &&
+        !hasAuthorization) {
+        throw new Error("Non-loopback MCP HTTP requires PM_MCP_HTTP_BEARER_TOKEN, PM_MCP_HTTP_AUTH_ISSUER, and PM_MCP_HTTP_RESOURCE");
+    }
+    const base = {
+        host: environment.host,
+        port: environment.port,
+        allowedOrigins: environment.allowedOrigins,
+    };
+    return hasAuthorization
+        ? {
+            ...base,
+            ...buildMcpHttpAuthorizationOptions({
+                issuer: environment.issuer,
+                resource: environment.resource,
+                token: environment.token,
+                scopes: environment.scopes,
+            }),
+        }
+        : base;
+}
+/** Internal HTTP transport seams used only by direct integration tests. */
+export const _testOnly = {
+    /** Return the first active request-scoped transport key for one server. */
+    activeSubscriptionKey: (server) => PM_MCP_HTTP_RUNTIMES.get(server).activeSubscriptions.keys().next().value,
+    /** Open a stream against one server runtime without a network socket. */
+    openHttpSubscription: (server, request, response) => openHttpSubscription({
+        request,
+        response,
+        runtime: PM_MCP_HTTP_RUNTIMES.get(server),
+    }),
+    /** Exercise committed-response handling without a network race. */
+    writeMcpHttpDispatchError,
+    /** Exercise the terminal request rejection handler without a live socket. */
+    destroyFailedMcpHttpResponse,
+};
+/* c8 ignore start -- executable guard and process lifecycle are integration-tested */
+if (isInvokedAsMcpMainModule(process.argv[1], import.meta.url)) {
+    startPmMcpHttpServer(resolvePmMcpHttpServerOptionsFromEnvironment()).catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}
+/* c8 ignore stop */
+//# sourceMappingURL=http-server.js.map
+//# debugId=7c5d2b34-e2ab-52a9-80a9-c5a28ce09dc7

package/dist/mcp/legacy-adapter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module mcp/legacy-adapter
+ *
+ * Isolates the bounded MCP 2025-06-18 stdio compatibility surface from the
+ * canonical stateless dispatcher. No modern transport imports policy from it.
+ */
+import { type AgentClientInfo } from "../sdk/runtime-primitives.js";
+import { type PmMcpImplementation, type PmMcpServerCapabilities } from "../sdk/mcp/protocol.js";
+/** Minimal request shape consumed by the compatibility adapter. */
+export interface LegacyMcpRequest {
+    /** Legacy method name. */
+    method?: string;
+    /** Legacy method parameters. */
+    params?: Record<string, unknown>;
+}
+/** Host callbacks keep this adapter separate from canonical SDK policy. */
+export interface LegacyMcpAdapterOptions {
+    /** Immutable server identity. */
+    serverInfo: PmMcpImplementation;
+    /** Compatibility-era capabilities. */
+    capabilities: PmMcpServerCapabilities;
+    /** Model-facing usage instructions. */
+    instructions: string;
+    /** Parse bounded historical client identity. */
+    parseClientInfo: (value: unknown) => AgentClientInfo | undefined;
+    /** Resolve legacy tool definitions. */
+    listTools: (params: Record<string, unknown> | undefined) => Promise<Record<string, unknown>>;
+    /** Execute one legacy tool call. */
+    callTool: (params: Record<string, unknown> | undefined, clientInfo: AgentClientInfo | undefined) => Promise<Record<string, unknown>>;
+    /** List legacy resources. */
+    listResources: () => Record<string, unknown>;
+    /** Read one legacy resource. */
+    readResource: (params: Record<string, unknown> | undefined) => Promise<Record<string, unknown>>;
+    /** List legacy prompts. */
+    listPrompts: () => Record<string, unknown>;
+    /** Render one legacy prompt. */
+    getPrompt: (params: Record<string, unknown> | undefined) => Record<string, unknown>;
+}
+/** Explicit compatibility adapter with no cross-process or modern-session role. */
+export declare class LegacyMcpAdapter {
+    #private;
+    /** Create one process-local legacy stdio adapter. */
+    constructor(options: LegacyMcpAdapterOptions);
+    /** Read the bounded identity most recently supplied to legacy initialize. */
+    getClientInfo(): AgentClientInfo | undefined;
+    /** Validate and answer the historical initialize handshake. */
+    initialize(params: Record<string, unknown> | undefined): Record<string, unknown>;
+    /** Dispatch one unversioned request through the finite legacy method set. */
+    dispatch(request: LegacyMcpRequest): Promise<Record<string, unknown>>;
+}