@typeship-ax/mcp 0.21.0 → 0.22.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 }));
+}