@typeship-ax/mcp 0.6.0 → 0.8.0

package/dist/mcp-protocol.js

@@ -15,6 +15,7 @@
  * Spec: https://modelcontextprotocol.io/specification/2026-07-28
  */
 import { dateKindOf, relativeDate } from "./dates.js";
+import { resolveDocsContentUrl } from "./docs.js";
 export const MCP_PROTOCOL_VERSION = "2026-07-28";
 /** Revisions served. Legacy (initialize-handshake) revisions are not; an
  * initialize request gets an error naming this list, as the spec asks of
@@ -185,7 +186,7 @@ export async function handleRpc(server, incoming) {
             const started = Date.now();
             const outcome = await server.callTool(name, args);
             if (outcome === undefined)
-                return rpcError(id, -32602, "Unknown tool: " + name, 400);
+                return rpcError(id, -32602, server.unknownToolMessage?.(name) ?? "Unknown tool: " + name, 400);
             if (server.afterToolCall)
                 await server.afterToolCall(name, outcome, Date.now() - started);
             // A tool that declares an outputSchema MUST return structuredContent,
@@ -275,8 +276,18 @@ export function exampleFromSchema(schema, field = "value", depth = 0) {
         return node.examples[0];
     if (node.default !== undefined)
         return node.default;
-    if (Array.isArray(node.enum) && node.enum.length > 0)
+    if (Array.isArray(node.enum) && node.enum.length > 0) {
+        if (typeof node.pattern === "string") {
+            try {
+                const pattern = new RegExp(node.pattern);
+                const matching = node.enum.find((value) => typeof value === "string" && pattern.test(value));
+                if (matching !== undefined)
+                    return matching;
+            }
+            catch { /* malformed patterns are ignored for examples */ }
+        }
         return node.enum.find((v) => v !== null) ?? node.enum[0];
+    }
     const variants = (Array.isArray(node.oneOf) ? node.oneOf : Array.isArray(node.anyOf) ? node.anyOf : null);
     if (variants) {
         const useful = variants.find((v) => v && typeof v === "object" && v.type !== "null") ?? variants[0];
@@ -316,7 +327,10 @@ export function exampleFromSchema(schema, field = "value", depth = 0) {
     if (type === "string" || type === undefined) {
         const format = typeof node.format === "string" ? node.format : "";
         const lower = field.toLowerCase();
-        let value = format === "date-time" ? "2026-01-15T12:00:00Z"
+        const min = typeof node.minLength === "number" ? node.minLength : 0;
+        const max = typeof node.maxLength === "number" ? node.maxLength : undefined;
+        const patterned = typeof node.pattern === "string" ? exampleMatchingPattern(node.pattern, min, max) : null;
+        let value = patterned ?? (format === "date-time" ? "2026-01-15T12:00:00Z"
             : format === "date" ? "2026-01-15"
                 : format === "email" || lower.includes("email") ? "person@example.com"
                     : (format === "uri" || format === "url" || lower.endsWith("url")) && (lower.includes("webhook") || lower.includes("callback")) ? "https://example.com/webhook"
@@ -327,16 +341,47 @@ export function exampleFromSchema(schema, field = "value", depth = 0) {
                                         : lower.includes("version") ? "1.0.0"
                                             : /(^|_)id$|Id$/.test(field) ? (lower === "id" ? "id" : field.replace(/[_-]?id$/i, "")) + "_123"
                                                 : lower.includes("name") ? "example"
-                                                    : "value";
-        const min = typeof node.minLength === "number" ? node.minLength : 0;
+                                                    : "value");
         while (value.length < min)
             value += "x";
-        if (typeof node.maxLength === "number")
-            value = value.slice(0, node.maxLength);
+        if (max !== undefined)
+            value = value.slice(0, max);
         return value;
     }
     return null;
 }
+/** A useful value for the common API-id pattern (`^agt_`, `^src_[a-z0-9]+$`).
+ * Full regex generation would be surprising and heavyweight; an anchored
+ * literal prefix plus ordinary id suffix covers the schemas that use a
+ * pattern to communicate a typed identifier. Every candidate is checked by
+ * the actual RegExp before it is returned. */
+function exampleMatchingPattern(pattern, minLength, maxLength) {
+    let regex;
+    try {
+        regex = new RegExp(pattern);
+    }
+    catch {
+        return null;
+    }
+    const match = /^\^((?:\\.|[A-Za-z0-9_-])+)/.exec(pattern);
+    const prefix = match?.[1]?.replace(/\\(.)/g, "$1") ?? "";
+    const fit = (candidate) => {
+        let value = candidate;
+        while (value.length < minLength)
+            value += "x";
+        if (maxLength !== undefined)
+            value = value.slice(0, maxLength);
+        return value;
+    };
+    const candidates = [prefix + "123", prefix + "example", prefix, "example", "value"];
+    for (const candidate of candidates) {
+        const value = fit(candidate);
+        regex.lastIndex = 0;
+        if (regex.test(value))
+            return value;
+    }
+    return null;
+}
 export function exampleArgumentsFromSchema(inputSchema) {
     const value = exampleFromSchema(inputSchema, "arguments");
     return value && typeof value === "object" && !Array.isArray(value) ? value : {};
@@ -400,7 +445,7 @@ export const EXECUTE_TOOL = {
     inputSchema: {
         type: "object",
         properties: {
-            operation: { type: "string", description: "Operation tool name, e.g. accounts_create" },
+            operation: { type: "string", description: "Operation tool name returned by search_docs" },
             arguments: { type: "object", description: "Operation arguments keyed by parameter name" },
             confirm: { type: "boolean", description: "Required and must be true for destructive operations. Omit for reads and ordinary writes." },
         },
@@ -433,36 +478,23 @@ export function parseIncludeList(value) {
  * three-tool "meta" shape (search_docs, read_docs, execute) that keeps huge
  * APIs from flooding an agent's context. Deterministic order.
  */
-export function toolDefinitions(ops, mode) {
+export function toolDefinitions(ops, mode, omittedOps = []) {
     if (mode === "meta") {
+        const execute = structuredClone(EXECUTE_TOOL);
+        const operation = execute.inputSchema.properties.operation;
+        if (ops[0])
+            operation.examples = [ops[0].tool];
+        const coverage = omittedOps.length > 0
+            ? " Generated " + ops.length + " of " + (ops.length + omittedOps.length) + " operations; search_docs names operations omitted by the plan limit."
+            : "";
         return [
-            { ...SEARCH_DOCS_TOOL, description: "Search this API's " + ops.length + " operations and, when a docs site is configured, its guides. Start here to find the operation you need." },
+            { ...SEARCH_DOCS_TOOL, description: "Search this API's " + ops.length + " generated operations and, when a docs site is configured, its guides. Start here to find the operation you need." + coverage },
             { ...READ_DOCS_TOOL, description: "Read an operation's full reference (arguments, schemas, authentication, safety and example) by tool name, or a docs-site guide page." },
-            EXECUTE_TOOL,
+            execute,
         ];
     }
     return [...ops.map(operationTool), SEARCH_DOCS_TOOL, READ_DOCS_TOOL];
 }
-/** How big a tools/list is, as agents pay for it. Characters of JSON and a
- * rough token count (one token per four characters, the usual estimate for
- * JSON). Generation and `<bin> mcp` report it. */
-export function toolsListSize(tools) {
-    const chars = JSON.stringify(tools).length;
-    return { tools: tools.length, chars, approxTokens: Math.round(chars / 4) };
-}
-/** Keep automatic per-operation discovery under roughly 10k tokens. The
- * schema, not merely the operation count, determines what an agent pays. */
-export const MCP_AUTO_MAX_TOOLS_LIST_CHARS = 40_000;
-export function resolveToolMode(ops, requested = "auto") {
-    if (requested === "operations" || requested === "meta") {
-        return { mode: requested, ...toolsListSize(toolDefinitions(ops, requested)) };
-    }
-    const operations = toolsListSize(toolDefinitions(ops, "operations"));
-    const mode = ops.length > 100 || operations.chars > MCP_AUTO_MAX_TOOLS_LIST_CHARS ? "meta" : "operations";
-    return mode === "operations"
-        ? { mode, ...operations }
-        : { mode, ...toolsListSize(toolDefinitions(ops, mode)) };
-}
 /** Resolve an operation by tool name or dotted resource.method. */
 export function findOperation(ops, wanted) {
     return ops.find((o) => o.tool === wanted)
@@ -480,6 +512,10 @@ export function serverInstructions(input) {
     parts.push(input.mode === "meta"
         ? input.title + " as MCP tools: search_docs, read_docs and execute over " + input.toolCount + " operations. Start with search_docs to find an operation, read_docs <tool> for its full argument reference, then execute it by name. Destructive operations require confirm: true on execute."
         : input.title + " as MCP tools: one tool per operation (" + input.toolCount + "), plus search_docs to find operations and read_docs <tool> for an operation's full argument reference.");
+    if (input.omittedOps?.length) {
+        const generated = input.generatedOperationCount ?? input.toolCount;
+        parts.push("Plan-limited generation: generated " + generated + " of " + (generated + input.omittedOps.length) + " operations. Omitted operations: " + input.omittedOps.map((op) => op.tool + " (" + op.httpMethod + " " + op.path + ")").join(", ") + ". Calling or searching for one returns PLAN_LIMIT with upgrade next_steps.");
+    }
     parts.push("Arguments use the API's wire names; an unknown, mistyped or missing argument returns an isError result listing each problem (nothing is dropped silently), and obvious forms are coerced (\"true\" to boolean, \"3\" to number, enum case).");
     parts.push("Paginated tools return items, hasMore and nextPage (the exact arguments for the following page). Pass fields (dotted paths) to keep only the result keys you need; oversized results are cut to whole items or keys with a truncated note saying how to ask for less.");
     parts.push("Errors carry error, code, message, status, the API's body and next_steps.");
@@ -786,12 +822,17 @@ export function pageOutcome(items, nextPage, options = {}) {
     const fields = options.fields ?? null;
     const maxChars = options.maxChars ?? DEFAULT_MAX_RESULT_CHARS;
     const shown = projectFields(items, fields);
-    const full = { items: shown, hasMore: nextPage !== null, ...(nextPage !== null ? { nextPage } : {}) };
+    const full = {
+        items: shown,
+        hasMore: nextPage !== null,
+        ...(nextPage !== null ? { nextPage } : {}),
+        ...(options.requestId ? { request_id: options.requestId } : {}),
+    };
     const text = JSON.stringify(full);
     if (text.length <= maxChars) {
         return { text, isError: false, structured: full };
     }
-    const overhead = JSON.stringify({ items: [], hasMore: true, nextPage: nextPage ?? {}, truncated: { omitted: 0, of: 0, reason: "x".repeat(160), next_steps: ["x".repeat(220), "x".repeat(120)] } }).length;
+    const overhead = JSON.stringify({ items: [], hasMore: true, nextPage: nextPage ?? {}, ...(options.requestId ? { request_id: options.requestId } : {}), truncated: { omitted: 0, of: 0, reason: "x".repeat(160), next_steps: ["x".repeat(220), "x".repeat(120)] } }).length;
     const k = itemsThatFit(shown, Math.max(0, maxChars - overhead));
     const omitted = shown.length - k;
     const pg = options.pagination;
@@ -818,6 +859,7 @@ export function pageOutcome(items, nextPage, options = {}) {
         items: shown.slice(0, k),
         hasMore: resume !== null ? true : nextPage !== null,
         ...(resume !== null ? { nextPage: resume } : nextPage !== null ? { nextPage } : {}),
+        ...(options.requestId ? { request_id: options.requestId } : {}),
         truncated: {
             omitted,
             of: shown.length,
@@ -961,6 +1003,7 @@ export function classifyError(error, context = {}) {
         return { code: "NETWORK_ERROR", nextSteps: ["The API could not be reached (network, DNS, TLS or timeout). Retry once with backoff; do not loop."] };
     }
     const status = typeof e.status === "number" ? e.status : 0;
+    const body = e.body;
     const auth = context.authHint ? context.authHint.trim().replace(/[.]?$/, ".") : null;
     if (status === 401) {
         return context.hadCredential
@@ -977,6 +1020,15 @@ export function classifyError(error, context = {}) {
         const retryAfter = extractRetryAfter(e);
         return { code: "RATE_LIMITED", nextSteps: [retryAfter ? "Wait " + retryAfter + " seconds, then call again." : "Back off and retry once; the request was already retried with the server's Retry-After."] };
     }
+    if (status === 422 && body?.errors?.[0]?.code === "spec_error") {
+        return {
+            code: "SPEC_INVALID",
+            nextSteps: [
+                "The API rejected the spec it was given; its error message names the invalid part.",
+                context.docsUrl ? "Use search_docs with the error message, fix the spec, then call again." : "Fix the spec, then call again.",
+            ],
+        };
+    }
     if (status === 400 || status === 409 || status === 413 || status === 422) {
         return { code: "INVALID_REQUEST", nextSteps: ["Read body for the field the API named, fix that argument and call again."] };
     }
@@ -1003,11 +1055,16 @@ function notFoundNextSteps(message, body) {
 export function errorOutcome(error, context = {}) {
     const e = error;
     const { code, nextSteps } = classifyError(error, context);
+    const bodyRequestId = e?.body && typeof e.body === "object" && !Array.isArray(e.body)
+        ? e.body.request_id ?? e.body.requestId
+        : undefined;
+    const requestId = e?.response?.requestId ?? (typeof bodyRequestId === "string" ? bodyRequestId : undefined);
     const structured = {
         error: e?.name ?? "Error",
         code,
         message: e?.message,
         ...(typeof e?.status === "number" ? { status: e.status } : {}),
+        ...(requestId ? { request_id: requestId } : {}),
         ...(e?.body !== undefined ? { body: e.body } : {}),
         ...(context.docsUrl ? { docs_url: context.docsUrl } : {}),
         next_steps: nextSteps,
@@ -1018,32 +1075,29 @@ export function textError(text, code = "CALL_FAILED", nextSteps = []) {
     const structured = { error: "Error", code, message: text, next_steps: nextSteps };
     return { text: JSON.stringify(structured), isError: true, structured };
 }
-function docsPageUrl(source, pathOrFile) {
-    const base = source.docsUrl();
-    if (base === null)
-        return null;
-    try {
-        const baseUrl = new URL(base);
-        if (baseUrl.protocol !== "https:" && baseUrl.protocol !== "http:")
-            return null;
-        const target = /^https?:\/\//.test(pathOrFile)
-            ? new URL(pathOrFile)
-            : new URL(pathOrFile.replace(/^\/+/, ""), baseUrl.toString().replace(/\/+$/, "") + "/");
-        // llms.txt commonly contains absolute links, but a docs tool is not a
-        // general-purpose URL fetcher. Keeping every page on the configured
-        // origin prevents an agent from turning hosted MCP into an SSRF proxy.
-        if (target.origin !== baseUrl.origin || target.username || target.password)
-            return null;
-        return target.toString();
-    }
-    catch {
-        return null;
-    }
-}
 async function fetchDocs(source, pathOrFile) {
-    const url = docsPageUrl(source, pathOrFile);
+    const url = resolveDocsContentUrl(source.docsUrl(), source.docsIndexUrl?.() ?? null, pathOrFile);
     return url === null ? null : source.fetchText(url);
 }
+function coverageText(source) {
+    const omitted = source.omittedOps ?? [];
+    const generated = source.generatedOperationCount ?? source.ops.length;
+    return omitted.length > 0
+        ? "Coverage: generated " + generated + " of " + (generated + omitted.length) + " operations. Omitted by the plan limit: " + omitted.map((op) => op.tool + " (" + op.httpMethod + " " + op.path + ")").join(", ") + "."
+        : null;
+}
+function omittedPlanLimit(ops, requested) {
+    const structured = {
+        error: "PlanLimitError",
+        code: "PLAN_LIMIT",
+        message: requested
+            ? "The operation " + requested + " exists in the API Definition but was omitted from this generated package by its plan limit."
+            : "Matching operations exist in the API Definition but were omitted from this generated package by its plan limit.",
+        omitted_operations: ops.map((op) => ({ tool: op.tool, method: op.httpMethod, path: op.path })),
+        next_steps: ["Upgrade at https://typeship.dev/pricing and regenerate the package without the operation cap.", "Do not invent or retry an omitted operation against this generated package."],
+    };
+    return { text: JSON.stringify(structured), isError: true, structured };
+}
 export function referenceText(op) {
     const safety = operationSafety(op);
     const example = op.exampleArguments ?? exampleArgumentsFromSchema(op.inputSchema);
@@ -1114,12 +1168,20 @@ export function searchScore(op, query) {
     return score;
 }
 export async function docsSearch(source, query, page = 1) {
-    const term = query.toLowerCase();
+    const term = query.trim().toLowerCase();
+    const terms = searchTerms(query);
     const sections = [];
     const ranked = source.ops
         .map((op) => ({ op, score: searchScore(op, query) }))
         .filter((r) => r.score > 0)
         .sort((a, b) => b.score - a.score || a.op.tool.localeCompare(b.op.tool));
+    const omittedRanked = (source.omittedOps ?? [])
+        .map((op) => ({ op, score: searchScore(op, query) }))
+        .filter((result) => result.score > 0)
+        .sort((a, b) => b.score - a.score || a.op.tool.localeCompare(b.op.tool));
+    const exactOmitted = findOperation(source.omittedOps ?? [], query);
+    if (exactOmitted)
+        return omittedPlanLimit([exactOmitted], exactOmitted.tool);
     const pageIndex = Math.max(1, Math.floor(page)) - 1;
     const slice = ranked.slice(pageIndex * SEARCH_PAGE_SIZE, (pageIndex + 1) * SEARCH_PAGE_SIZE);
     if (slice.length > 0) {
@@ -1132,31 +1194,56 @@ export async function docsSearch(source, query, page = 1) {
         sections.push("No reference matches on page " + (pageIndex + 1) + "; there are " + Math.ceil(ranked.length / SEARCH_PAGE_SIZE) + " pages.");
     }
     const prose = await fetchDocs(source, "llms-full.txt");
+    let proseMatchCount = 0;
     if (prose !== null) {
         let heading = "";
         const proseMatches = [];
         for (const line of prose.split("\n")) {
             if (/^#{1,3} /.test(line))
                 heading = line.replace(/^#+ /, "").trim();
-            else if (line.toLowerCase().includes(term) && proseMatches.length < 15) {
-                proseMatches.push("- [" + heading + "] " + line.trim().slice(0, 160));
+            else {
+                const lowerHeading = heading.toLowerCase();
+                const lowerLine = line.toLowerCase();
+                const matched = terms.filter((word) => lowerHeading.includes(word) || lowerLine.includes(word));
+                if (matched.length > 0) {
+                    const allTerms = matched.length === terms.length;
+                    proseMatches.push({
+                        heading,
+                        excerpt: line.trim().slice(0, 160),
+                        score: matched.length * 10 + (allTerms ? 50 : 0) + (lowerHeading.includes(term) || lowerLine.includes(term) ? 25 : 0),
+                    });
+                }
             }
         }
-        if (proseMatches.length > 0)
-            sections.push("Guide matches:\n" + proseMatches.join("\n"));
+        proseMatches.sort((a, b) => b.score - a.score || a.heading.localeCompare(b.heading) || a.excerpt.localeCompare(b.excerpt));
+        proseMatchCount = proseMatches.length;
+        if (proseMatches.length > 0) {
+            sections.push("Guide matches (best first):\n" + proseMatches.slice(0, 15).map((match) => "- [" + match.heading + "] " + match.excerpt).join("\n"));
+        }
+    }
+    if (omittedRanked.length > 0 && ranked.length === 0 && proseMatchCount === 0) {
+        return omittedPlanLimit(omittedRanked.map((result) => result.op));
     }
+    if (omittedRanked.length > 0) {
+        sections.push("Operations omitted by the plan limit:\n" + omittedRanked.slice(0, SEARCH_PAGE_SIZE).map((result) => "- " + result.op.tool + ": " + (result.op.summary ?? result.op.httpMethod + " " + result.op.path)).join("\n"));
+    }
+    const coverage = coverageText(source);
     if (sections.length === 0) {
         return {
-            text: "No matches for: " + query + (source.docsUrl() === null ? " (no docs site configured; only the API reference was searched)" : ""),
+            text: (coverage ? coverage + "\n\n" : "") + "No matches for: " + query + (source.docsUrl() === null && (source.docsIndexUrl?.() ?? null) === null ? " (a docs URL was not provided at generate time; only the API reference was searched)" : ""),
             isError: false,
         };
     }
-    return { text: sections.join("\n\n"), isError: false };
+    return { text: [...(coverage ? [coverage] : []), ...sections].join("\n\n"), isError: false };
 }
 export async function docsRead(source, page) {
     const opMatch = findOperation(source.ops, page);
+    const coverage = coverageText(source);
     if (opMatch)
-        return { text: referenceText(opMatch), isError: false };
+        return { text: [...(coverage ? [coverage] : []), referenceText(opMatch)].join("\n\n"), isError: false };
+    const omittedMatch = findOperation(source.omittedOps ?? [], page);
+    if (omittedMatch)
+        return omittedPlanLimit([omittedMatch], omittedMatch.tool);
     let target = page;
     if (!/^https?:\/\//.test(target)) {
         const index = await fetchDocs(source, "llms.txt");
@@ -1167,11 +1254,11 @@ export async function docsRead(source, page) {
     }
     const text = await fetchDocs(source, target);
     if (text === null) {
-        return textError(source.docsUrl() === null
-            ? "No docs site is configured for this server, and no operation matches \"" + page + "\"."
+        return textError(source.docsUrl() === null && (source.docsIndexUrl?.() ?? null) === null
+            ? "A docs URL was not provided at generate time, and no generated operation matches \"" + page + "\"."
             : "Couldn't fetch \"" + page + "\". Use search_docs to find pages.", "NOT_FOUND", ["search_docs finds operations and guide pages."]);
     }
-    return { text, isError: false };
+    return { text: [...(coverage ? [coverage] : []), text].join("\n\n"), isError: false };
 }
 /**
  * Dispatch for the shared tools (search_docs, read_docs, execute); returns
@@ -1193,8 +1280,12 @@ export async function callSharedTool(name, args, source, runOperation) {
         if (typeof args.operation !== "string")
             return argumentsError({ tool: name }, [{ code: "MISSING_ARGUMENT", argument: "operation", message: "execute requires an operation name." }]);
         const target = findOperation(source.ops, args.operation);
-        if (!target)
-            return textError("Unknown operation: " + args.operation + ".", "NOT_FOUND", ["search_docs finds operations by name, path or description."]);
+        if (!target) {
+            const omitted = findOperation(source.omittedOps ?? [], args.operation);
+            return omitted
+                ? omittedPlanLimit([omitted], omitted.tool)
+                : textError("Unknown operation: " + args.operation + ".", "NOT_FOUND", ["search_docs finds operations by name, path or description."]);
+        }
         if (operationSafety(target) === "destructive" && args.confirm !== true) {
             return textError("The destructive operation " + target.tool + " requires explicit confirmation.", "CONFIRMATION_REQUIRED", ["Review read_docs " + target.tool + ", then retry execute with confirm: true if the destructive effect is intended."]);
         }
@@ -1205,58 +1296,3 @@ export async function callSharedTool(name, args, source, runOperation) {
     }
     return undefined;
 }
-/** A fetch for docs pages: markdown preferred, same-origin redirects only,
- * a 10s deadline, and a 2 MB streaming cap. The caller already constrained
- * the first URL to its configured docs origin; redirects must not escape it. */
-export const MAX_DOCS_TEXT_BYTES = 2_000_000;
-export async function fetchDocsText(url) {
-    try {
-        const allowedOrigin = new URL(url).origin;
-        let current = url;
-        const signal = AbortSignal.timeout(10_000);
-        for (let redirects = 0; redirects <= 3; redirects += 1) {
-            const response = await fetch(current, {
-                headers: { Accept: "text/markdown, text/plain, */*" },
-                redirect: "manual",
-                signal,
-            });
-            if (response.status >= 300 && response.status < 400) {
-                const location = response.headers.get("location");
-                if (!location || redirects === 3)
-                    return null;
-                const next = new URL(location, current);
-                if (next.origin !== allowedOrigin || next.username || next.password)
-                    return null;
-                current = next.toString();
-                continue;
-            }
-            if (!response.ok)
-                return null;
-            const declared = Number(response.headers.get("content-length"));
-            if (Number.isFinite(declared) && declared > MAX_DOCS_TEXT_BYTES)
-                return null;
-            if (!response.body)
-                return "";
-            const reader = response.body.getReader();
-            const decoder = new TextDecoder();
-            let bytes = 0;
-            let text = "";
-            for (;;) {
-                const chunk = await reader.read();
-                if (chunk.done)
-                    break;
-                bytes += chunk.value.byteLength;
-                if (bytes > MAX_DOCS_TEXT_BYTES) {
-                    await reader.cancel();
-                    return null;
-                }
-                text += decoder.decode(chunk.value, { stream: true });
-            }
-            return text + decoder.decode();
-        }
-        return null;
-    }
-    catch {
-        return null;
-    }
-}

package/dist/mcp.js

@@ -20,12 +20,13 @@ 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, argumentsError, asJsonRpc, binaryOutcome, callSharedTool, checkRequestHeaders, dataOutcome, errorOutcome, handleRpc, isRpcOutcome, pageOutcome, parseIncludeList, prepareCall, serverInstructions, takeCancelled, textError, toolDefinitions, visibleOps, } from "./mcp-protocol.js";
+import { fetchDocsText } from "./docs.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.8.0";
 /** The MCP client's announced name (clientInfo in request _meta), for the User-Agent. */
 let MCP_CLIENT_NAME = null;
 function noteClientInfo(message) {
@@ -39,9 +40,9 @@ function noteClientInfo(message) {
 const DEFAULT_BASE_URL = "https://typeship.dev/api/v1";
 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";
@@ -78,7 +79,6 @@ function readJson(file) {
 function makeClient() {
     const stored = readJson("credentials.json");
     const config = readJson("config.json");
-    const options = {};
     const baseUrl = process.env["TYPESHIP_BASE_URL"]
         ?? config?.baseUrl
         ?? (config?.environment !== undefined ? ENVIRONMENTS[config.environment] : undefined)
@@ -88,7 +88,7 @@ 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;
+    const options = { baseUrl };
     for (const a of AUTH_SCALARS) {
         const v = process.env[a.env] ?? stored?.scalars?.[a.option];
         if (v !== undefined)
@@ -100,17 +100,6 @@ 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;
     }
@@ -187,7 +176,7 @@ async function callOperation(op, rawArgs, authHeader) {
             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 "{}".
@@ -224,7 +213,10 @@ 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
@@ -236,6 +228,8 @@ function serverFor(authHeader) {
         instructions: serverInstructions({
             title: "typeship",
             toolCount: MCP_OPS.length,
+            generatedOperationCount: OPS.length,
+            omittedOps: docsSource.omittedOps,
             mode: TOOL_MODE,
             readOnly: READ_ONLY,
             hiddenWrites: HIDDEN_WRITES,
@@ -245,7 +239,10 @@ function serverFor(authHeader) {
             custom: CUSTOM_INSTRUCTIONS,
         }),
         toolsTtlMs: TOOLS_TTL_MS,
-        listTools: () => toolDefinitions(docsSource.ops, TOOL_MODE),
+        listTools: () => toolDefinitions(docsSource.ops, TOOL_MODE, docsSource.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));
             if (shared !== undefined)

package/dist/ops.d.ts

@@ -96,6 +96,11 @@ export interface OpSpec {
     outputSchema?: Record<string, unknown>;
 }
 export declare const OPS: OpSpec[];
+/** Operations present in the API Definition but omitted by this
+ * generation's operation cap. Kept deliberately small: enough for honest
+ * discovery and PLAN_LIMIT errors, never enough to call an absent method. */
+export type OmittedOpSpec = Pick<OpSpec, "resource" | "method" | "command" | "commandAlias" | "tool" | "httpMethod" | "path" | "summary" | "description" | "toolDescription" | "paginated" | "select" | "safety" | "auth" | "params" | "inputSchema">;
+export declare const OMITTED_OPS: OmittedOpSpec[];
 /** Parameters settable once on the client (globals option): CLI/MCP fill
  * them from flags or environment; the SDK falls back per request. */
 export declare const GLOBALS: {

package/dist/ops.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../src/ops.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC3C;;;uDAGmD;IACnD,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IAC7E,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,mFAAmF;IACnF,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACvF,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;6EACyE;IACzE,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtC,uDAAuD;IACvD,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC;IACnE;0BACsB;IACtB,GAAG,EAAE,OAAO,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB;kEAC8D;IAC9D,MAAM,EAAE,OAAO,CAAC;IAChB,oEAAoE;IACpE,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,CAAC;IACrG,iEAAiE;IACjE,UAAU,EAAE,OAAO,CAAC;IACpB,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,KAAK,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACjI,qFAAqF;IACrF,UAAU,CAAC,EAAE;QACX,KAAK,EAAE,QAAQ,GAAG,kBAAkB,GAAG,MAAM,GAAG,QAAQ,CAAC;QACzD,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF;qEACiE;IACjE,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IACvC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;IACzC,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C;gFAC4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,eAAO,MAAM,GAAG,EAAE,MAAM,EAkBvB,CAAC;AAEF;qEACqE;AACrE,eAAO,MAAM,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAEtF,CAAC;AAEF,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE3E;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAIrF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,CAAC,EAAE,OAAO,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,EAAE,CAuCX"}
+{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../src/ops.ts"],"names":[],"mappings":"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"}