@typeship-ax/mcp 0.6.0 → 0.8.0

package/src/mcp-protocol.ts

@@ -16,6 +16,7 @@
  */
 
 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
@@ -154,6 +155,10 @@ export interface McpServer {
    * -32602), a ToolOutcome otherwise. Throwing yields -32603.
    */
   callTool(name: string, args: Record<string, unknown>): Promise<ToolOutcome | undefined>;
+  /** Optional actionable wording for an unknown tool name. The protocol
+   * code remains -32602; compact tool surfaces can explain how to call an
+   * operation without pretending that operation is absent. */
+  unknownToolMessage?(name: string): string;
   /** Called before a tool runs; a non-null outcome is sent instead
    * (rate limiting, entitlement). */
   beforeToolCall?(name: string): Promise<RpcOutcome | null> | RpcOutcome | null;
@@ -311,7 +316,7 @@ export async function handleRpc(server: McpServer, incoming: unknown): Promise<R
       if (denied) return denied;
       const started = Date.now();
       const outcome = await server.callTool(name, args);
-      if (outcome === undefined) return rpcError(id, -32602, "Unknown tool: " + name, 400);
+      if (outcome === undefined) 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,
       // and clients enforce it: a successful result without it fails the
@@ -396,7 +401,16 @@ export function exampleFromSchema(schema: unknown, field = "value", depth = 0):
   if (node.example !== undefined) return node.example;
   if (Array.isArray(node.examples) && node.examples.length > 0) return node.examples[0];
   if (node.default !== undefined) return node.default;
-  if (Array.isArray(node.enum) && node.enum.length > 0) return node.enum.find((v) => v !== null) ?? node.enum[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) as unknown[] | null;
   if (variants) {
     const useful = variants.find((v) => v && typeof v === "object" && (v as Record<string, unknown>).type !== "null") ?? variants[0];
@@ -432,7 +446,10 @@ export function exampleFromSchema(schema: unknown, 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"
@@ -443,11 +460,35 @@ export function exampleFromSchema(schema: unknown, 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: string, minLength: number, maxLength?: number): string | null {
+  let regex: RegExp;
+  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: string): string => {
+    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;
 }
@@ -523,7 +564,7 @@ export const EXECUTE_TOOL: ToolDefinition = {
   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." },
     },
@@ -569,42 +610,23 @@ export function parseIncludeList(value: string | undefined | null): string[] | u
  * 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: OpLike[], mode: "operations" | "meta"): ToolDefinition[] {
+export function toolDefinitions(ops: OpLike[], mode: "operations" | "meta", omittedOps: OpLike[] = []): ToolDefinition[] {
   if (mode === "meta") {
+    const execute = structuredClone(EXECUTE_TOOL);
+    const operation = (execute.inputSchema.properties as Record<string, Record<string, unknown>>).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: ToolDefinition[]): { tools: number; chars: number; approxTokens: number } {
-  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: OpLike[],
-  requested: "operations" | "meta" | "auto" = "auto",
-): { mode: "operations" | "meta"; tools: number; chars: number; approxTokens: number } {
-  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: OpLike[], wanted: string): OpLike | undefined {
@@ -623,6 +645,10 @@ export interface InstructionsInput {
   title: string;
   /** Operations the server serves (after read-only / include filtering). */
   toolCount: number;
+  /** Operations present in the Definition but absent from this capped generation. */
+  omittedOps?: OpLike[];
+  /** Count generated before read-only or include filters narrow this server. */
+  generatedOperationCount?: number;
   mode: "operations" | "meta";
   readOnly?: boolean;
   /** Write operations hidden by read-only mode. */
@@ -645,6 +671,10 @@ export function serverInstructions(input: InstructionsInput): string {
   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.");
@@ -920,6 +950,9 @@ export function projectFields(value: unknown, paths: string[][] | null): unknown
 export interface ResultOptions {
   fields?: string[][] | null;
   maxChars?: number;
+  /** Request identifier for a page that is reshaped into the MCP paging
+   * envelope. Ordinary object results already retain their body field. */
+  requestId?: string;
   /** For paginated results that must be cut: the op's pagination config and
    * the call's arguments let some styles resume exactly where the cut fell. */
   pagination?: OpLike["pagination"];
@@ -951,13 +984,18 @@ export function pageOutcome(items: unknown[], nextPage: Record<string, unknown>
   const fields = options.fields ?? null;
   const maxChars = options.maxChars ?? DEFAULT_MAX_RESULT_CHARS;
   const shown = projectFields(items, fields) as unknown[];
-  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;
@@ -981,6 +1019,7 @@ export function pageOutcome(items: unknown[], nextPage: Record<string, unknown>
     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,
@@ -1123,7 +1162,7 @@ export async function binaryOutcome(blob: Blob, options: BinaryOptions = {}): Pr
  * generated CLI's error envelope). Additive only. */
 export type ErrorCode =
   | "NO_AUTH" | "AUTH_INVALID" | "PLAN_LIMIT" | "NOT_FOUND" | "INVALID_REQUEST" | "RATE_LIMITED"
-  | "SERVER_ERROR" | "NETWORK_ERROR" | "VALIDATION_FAILED" | "INVALID_ARGUMENTS" | "CONFIRMATION_REQUIRED" | "NOT_AVAILABLE" | "CALL_FAILED";
+  | "SPEC_INVALID" | "SERVER_ERROR" | "NETWORK_ERROR" | "VALIDATION_FAILED" | "INVALID_ARGUMENTS" | "CONFIRMATION_REQUIRED" | "NOT_AVAILABLE" | "CALL_FAILED";
 
 export interface ErrorContext {
   /** One sentence on how to supply a credential on this transport. */
@@ -1151,6 +1190,7 @@ export function classifyError(error: unknown, context: ErrorContext = {}): { cod
     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 as { errors?: { code?: string; message?: string }[] } | undefined;
   const auth = context.authHint ? context.authHint.trim().replace(/[.]?$/, ".") : null;
   if (status === 401) {
     return context.hadCredential
@@ -1164,6 +1204,15 @@ export function classifyError(error: unknown, context: ErrorContext = {}): { cod
     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."] };
   }
@@ -1189,13 +1238,18 @@ function notFoundNextSteps(message: string, body: unknown): string[] {
 /** A typed API error as the agent should see it: name, a stable code, the
  * message, status, the API's body, where to read more, and what to do. */
 export function errorOutcome(error: unknown, context: ErrorContext = {}): ToolOutcome {
-  const e = error as { name?: string; message?: string; status?: number; body?: unknown };
+  const e = error as { name?: string; message?: string; status?: number; body?: unknown; response?: { requestId?: string } };
   const { code, nextSteps } = classifyError(error, context);
+  const bodyRequestId = e?.body && typeof e.body === "object" && !Array.isArray(e.body)
+    ? (e.body as Record<string, unknown>).request_id ?? (e.body as Record<string, unknown>).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,
@@ -1212,36 +1266,44 @@ export function textError(text: string, code: ErrorCode = "CALL_FAILED", nextSte
 
 export interface DocsSource {
   ops: OpLike[];
+  /** Operations omitted from a capped generation. */
+  omittedOps?: OpLike[];
+  /** Count generated before runtime surface filters. */
+  generatedOperationCount?: number;
   /** Base URL of the docs site, or null when none is configured. */
   docsUrl(): string | null;
+  /** Exact llms.txt URL when it is not at <docsUrl>/llms.txt. */
+  docsIndexUrl?(): string | null;
   /** Fetch a URL's text, or null on any failure. */
   fetchText(url: string): Promise<string | null>;
 }
 
-function docsPageUrl(source: DocsSource, pathOrFile: string): string | null {
-  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: DocsSource, pathOrFile: string): Promise<string | null> {
-  const url = docsPageUrl(source, pathOrFile);
+  const url = resolveDocsContentUrl(source.docsUrl(), source.docsIndexUrl?.() ?? null, pathOrFile);
   return url === null ? null : source.fetchText(url);
 }
 
+function coverageText(source: DocsSource): string | null {
+  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: OpLike[], requested?: string): ToolOutcome {
+  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: OpLike): string {
   const safety = operationSafety(op);
   const example = op.exampleArguments ?? exampleArgumentsFromSchema(op.inputSchema);
@@ -1306,12 +1368,19 @@ export function searchScore(op: OpLike, query: string): number {
 }
 
 export async function docsSearch(source: DocsSource, query: string, page = 1): Promise<ToolOutcome> {
-  const term = query.toLowerCase();
+  const term = query.trim().toLowerCase();
+  const terms = searchTerms(query);
   const sections: string[] = [];
   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) {
@@ -1323,29 +1392,54 @@ export async function docsSearch(source: DocsSource, query: string, page = 1): P
     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: string[] = [];
+    const proseMatches: { heading: string; excerpt: string; score: number }[] = [];
     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: DocsSource, page: string): Promise<ToolOutcome> {
   const opMatch = findOperation(source.ops, page);
-  if (opMatch) return { text: referenceText(opMatch), isError: false };
+  const coverage = coverageText(source);
+  if (opMatch) 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");
@@ -1355,11 +1449,11 @@ export async function docsRead(source: DocsSource, page: string): Promise<ToolOu
   }
   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 };
 }
 
 /**
@@ -1385,7 +1479,12 @@ export async function callSharedTool(
   if (name === "execute") {
     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.",
@@ -1400,52 +1499,3 @@ export async function callSharedTool(
   }
   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: string): Promise<string | null> {
-  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/src/mcp.ts

@@ -20,19 +20,20 @@ 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, type DebugEvent } from "./index.js";
-import { GLOBALS, OPS, buildArgs, type OpSpec } from "./ops.js";
+import { TypeshipClient, formatDebugEvent, type ClientOptions, type DebugEvent } from "./index.js";
+import { GLOBALS, OMITTED_OPS, OPS, buildArgs, type OpSpec } 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,
+  dataOutcome, errorOutcome, handleRpc, isRpcOutcome, pageOutcome, parseIncludeList, prepareCall, serverInstructions,
   takeCancelled, textError, toolDefinitions, visibleOps,
   type ArgumentIssue, type DocsSource, type McpServer, type OpLike, type RpcOutcome, type ToolOutcome,
 } 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: string | null = null;
 function noteClientInfo(message: unknown): void {
@@ -43,9 +44,10 @@ function noteClientInfo(message: unknown): void {
 const DEFAULT_BASE_URL = "https://typeship.dev/api/v1";
 const AUTH_SCALARS: { option: string; flag: string; env: string }[] = [{"option":"bearerToken","flag":"token","env":"TYPESHIP_TOKEN"}];
 const BASIC: { envUser: string; envPass: string } | null = null;
-const OAUTH_TOKEN_URL: string | null = null;
+
 const ENVIRONMENTS: Record<string, string> = {};
 const DOCS_URL_DEFAULT: string | null = "https://typeship.dev";
+const DOCS_INDEX_URL_DEFAULT: string | null = 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: "operations" | "meta" = "meta";
@@ -88,7 +90,6 @@ function makeClient(): TypeshipClient {
     oauth?: { accessToken: string };
   }>("credentials.json");
   const config = readJson<{ baseUrl?: string; environment?: string }>("config.json");
-  const options: Record<string, unknown> = {};
   const baseUrl = process.env["TYPESHIP_BASE_URL"]
     ?? config?.baseUrl
     ?? (config?.environment !== undefined ? ENVIRONMENTS[config.environment] : undefined)
@@ -98,7 +99,7 @@ function makeClient(): TypeshipClient {
     // 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: ClientOptions & Record<string, unknown> = { baseUrl };
   for (const a of AUTH_SCALARS) {
     const v = process.env[a.env] ?? stored?.scalars?.[a.option];
     if (v !== undefined) options[a.option] = v;
@@ -108,16 +109,7 @@ function makeClient(): TypeshipClient {
     const password = process.env[BASIC.envPass] ?? stored?.basic?.password;
     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;
   }
@@ -130,7 +122,7 @@ function makeClient(): TypeshipClient {
   }
   // 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 as never);
+  return new TypeshipClient(options);
 }
 
 let clientInstance: TypeshipClient | undefined;
@@ -180,11 +172,11 @@ async function callOperation(op: OpSpec, rawArgs: Record<string, unknown>, authH
   const shape = { fields, maxChars, pagination: op.pagination, args };
   try {
     const target = (getClient() as unknown as Record<string, Record<string, (...a: unknown[]) => unknown>>)[op.resource]!;
-    const result = await (target[op.method]!(...callArgs) as Promise<{ ok: boolean; data?: unknown; error?: unknown }>);
+    const result = await (target[op.method]!(...callArgs) as Promise<{ ok: boolean; data?: unknown; error?: unknown; response?: { requestId?: string } }>);
     if (!result.ok) return errorOutcome(result.error, errorContext);
     if (op.paginated) {
-      const page = result.data as { items: unknown[]; nextPageParams(): Record<string, unknown> | null };
-      return pageOutcome(page.items, page.nextPageParams(), shape);
+      const page = result.data as { items: unknown[]; nextPageParams(): Record<string, unknown> | null; response: { requestId?: string } };
+      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 "{}".
@@ -223,7 +215,10 @@ function saveBinary(bytes: Uint8Array, _mediaType: string, suggestedName: string
 
 const docsSource: DocsSource = {
   ops: MCP_OPS as unknown as OpLike[],
+  omittedOps: OMITTED_OPS as unknown as OpLike[],
+  generatedOperationCount: OPS.length,
   docsUrl: () => readJson<{ docsUrl?: string }>("config.json")?.docsUrl ?? DOCS_URL_DEFAULT,
+  docsIndexUrl: () => readJson<{ docsUrl?: string }>("config.json")?.docsUrl ? null : DOCS_INDEX_URL_DEFAULT,
   fetchText: fetchDocsText,
 };
 
@@ -236,6 +231,8 @@ function serverFor(authHeader?: string): McpServer {
     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 +242,10 @@ function serverFor(authHeader?: string): McpServer {
       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 as OpSpec, opArgs, authHeader));
       if (shared !== undefined) return shared;