@typeship-ax/mcp 0.21.0 → 0.23.0

package/dist/search.js

@@ -0,0 +1,421 @@
+/**
+ * Operation search shared by the generated CLI (`docs search`) and MCP
+ * server (`search_docs`). Generated by Typeship — https://typeship.dev
+ *
+ * Agents describe a task ("assign issue", "list calls"), not an operation
+ * name, so ranking works on stems, weighs rare words over common ones
+ * (IDF), and reads the verb of the query against what each operation does:
+ * its HTTP method and whether its path names one item or a collection, or
+ * its GraphQL root field. GraphQL mutations are also indexed by their input
+ * fields, so "assign issue" finds issueUpdate through assigneeId.
+ * Deterministic and dependency-free.
+ */
+/** Reference matches per search page. */
+export const SEARCH_PAGE_SIZE = 10;
+/** Query verbs and the operation kinds they ask for, best first. */
+const VERBS = {
+    list: ["list"], all: ["list"], browse: ["list"], enumerate: ["list"],
+    search: ["search", "list"], find: ["search", "list", "get"], query: ["search", "list"], lookup: ["get", "search"],
+    get: ["get", "list"], release: ["delete"], fetch: ["get", "list"], retrieve: ["get", "list"], read: ["get", "list"], show: ["get", "list"],
+    view: ["get", "list"], check: ["get"], describe: ["get"], inspect: ["get"], status: ["get"],
+    create: ["create"], add: ["create", "update"], new: ["create"], make: ["create"], send: ["create"], post: ["create"],
+    submit: ["create"], open: ["create"], start: ["create", "update"], upload: ["create", "update"], generate: ["create"],
+    buy: ["create"], purchase: ["create"], place: ["create"], invite: ["create"], write: ["create", "update"],
+    publish: ["create", "update"], register: ["create"],
+    update: ["update"], change: ["update"], edit: ["update"], modify: ["update"], set: ["update", "create"],
+    assign: ["update", "create"], rename: ["update"], move: ["update"], close: ["update", "delete"], reopen: ["update"],
+    mark: ["update"], archive: ["delete", "update"], unarchive: ["update"], enable: ["update"], disable: ["update"],
+    pause: ["update"], resume: ["update"], replace: ["update"], patch: ["update"], merge: ["update", "create"],
+    save: ["create", "update"], follow: ["create", "update"], unfollow: ["delete", "update"], comment: ["create"], reply: ["create"], request: ["create"], hang: ["update", "delete"],
+    delete: ["delete"], remove: ["delete", "update"], destroy: ["delete"], erase: ["delete"], drop: ["delete"],
+    revoke: ["delete"], cancel: ["delete", "update"], unassign: ["update", "delete"], clear: ["delete"],
+};
+/** Words that name the caller: "who am I", "my issues", "me". */
+const IDENTITY_WORDS = new Set(["who", "whoami", "me", "my", "mine", "myself", "self"]);
+const IDENTITY_TERMS = ["me", "self", "whoami", "authenticated"];
+/** An operation about the caller: GET /user, /me/…, a viewer or me root
+ * field, users_get_authenticated. */
+function isIdentityOperation(op) {
+    if (op.graphql?.field)
+        return /^(viewer|me|currentUser|whoami)$/.test(op.graphql.field);
+    const nameWords = words([op.tool, op.method ?? ""].join(" "));
+    if (nameWords.some((w) => w === "me" || w === "whoami" || w === "authenticated" || w === "self"))
+        return true;
+    return /^(\/v\d+)?\/(me|user|self|whoami)(\/|$)/i.test(op.path) || /\/(users\/)?me(\/|$)/i.test(op.path);
+}
+/** Words that narrow a request rather than name the operation. */
+const QUALIFIERS = new Set(["yesterday", "today", "tomorrow", "recent", "recently", "latest", "last", "week", "month", "year", "daily"]);
+/** A few everyday words for what APIs call something else. */
+const SYNONYMS = {
+    now: ["current"], sms: ["message"], mms: ["message"], text: ["message"], document: ["file"], kyc: ["identity", "verification"],
+};
+const STOPWORDS = new Set([
+    "a", "an", "the", "to", "of", "for", "in", "on", "at", "from", "by", "with", "and", "or", "is", "are", "am", "be",
+    "do", "does", "it", "its", "this", "that", "these", "those", "into", "onto", "up", "how", "what", "which", "can",
+    "please", "via", "using", "some", "any", "there", "i", "you", "your", "we", "our",
+]);
+/** Field weights: a word in the operation's name says most about it. */
+const W_NAME = 10, W_SUMMARY = 6, W_PATH = 4, W_PARAM = 3, W_ENUM = 2, W_DESCRIPTION = 1.5, W_OUTPUT = 1;
+/** A light English stemmer: plurals, -ing/-ed, a few derivational
+ * suffixes, a trailing e. It only has to map a word and its common
+ * variants to one stem ("assignee", "assigned", "assigns" to "assign";
+ * "moderate", "moderations" to "moder"). */
+export function stem(word) {
+    let w = word.toLowerCase();
+    if (w.length <= 3)
+        return w;
+    if (w.endsWith("ies") && w.length > 4)
+        w = w.slice(0, -3) + "y";
+    else if (/(sses|xes|ches|shes|zes)$/.test(w))
+        w = w.slice(0, -2);
+    else if (w.endsWith("s") && !/(ss|us|is)$/.test(w))
+        w = w.slice(0, -1);
+    let stripped = false;
+    if (w.endsWith("ly") && w.length >= 6)
+        w = w.slice(0, -2);
+    for (const [suffix, min] of [["ing", 4], ["ed", 3]]) {
+        if (w.endsWith(suffix) && w.length - suffix.length >= min) {
+            w = w.slice(0, -suffix.length);
+            stripped = true;
+            break;
+        }
+    }
+    if (stripped) {
+        if (/(at|bl|iz)$/.test(w))
+            w += "e";
+        else if (/([^aeioulsz])\1$/.test(w))
+            w = w.slice(0, -1);
+    }
+    for (const [suffix, min] of [["ations", 4], ["ation", 4], ["ments", 4], ["ment", 4], ["ption", 4], ["ions", 4], ["ion", 4], ["ers", 4], ["er", 4], ["ee", 4], ["ate", 4]]) {
+        if (w.endsWith(suffix) && w.length - suffix.length >= min) {
+            w = w.slice(0, -suffix.length);
+            break;
+        }
+    }
+    if (w.endsWith("e") && w.length >= 5)
+        w = w.slice(0, -1);
+    return w;
+}
+/** Lowercase words of two or more characters, with snake, kebab, camel and
+ * letter-digit seams split so "createAccount" and "accounts_create" share
+ * words. */
+function words(text) {
+    return text.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([a-zA-Z])([0-9])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= 2);
+}
+function stems(text) {
+    return words(text).filter((w) => !STOPWORDS.has(w)).map(stem);
+}
+// A server keeps one operation list, and a hosted one filters the same
+// operation objects per request: cache by both.
+const INDEXES = new WeakMap();
+const INDEXED = new WeakMap();
+const READ_ACTIONS = ["list", "get", "search"];
+const WRITE_ACTIONS = ["create", "update", "delete"];
+/** The first of `words` (in order) that names an allowed action. */
+function actionIn(candidates, allowed) {
+    for (const word of candidates) {
+        const action = VERBS[word]?.[0];
+        if (action && allowed.includes(action))
+            return { action, word };
+    }
+    return undefined;
+}
+/** What an operation does, and the word of its name that says so: its
+ * name's verb when it has one, else its HTTP method and whether the path
+ * ends at one item or a collection. A read never creates, updates or
+ * deletes, whatever its name ("query comment" is a read of a comment). */
+function operationAction(op) {
+    const collection = () => {
+        const segments = op.path.replace(/\.[a-z]+$/i, "").split("/").filter(Boolean);
+        const last = segments.at(-1) ?? "";
+        if (last.startsWith("{") || last.startsWith(":"))
+            return "get";
+        return op.paginated ? "list" : "get";
+    };
+    if (op.graphql?.field) {
+        // issueUpdate, createIssue: the verb may sit at either end.
+        const fieldWords = words(op.graphql.field);
+        const read = op.graphql.kind !== "mutation";
+        const found = actionIn([...fieldWords].reverse(), read ? READ_ACTIONS : WRITE_ACTIONS);
+        if (found)
+            return found;
+        return { action: read ? (op.paginated || /s$/.test(op.graphql.field) ? "list" : "get") : "update", word: null };
+    }
+    const verb = op.httpMethod.toUpperCase();
+    const read = verb === "GET" || verb === "HEAD";
+    const found = actionIn(words(op.method ?? ""), read ? READ_ACTIONS : [...WRITE_ACTIONS, "search"]);
+    if (found)
+        return found;
+    if (verb === "DELETE")
+        return { action: "delete", word: null };
+    if (verb === "PUT" || verb === "PATCH")
+        return { action: "update", word: null };
+    if (verb === "POST")
+        return { action: "create", word: null };
+    return { action: collection(), word: null };
+}
+/** Literal path words: no parameters, versions or date segments. */
+function pathWords(path) {
+    return path.replace(/\.[a-z]+$/i, "").split("/").filter((s) => s && !/^[{:]/.test(s) && !/^v\d+$/i.test(s) && !/^\d/.test(s)).join(" ");
+}
+/** Property names and enum values of a schema, one level into objects,
+ * and one more for object-typed properties (a GraphQL input object). */
+function schemaWords(schema, depth, names, enums) {
+    if (!schema || typeof schema !== "object" || depth < 0)
+        return;
+    const node = schema;
+    if (Array.isArray(node.enum))
+        for (const value of node.enum)
+            if (typeof value === "string")
+                enums.push(value);
+    for (const key of ["anyOf", "oneOf", "allOf"]) {
+        if (Array.isArray(node[key]))
+            for (const part of node[key])
+                schemaWords(part, depth, names, enums);
+    }
+    if (node.items)
+        schemaWords(node.items, depth, names, enums);
+    const properties = node.properties;
+    if (properties && typeof properties === "object") {
+        for (const [name, child] of Object.entries(properties)) {
+            names.push(name);
+            schemaWords(child, depth - 1, names, enums);
+        }
+    }
+}
+function outputWords(schema, depth, out) {
+    if (!schema || typeof schema !== "object" || depth < 0)
+        return;
+    const node = schema;
+    if (typeof node.description === "string")
+        out.push(node.description.slice(0, 200));
+    if (node.items)
+        outputWords(node.items, depth, out);
+    for (const key of ["anyOf", "oneOf", "allOf"]) {
+        if (Array.isArray(node[key]))
+            for (const part of node[key])
+                outputWords(part, depth, out);
+    }
+    const properties = node.properties;
+    if (properties && typeof properties === "object") {
+        for (const [name, child] of Object.entries(properties)) {
+            out.push(name);
+            outputWords(child, depth - 1, out);
+        }
+    }
+}
+function firstSentence(text) {
+    return /^(.{1,200}?[.!?])(\s|$)/s.exec(text.trim())?.[1] ?? "";
+}
+function indexOperation(op) {
+    const weights = new Map();
+    const add = (text, weight) => {
+        for (const s of new Set(stems(text))) {
+            const entry = weights.get(s);
+            if (!entry)
+                weights.set(s, { best: weight, rest: 0 });
+            else if (weight > entry.best) {
+                entry.rest += entry.best;
+                entry.best = weight;
+            }
+            else
+                entry.rest += weight;
+        }
+    };
+    // GraphQL tools are named query_<field> / mutation_<field>; the prefix is
+    // the kind, not a word a task would use.
+    const name = op.graphql?.field
+        ? [op.graphql.field]
+        : [op.tool, op.resource ?? "", op.method ?? ""];
+    add(name.join(" "), W_NAME);
+    // Without a summary, the description's first sentence plays its part.
+    const summary = op.summary?.trim() || firstSentence(op.description ?? "");
+    add(summary, W_SUMMARY);
+    add(pathWords(op.path), W_PATH);
+    const paramNames = [];
+    const enumValues = [];
+    const paramText = [];
+    for (const param of op.params) {
+        paramNames.push(param.name);
+        if (param.enum)
+            enumValues.push(...param.enum);
+        if (param.description)
+            paramText.push(param.description.split("\n")[0].slice(0, 200));
+    }
+    const properties = (op.inputSchema?.properties ?? {});
+    for (const child of Object.values(properties))
+        schemaWords(child, 1, paramNames, enumValues);
+    add(paramNames.join(" "), W_PARAM);
+    add(enumValues.join(" "), W_ENUM);
+    add(op.description ?? "", W_DESCRIPTION);
+    add(paramText.join(" "), W_OUTPUT);
+    const output = [];
+    outputWords(op.outputSchema, 2, output);
+    add(output.join(" "), W_OUTPUT);
+    const { action, word } = operationAction(op);
+    const actionStem = word === null ? null : stem(word);
+    const nameStems = [...new Set(stems(name.join(" ")))].filter((s) => s !== actionStem);
+    return { weights, nameStems, action, actionStem, identity: isIdentityOperation(op), summary: stems(summary).join(" "), deprecated: op.deprecated === true || /^deprecated\b/i.test(op.summary ?? "") };
+}
+function indexFor(ops) {
+    const cached = INDEXES.get(ops);
+    if (cached)
+        return cached;
+    const docs = ops.map((op) => {
+        let doc = INDEXED.get(op);
+        if (!doc)
+            INDEXED.set(op, doc = indexOperation(op));
+        return doc;
+    });
+    const df = new Map();
+    for (const doc of docs)
+        for (const s of doc.weights.keys())
+            df.set(s, (df.get(s) ?? 0) + 1);
+    const index = { docs, df, vocabulary: [...df.keys()] };
+    INDEXES.set(ops, index);
+    return index;
+}
+/** A query stem's matches in the vocabulary: itself, and longer or
+ * shorter forms sharing a long prefix ("transcrib" and "transcript"),
+ * which count for less. */
+function variants(term, index) {
+    const out = new Map();
+    if (index.df.has(term))
+        out.set(term, 1);
+    if (term.length < 5)
+        return out;
+    for (const word of index.vocabulary) {
+        if (word === term || word.length < 5)
+            continue;
+        let common = 0;
+        while (common < word.length && common < term.length && word[common] === term[common])
+            common++;
+        if (common >= 6 && Math.max(word.length, term.length) - common <= 3)
+            out.set(word, 0.6);
+    }
+    return out;
+}
+function parseQuery(query, index) {
+    const raw = words(query);
+    let verb = null;
+    let identity = false;
+    const terms = [];
+    const seen = new Set();
+    for (const word of raw) {
+        if (IDENTITY_WORDS.has(word)) {
+            identity = true;
+            continue;
+        }
+        if (STOPWORDS.has(word))
+            continue;
+        const s = stem(word);
+        if (seen.has(s))
+            continue;
+        seen.add(s);
+        const actions = VERBS[word] ?? VERBS[s] ?? null;
+        const isVerb = actions !== null && actions.length > 0 && verb === null;
+        if (isVerb)
+            verb = actions;
+        const matches = variants(s, index);
+        for (const synonym of SYNONYMS[word] ?? [])
+            for (const [v, strength] of variants(stem(synonym), index))
+                matches.set(v, Math.max(matches.get(v) ?? 0, strength * 0.8));
+        // The verb is scored against what the operation does, so its word
+        // counts for little; the first noun is usually the object of the task.
+        const qualifier = QUALIFIERS.has(word);
+        const primary = !isVerb && !qualifier && !terms.some((t) => t.primary);
+        const weight = isVerb || qualifier ? 0.3 : primary ? 1.3 : 1;
+        terms.push({ matches, weight, verb: isVerb ? actions : null, primary, stem: s });
+    }
+    if (identity) {
+        const matches = new Map();
+        for (const t of IDENTITY_TERMS)
+            for (const [s, strength] of variants(stem(t), index))
+                matches.set(s, Math.max(matches.get(s) ?? 0, strength));
+        terms.push({ matches, weight: 0.8, verb: null, primary: false, stem: "@me" });
+    }
+    return { terms, verb };
+}
+/**
+ * Operations for a free-text query, best first. Weak matches (under a
+ * fifth of the best score, or matching only the query's verb) are left
+ * out, and deprecated operations follow every current one.
+ */
+export function rankOperations(ops, query) {
+    const index = indexFor(ops);
+    const { terms, verb } = parseQuery(query, index);
+    if (terms.length === 0)
+        return [];
+    const idf = (s) => Math.log(1 + index.docs.length / (index.df.get(s) ?? index.docs.length));
+    const nonVerbTerms = terms.filter((t) => t.verb === null).length;
+    const primary = terms.find((t) => t.primary);
+    const verbStem = terms.find((t) => t.verb !== null)?.stem ?? null;
+    const identityTerm = terms.find((t) => t.stem === "@me");
+    const identityIdf = Math.log(1 + index.docs.length / Math.max(1, index.docs.filter((d) => d.identity).length));
+    const scored = [];
+    const phrase = words(query).filter((w) => !STOPWORDS.has(w)).map(stem).join(" ");
+    index.docs.forEach((doc, position) => {
+        let score = 0;
+        let matchedNonVerb = 0;
+        let primaryInName = false;
+        let verbInName = false;
+        const covered = new Set();
+        for (const term of terms) {
+            let best = term === identityTerm && doc.identity ? W_NAME * identityIdf : 0;
+            for (const [s, strength] of term.matches) {
+                const entry = doc.weights.get(s);
+                if (!entry)
+                    continue;
+                const value = (entry.best + 0.1 * Math.min(entry.rest, 10)) * strength * idf(s);
+                if (value > best)
+                    best = value;
+                if (doc.nameStems.includes(s)) {
+                    covered.add(s);
+                    if (term === primary)
+                        primaryInName = true;
+                    // The query's verb as a noun of the name: upload_url for "upload".
+                    if (term.verb !== null)
+                        verbInName = true;
+                }
+            }
+            if (best > 0 && term.verb === null)
+                matchedNonVerb++;
+            score += best * term.weight;
+        }
+        if (score === 0)
+            return;
+        if (nonVerbTerms > 0 && matchedNonVerb === 0)
+            return;
+        // How much of the operation's name the query accounts for: call_list
+        // for "list calls" over sip_auth_calls_credential_list_mapping_delete.
+        const coverage = doc.nameStems.length === 0 ? 1 : covered.size / doc.nameStems.length;
+        score *= 0.6 + 0.8 * coverage;
+        // The query's verb against what the operation does.
+        if (verb) {
+            const rank = verb.indexOf(doc.action);
+            score *= rank === 0 ? 1.5 : rank > 0 ? 1.2 : doc.action === "search" && verb.includes("list") ? 1.2 : verbInName ? 1 : 0.55;
+            // The very word: issue_add_label for "add", over a generic create.
+            if (verbStem !== null && doc.actionStem === verbStem)
+                score *= 1.2;
+        }
+        // Every query word matched: a stronger signal than any single word.
+        if (matchedNonVerb === nonVerbTerms && nonVerbTerms > 1)
+            score *= 1.2;
+        if (phrase.includes(" ") && doc.nameStems.join(" ").includes(phrase))
+            score *= 1.2;
+        if (phrase.includes(" ") && doc.summary.includes(phrase))
+            score *= 1.3;
+        // The operation is named for the task's object: issue_update, not
+        // workflow_state_update, for "change issue state".
+        if (primaryInName)
+            score *= 1.3;
+        scored.push({ op: ops[position], score, deprecated: doc.deprecated });
+    });
+    if (scored.length === 0)
+        return [];
+    const top = Math.max(...scored.map((s) => s.score));
+    return scored
+        .filter((s) => s.score >= top * 0.2)
+        .sort((a, b) => Number(a.deprecated) - Number(b.deprecated) || b.score - a.score || a.op.tool.localeCompare(b.op.tool))
+        .map(({ op, score }) => ({ op, score: Math.round(score * 100) / 100 }));
+}

package/dist/type-docs.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Named input types for the docs surfaces (MCP read_docs, the CLI's docs
+ * command): a type's reference by name, and an argument path such as
+ * "filter.team.key" resolved to its type. Each type is described once with
+ * its fields typed by name, so a lookup is bounded and every type it
+ * mentions can be looked up the same way.
+ */
+export interface InputTypeField {
+    /** As an agent writes it: a type name, string[], "a"|"b", object. */
+    type: string;
+    required?: true;
+    description?: string;
+    default?: unknown;
+    deprecated?: true;
+}
+export interface InputTypeDoc {
+    description?: string;
+    /** An input object's fields. */
+    fields?: Record<string, InputTypeField>;
+    /** An enum's values. */
+    values?: unknown[];
+    /** A union's member types. */
+    variants?: string[];
+}
+export interface InputTypes {
+    types: Record<string, InputTypeDoc>;
+    /** Per tool, each argument whose type is (or contains) a named type. */
+    args: Record<string, Record<string, string>>;
+}
+/** The table's type names an expression mentions, in order. */
+export declare function namedTypesIn(table: InputTypes | undefined, expression: string | undefined): string[];
+/** A type by exact name, else by a case-insensitive match. */
+export declare function findInputType(table: InputTypes | undefined, name: string): string | undefined;
+/** How to read another type, in the caller's own syntax. */
+export type TypeLookupHint = (name: string) => string;
+/** A named type's reference: description, then its fields, values or
+ * members, then how to read the named types it mentions. */
+export declare function inputTypeText(table: InputTypes, name: string, lookup: TypeLookupHint): string;
+export type PathLookup = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    message: string;
+    available: string[];
+};
+/**
+ * What one argument path means: the field's type, whether it is required,
+ * its description, and, when its type is named, that type's reference in
+ * full (a comparator's operators, an enum's values). `root` is an
+ * operation (its tool name, inline input schema, and how the caller names
+ * it) or a named type.
+ */
+export declare function argumentPathText(table: InputTypes | undefined, root: {
+    tool: string;
+    inputSchema: Record<string, unknown>;
+    label?: string;
+} | {
+    type: string;
+}, path: string, lookup: TypeLookupHint): PathLookup;
+//# sourceMappingURL=type-docs.d.ts.map

package/dist/type-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-docs.d.ts","sourceRoot":"","sources":["../src/type-docs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC,wBAAwB;IACxB,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACpC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC9C;AAUD,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAGpG;AASD,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK7F;AAYD,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAEtD;4DAC4D;AAC5D,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAyB7F;AA6BD,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAExD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAC/F,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,GACrB,UAAU,CAyDZ"}

package/dist/type-docs.js

@@ -0,0 +1,174 @@
+/**
+ * Named input types for the docs surfaces (MCP read_docs, the CLI's docs
+ * command): a type's reference by name, and an argument path such as
+ * "filter.team.key" resolved to its type. Each type is described once with
+ * its fields typed by name, so a lookup is bounded and every type it
+ * mentions can be looked up the same way.
+ */
+/** Enum values a type page lists before a count. */
+const TYPE_ENUM_VALUES = 200;
+/** One line of prose: links reduced to their text. */
+function prose(text) {
+    return (text ?? "").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/\s+/g, " ").trim();
+}
+/** The table's type names an expression mentions, in order. */
+export function namedTypesIn(table, expression) {
+    if (!table || !expression)
+        return [];
+    return [...new Set(expression.split(/[|()[\]\s]+/).filter((part) => Object.hasOwn(table.types, part)))];
+}
+/** The one input object an expression names (IssueFilter, IssueFilter[]),
+ * whose fields a path continues into. */
+function objectTypeOf(table, expression) {
+    const objects = namedTypesIn(table, expression).filter((name) => table.types[name].fields);
+    return objects.length === 1 ? objects[0] : undefined;
+}
+/** A type by exact name, else by a case-insensitive match. */
+export function findInputType(table, name) {
+    if (!table)
+        return undefined;
+    if (Object.hasOwn(table.types, name))
+        return name;
+    const lower = name.toLowerCase();
+    return Object.keys(table.types).find((candidate) => candidate.toLowerCase() === lower);
+}
+function fieldLine(name, field) {
+    const extras = [
+        ...(field.required ? ["required"] : []),
+        ...(field.default !== undefined ? ["default " + JSON.stringify(field.default)] : []),
+        ...(field.deprecated ? ["deprecated"] : []),
+    ];
+    const description = prose(field.description);
+    return "  " + name + " (" + field.type + (extras.length ? ", " + extras.join(", ") : "") + ")" + (description ? ": " + description : "");
+}
+/** A named type's reference: description, then its fields, values or
+ * members, then how to read the named types it mentions. */
+export function inputTypeText(table, name, lookup) {
+    const doc = table.types[name];
+    const kind = doc.fields ? "input object" : doc.values ? "enum" : "union";
+    const lines = [name + " (" + kind + ")"];
+    if (doc.description)
+        lines.push(prose(doc.description));
+    const mentioned = [];
+    if (doc.fields) {
+        const entries = Object.entries(doc.fields);
+        lines.push("", entries.length === 0 ? "No fields." : "Fields (" + entries.length + "):");
+        for (const [field, spec] of entries) {
+            lines.push(fieldLine(field, spec));
+            mentioned.push(...namedTypesIn(table, spec.type));
+        }
+    }
+    else if (doc.values) {
+        const values = doc.values.slice(0, TYPE_ENUM_VALUES).map((value) => JSON.stringify(value));
+        lines.push("", "Values: " + values.join(", ") + (doc.values.length > TYPE_ENUM_VALUES ? ", … " + (doc.values.length - TYPE_ENUM_VALUES) + " more" : ""));
+    }
+    else if (doc.variants) {
+        lines.push("", "One of: " + doc.variants.join(" | "));
+        for (const variant of doc.variants)
+            mentioned.push(...namedTypesIn(table, variant));
+    }
+    const others = [...new Set(mentioned)].filter((other) => other !== name);
+    if (others.length > 0) {
+        lines.push("", "Types used above (" + others.length + "): " + others.join(", ") + ". Read one with " + lookup("<type>") + ".");
+    }
+    return lines.join("\n");
+}
+function inlineObject(schema) {
+    if (!schema || typeof schema !== "object")
+        return undefined;
+    if (schema.properties && typeof schema.properties === "object")
+        return schema;
+    if (schema.items)
+        return inlineObject(schema.items);
+    const variants = schema.anyOf ?? schema.oneOf;
+    if (Array.isArray(variants)) {
+        const objects = variants.map(inlineObject).filter((variant) => variant !== undefined);
+        if (objects.length === 1)
+            return objects[0];
+    }
+    return undefined;
+}
+function inlineType(schema) {
+    if (Array.isArray(schema.enum))
+        return schema.enum.filter((value) => value !== null).map((value) => JSON.stringify(value)).join("|");
+    const variants = schema.anyOf ?? schema.oneOf;
+    if (Array.isArray(variants))
+        return [...new Set(variants.map(inlineType))].filter((t) => t !== "null").join("|") || "null";
+    const types = (Array.isArray(schema.type) ? schema.type : typeof schema.type === "string" ? [schema.type] : []).filter((t) => t !== "null");
+    if (types.includes("array")) {
+        const inner = schema.items ? inlineType(schema.items) : "any";
+        return (/[| ]/.test(inner) ? "(" + inner + ")" : inner) + "[]";
+    }
+    return types.join("|") || (schema.properties ? "object" : "any");
+}
+/**
+ * What one argument path means: the field's type, whether it is required,
+ * its description, and, when its type is named, that type's reference in
+ * full (a comparator's operators, an enum's values). `root` is an
+ * operation (its tool name, inline input schema, and how the caller names
+ * it) or a named type.
+ */
+export function argumentPathText(table, root, path, lookup) {
+    const segments = path.split(".").map((segment) => segment.trim()).filter((segment) => segment.length > 0);
+    if (segments.length === 0)
+        return { ok: false, message: "The path is empty.", available: [] };
+    // Walk the named-type table where the path has a type name, else the
+    // operation's inline schema.
+    let typeName = "type" in root ? root.type : undefined;
+    let inline = "type" in root ? undefined : root.inputSchema;
+    let expression;
+    let field;
+    const label = "type" in root ? root.type : root.label ?? root.tool;
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        const at = index === 0 ? label : label + " " + segments.slice(0, index).join(".");
+        if (typeName && table) {
+            const fields = table.types[typeName].fields ?? {};
+            if (!Object.hasOwn(fields, segment))
+                return { ok: false, message: at + " (" + typeName + ") has no field \"" + segment + "\".", available: Object.keys(fields) };
+            field = fields[segment];
+            expression = field.type;
+            inline = undefined;
+        }
+        else {
+            const object = inlineObject(inline);
+            const properties = object?.properties ?? {};
+            if (!object || !Object.hasOwn(properties, segment)) {
+                return { ok: false, message: object ? at + " has no field \"" + segment + "\"." : at + " is not an object; the path cannot continue past it.", available: Object.keys(properties) };
+            }
+            const child = properties[segment];
+            const topLevel = index === 0 && !("type" in root) ? table?.args[root.tool]?.[segment] : undefined;
+            expression = topLevel ?? inlineType(child);
+            field = {
+                type: expression,
+                ...(Array.isArray(object.required) && object.required.includes(segment) ? { required: true } : {}),
+                ...(typeof child.description === "string" ? { description: child.description } : {}),
+            };
+            inline = child;
+        }
+        typeName = table ? objectTypeOf(table, expression) : undefined;
+        if (!typeName && index < segments.length - 1 && !inlineObject(inline)) {
+            return { ok: false, message: label + " " + segments.slice(0, index + 1).join(".") + " is " + expression + ", not an object; the path cannot continue past it.", available: [] };
+        }
+    }
+    const lines = [label + " " + segments.join(".") + ": " + field.type + (field.required ? " (required)" : "")];
+    const description = prose(field.description);
+    if (description)
+        lines.push(description);
+    const named = namedTypesIn(table, expression);
+    if (named.length > 0 && table) {
+        for (const name of named)
+            lines.push("", inputTypeText(table, name, lookup));
+    }
+    else {
+        const object = inlineObject(inline);
+        if (object) {
+            const required = new Set(object.required ?? []);
+            lines.push("", "Fields:");
+            for (const [name, child] of Object.entries(object.properties ?? {})) {
+                lines.push(fieldLine(name, { type: inlineType(child), ...(required.has(name) ? { required: true } : {}), ...(child.description ? { description: child.description } : {}) }));
+            }
+        }
+    }
+    return { ok: true, text: lines.join("\n") };
+}