@typeship-ax/mcp 0.6.0 → 0.9.1

package/dist/mcp.d.ts

@@ -1,5 +1,23 @@
 #!/usr/bin/env node
-/** Fetch-style handler: mount in any runtime (workers, serverless, node).
- * Never rejects: every failure is an HTTP or JSON-RPC error response. */
-export declare function handleHttp(request: Request): Promise<Response>;
+import { type ClientOptions } from "./index.js";
+import { type McpAuthorizationConfiguration, type McpTokenIntrospectionConfiguration, type McpPrincipal } from "./mcp-authorization.js";
+export type { McpAuthorizationConfiguration, McpTokenIntrospectionConfiguration, McpPrincipal } from "./mcp-authorization.js";
+export { McpAccountLinkRequired } from "./mcp-protocol.js";
+export interface McpHttpOptions {
+    authorization?: McpAuthorizationConfiguration;
+    /** Optional server-only introspection. When set, checks every token with the
+     * provider instead of local JWT verification. Never put secrets in config. */
+    introspection?: McpTokenIntrospectionConfiguration;
+    /** Application-owned lookup or token exchange for this verified identity.
+     * Keep it outside the generated directory so regeneration preserves it.
+     * Throw McpAccountLinkRequired with a public linking page when the user
+     * needs to connect an account. Always verify the link server-side on retry.
+     * The MCP access token and request headers are deliberately not provided. */
+    credentialsFor(principal: McpPrincipal): ClientOptions | Promise<ClientOptions>;
+}
+/** Create once at startup; metadata/key caching is isolated to this server. */
+export declare function createMcpHandler(options: McpHttpOptions): (request: Request) => Promise<Response>;
+/** A generated entry point cannot infer the host application's user-to-API
+ * credential mapping. It remains closed until the owner installs a handler. */
+export declare function handleHttp(_request: Request): Promise<Response>;
 //# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":";AA2SA;yEACyE;AACzE,wBAAsB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsDpE"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":";AAuBA,OAAO,EAAoC,KAAK,aAAa,EAAmB,MAAM,YAAY,CAAC;AAcnG,OAAO,EAA8C,KAAK,6BAA6B,EAAE,KAAK,kCAAkC,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACpL,YAAY,EAAE,6BAA6B,EAAE,kCAAkC,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC9H,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AA4U3D,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,6BAA6B,CAAC;IAC9C;kFAC8E;IAC9E,aAAa,CAAC,EAAE,kCAAkC,CAAC;IACnD;;;;iFAI6E;IAC7E,cAAc,CAAC,SAAS,EAAE,YAAY,GAAG,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACjF;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAMjG;AAED;+EAC+E;AAC/E,wBAAsB,UAAU,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAErE"}

package/dist/mcp.js

@@ -5,27 +5,35 @@
 // live in ./mcp-protocol.js, shared with typeship's hosted endpoint. Two
 // transports, zero dependencies:
 //   node mcp.js            stdio (newline-delimited JSON-RPC 2.0)
-//   node mcp.js --http     Streamable HTTP on PORT (default 3000)
+//   createMcpHandler()    configured Streamable HTTP handler
 // Surface switches (flags or environment):
 //   --read-only / TYPESHIP_MCP_READ_ONLY=1     reads only; writes are not callable
 //   --tools a,b / TYPESHIP_MCP_TOOLS=a,b       only these resources or tools
 //   TYPESHIP_MCP_MAX_RESULT_CHARS=<n>          result size cap (default 64000)
-// handleHttp() is exported for serverless/worker runtimes.
-// In HTTP mode an incoming Authorization header is forwarded to the
-// upstream API (per-request passthrough); stdio resolves auth from the
+// The bare handleHttp()/--http entry stays closed until a handler is configured.
+// HTTP validates a dedicated MCP token and resolves API credentials through
+// createMcpHandler's application-owned callback; stdio resolves auth from the
 // environment, then from credentials/config saved by the CLI's `login`
 // and `config` commands (same files, so one login covers both bins).
+import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { TypeshipClient, formatDebugEvent } from "./index.js";
-import { GLOBALS, OPS, buildArgs } from "./ops.js";
-import { DEFAULT_MAX_RESULT_CHARS, SUPPORTED_PROTOCOL_VERSIONS, argumentsError, asJsonRpc, binaryOutcome, callSharedTool, checkRequestHeaders, dataOutcome, errorOutcome, fetchDocsText, handleRpc, isRpcOutcome, pageOutcome, parseIncludeList, prepareCall, serverInstructions, takeCancelled, textError, toolDefinitions, visibleOps, } from "./mcp-protocol.js";
+import { GLOBALS, OMITTED_OPS, OPS, buildArgs } from "./ops.js";
+import { DEFAULT_MAX_RESULT_CHARS, SUPPORTED_PROTOCOL_VERSIONS, McpAccountLinkRequired, argumentsError, asJsonRpc, binaryOutcome, callSharedTool, checkRequestHeaders, dataOutcome, errorOutcome, handleRpc, isRpcOutcome, pageOutcome, parseIncludeList, prepareCall, resolveReferences, serverInstructions, takeCancelled, textError, toolDefinitions, visibleOps, } from "./mcp-protocol.js";
+import { fetchDocsText } from "./docs.js";
+import { assertCredentialDestination, assertStoredIdentity } from "./oauth-session.js";
+import { createCredentialStore } from "./credential-storage.js";
+import { parseNamedCredentials, resolveNamedCredentials, namedCredentialAvailability } from "./named-credentials.js";
+import { resolveProfile, profileFlag, readProfileConfig } from "./auth-profiles.js";
+import { createMcpAuthorizer, McpAuthorizationError } from "./mcp-authorization.js";
+export { McpAccountLinkRequired } from "./mcp-protocol.js";
 const BIN = "typeship";
 const PKG_NAME = "@typeship-ax/mcp";
 const SERVER_NAME = "typeship-mcp";
-const SERVER_VERSION = "0.6.0";
+const SERVER_VERSION = "0.9.1";
 /** The MCP client's announced name (clientInfo in request _meta), for the User-Agent. */
 let MCP_CLIENT_NAME = null;
 function noteClientInfo(message) {
@@ -33,20 +41,18 @@ function noteClientInfo(message) {
     const name = meta?.["io.modelcontextprotocol/clientInfo"]?.name;
     if (typeof name === "string" && name && name !== MCP_CLIENT_NAME) {
         MCP_CLIENT_NAME = name.slice(0, 60);
-        clientInstance = undefined;
     }
 }
 const DEFAULT_BASE_URL = "https://typeship.dev/api/v1";
+const NAMED_SCHEMES = { "apiKey": { "kind": "bearer", "options": ["bearerToken"] } };
 const AUTH_SCALARS = [{ "option": "bearerToken", "flag": "token", "env": "TYPESHIP_TOKEN" }];
 const BASIC = null;
-const OAUTH_TOKEN_URL = null;
 const ENVIRONMENTS = {};
 const DOCS_URL_DEFAULT = "https://typeship.dev";
+const DOCS_INDEX_URL_DEFAULT = null;
 /** "meta" collapses per-operation tools into search/read/execute so huge
  * APIs don't flood agent context with hundreds of tools. */
 const TOOL_MODE = "meta";
-/** Authorization server for OAuth discovery (RFC 9728), from the spec. */
-const OAUTH_ISSUER = null;
 /** Project-supplied guidance appended to the server instructions. */
 const CUSTOM_INSTRUCTIONS = null;
 /** The tool that returns the caller (the CLI's whoami target), named in the instructions. */
@@ -59,15 +65,18 @@ const INCLUDE = parseIncludeList(ARGV.includes("--tools") ? ARGV[ARGV.indexOf("-
 const MAX_RESULT_CHARS = Number(process.env["TYPESHIP_MCP_MAX_RESULT_CHARS"]) || DEFAULT_MAX_RESULT_CHARS;
 /** One sentence on where credentials come from on each transport; goes
  * into the instructions and into 401 results. */
-const AUTH_HINT_STDIO = "Credentials come from the MCP server's environment (TYPESHIP_TOKEN) or from 'typeship login'";
-const AUTH_HINT_HTTP = "Send the API credential as the Authorization header of each MCP request; it is forwarded to the API as is";
+const AUTH_HINT_STDIO = "Credentials come from the MCP server's environment (TYPESHIP_CREDENTIALS, TYPESHIP_TOKEN) or from 'typeship login'";
+const AUTH_HINT_HTTP = "Sign in to this MCP server. The server resolves your API credentials separately; its connection token is never forwarded to the API.";
 /** The tool list is fixed at generation, so clients may cache it for an
  * hour and shared caches may hold it (identical for every caller). */
 const TOOLS_TTL_MS = 60 * 60 * 1000;
-function configDir() {
+function configRoot() {
     return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), BIN);
 }
+function configDir() { return resolveProfile(configRoot(), { flag: profileFlag(ARGV), environment: process.env["TYPESHIP_PROFILE"] }).directory; }
 function readJson(file) {
+    if (!LOCAL_CREDENTIALS)
+        return null;
     try {
         return JSON.parse(readFileSync(join(configDir(), file), "utf8"));
     }
@@ -75,10 +84,22 @@ function readJson(file) {
         return null;
     }
 }
-function makeClient() {
-    const stored = readJson("credentials.json");
-    const config = readJson("config.json");
-    const options = {};
+function makeClient(op) {
+    const profile = LOCAL_CREDENTIALS ? resolveProfile(configRoot(), { flag: profileFlag(ARGV), environment: process.env["TYPESHIP_PROFILE"] }) : null;
+    const store = createCredentialStore(profile?.directory ?? configRoot(), process.env["TYPESHIP_CREDENTIAL_STORE"], "TYPESHIP_CREDENTIAL_STORE");
+    if (BASIC && (process.env[BASIC.envUser] !== undefined) !== (process.env[BASIC.envPass] !== undefined))
+        throw new Error("Supply both Basic-auth environment variables together, or use a complete named Basic credential.");
+    const envNamed = LOCAL_CREDENTIALS && process.env["TYPESHIP_CREDENTIALS"] !== undefined ? parseNamedCredentials(process.env["TYPESHIP_CREDENTIALS"], NAMED_SCHEMES) : {};
+    const explicitOptions = new Set(AUTH_SCALARS.filter((a) => process.env[a.env] !== undefined).map((a) => a.option));
+    if (BASIC && process.env[BASIC.envUser] !== undefined && process.env[BASIC.envPass] !== undefined)
+        explicitOptions.add("basicAuth");
+    namedCredentialAvailability(NAMED_SCHEMES, explicitOptions, envNamed);
+    const identityPolicy = {};
+    const identityOp = OPS.find((candidate) => candidate.tool === IDENTITY_TOOL);
+    const identity = identityOp && Object.keys(identityPolicy).length ? { operation: identityOp.resource + "." + identityOp.method, fields: identityPolicy } : undefined;
+    const explicitCredentials = op.credentialOptions?.some((alternative) => alternative.length > 0 && alternative.every((option) => explicitOptions.has(option)));
+    const stored = op.auth !== "none" && LOCAL_CREDENTIALS && !explicitCredentials ? store.read() : null;
+    const config = profile ? readProfileConfig(profile.directory) : {};
     const baseUrl = process.env["TYPESHIP_BASE_URL"]
         ?? config?.baseUrl
         ?? (config?.environment !== undefined ? ENVIRONMENTS[config.environment] : undefined)
@@ -88,7 +109,11 @@ function makeClient() {
         // instead of a server that vanished mid-conversation.
         throw new Error("No base URL configured: set TYPESHIP_BASE_URL in the MCP server's environment, or run '" + BIN + " config set base-url <url>'.");
     }
-    options.baseUrl = baseUrl;
+    if (stored) {
+        assertCredentialDestination(stored, { apiBaseUrl: baseUrl, environment: config.environment, profile: profile?.name });
+        assertStoredIdentity(stored, identity);
+    }
+    const options = { baseUrl };
     for (const a of AUTH_SCALARS) {
         const v = process.env[a.env] ?? stored?.scalars?.[a.option];
         if (v !== undefined)
@@ -100,20 +125,16 @@ function makeClient() {
         if (username !== undefined && password !== undefined)
             options.basicAuth = { username, password };
     }
-    const oauthClientId = process.env["TYPESHIP_CLIENT_ID"];
-    const oauthClientSecret = process.env["TYPESHIP_CLIENT_SECRET"];
-    if ((oauthClientId === undefined) !== (oauthClientSecret === undefined)) {
-        throw new Error("OAuth client credentials are incomplete: set both TYPESHIP_CLIENT_ID and TYPESHIP_CLIENT_SECRET in the MCP server's environment.");
-    }
-    if (oauthClientId !== undefined && oauthClientSecret !== undefined) {
-        const tokenUrl = process.env["TYPESHIP_TOKEN_URL"] ?? OAUTH_TOKEN_URL ?? undefined;
-        if (!tokenUrl)
-            throw new Error("OAuth client credentials need a token URL: set TYPESHIP_TOKEN_URL in the MCP server's environment.");
-        options.clientCredentials = { clientId: oauthClientId, clientSecret: oauthClientSecret, tokenUrl };
-    }
-    if (options.bearerToken === undefined && stored?.oauth?.accessToken !== undefined) {
-        options.bearerToken = stored.oauth.accessToken;
-    }
+    const envOptions = {};
+    for (const a of AUTH_SCALARS)
+        if (process.env[a.env] !== undefined)
+            envOptions[a.option] = process.env[a.env];
+    if (BASIC && process.env[BASIC.envUser] !== undefined && process.env[BASIC.envPass] !== undefined)
+        envOptions.basicAuth = { username: process.env[BASIC.envUser], password: process.env[BASIC.envPass] };
+    options.credentials = resolveNamedCredentials(NAMED_SCHEMES, [
+        { named: stored?.named, options: { ...stored?.scalars, ...(stored?.basic ? { basicAuth: stored.basic } : {}) } },
+        { named: envNamed, options: envOptions },
+    ]);
     for (const g of GLOBALS) {
         const value = process.env["TYPESHIP_" + g.envSuffix];
         if (value !== undefined)
@@ -124,15 +145,25 @@ function makeClient() {
     }
     // The local MCP server identifies itself (surface + the client it serves, when announced).
     options.defaultHeaders = { "User-Agent": PKG_NAME + "-mcp/" + SERVER_VERSION + " (typeship" + (MCP_CLIENT_NAME ? "; client=" + MCP_CLIENT_NAME : "") + ")" };
-    return new TypeshipClient(options);
+    // Keep the SDK's machine-token cache while re-evaluating local configuration.
+    const key = createHash("sha256").update(JSON.stringify([options, config, profile?.name, stored?.oauth?.sessionId, null, process.env["TYPESHIP_DEBUG"]])).digest("hex");
+    if (clientInstance && clientKey === key)
+        return clientInstance;
+    const client = new TypeshipClient(options);
+    clientKey = key;
+    CLIENT_CREDENTIALS.set(client, Object.keys(options.credentials ?? {}).length > 0 || AUTH_SCALARS.some((a) => options[a.option] !== undefined) || options.basicAuth !== undefined || options.bearerToken !== undefined || options.clientCredentials !== undefined);
+    return (clientInstance = client);
 }
 let clientInstance;
-function getClient() {
-    return (clientInstance ??= makeClient());
+let clientKey = "";
+const CLIENT_CREDENTIALS = new WeakMap();
+/** Resolve configuration and credentials for each tool call, including login/logout changes. */
+function getClient(op) {
+    return makeClient(op);
 }
 /** Run one operation through the generated SDK: the same client, the same
  * typed errors and pagination a hand-written caller would get. */
-async function callOperation(op, rawArgs, authHeader) {
+async function callOperationRaw(op, rawArgs, remote, client) {
     // Arguments are checked against the tool's schema first: unknown names,
     // wrong types and missing requirements come back as one isError result,
     // nothing reaches the API half-formed and nothing is dropped silently.
@@ -149,7 +180,7 @@ async function callOperation(op, rawArgs, authHeader) {
     // argument errors, reported before anything is sent.
     const fileIssues = [];
     let rawBody = op.bodyStyle === "data" ? args.body : undefined;
-    if (LOCAL_PROCESS) {
+    if (LOCAL_PROCESS && !remote) {
         for (const p of op.params) {
             if (p.type !== "file" || typeof values[p.name] !== "string")
                 continue;
@@ -172,37 +203,80 @@ async function callOperation(op, rawArgs, authHeader) {
     if (fileIssues.length > 0)
         return argumentsError(op, fileIssues);
     const callArgs = buildArgs(op, values, rawBody, typeof args.select === "string" ? args.select : undefined);
-    if (authHeader)
-        callArgs.push({ headers: { Authorization: authHeader } });
     const errorContext = {
-        authHint: authHeader !== undefined ? AUTH_HINT_HTTP : AUTH_HINT_STDIO,
+        authHint: remote ? AUTH_HINT_HTTP : AUTH_HINT_STDIO,
         docsUrl: docsSource.docsUrl(),
-        hadCredential: authHeader !== undefined || AUTH_SCALARS.some((a) => process.env[a.env] !== undefined) || readJson("credentials.json") !== null,
+        hadCredential: !!remote || CLIENT_CREDENTIALS.get(client) === true,
     };
     const shape = { fields, maxChars, pagination: op.pagination, args };
     try {
-        const target = getClient()[op.resource];
+        const target = client[op.resource];
         const result = await target[op.method](...callArgs);
         if (!result.ok)
             return errorOutcome(result.error, errorContext);
         if (op.paginated) {
             const page = result.data;
-            return pageOutcome(page.items, page.nextPageParams(), shape);
+            return pageOutcome(page.items, page.nextPageParams(), { ...shape, requestId: page.response.requestId });
         }
         // A binary body (the SDK hands back a Blob): an image block, or a file
         // on disk, never "{}".
         if (result.data instanceof Blob)
-            return binaryOutcome(result.data, { tool: op.tool, ...(LOCAL_PROCESS ? { saveBinary } : {}) });
+            return binaryOutcome(result.data, { tool: op.tool, ...(LOCAL_PROCESS && !remote ? { saveBinary } : {}) });
         return dataOutcome(result.data, shape);
     }
     catch (e) {
         return textError(e.message ?? "Tool call failed");
     }
 }
+/** Name-or-ID resolution is the one wrapper around the ordinary executor,
+ * so a direct operation tool and compact execute take exactly the same path. */
+const REFERENCE_CACHES = new Map();
+function referenceCacheFor(authHeader) {
+    const key = createHash("sha256").update(JSON.stringify([authHeader ?? "stdio", clientKey])).digest("hex");
+    let cache = REFERENCE_CACHES.get(key);
+    if (!cache) {
+        cache = new Map();
+        REFERENCE_CACHES.set(key, cache);
+        while (REFERENCE_CACHES.size > 16)
+            REFERENCE_CACHES.delete(REFERENCE_CACHES.keys().next().value);
+    }
+    return cache;
+}
+async function callOperation(op, rawArgs, remote) {
+    const prepared = prepareCall(op, rawArgs, { maxChars: MAX_RESULT_CHARS });
+    if (!prepared.ok)
+        return prepared.outcome;
+    // One client/session for the entire tool, including name-to-ID lookups.
+    // If login changes during a lookup, the token callback rejects the old session.
+    let client;
+    try {
+        client = remote ? await remote.client() : getClient(op);
+    }
+    catch (error) {
+        if (remote && error instanceof McpAccountLinkRequired)
+            throw error;
+        return textError(remote ? "API access is unavailable for this MCP account. Reconnect your API account or contact the server owner." : error.message);
+    }
+    const resolved = await resolveReferences(op, prepared.call.args, {
+        ops: OPS,
+        identityTool: IDENTITY_TOOL,
+        cache: remote?.references ?? referenceCacheFor(),
+        runOperation: (source, args) => callOperationRaw(source, args, remote, client),
+    });
+    if (!resolved.ok)
+        return resolved.outcome;
+    const args = {
+        ...resolved.args,
+        ...(prepared.call.fields ? { fields: prepared.call.fields.map((path) => path.join(".")) } : {}),
+    };
+    return callOperationRaw(op, args, remote, client);
+}
 /** Running as a process on this machine (stdio, or --http launched here),
  * as opposed to imported by a worker: the server can read and write local
  * files, so uploads are tools and binaries are saved to disk. */
 const LOCAL_PROCESS = invokedDirectly();
+/** Saved human sessions are available only to local stdio, never HTTP/worker callers. */
+const LOCAL_CREDENTIALS = LOCAL_PROCESS && !ARGV.includes("--http");
 /** The callable operations: event streams are CLI-only, uploads are tools
  * only on a local server (mcpExposed), writes are out under --read-only,
  * and --tools narrows to a subset. A hidden operation is unknown to
@@ -224,30 +298,40 @@ function saveBinary(bytes, _mediaType, suggestedName) {
 }
 const docsSource = {
     ops: MCP_OPS,
+    omittedOps: OMITTED_OPS,
+    generatedOperationCount: OPS.length,
     docsUrl: () => readJson("config.json")?.docsUrl ?? DOCS_URL_DEFAULT,
+    docsIndexUrl: () => readJson("config.json")?.docsUrl ? null : DOCS_INDEX_URL_DEFAULT,
     fetchText: fetchDocsText,
 };
-/** The MCP server for one request context (the HTTP transport passes the
- * caller's Authorization through; stdio has none). */
-function serverFor(authHeader) {
+function serverFor(remote) {
+    const operations = remote ? visibleOps(MCP_OPS, { uploads: false }) : MCP_OPS;
+    const source = remote ? { ...docsSource, ops: operations } : docsSource;
     const website = docsSource.docsUrl();
     return {
         serverInfo: { name: SERVER_NAME, title: "typeship", version: SERVER_VERSION, ...(website ? { websiteUrl: website } : {}) },
         instructions: serverInstructions({
             title: "typeship",
-            toolCount: MCP_OPS.length,
+            ops: operations,
+            toolCount: operations.length,
+            generatedOperationCount: OPS.length,
+            omittedOps: docsSource.omittedOps,
             mode: TOOL_MODE,
             readOnly: READ_ONLY,
             hiddenWrites: HIDDEN_WRITES,
-            authHint: authHeader !== undefined ? AUTH_HINT_HTTP : AUTH_HINT_STDIO,
+            authHint: remote ? AUTH_HINT_HTTP : AUTH_HINT_STDIO,
             identityTool: MCP_OPS.some((o) => o.tool === IDENTITY_TOOL) ? IDENTITY_TOOL : null,
-            uploads: HAS_UPLOADS,
+            referenceResolution: MCP_OPS.some((o) => o.params.some((p) => p.resolve && typeof p.resolve === "object")),
+            uploads: !remote && HAS_UPLOADS,
             custom: CUSTOM_INSTRUCTIONS,
         }),
         toolsTtlMs: TOOLS_TTL_MS,
-        listTools: () => toolDefinitions(docsSource.ops, TOOL_MODE),
+        listTools: () => toolDefinitions(source.ops, TOOL_MODE, source.omittedOps),
+        unknownToolMessage: TOOL_MODE === "meta"
+            ? (name) => "Unknown tool: " + name + ". This server uses compact mode; call search_docs to discover an operation, then call execute with operation: \"" + name + "\"."
+            : undefined,
         callTool: async (name, args) => {
-            const shared = await callSharedTool(name, args, docsSource, (op, opArgs) => callOperation(op, opArgs, authHeader));
+            const shared = await callSharedTool(name, args, source, (op, opArgs) => callOperation(op, opArgs, remote));
             if (shared !== undefined)
                 return shared;
             // tools/list is the callable contract. In meta mode every operation
@@ -255,8 +339,8 @@ function serverFor(authHeader) {
             // confirmation gate; an unlisted operation name must stay unknown.
             if (TOOL_MODE !== "operations")
                 return undefined;
-            const op = MCP_OPS.find((o) => o.tool === name);
-            return op ? callOperation(op, args, authHeader) : undefined;
+            const op = operations.find((o) => o.tool === name);
+            return op ? callOperation(op, args, remote) : undefined;
         },
     };
 }
@@ -266,7 +350,7 @@ function serverFor(authHeader) {
  * validating the header when present (DNS-rebinding defense), so browser
  * callers must be same-host, localhost, or listed in
  * TYPESHIP_MCP_ALLOWED_ORIGINS (comma-separated, "*" for any). */
-function originAllowed(request) {
+function originAllowed(request, resourceOrigin) {
     const origin = request.headers.get("origin");
     if (origin === null)
         return true;
@@ -275,9 +359,9 @@ function originAllowed(request) {
         return true;
     try {
         const o = new URL(origin);
-        if (o.host === new URL(request.url).host)
+        if (o.origin === resourceOrigin)
             return true;
-        return ["localhost", "127.0.0.1", "[::1]"].includes(o.hostname);
+        return ["localhost", "127.0.0.1", "[::1]"].includes(new URL(resourceOrigin).hostname) && ["localhost", "127.0.0.1", "[::1]"].includes(o.hostname);
     }
     catch {
         return false;
@@ -286,45 +370,75 @@ function originAllowed(request) {
 function corsHeaders(request) {
     return {
         "Access-Control-Allow-Origin": request.headers.get("origin") ?? "*",
-        "Access-Control-Allow-Methods": "POST, OPTIONS",
+        "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+        "Access-Control-Expose-Headers": "WWW-Authenticate",
         "Access-Control-Allow-Headers": "Content-Type, Authorization, Accept, MCP-Protocol-Version, Mcp-Method, Mcp-Name",
         Vary: "Origin",
     };
 }
-function protectedResourceMetadata(origin) {
-    return {
-        resource: origin,
-        ...(OAUTH_ISSUER ? { authorization_servers: [OAUTH_ISSUER] } : {}),
-        bearer_methods_supported: ["header"],
-    };
+/** Create once at startup; metadata/key caching is isolated to this server. */
+export function createMcpHandler(options) {
+    const configured = {};
+    const apiBaseUrl = process.env["TYPESHIP_BASE_URL"] ?? DEFAULT_BASE_URL ?? undefined;
+    const authorizer = createMcpAuthorizer(options.authorization ?? { issuer: configured.mcpIssuer ?? "", resource: configured.mcpResource ?? "", ...(configured.mcpJwksUrl ? { jwksUrl: configured.mcpJwksUrl } : {}), scopes: configured.mcpScopes ?? [] }, options.introspection);
+    if (typeof options.credentialsFor !== "function")
+        throw new Error("Provide credentialsFor to resolve each MCP caller's upstream API credentials.");
+    return (request) => authorizedHttp(request, authorizer, options.credentialsFor, apiBaseUrl).catch(() => new Response(JSON.stringify({ error: "MCP request failed." }), { status: 500, headers: { "Content-Type": "application/json", "Cache-Control": "no-store" } }));
 }
-/** Fetch-style handler: mount in any runtime (workers, serverless, node).
- * Never rejects: every failure is an HTTP or JSON-RPC error response. */
-export async function handleHttp(request) {
+/** A generated entry point cannot infer the host application's user-to-API
+ * credential mapping. It remains closed until the owner installs a handler. */
+export async function handleHttp(_request) {
+    return new Response(JSON.stringify({ error: "Configure createMcpHandler with MCP authorization and credentialsFor before serving remote requests." }), { status: 503, headers: { "Content-Type": "application/json", "Cache-Control": "no-store" } });
+}
+async function authorizedHttp(request, authorizer, credentialsFor, apiBaseUrl) {
     const url = new URL(request.url);
-    const cors = corsHeaders(request);
-    const json = (status, body, extra = {}) => new Response(JSON.stringify(body), { status, headers: { ...cors, "Content-Type": "application/json", ...extra } });
+    const resource = new URL(authorizer.configuration.resource);
+    const cors = originAllowed(request, resource.origin) ? corsHeaders(request) : {};
+    const json = (status, body, extra = {}) => new Response(JSON.stringify(body), { status, headers: { ...cors, "Content-Type": "application/json", "Cache-Control": "no-store", ...extra } });
     if (request.method === "OPTIONS") {
-        return new Response(null, { status: originAllowed(request) ? 204 : 403, headers: cors });
+        return new Response(null, { status: originAllowed(request, resource.origin) ? 204 : 403, headers: cors });
     }
-    if (!originAllowed(request)) {
+    if (!originAllowed(request, resource.origin)) {
         return json(403, { jsonrpc: "2.0", error: { code: -32600, message: "Origin not allowed. Set TYPESHIP_MCP_ALLOWED_ORIGINS to permit browser callers." } });
     }
-    if (url.pathname.endsWith("/.well-known/oauth-protected-resource")) {
-        return json(200, protectedResourceMetadata(url.origin));
-    }
+    const metadataPath = "/.well-known/oauth-protected-resource" + resource.pathname.replace(/\/$/, "");
+    if (url.pathname === metadataPath && request.method === "GET")
+        return json(200, authorizer.metadata());
+    if (url.pathname !== resource.pathname)
+        return json(404, { error: "Unknown MCP endpoint." });
     if (request.method !== "POST") {
         // GET streams, DELETE (session end) and Mcp-Session-Id belong to earlier
         // revisions; the spec asks modern-only servers to answer 405.
         return json(405, { error: "POST JSON-RPC messages to this endpoint (MCP " + SUPPORTED_PROTOCOL_VERSIONS[0] + ", stateless)." }, { Allow: "POST, OPTIONS" });
     }
-    const authHeader = request.headers.get("authorization") ?? undefined;
-    const envHasAuth = AUTH_SCALARS.some((a) => process.env[a.env] !== undefined);
-    if (OAUTH_ISSUER && !authHeader && !envHasAuth) {
-        return json(401, { error: "Authorization required." }, {
-            "WWW-Authenticate": 'Bearer resource_metadata="' + url.origin + '/.well-known/oauth-protected-resource"',
-        });
-    }
+    let principal;
+    try {
+        principal = await authorizer.authorize(request.headers.get("authorization"));
+    }
+    catch (error) {
+        const failure = error instanceof McpAuthorizationError ? error : new McpAuthorizationError(503, "authorization_unavailable");
+        return json(failure.status, { error: failure.code, message: failure.message }, failure.status === 503 ? {} : { "WWW-Authenticate": authorizer.challenge(failure.code === "insufficient_scope" ? "insufficient_scope" : "invalid_token") });
+    }
+    let client;
+    const remote = { references: new Map(), client: () => client ??= (async () => {
+            const credentials = await credentialsFor(principal);
+            if (!credentials || typeof credentials !== "object")
+                throw new Error("API credentials unavailable.");
+            const baseUrl = apiBaseUrl;
+            if (typeof baseUrl !== "string")
+                throw new Error("Configure the upstream API URL.");
+            if (credentials.baseUrl !== undefined && credentials.baseUrl !== baseUrl)
+                throw new Error("API credentials target a different API URL.");
+            const token = request.headers.get("authorization").slice(7);
+            const transport = credentials.fetch ?? fetch;
+            return new TypeshipClient({ ...credentials, baseUrl, fetch: async (input, init) => {
+                    const headers = new Headers(init?.headers);
+                    const destination = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
+                    if ([...headers.values()].some(value => value === token || value === "Bearer " + token) || [...destination.searchParams.values()].includes(token))
+                        throw new Error("An MCP connection token cannot authorize an upstream API request.");
+                    return transport(input, init);
+                } });
+        })() };
     let incoming;
     try {
         incoming = await request.json();
@@ -345,10 +459,10 @@ export async function handleHttp(request) {
     noteClientInfo(parsed);
     let outcome;
     try {
-        outcome = await handleRpc(serverFor(authHeader), parsed);
+        outcome = await handleRpc(serverFor(remote), parsed);
     }
     catch (e) {
-        return json(500, { jsonrpc: "2.0", id: parsed.id ?? null, error: { code: -32603, message: e.message ?? "Internal error" } });
+        return json(500, { jsonrpc: "2.0", id: parsed.id ?? null, error: { code: -32603, message: "Internal error" } });
     }
     if (outcome.message === null) {
         return new Response(null, { status: outcome.status, headers: cors });
@@ -416,7 +530,7 @@ async function startStdio() {
         })
             .catch((e) => {
             if (id !== undefined) {
-                write({ jsonrpc: "2.0", id: id ?? null, error: { code: -32603, message: e.message ?? "Internal error" } });
+                write({ jsonrpc: "2.0", id: id ?? null, error: { code: -32603, message: "Internal error" } });
             }
         });
     });

package/dist/named-credentials.d.ts

@@ -0,0 +1,21 @@
+/** Runtime credentials keyed by the API's exact security-scheme names. */
+export type NamedCredential = string | {
+    username: string;
+    password: string;
+};
+export type NamedCredentials = Record<string, NamedCredential>;
+export type CredentialSchemes = Record<string, {
+    kind: string;
+    options: string[];
+}>;
+export declare function parseNamedCredentials(value: unknown, schemes: CredentialSchemes): NamedCredentials;
+/** Low-to-high source order. Within a source, exact names beat convenience options. */
+export declare function resolveNamedCredentials(schemes: CredentialSchemes, layers: {
+    named?: NamedCredentials;
+    options?: Record<string, unknown>;
+}[]): NamedCredentials;
+/** Make convenience and named inputs comparable without expanding combinations. */
+export declare function namedCredentialAvailability(schemes: CredentialSchemes, options: Set<string>, named: NamedCredentials): Set<string>;
+/** Bound file/stdin reads before allocating a full credential document. */
+export declare function readNamedCredentialsFile(input: string, schemes: CredentialSchemes): NamedCredentials;
+//# sourceMappingURL=named-credentials.d.ts.map

package/dist/named-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"named-credentials.d.ts","sourceRoot":"","sources":["../src/named-credentials.ts"],"names":[],"mappings":"AAEA,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAC9E,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAC/D,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAAC;AAEpF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAqBlG;AAED,uFAAuF;AACvF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAAE,GAAG,gBAAgB,CAa/J;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,gBAAgB,GAAG,GAAG,CAAC,MAAM,CAAC,CAKlI;AAED,2EAA2E;AAC3E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAkBpG"}

package/dist/named-credentials.js

@@ -0,0 +1,86 @@
+import { openSync, readSync, closeSync } from "node:fs";
+export function parseNamedCredentials(value, schemes) {
+    if (typeof value === "string") {
+        if (new TextEncoder().encode(value).byteLength > 1_048_576)
+            throw new Error("Named credentials exceed the 1 MiB limit.");
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            throw new Error("Named credentials must be a JSON object keyed by security scheme. Credential contents are not included in errors.");
+        }
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Named credentials must be a JSON object keyed by security scheme.");
+    const result = Object.create(null);
+    for (const [name, credential] of Object.entries(value)) {
+        if (!Object.hasOwn(schemes, name))
+            throw new Error("Named credentials contain an unknown or unsupported security scheme. Check the names listed by login --help.");
+        if (schemes[name].kind === "basic") {
+            if (!credential || typeof credential !== "object" || Array.isArray(credential) || Object.keys(credential).some((key) => key !== "username" && key !== "password") ||
+                typeof credential.username !== "string" || typeof credential.password !== "string" || !credential.username || !credential.password || credential.username.includes(":")) {
+                throw new Error("A named Basic credential requires a nonempty username and password; the username cannot contain a colon.");
+            }
+            result[name] = { username: credential.username, password: credential.password };
+        }
+        else {
+            if (typeof credential !== "string" || !credential || /[\x00-\x1f\x7f]/.test(credential) || (schemes[name].kind === "bearer" && credential.includes(" ")))
+                throw new Error("A named token or API key must be a nonempty string without control characters; bearer tokens cannot contain spaces.");
+            result[name] = credential;
+        }
+    }
+    return result;
+}
+/** Low-to-high source order. Within a source, exact names beat convenience options. */
+export function resolveNamedCredentials(schemes, layers) {
+    const resolved = Object.create(null);
+    for (const layer of layers) {
+        for (const [name, scheme] of Object.entries(schemes)) {
+            for (const option of scheme.options) {
+                if (option === "clientCredentials")
+                    continue;
+                const value = layer.options?.[option];
+                if (value !== undefined)
+                    resolved[name] = value;
+            }
+        }
+        if (layer.named)
+            Object.assign(resolved, parseNamedCredentials(layer.named, schemes));
+    }
+    return resolved;
+}
+/** Make convenience and named inputs comparable without expanding combinations. */
+export function namedCredentialAvailability(schemes, options, named) {
+    for (const [name, scheme] of Object.entries(schemes)) {
+        if (Object.hasOwn(named, name) || scheme.options.some((option) => options.has(option)))
+            options.add("credentials." + name);
+    }
+    return options;
+}
+/** Bound file/stdin reads before allocating a full credential document. */
+export function readNamedCredentialsFile(input, schemes) {
+    let fd;
+    const chunks = [];
+    let total = 0;
+    try {
+        fd = input === "-" ? 0 : openSync(input.slice(1), "r");
+        while (true) {
+            const buffer = Buffer.alloc(Math.min(32_768, 1_048_577 - total));
+            const size = readSync(fd, buffer, 0, buffer.length, null);
+            if (!size)
+                break;
+            total += size;
+            if (total > 1_048_576)
+                throw new Error("size");
+            chunks.push(buffer.subarray(0, size));
+        }
+    }
+    catch {
+        throw new Error("Cannot read named credentials. Supply a readable JSON file or stdin input of at most 1 MiB.");
+    }
+    finally {
+        if (fd !== undefined && input !== "-")
+            closeSync(fd);
+    }
+    return parseNamedCredentials(Buffer.concat(chunks).toString("utf8"), schemes);
+}