@utdk/mcp-core 0.1.0-dev.37053ca

package/dist/meta-tools.d.ts

@@ -0,0 +1,201 @@
+import type { ProviderTool } from "./loader.js";
+/**
+ * A text content block. Structurally compatible with the MCP SDK's text
+ * `ContentBlock` so handlers can be returned directly from a tools/call
+ * handler.
+ */
+export interface TextContent {
+    type: "text";
+    text: string;
+}
+/**
+ * Result of a tools/call handler. Structurally compatible with the MCP SDK's
+ * `CallToolResult` so values returned from these handlers can be passed
+ * straight back to the SDK without an adapter: the stdio server returns them
+ * directly from its `tools/call` request handler, and the hosted gateway
+ * (Phase 2) serializes the same shape over HTTP. mcp-core deliberately does
+ * not depend on `@modelcontextprotocol/sdk`; the handlers return fresh object
+ * literals whose inferred types are assignable to the SDK's `ServerResult`
+ * union, and this interface is the documented shape of those literals.
+ */
+export interface CallToolResult {
+    content: TextContent[];
+    isError?: boolean;
+}
+/**
+ * Ensure the input schema is a valid MCP tool inputSchema (type: "object").
+ */
+export declare function normalizeInputSchema(schema: Record<string, unknown>): {
+    type: "object";
+    properties?: Record<string, object>;
+    required?: string[];
+};
+export declare const META_TOOLS: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            provider: {
+                type: string;
+                description: string;
+            };
+            group_by: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            query?: undefined;
+            limit?: undefined;
+            tool_name?: undefined;
+            arguments?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            provider: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            group_by?: undefined;
+            tool_name?: undefined;
+            arguments?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            tool_name: {
+                type: string;
+                description: string;
+            };
+            provider?: undefined;
+            group_by?: undefined;
+            query?: undefined;
+            limit?: undefined;
+            arguments?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            tool_name: {
+                type: string;
+                description: string;
+            };
+            arguments: {
+                type: string;
+                description: string;
+            };
+            provider?: undefined;
+            group_by?: undefined;
+            query?: undefined;
+            limit?: undefined;
+        };
+        required: string[];
+    };
+})[];
+export declare function handleListTools(tools: ProviderTool[], args: Record<string, unknown>): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function handleSearchTools(tools: ProviderTool[], args: Record<string, unknown>): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function handleToolInfo(toolMap: Map<string, ProviderTool>, args: Record<string, unknown>): {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+};
+/**
+ * Payload handed to an {@link Execute} callback: the resolved tool plus the
+ * arguments extracted from the `call_tool` meta-tool's `arguments` field.
+ */
+export interface ExecuteInput {
+    tool: ProviderTool;
+    args: Record<string, unknown>;
+}
+/**
+ * Transport-agnostic result of executing a tool.
+ *
+ * - `ok: true` carries the parsed tool output (`data`); mcp-core serializes it
+ *   as the `text` content of the {@link CallToolResult}.
+ * - `ok: false` carries an `error` message; mcp-core surfaces it as an
+ *   `isError` {@link CallToolResult}.
+ *
+ * The stdio server wraps its `fetch`-based executor (which throws on HTTP
+ * errors) into this discriminated union; the hosted gateway (Phase 2) maps its
+ * `IsolateResult` onto the same shape. Keeping errors as values (instead of
+ * throwing) lets both transports share a single handler.
+ */
+export type ExecuteResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Callback that performs the actual tool execution. Injected into
+ * {@link handleCallTool} so the handler stays transport-agnostic: the stdio
+ * server passes a `fetch`-based implementation, the gateway passes its own
+ * executor.
+ */
+export type Execute = (input: ExecuteInput) => Promise<ExecuteResult>;
+/**
+ * Handle a `call_tool` meta-tool invocation.
+ *
+ * `tool` is the *resolved* tool (the caller looks it up in its tool map, which
+ * for the gateway is the per-caller filtered catalog); `undefined` produces an
+ * "Unknown tool" result, matching the prior stdio behavior. The injected
+ * `execute` callback is invoked with `{ tool, args }` (the arguments extracted
+ * from `args["arguments"]`) and its {@link ExecuteResult} is wrapped in a
+ * {@link CallToolResult}.
+ */
+export declare function handleCallTool(tool: ProviderTool | undefined, args: Record<string, unknown>, execute: Execute): Promise<{
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/meta-tools.js

@@ -0,0 +1,183 @@
+import { searchTools, groupTools } from "./search.js";
+// ---------------------------------------------------------------------------
+// Schema normalization
+// ---------------------------------------------------------------------------
+/**
+ * Ensure the input schema is a valid MCP tool inputSchema (type: "object").
+ */
+export function normalizeInputSchema(schema) {
+    return {
+        type: "object",
+        ...(schema["properties"]
+            ? { properties: schema["properties"] }
+            : {}),
+        ...(schema["required"] ? { required: schema["required"] } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Meta-tool definitions (served by tools/list)
+// ---------------------------------------------------------------------------
+export const META_TOOLS = [
+    {
+        name: "list_tools",
+        description: "List available tool names without full schemas. Pass an optional provider to filter results, or group_by to organize by category.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                provider: {
+                    type: "string",
+                    description: "Filter results to tools from this provider name (e.g. 'github')",
+                },
+                group_by: {
+                    type: "string",
+                    enum: ["provider", "tag"],
+                    description: "Group results by 'provider' or by OpenAPI 'tag'. When omitted, returns a flat list of names.",
+                },
+            },
+        },
+    },
+    {
+        name: "search_tools",
+        description: "Find tools by keyword. Searches tool names, OpenAPI tags, and descriptions using TF-IDF relevance ranking so the LLM can locate relevant tools without browsing the full catalog.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Natural language or keyword search (all words must appear in name, tags, or description)",
+                },
+                provider: {
+                    type: "string",
+                    description: "Restrict search to tools from this provider name (e.g. 'github')",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of results to return (default 10)",
+                },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "tool_info",
+        description: "Get the full schema and metadata for a specific tool by name. Use this after list_tools or search_tools to retrieve the complete input schema before calling the tool.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tool_name: {
+                    type: "string",
+                    description: "The MCP tool name (e.g. 'github__repos_list')",
+                },
+            },
+            required: ["tool_name"],
+        },
+    },
+    {
+        name: "call_tool",
+        description: "Execute any registered tool by name with the provided arguments. Use tool_info first to get the correct argument schema.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tool_name: {
+                    type: "string",
+                    description: "The MCP tool name to execute (e.g. 'github__repos_list')",
+                },
+                arguments: {
+                    type: "object",
+                    description: "Arguments to pass to the tool",
+                },
+            },
+            required: ["tool_name", "arguments"],
+        },
+    },
+];
+// ---------------------------------------------------------------------------
+// Meta-tool call handlers
+//
+// Each handler returns a fresh object literal (no explicit return annotation)
+// so the inferred type stays assignable to the MCP SDK's `ServerResult`
+// union, which includes an index-signature envelope that named interface types
+// cannot satisfy. `type: "text" as const` keeps the content block's `type`
+// literal so the result is still assignable to {@link CallToolResult}.
+// ---------------------------------------------------------------------------
+export function handleListTools(tools, args) {
+    const providerFilter = typeof args["provider"] === "string" ? args["provider"] : undefined;
+    const groupBy = args["group_by"] === "provider" || args["group_by"] === "tag"
+        ? args["group_by"]
+        : undefined;
+    const filtered = providerFilter
+        ? tools.filter((t) => t.providerName === providerFilter)
+        : tools;
+    const result = groupBy === "provider" || groupBy === "tag"
+        ? groupTools(filtered, groupBy)
+        : filtered.map((t) => t.mcpName);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+}
+export function handleSearchTools(tools, args) {
+    const query = typeof args["query"] === "string" ? args["query"] : "";
+    const providerFilter = typeof args["provider"] === "string" ? args["provider"] : undefined;
+    const limit = typeof args["limit"] === "number" && args["limit"] > 0 ? Math.floor(args["limit"]) : 10;
+    const results = searchTools(tools, query, providerFilter, limit);
+    return {
+        content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+    };
+}
+export function handleToolInfo(toolMap, args) {
+    const requestedName = typeof args["tool_name"] === "string" ? args["tool_name"] : "";
+    const tool = toolMap.get(requestedName);
+    if (!tool) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Unknown tool: ${requestedName}` }],
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    name: tool.mcpName,
+                    description: tool.description,
+                    provider: tool.providerName,
+                    inputSchema: normalizeInputSchema(tool.inputSchema),
+                }, null, 2),
+            },
+        ],
+    };
+}
+/**
+ * Handle a `call_tool` meta-tool invocation.
+ *
+ * `tool` is the *resolved* tool (the caller looks it up in its tool map, which
+ * for the gateway is the per-caller filtered catalog); `undefined` produces an
+ * "Unknown tool" result, matching the prior stdio behavior. The injected
+ * `execute` callback is invoked with `{ tool, args }` (the arguments extracted
+ * from `args["arguments"]`) and its {@link ExecuteResult} is wrapped in a
+ * {@link CallToolResult}.
+ */
+export async function handleCallTool(tool, args, execute) {
+    const requestedName = typeof args["tool_name"] === "string" ? args["tool_name"] : "";
+    if (!tool) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Unknown tool: ${requestedName}` }],
+        };
+    }
+    const toolArgs = typeof args["arguments"] === "object" && args["arguments"] !== null
+        ? args["arguments"]
+        : {};
+    const result = await execute({ tool, args: toolArgs });
+    if (!result.ok) {
+        return {
+            isError: true,
+            content: [
+                { type: "text", text: `Error calling ${tool.mcpName}: ${result.error}` },
+            ],
+        };
+    }
+    const text = typeof result.data === "string" ? result.data : JSON.stringify(result.data, null, 2);
+    return { content: [{ type: "text", text }] };
+}
+//# sourceMappingURL=meta-tools.js.map

package/dist/meta-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-tools.js","sourceRoot":"","sources":["../src/meta-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAgCtD,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAA+B;IAKlE,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC;YACtB,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,YAAY,CAA2B,EAAE;YAChE,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5E,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,+CAA+C;AAC/C,8EAA8E;AAE9E,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EACT,mIAAmI;QACrI,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE;gBACV,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,iEAAiE;iBAC/E;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,UAAU,EAAE,KAAK,CAAC;oBACzB,WAAW,EACT,8FAA8F;iBACjG;aACF;SACF;KACF;IACD;QACE,IAAI,EAAE,cAAc;QACpB,WAAW,EACT,mLAAmL;QACrL,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,0FAA0F;iBAC7F;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,kEAAkE;iBAChF;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,kDAAkD;iBAChE;aACF;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;KACF;IACD;QACE,IAAI,EAAE,WAAW;QACjB,WAAW,EACT,wKAAwK;QAC1K,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE;gBACV,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,+CAA+C;iBAC7D;aACF;YACD,QAAQ,EAAE,CAAC,WAAW,CAAC;SACxB;KACF;IACD;QACE,IAAI,EAAE,WAAW;QACjB,WAAW,EACT,0HAA0H;QAC5H,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE;gBACV,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,0DAA0D;iBACxE;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,+BAA+B;iBAC7C;aACF;YACD,QAAQ,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC;SACrC;KACF;CACF,CAAC;AAEF,8EAA8E;AAC9E,0BAA0B;AAC1B,EAAE;AACF,8EAA8E;AAC9E,wEAAwE;AACxE,+EAA+E;AAC/E,2EAA2E;AAC3E,uEAAuE;AACvE,8EAA8E;AAE9E,MAAM,UAAU,eAAe,CAAC,KAAqB,EAAE,IAA6B;IAClF,MAAM,cAAc,GAClB,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,MAAM,OAAO,GACX,IAAI,CAAC,UAAU,CAAC,KAAK,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,KAAK;QAC3D,CAAC,CAAE,IAAI,CAAC,UAAU,CAAwB;QAC1C,CAAC,CAAC,SAAS,CAAC;IAChB,MAAM,QAAQ,GAAG,cAAc;QAC7B,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,cAAc,CAAC;QACxD,CAAC,CAAC,KAAK,CAAC;IACV,MAAM,MAAM,GACV,OAAO,KAAK,UAAU,IAAI,OAAO,KAAK,KAAK;QACzC,CAAC,CAAC,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC/B,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KAC5E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAqB,EAAE,IAA6B;IACpF,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACrE,MAAM,cAAc,GAClB,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,MAAM,KAAK,GACT,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1F,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;IACjE,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KAC7E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,OAAkC,EAClC,IAA6B;IAE7B,MAAM,aAAa,GAAG,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACrF,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACxC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,iBAAiB,aAAa,EAAE,EAAE,CAAC;SAC7E,CAAC;IACJ,CAAC;IACD,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAClB;oBACE,IAAI,EAAE,IAAI,CAAC,OAAO;oBAClB,WAAW,EAAE,IAAI,CAAC,WAAW;oBAC7B,QAAQ,EAAE,IAAI,CAAC,YAAY;oBAC3B,WAAW,EAAE,oBAAoB,CAAC,IAAI,CAAC,WAAW,CAAC;iBACpD,EACD,IAAI,EACJ,CAAC,CACF;aACF;SACF;KACF,CAAC;AACJ,CAAC;AAsCD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAA8B,EAC9B,IAA6B,EAC7B,OAAgB;IAEhB,MAAM,aAAa,GAAG,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACrF,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,iBAAiB,aAAa,EAAE,EAAE,CAAC;SAC7E,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GACZ,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI;QACjE,CAAC,CAAE,IAAI,CAAC,WAAW,CAA6B;QAChD,CAAC,CAAC,EAAE,CAAC;IACT,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EAAE;gBACP,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,iBAAiB,IAAI,CAAC,OAAO,KAAK,MAAM,CAAC,KAAK,EAAE,EAAE;aAClF;SACF,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GACR,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACvF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AACxD,CAAC"}

package/dist/search.d.ts

@@ -0,0 +1,44 @@
+import type { ProviderTool } from "./loader.js";
+/**
+ * Tokenize text into lowercase words, splitting on non-alphanumeric characters.
+ * Also splits camelCase boundaries for better matching of MCP tool names.
+ *
+ * Examples:
+ *   "github__repos_list" → ["github", "repos", "list"]
+ *   "List public repositories" → ["list", "public", "repositories"]
+ *   "security-advisories" → ["security", "advisories"]
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Build a TF-IDF scoring function over a corpus of tools.
+ *
+ * Field weights applied during term-frequency calculation:
+ *   - name  × 3   (most signal)
+ *   - tags  × 2   (category signal)
+ *   - description × 1
+ *
+ * IDF formula: log((N + 1) / df)  — smoothed to avoid division-by-zero.
+ *
+ * Returns a function `score(tool, queryWords) → number` that can be called
+ * for each candidate. Build once per search call, reuse across candidates.
+ */
+export declare function buildTfIdf(tools: ProviderTool[]): (tool: ProviderTool, words: string[]) => number;
+/**
+ * Search tools by keyword using TF-IDF relevance ranking.
+ *
+ * Matching: ALL query words must appear in at least one of name, tags, or
+ * description (case-insensitive substring match used for filtering; TF-IDF
+ * token scoring used for ranking).
+ *
+ * Returns up to `limit` results in descending relevance order.
+ */
+export declare function searchTools(tools: ProviderTool[], query: string, provider: string | undefined, limit: number): Array<{
+    name: string;
+    description: string;
+    tags: string[];
+}>;
+/**
+ * Group tools by provider name or by OpenAPI tag.
+ * Tools with no tags fall back to grouping under their provider name.
+ */
+export declare function groupTools(tools: ProviderTool[], by: "provider" | "tag"): Record<string, string[]>;

package/dist/search.js

@@ -0,0 +1,137 @@
+// ---------------------------------------------------------------------------
+// Tokenization
+// ---------------------------------------------------------------------------
+/**
+ * Tokenize text into lowercase words, splitting on non-alphanumeric characters.
+ * Also splits camelCase boundaries for better matching of MCP tool names.
+ *
+ * Examples:
+ *   "github__repos_list" → ["github", "repos", "list"]
+ *   "List public repositories" → ["list", "public", "repositories"]
+ *   "security-advisories" → ["security", "advisories"]
+ */
+export function tokenize(text) {
+    return text
+        .replace(/([a-z])([A-Z])/g, "$1 $2") // split camelCase boundaries
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+// ---------------------------------------------------------------------------
+// TF-IDF scoring
+// ---------------------------------------------------------------------------
+/**
+ * Build a TF-IDF scoring function over a corpus of tools.
+ *
+ * Field weights applied during term-frequency calculation:
+ *   - name  × 3   (most signal)
+ *   - tags  × 2   (category signal)
+ *   - description × 1
+ *
+ * IDF formula: log((N + 1) / df)  — smoothed to avoid division-by-zero.
+ *
+ * Returns a function `score(tool, queryWords) → number` that can be called
+ * for each candidate. Build once per search call, reuse across candidates.
+ */
+export function buildTfIdf(tools) {
+    const N = tools.length;
+    if (N === 0)
+        return () => 0;
+    // Precompute weighted token bags for each tool
+    const bags = tools.map((tool) => {
+        const bag = new Map();
+        const add = (tokens, weight) => {
+            for (const tok of tokens) {
+                bag.set(tok, (bag.get(tok) ?? 0) + weight);
+            }
+        };
+        add(tokenize(tool.mcpName), 3);
+        for (const tag of tool.tags) {
+            add(tokenize(tag), 2);
+        }
+        add(tokenize(tool.description), 1);
+        return bag;
+    });
+    // Document frequency: how many tools contain each token
+    const df = new Map();
+    for (const bag of bags) {
+        for (const tok of bag.keys()) {
+            df.set(tok, (df.get(tok) ?? 0) + 1);
+        }
+    }
+    const bagIndex = new Map(tools.map((t, i) => [t, bags[i]]));
+    return (tool, words) => {
+        const bag = bagIndex.get(tool);
+        if (!bag)
+            return 0;
+        const totalWeight = [...bag.values()].reduce((s, v) => s + v, 0) || 1;
+        let score = 0;
+        for (const word of words) {
+            const tf = (bag.get(word) ?? 0) / totalWeight;
+            const docFreq = df.get(word) ?? 0;
+            if (docFreq === 0)
+                continue;
+            const idf = Math.log((N + 1) / docFreq);
+            score += tf * idf;
+        }
+        return score;
+    };
+}
+// ---------------------------------------------------------------------------
+// searchTools
+// ---------------------------------------------------------------------------
+/**
+ * Search tools by keyword using TF-IDF relevance ranking.
+ *
+ * Matching: ALL query words must appear in at least one of name, tags, or
+ * description (case-insensitive substring match used for filtering; TF-IDF
+ * token scoring used for ranking).
+ *
+ * Returns up to `limit` results in descending relevance order.
+ */
+export function searchTools(tools, query, provider, limit) {
+    const words = tokenize(query);
+    if (words.length === 0)
+        return [];
+    const source = provider ? tools.filter((t) => t.providerName === provider) : tools;
+    const scoreFn = buildTfIdf(source);
+    const candidates = [];
+    for (const tool of source) {
+        const nameLower = tool.mcpName.toLowerCase();
+        const tagsText = tool.tags.join(" ").toLowerCase();
+        const descLower = tool.description.toLowerCase();
+        const allMatch = words.every((word) => nameLower.includes(word) || tagsText.includes(word) || descLower.includes(word));
+        if (allMatch) {
+            candidates.push({ tool, score: scoreFn(tool, words) });
+        }
+    }
+    candidates.sort((a, b) => b.score - a.score);
+    return candidates.slice(0, limit).map(({ tool }) => ({
+        name: tool.mcpName,
+        description: tool.description,
+        tags: tool.tags,
+    }));
+}
+// ---------------------------------------------------------------------------
+// groupTools
+// ---------------------------------------------------------------------------
+/**
+ * Group tools by provider name or by OpenAPI tag.
+ * Tools with no tags fall back to grouping under their provider name.
+ */
+export function groupTools(tools, by) {
+    const grouped = {};
+    for (const tool of tools) {
+        if (by === "provider") {
+            (grouped[tool.providerName] ??= []).push(tool.mcpName);
+        }
+        else {
+            const keys = tool.tags.length > 0 ? tool.tags : [tool.providerName];
+            for (const key of keys) {
+                (grouped[key] ??= []).push(tool.mcpName);
+            }
+        }
+    }
+    return grouped;
+}
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@utdk/mcp-core",
+  "version": "0.1.0-dev.37053ca",
+  "type": "module",
+  "description": "Shared tool catalog and meta-tool handlers for @utdk/mcp packages",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@utcp/http": "^1.1.1",
+    "@utdk/common": "0.1.0-dev.37053ca"
+  },
+  "optionalDependencies": {
+    "@utdk/datadog": "1.0.0-20260407.1-dev.37053ca",
+    "@utdk/figma": "0.37.0-20260408.5-dev.37053ca",
+    "@utdk/github": "1.1.4-20260608.2-dev.37053ca",
+    "@utdk/airtable": "0.1.0-20260530.2-dev.37053ca",
+    "@utdk/google": "0.0.1-20260407.8-dev.37053ca",
+    "@utdk/intercom": "2.15.0-20260530.1-dev.37053ca",
+    "@utdk/hubspot": "3.0.0-20260530.2-dev.37053ca",
+    "@utdk/jira": "1001.0.0-SNAPSHOT-500abd49de29b046db51cf0460caa503167075c0-20260530.2-dev.37053ca",
+    "@utdk/linear": "1.0.0-20260530.1-dev.37053ca",
+    "@utdk/notion": "1.0.0-20260530.1-dev.37053ca",
+    "@utdk/salesforce": "58.0.0-20260530.1-dev.37053ca",
+    "@utdk/openai": "2.3.0-20260407.1-dev.37053ca",
+    "@utdk/sendgrid": "1.0.0-20260530.1-dev.37053ca",
+    "@utdk/slack": "1.7.0-20260530.1-dev.37053ca",
+    "@utdk/spotify": "1.0.0-20260407.6-dev.37053ca",
+    "@utdk/twilio": "1.0.0-20260530.2-dev.37053ca",
+    "@utdk/zendesk": "2.0.0-20260530.2-dev.37053ca",
+    "@utdk/stripe": "0.0.1-20260530.2-dev.37053ca"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.7.3",
+    "vitest": "2.1.5"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}