@typeship-ax/mcp 0.22.0 → 0.23.0

package/dist/mcp-protocol.js

@@ -15,10 +15,11 @@
  *
  * Spec: https://modelcontextprotocol.io/specification/2026-07-28
  */
-import { checkValue, closestName, isMeReference, normalizeName, userShapedReference } from "./arguments.js";
+import { checkValue, closestName, isMeReference, meIdentityField, normalizeName, userShapedReference } from "./arguments.js";
 import { docsReadTarget, resolveDocsContentUrl, searchConnectedGuides } from "./docs.js";
 import { projectFields, unmatchedFields, unmatchedFieldsMessage } from "./fields.js";
 import { SEARCH_PAGE_SIZE, rankOperations } from "./search.js";
+import { argumentPathText, findInputType, inputTypeText, namedTypesIn } from "./type-docs.js";
 export { projectFields } from "./fields.js";
 export const MCP_PROTOCOL_VERSION = "2026-07-28";
 export const LEGACY_PROTOCOL_VERSION = "2025-11-25";
@@ -437,8 +438,8 @@ export const SEARCH_DOCS_TOOL = {
 };
 export const READ_DOCS_TOOL = {
     name: "read_docs",
-    description: 'Read a documentation page: an operation reference (a tool name, or dotted "resource.method") or a docs-site guide page by name or URL. Long pages come in parts; pass the offset a part ends with to continue.',
-    inputSchema: { type: "object", properties: { page: { type: "string" }, schema: { type: "boolean", description: "Also return the operation's complete input and output JSON Schemas, default false" }, offset: { type: "integer", minimum: 0, description: "Character offset to continue a long page from, default 0" } }, required: ["page"] },
+    description: 'Read a documentation page: an operation reference (a tool name, or dotted "resource.method"), a named input type such as a filter, or a docs-site guide page by name or URL. Long pages come in parts; pass the offset a part ends with to continue.',
+    inputSchema: { type: "object", properties: { page: { type: "string" }, path: { type: "string", description: "A dotted argument path within the operation or type, e.g. \"filter.team.key\": that field's type, with its named type's fields or values" }, schema: { type: "boolean", description: "Also return the operation's complete input and output JSON Schemas, default false" }, offset: { type: "integer", minimum: 0, description: "Character offset to continue a long page from, default 0" } }, required: ["page"] },
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
 };
 export const EXECUTE_TOOL = {
@@ -531,7 +532,7 @@ export function toolDefinitions(ops, mode, omittedOps = []) {
             : "";
         return [
             { ...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 reference (arguments, authentication, safety, an example and the result's shape) by tool name, or a docs-site guide page. schema: true adds the complete JSON Schemas." },
+            { ...READ_DOCS_TOOL, description: "Read an operation's reference (arguments, authentication, safety, an example and the result's shape) by tool name, a named input type, or a docs-site guide page. path narrows to one nested argument, e.g. \"filter.team.key\"; schema: true adds the complete JSON Schemas." },
             execute,
         ];
     }
@@ -546,6 +547,58 @@ export function findOperation(ops, wanted) {
 export function missingArguments(op, args) {
     return op.params.filter((p) => p.required && args[p.name] === undefined).map((p) => p.name);
 }
+// ---- server instructions ----------------------------------------------------------
+/** Identity fields that name the caller for a login-shaped "me" (GitHub's
+ * users_get_authenticated returns login). */
+const IDENTITY_LOGIN_FIELDS = ["login", "username", "handle"];
+const MAX_ME_SCHEMA_DEPTH = 6;
+function acceptsString(schema) {
+    if (!schema || typeof schema !== "object")
+        return false;
+    const record = schema;
+    const type = record.type;
+    if (type === "string" || (Array.isArray(type) && type.includes("string")))
+        return true;
+    const variants = record.anyOf ?? record.oneOf;
+    return Array.isArray(variants) && variants.some(acceptsString);
+}
+function objectVariants(schema) {
+    if (!schema || typeof schema !== "object")
+        return [];
+    const record = schema;
+    const variants = record.anyOf ?? record.oneOf;
+    return [record, ...(Array.isArray(variants) ? variants.flatMap(objectVariants) : [])]
+        .filter((candidate) => candidate.properties && typeof candidate.properties === "object");
+}
+/** Every argument path where the server resolves "me": a user-shaped string
+ * (or a list or union that takes one) at the top level or inside an object
+ * argument. The instructions name exactly these. */
+export function meReferenceArguments(ops) {
+    const found = new Set();
+    const visit = (name, schema, path, depth) => {
+        if (!schema || typeof schema !== "object" || depth > MAX_ME_SCHEMA_DEPTH)
+            return;
+        const record = schema;
+        const items = record.items ?? (Array.isArray(record.anyOf ?? record.oneOf) ? (record.anyOf ?? record.oneOf).find((variant) => variant && variant.items)?.items : undefined);
+        if (userShapedReference(name) && (acceptsString(record) || acceptsString(items)))
+            found.add(path);
+        const nested = [[objectVariants(record), path], [objectVariants(items), path + "[]"]];
+        for (const [variants, prefix] of nested) {
+            for (const variant of variants) {
+                for (const [key, child] of Object.entries(variant.properties))
+                    visit(key, child, prefix + "." + key, depth + 1);
+            }
+        }
+    };
+    for (const op of ops) {
+        const properties = (op.inputSchema.properties ?? {});
+        for (const param of op.params) {
+            if (param.resolve !== false)
+                visit(param.name, properties[param.name], param.name, 0);
+        }
+    }
+    return [...found].sort((a, b) => a.split(".").length - b.split(".").length || a.localeCompare(b));
+}
 /** The server/discover instructions: what the tools are, how arguments and
  * results behave, where credentials come from, plus whatever the project
  * adds. One paragraph; agents read it once per session. */
@@ -561,8 +614,9 @@ export function serverInstructions(input) {
     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).");
     if (input.referenceResolution)
         parts.push("Reference arguments marked in their schema accept either an ID or an exact case-insensitive name, slug, key or email; the server resolves one match through the named list tool, reports multiple candidates, and never guesses fuzzily.");
-    if (input.identityTool && input.ops.some((op) => op.params.some((param) => param.type === "string" && param.resolve !== false && userShapedReference(param.name)))) {
-        parts.push("User-shaped reference arguments also accept \"me\", resolved through " + input.identityTool + ".");
+    const meArguments = input.identityTool ? meReferenceArguments(input.ops) : [];
+    if (meArguments.length > 0) {
+        parts.push("These arguments also accept \"me\" for the caller, resolved through " + input.identityTool + " (ID arguments take its id, others its login when it has one): " + meArguments.join(", ") + ".");
     }
     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.");
@@ -656,7 +710,7 @@ export function prepareCall(op, rawArgs, options = {}) {
         // Patterns apply inside objects and arrays. A top-level argument's own
         // pattern is left to the API: its documented example values do not all
         // satisfy it yet, and a name or "me" is only resolved to an ID later.
-        args[name] = checkValue(value, propSchema, name, issues, { skipPattern: true });
+        args[name] = checkValue(value, propSchema, name, issues, { skipPattern: true, meName: name });
     }
     // A path argument that is the configured credential's username (Twilio's
     // AccountSid) defaults to it; without one it is an ordinary missing argument
@@ -763,30 +817,39 @@ export async function resolveReferences(op, preparedArgs, options) {
     const args = { ...preparedArgs };
     const maxPages = Math.max(1, Math.floor(options.maxPages ?? 5));
     const identity = options.identityTool ? findOperation(options.ops, options.identityTool) : undefined;
-    /** The caller's ID for "me", fetched once per cache. */
-    const callerId = async (argument) => {
-        const cacheKey = "me:" + identity.tool;
+    let identityBody;
+    /** The caller's ID, or login for a login-shaped name (GitHub's owner and
+     * assignees), for "me": one identity call per cache. */
+    const callerId = async (argument, key) => {
+        const field = meIdentityField(key);
+        const cacheKey = "me:" + identity.tool + (field === "id" ? "" : ":" + field);
         const cached = options.cache.get(cacheKey);
         if (cached !== undefined)
             return { id: cached };
-        const outcome = await options.runOperation(identity, {});
-        if (outcome.isError)
-            return { outcome };
-        const body = outcomeValue(outcome);
-        const id = body && typeof body === "object" && !Array.isArray(body) ? body.id : undefined;
+        if (!identityBody) {
+            const outcome = await options.runOperation(identity, {});
+            if (outcome.isError)
+                return { outcome };
+            const body = outcomeValue(outcome);
+            identityBody = body && typeof body === "object" && !Array.isArray(body) ? body : {};
+        }
+        const login = IDENTITY_LOGIN_FIELDS.map((name) => identityBody[name]).find((value) => typeof value === "string" && value !== "");
+        const id = field === "login" && login !== undefined ? login : identityBody.id;
         if (typeof id !== "string" && typeof id !== "number") {
-            return { outcome: referenceError("NOT_AVAILABLE", `${identity.tool} did not return a top-level id, so "me" cannot be resolved for ${argument}.`, argument, ["Pass the caller's exact ID instead."]) };
+            const expected = field === "id" ? "a top-level id" : "a top-level " + IDENTITY_LOGIN_FIELDS.join(", ") + " or id";
+            return { outcome: referenceError("NOT_AVAILABLE", `${identity.tool} did not return ${expected}, so "me" cannot be resolved for ${argument}.`, argument, [field === "id" ? "Pass the caller's exact ID instead." : "Pass the caller's exact login instead."]) };
         }
         putReferenceCache(options.cache, cacheKey, id);
         return { id };
     };
-    /** "me" inside an object argument (a GraphQL input's assigneeId, or each
-     * of its subscriberIds): the same resolution, keyed by property name. */
+    /** "me" inside an object or array argument (a GraphQL input's assigneeId,
+     * each of its subscriberIds, each of GitHub's assignees): the same
+     * resolution, keyed by property name. */
     const resolveNestedMe = async (value, key, path) => {
         if (typeof value === "string") {
             if (!isMeReference(key, value))
                 return { value };
-            const caller = await callerId(path);
+            const caller = await callerId(path, key);
             return "outcome" in caller ? caller : { value: caller.id };
         }
         if (Array.isArray(value)) {
@@ -824,7 +887,7 @@ export async function resolveReferences(op, preparedArgs, options) {
             continue;
         const value = raw.trim();
         if (identity && isMeReference(param.name, value)) {
-            const caller = await callerId(param.name);
+            const caller = await callerId(param.name, param.name);
             if ("outcome" in caller)
                 return { ok: false, outcome: caller.outcome };
             args[param.name] = caller.id;
@@ -907,32 +970,59 @@ export function argumentsError(op, issues) {
     return { text: JSON.stringify(structured), isError: true, structured };
 }
 /** A fields path that selects nothing is an error that names the keys
- * that exist, not a silent {}. The API call already happened, so the error
- * says so, and a write's unprojected result comes back with it. */
-function unmatchedFieldsOutcome(value, fields, perItem, options) {
+ * that exist, not a silent {}. A path the response schema declares is not
+ * one: an optional key no item has is simply absent. The API call already
+ * happened, so the error says so and carries the unprojected result (as
+ * much as fits under half the cap), so neither a read nor a write has to
+ * run again to see it. */
+function unmatchedFieldsOutcome(value, fields, perItem, options, schema, page) {
     if (fields === null)
         return null;
     const optional = new Set(options.optionalFields ?? []);
-    const unmatched = unmatchedFields(value, fields).filter((u) => !optional.has(u.path));
+    const unmatched = unmatchedFields(value, fields, schema).filter((u) => !optional.has(u.path));
     if (unmatched.length === 0)
         return null;
     const write = options.safety !== "read";
     const maxChars = options.maxChars ?? DEFAULT_MAX_RESULT_CHARS;
-    const full = write ? JSON.stringify(value) : undefined;
+    const retained = retainedResult(value, Math.floor(maxChars / 2));
+    const steps = [];
+    if (write)
+        steps.push("This operation has already run; do not call it again to change fields." + (retained.whole ? " Its full result is in result." : retained.result !== undefined ? " The first items of its result are in result." : ""));
+    else if (retained.whole)
+        steps.push("The full result is in result; use it rather than calling again.");
+    else if (retained.result !== undefined)
+        steps.push("result holds the first " + retained.result.length + " of " + value.length + " items; the rest are over the size cap.");
+    steps.push((write ? "Next time, use" : "To project a later call, use") + " fields from the available keys" + (perItem ? " (fields apply to each item)" : "") + ", or omit fields for the whole result.");
     const structured = {
         error: "UnmatchedFields",
         code: "FIELDS_UNMATCHED",
         message: unmatchedFieldsMessage(unmatched, perItem),
         unmatched,
-        ...(full !== undefined && full.length <= maxChars / 2 ? { result: value } : {}),
-        next_steps: [
-            ...(write
-                ? ["This operation has already run; do not call it again to change fields." + (full !== undefined && full.length <= maxChars / 2 ? " Its full result is in result." : "")]
-                : ["Call again with fields from the available keys" + (perItem ? " (fields apply to each item)" : "") + ", or omit fields for the whole result."]),
-        ],
+        ...(retained.result !== undefined ? { result: retained.result } : {}),
+        ...(retained.omitted ? { result_omitted: retained.omitted } : {}),
+        ...(page ? { hasMore: page.nextPage !== null, ...(page.nextPage !== null ? { nextPage: page.nextPage } : {}) } : {}),
+        ...(options.requestId ? { request_id: options.requestId } : {}),
+        next_steps: steps,
     };
     return { text: JSON.stringify(structured), isError: true, structured };
 }
+/** The unprojected result an unmatched-fields error carries: whole when it
+ * fits the budget, the leading items of a list when only some do, and
+ * nothing for an object over the budget. */
+function retainedResult(value, budget) {
+    const text = JSON.stringify(value);
+    if (text === undefined)
+        return { whole: false };
+    if (text.length <= budget)
+        return { result: value, whole: true };
+    if (!Array.isArray(value))
+        return { whole: false };
+    const k = itemsThatFit(value, budget);
+    const head = value.slice(0, k);
+    if (JSON.stringify(head).length > budget)
+        return { whole: false };
+    return { result: head, whole: false, omitted: value.length - k };
+}
 const fieldsHint = (perItem) => "Pass fields (dotted paths" + (perItem ? ", applied per item" : "") + ") to keep only the keys you need.";
 /** How many leading items fit under `budget` characters once serialized
  * compactly with commas between them. At least one. */
@@ -966,7 +1056,8 @@ export function pageOutcome(items, nextPage, options = {}) {
     }
     const fields = options.fields ?? null;
     const maxChars = options.maxChars ?? DEFAULT_MAX_RESULT_CHARS;
-    const unmatched = unmatchedFieldsOutcome(items, fields, true, options);
+    const pageSchema = options.outputSchema?.properties;
+    const unmatched = unmatchedFieldsOutcome(items, fields, true, options, pageSchema?.items, { nextPage });
     if (unmatched)
         return unmatched;
     const shown = projectFields(items, fields);
@@ -1026,7 +1117,7 @@ const omittedMarker = (key, chars, maxChars) => chars > maxChars
 export function dataOutcome(data, options = {}) {
     const fields = options.fields ?? null;
     const maxChars = options.maxChars ?? DEFAULT_MAX_RESULT_CHARS;
-    const unmatched = data !== undefined && data !== null ? unmatchedFieldsOutcome(data, fields, Array.isArray(data), options) : null;
+    const unmatched = data !== undefined && data !== null ? unmatchedFieldsOutcome(data, fields, Array.isArray(data), options, options.outputSchema) : null;
     if (unmatched)
         return unmatched;
     const value = data !== undefined && data !== null ? projectFields(data, fields) : { ok: true };
@@ -1156,6 +1247,31 @@ function payloadFailureCode(code) {
         return "RATE_LIMITED";
     return undefined;
 }
+/** The vendor's own code on an in-band GraphQL error: the first error's
+ * extensions.code, or its type (GitHub). */
+function graphqlVendorCode(error) {
+    const first = error?.errors?.[0];
+    const code = first?.extensions?.code ?? first?.type;
+    return typeof code === "string" && code !== "" ? code : undefined;
+}
+/** GraphQL error codes whose meaning is settled (Apollo's standard codes,
+ * GitHub's types, Linear's codes), by recovery class. Any other code is
+ * passed through as is, with no guessed next step. The CLI's
+ * classification (cli-agent.ts) uses the same table. */
+function graphqlErrorClass(code) {
+    const c = code.toUpperCase();
+    if (c === "NOT_FOUND")
+        return "not_found";
+    if (c === "UNAUTHENTICATED" || c === "AUTHENTICATION_ERROR")
+        return "unauthenticated";
+    if (c === "FORBIDDEN")
+        return "forbidden";
+    if (c === "BAD_USER_INPUT" || c === "GRAPHQL_VALIDATION_FAILED" || c === "GRAPHQL_PARSE_FAILED" || c === "INPUT_ERROR")
+        return "bad_input";
+    if (c === "RATE_LIMITED" || c === "RATELIMITED")
+        return "rate_limited";
+    return undefined;
+}
 /** Classify an SDK error result by status: the code and what to do next. */
 export function classifyError(error, context = {}) {
     const e = (error ?? {});
@@ -1184,15 +1300,26 @@ export function classifyError(error, context = {}) {
             return { code: "RATE_LIMITED", nextSteps: [rateLimitNextStep(undefined)] };
         return { code: "CALL_FAILED", nextSteps: ["The API reported a failure in a successful response; body says why. Do not treat the call as done."] };
     }
-    if (status === 401) {
-        return context.hadCredential
-            ? { code: "AUTH_INVALID", nextSteps: ["The credential was rejected; it may be expired or for another environment." + (auth ? " " + auth : "")] }
-            : { code: "NO_AUTH", nextSteps: ["No credential was sent." + (auth ? " " + auth : "")] };
+    const unauthenticated = () => context.hadCredential
+        ? { code: "AUTH_INVALID", nextSteps: ["The credential was rejected; it may be expired or for another environment." + (auth ? " " + auth : "")] }
+        : { code: "NO_AUTH", nextSteps: ["No credential was sent." + (auth ? " " + auth : "")] };
+    const forbidden = () => scopes.length ? scopeFailure : { code: "AUTH_INVALID", nextSteps: ["The credential lacks access to this operation; it is not a retryable error."] };
+    // An in-band GraphQL error (HTTP 200): classified by the vendor's code.
+    if (e.name === "GraphQLRequestError") {
+        const vendor = graphqlVendorCode(error);
+        switch (vendor === undefined ? undefined : graphqlErrorClass(vendor)) {
+            case "not_found": return { code: "NOT_FOUND", nextSteps: ["Check the id in the arguments; list the resource first to find the right one."] };
+            case "unauthenticated": return unauthenticated();
+            case "forbidden": return forbidden();
+            case "bad_input": return { code: "INVALID_REQUEST", nextSteps: ["The API rejected an argument or the selection; the errors in body name it (message, path). Fix that and call again."] };
+            case "rate_limited": return { code: "RATE_LIMITED", nextSteps: [rateLimitNextStep(undefined)] };
+            default: return { code: "CALL_FAILED", nextSteps: [] };
+        }
     }
-    if (status === 403 && scopes.length)
-        return scopeFailure;
+    if (status === 401)
+        return unauthenticated();
     if (status === 403)
-        return { code: "AUTH_INVALID", nextSteps: ["The credential lacks access to this operation; it is not a retryable error."] };
+        return forbidden();
     if (status === 402)
         return { code: "PLAN_LIMIT", nextSteps: ["The account's plan stops here; the body may name where to lift the limit. Do not retry the same call as is."] };
     if (status === 404)
@@ -1251,9 +1378,12 @@ export function errorOutcome(error, context = {}) {
         ? e.body.request_id ?? e.body.requestId
         : undefined;
     const requestId = e?.response?.requestId ?? (typeof bodyRequestId === "string" ? bodyRequestId : undefined);
+    // The vendor's identity for the failure, next to the normalized code.
+    const vendorCode = e?.name === "GraphQLRequestError" ? graphqlVendorCode(error) : undefined;
     const structured = {
         error: e?.name ?? "Error",
         code,
+        ...(vendorCode ? { vendor_code: vendorCode } : {}),
         message: e?.message,
         ...(typeof e?.status === "number" ? { status: e.status } : {}),
         ...(requestId ? { request_id: requestId } : {}),
@@ -1312,11 +1442,55 @@ const REFERENCE_DEPTH = 3;
 const REFERENCE_ARGUMENT_BUDGET = 6_000;
 /** Enum values listed inline; longer enums are cut with a count. */
 const REFERENCE_ENUM_VALUES = 30;
-/** Prose for one description: one line, markdown links reduced to their text. */
-function referenceProse(text) {
+/** HTML that API descriptions carry for formatting only. Anything else
+ * in angle brackets (a <placeholder>) is text and stays. */
+const FORMATTING_TAGS = /<\/?(?:a|abbr|b|br|code|div|em|i|li|ol|p|pre|small|span|strong|sub|sup|u|ul)(?:\s[^<>]*)?\/?>/gi;
+/** A Markdown link or image: [text](url "title"), where the URL may hold
+ * one level of parentheses (Wikipedia's Foo_(bar)). */
+const MARKDOWN_LINK = /!?\[([^\[\]]*(?:\[[^\[\]]*\][^\[\]]*)*)\]\((?:[^()\s]|\([^()\s]*\))*(?:\s+"[^"]*")?\)/g;
+/** Prose for one description, as one line: Markdown and HTML links reduced
+ * to their visible text, formatting tags and emphasis dropped, <code> as
+ * inline code (kept, because agents copy it). */
+export function referenceProse(text) {
     if (typeof text !== "string")
         return "";
-    return text.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/\s+/g, " ").trim();
+    return text
+        .replace(/<code>([\s\S]*?)<\/code>/gi, "`$1`")
+        .replace(/<br\s*\/?>/gi, " ")
+        .replace(FORMATTING_TAGS, "")
+        .replace(MARKDOWN_LINK, "$1")
+        .replace(/\[([^\[\]]+)\]\[[^\[\]]*\]/g, "$1")
+        .replace(/(\*\*|__)(?=\S)([^*_]*?\S)\1/g, "$2")
+        .replace(/&nbsp;/g, " ").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&#39;/g, "'").replace(/&amp;/g, "&")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Abbreviations whose period does not end a sentence. */
+const ABBREVIATION = /(?:^|[\s(])(?:e\.g|i\.e|etc|vs|approx|incl|cf|no|min|max)\.$/i;
+/** A description's sentences, every character kept: a sentence ends at
+ * . ! or ? (closing quotes and brackets included) before whitespace, not
+ * after an abbreviation, and never inside inline code. */
+function sentencesOf(prose) {
+    const sentences = [];
+    let current = "";
+    for (const part of prose.split(/(?<=[.!?]["')\]]?)\s+/)) {
+        current = current ? current + " " + part : part;
+        const openCode = (current.match(/`/g) ?? []).length % 2 === 1;
+        if (!openCode && !ABBREVIATION.test(current)) {
+            sentences.push(current);
+            current = "";
+        }
+    }
+    if (current)
+        sentences.push(current);
+    return sentences;
+}
+/** Cut one long sentence at a word boundary, never inside inline code. */
+function cutSentence(sentence, limit) {
+    let cut = sentence.slice(0, limit).replace(/\s+\S*$/, "");
+    if ((cut.match(/`/g) ?? []).length % 2 === 1)
+        cut = cut.slice(0, cut.lastIndexOf("`")).trimEnd();
+    return cut.replace(/[\s,;:(]+$/, "") + "…";
 }
 /** Sentences the generator appends to an argument's description because a
  * call depends on them: enum meanings, defaults, deprecation, reference
@@ -1327,22 +1501,20 @@ const REFERENCE_ARGUMENT_PROSE = 160;
 /** An argument's description, cut to its leading sentences within the
  * budget plus every note the generator added. The full text is in the
  * schema (schema: true). */
-function argumentProse(text) {
+export function argumentProse(text) {
     const prose = referenceProse(text);
     if (prose.length <= REFERENCE_ARGUMENT_PROSE)
         return prose;
-    const sentences = prose.match(/[^.!?]+(?:[.!?]+(?=\s|$)|$)\s*/g) ?? [prose];
     const kept = [];
     let used = 0;
     let cut = false;
-    for (const raw of sentences) {
-        const sentence = raw.trim();
+    for (const sentence of sentencesOf(prose)) {
         if (REFERENCE_NOTE.test(sentence)) {
             kept.push(sentence);
             continue;
         }
         if (kept.length === 0 || used + sentence.length <= REFERENCE_ARGUMENT_PROSE) {
-            kept.push(sentence.length > REFERENCE_ARGUMENT_PROSE * 2 ? sentence.slice(0, REFERENCE_ARGUMENT_PROSE * 2).replace(/\s+\S*$/, "") + "…" : sentence);
+            kept.push(sentence.length > REFERENCE_ARGUMENT_PROSE * 2 ? cutSentence(sentence, REFERENCE_ARGUMENT_PROSE * 2) : sentence);
             used += sentence.length;
         }
         else {
@@ -1392,7 +1564,7 @@ function referenceObject(schema) {
 }
 /** One line per argument, nested fields indented beneath their object.
  * Each top-level argument is spelled out as deep as fits its budget. */
-function referenceArguments(schema, lines) {
+function referenceArguments(schema, lines, context) {
     const properties = (schema.properties ?? {});
     for (const name of Object.keys(properties)) {
         const only = { ...schema, properties: { [name]: properties[name] } };
@@ -1401,14 +1573,14 @@ function referenceArguments(schema, lines) {
         // below the cut; then one level with names only.
         for (const [depth, names] of [[REFERENCE_DEPTH, true], [2, true], [2, false], [1, true]]) {
             block = [];
-            referenceArgumentLines(only, 0, depth, names, "  ", block);
+            referenceArgumentLines(only, 0, depth, names, "  ", block, context);
             if (block.join("\n").length <= REFERENCE_ARGUMENT_BUDGET)
                 break;
         }
         lines.push(...block);
     }
 }
-function referenceArgumentLines(schema, depth, maxDepth, names, indent, lines) {
+function referenceArgumentLines(schema, depth, maxDepth, names, indent, lines, context) {
     const properties = (schema.properties ?? {});
     const required = new Set(Array.isArray(schema.required) ? schema.required : []);
     for (const [name, child] of Object.entries(properties)) {
@@ -1419,18 +1591,29 @@ function referenceArgumentLines(schema, depth, maxDepth, names, indent, lines) {
             ...(child.default !== undefined && !/\bdefault\b/i.test(description) ? ["default " + JSON.stringify(child.default)] : []),
             ...(child.deprecated === true && !/deprecated/i.test(description) ? ["deprecated"] : []),
         ];
-        lines.push(indent + name + " (" + referenceType(child) + (required.has(name) ? ", required" : "") + (extras.length ? ", " + extras.join(", ") : "") + ")" + (description ? ": " + description : ""));
         const nested = referenceObject(child);
+        // An object argument reads as its named type (IssueFilter), which
+        // read_docs can look up; everything else keeps its inline type.
+        const expression = context.path.length === 0
+            ? context.types?.args[context.tool]?.[name]
+            : context.typeName ? context.types?.types[context.typeName]?.fields?.[name]?.type : undefined;
+        const named = nested ? namedTypesIn(context.types, expression) : [];
+        const type = named.length > 0 ? expression : referenceType(child);
+        lines.push(indent + name + " (" + type + (required.has(name) ? ", required" : "") + (extras.length ? ", " + extras.join(", ") : "") + ")" + (description ? ": " + description : ""));
         if (!nested)
             continue;
+        const path = [...context.path, name];
+        const objects = named.filter((typeName) => context.types.types[typeName].fields);
+        const inner = { ...context, path, typeName: objects.length === 1 ? objects[0] : undefined };
         if (depth + 1 < maxDepth) {
-            referenceArgumentLines(nested, depth + 1, maxDepth, names, indent + "  ", lines);
+            referenceArgumentLines(nested, depth + 1, maxDepth, names, indent + "  ", lines, inner);
             continue;
         }
         if (!names)
             continue;
         const keys = Object.keys(nested.properties);
-        lines.push(indent + "  fields: " + keys.slice(0, 40).join(", ") + (keys.length > 40 ? ", … " + (keys.length - 40) + " more" : "") + " (types with schema: true)");
+        // Field types (and any cut names) are one path lookup away.
+        lines.push(indent + "  fields: " + keys.slice(0, 40).join(", ") + (keys.length > 40 ? ", … " + (keys.length - 40) + " more: read_docs " + JSON.stringify({ page: context.tool, path: path.join(".") }) + " lists all" : ""));
     }
 }
 /** A result's shape in one line: keys and types, one level into objects. */
@@ -1481,7 +1664,7 @@ export function referenceText(op, options = {}) {
     const input = toolInputSchema(op);
     if (Object.keys((input.properties ?? {})).length > 0) {
         lines.push("", "Arguments:");
-        referenceArguments(input, lines);
+        referenceArguments(input, lines, { tool: op.tool, types: options.types, path: [] });
     }
     lines.push("", "Example arguments: " + JSON.stringify(example));
     if (op.outputSchema) {
@@ -1493,6 +1676,15 @@ export function referenceText(op, options = {}) {
             lines.push("", "Output schema: " + JSON.stringify(op.outputSchema));
     }
     else {
+        // Say how to drill into an object argument: the page above stops at a
+        // depth and a size, and the schema is the whole graph at once.
+        const nested = Object.entries((input.properties ?? {}))
+            .find(([, child]) => child && typeof child === "object" && referenceObject(child))?.[0];
+        if (nested) {
+            const named = namedTypesIn(options.types, options.types?.args[op.tool]?.[nested])[0];
+            lines.push("", "Nested arguments: read_docs " + JSON.stringify({ page: op.tool, path: nested }) + " gives an argument's type and all its fields; extend the path (\"" + nested + ".<field>\") to go deeper."
+                + (named ? " Named types read the same way: read_docs " + JSON.stringify({ page: named }) + "." : ""));
+        }
         lines.push("", "Full input and output JSON Schemas: read_docs " + JSON.stringify({ page: op.tool, schema: true }) + ".");
     }
     return lines.join("\n");
@@ -1561,22 +1753,51 @@ function searchLabel(op) {
 export const READ_DOCS_LIMIT = 20_000;
 /** One part of a long page, ending with how to read the next part. */
 function docsPart(page, text, offset, schema = false) {
+    return docsPartFor({ page, ...(schema ? { schema: true } : {}) }, text, offset);
+}
+/** docsPart for any read_docs arguments (a page, a path, schema). */
+function docsPartFor(request, text, offset) {
     if (offset <= 0 && text.length <= READ_DOCS_LIMIT)
         return text;
     const start = Math.min(Math.max(0, offset), text.length);
     const end = Math.min(text.length, start + READ_DOCS_LIMIT);
     const more = end < text.length
-        ? "\n\n[Characters " + start + "-" + end + " of " + text.length + ". Continue with read_docs " + JSON.stringify({ page, ...(schema ? { schema: true } : {}), offset: end }) + ".]"
+        ? "\n\n[Characters " + start + "-" + end + " of " + text.length + ". Continue with read_docs " + JSON.stringify({ ...request, offset: end }) + ".]"
         : "\n\n[Characters " + start + "-" + end + " of " + text.length + "; end of page.]";
     return text.slice(start, end) + more;
 }
+/** How read_docs names a type lookup, for the pages that mention types. */
+function readDocsTypeHint(name) {
+    return "read_docs " + JSON.stringify({ page: name });
+}
+/** One argument path within an operation or a named type. */
+function docsPathOutcome(source, root, page, path, offset) {
+    const found = argumentPathText(source.inputTypes, root, path, readDocsTypeHint);
+    if (found.ok)
+        return { text: docsPartFor({ page, path }, found.text, offset), isError: false };
+    const structured = {
+        error: "NotFoundError", code: "NOT_FOUND", message: found.message,
+        ...(found.available.length > 0 ? { available: found.available } : {}),
+        next_steps: [found.available.length > 0 ? "Pass one of the available fields as the next path segment." : "read_docs " + JSON.stringify({ page }) + " lists the arguments."],
+    };
+    return { text: JSON.stringify(structured), isError: true, structured };
+}
 export async function docsRead(source, page, offset = 0, options = {}) {
     const opMatch = findOperation(source.ops, page);
+    const typeMatch = opMatch ? undefined : findInputType(source.inputTypes, page);
+    if (options.path !== undefined && options.path.trim() !== "") {
+        if (opMatch)
+            return docsPathOutcome(source, opMatch, page, options.path, offset);
+        if (typeMatch)
+            return docsPathOutcome(source, { type: typeMatch }, page, options.path, offset);
+    }
     if (opMatch)
-        return { text: docsPart(page, referenceText(opMatch, options), offset, options.schema === true), isError: false };
+        return { text: docsPart(page, referenceText(opMatch, { schema: options.schema, types: source.inputTypes }), offset, options.schema === true), isError: false };
     const omittedMatch = findOperation(source.omittedOps ?? [], page);
     if (omittedMatch)
         return omittedPlanLimit(source, [omittedMatch], omittedMatch.tool);
+    if (typeMatch)
+        return { text: docsPartFor({ page }, inputTypeText(source.inputTypes, typeMatch, readDocsTypeHint), offset), isError: false };
     let target = page;
     if (!/^https?:\/\//.test(target)) {
         const index = await fetchDocs(source, "llms.txt");
@@ -1611,7 +1832,8 @@ export async function callSharedTool(name, args, source, runOperation) {
             if (hidden)
                 return hiddenOutcome(hidden);
         }
-        return typeof args.page === "string" ? docsRead(source, args.page, offset, { schema }) : argumentsError({ tool: name }, [{ code: "MISSING_ARGUMENT", argument: "page", message: "read_docs requires a page string." }]);
+        const path = typeof args.path === "string" ? args.path : undefined;
+        return typeof args.page === "string" ? docsRead(source, args.page, offset, { schema, path }) : argumentsError({ tool: name }, [{ code: "MISSING_ARGUMENT", argument: "page", message: "read_docs requires a page string." }]);
     }
     if (name === "execute") {
         if (typeof args.operation !== "string")

package/dist/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":";AAuBA,OAAO,EAAoC,KAAK,aAAa,EAAmB,MAAM,YAAY,CAAC;AAenG,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;AAma3D,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"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":";AAuBA,OAAO,EAAoC,KAAK,aAAa,EAAmB,MAAM,YAAY,CAAC;AAenG,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;AAoa3D,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

@@ -22,7 +22,7 @@ import { basename, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { TypeshipClient, formatDebugEvent } from "./index.js";
 import { asApiResult, mediaTypeForPath } from "./core/http.js";
-import { GLOBALS, OMITTED_OPS, OPS, buildArgs } from "./ops.js";
+import { GLOBALS, INPUT_TYPES, OMITTED_OPS, OPS, buildArgs } from "./ops.js";
 import { DEFAULT_MAX_RESULT_CHARS, SUPPORTED_PROTOCOL_VERSIONS, McpAccountLinkRequired, argumentsError, asJsonRpc, binaryOutcome, callSharedTool, checkRequestHeaders, createStdioRpcHandler, dataOutcome, errorOutcome, handleRpc, hiddenOperations, isRpcOutcome, pageOutcome, parseIncludeList, prepareCall, resolveReferences, serverInstructions, requiredScopes, takeCancelled, textError, toolDefinitions, unmatchedIncludes, unsupportedAuthOutcome, visibleOps, } from "./mcp-protocol.js";
 import { fetchDocsText } from "./docs.js";
 import { assertCredentialDestination, assertStoredIdentity } from "./oauth-session.js";
@@ -34,7 +34,7 @@ export { McpAccountLinkRequired } from "./mcp-protocol.js";
 const BIN = "typeship";
 const PKG_NAME = "@typeship-ax/mcp";
 const SERVER_NAME = "typeship-mcp";
-const SERVER_VERSION = "0.22.0";
+const SERVER_VERSION = "0.23.0";
 /** The MCP client's announced name (clientInfo in request _meta), for the User-Agent. */
 let MCP_CLIENT_NAME = null;
 function noteClientInfo(message) {
@@ -272,7 +272,7 @@ async function callOperationRaw(op, rawArgs, remote, client) {
         hadCredential: !!remote || CLIENT_CREDENTIALS.get(client) === true,
         requiredScopes: requiredScopes(op.security),
     };
-    const shape = { fields, optionalFields, maxChars, pagination: op.pagination, args, safety: op.safety };
+    const shape = { fields, optionalFields, maxChars, pagination: op.pagination, args, safety: op.safety, outputSchema: op.outputSchema };
     try {
         const target = client[op.resource];
         let result = await asApiResult(target[op.method](...callArgs));
@@ -398,6 +398,7 @@ function saveBinary(bytes, _mediaType, suggestedName) {
 const docsSource = {
     ops: MCP_OPS,
     omittedOps: OMITTED_OPS,
+    inputTypes: INPUT_TYPES,
     hiddenOps: hiddenOperations(OPS, { readOnly: READ_ONLY, include: INCLUDE, uploads: LOCAL_PROCESS }, { readOnly: READ_ONLY_SWITCH, include: TOOLS_SWITCH }),
     generatedOperationCount: OPS.length,
     docsUrl: () => readJson("config.json")?.docsUrl ?? DOCS_URL_DEFAULT,

package/dist/ops.d.ts

@@ -1,3 +1,4 @@
+import type { InputTypes } from "./type-docs.js";
 export interface ParamSpec {
     /** wire name (JSON key, query name, or path placeholder) */
     name: string;
@@ -166,6 +167,10 @@ export type OmittedOpSpec = Pick<OpSpec, "resource" | "method" | "command" | "co
     };
 };
 export declare const OMITTED_OPS: OmittedOpSpec[];
+/** Named input types the operations' arguments reach, each described once
+ * with its fields typed by name: what docs lookups by type or argument
+ * path read. */
+export declare const INPUT_TYPES: InputTypes;
 /** 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: {