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

package/src/__tests__/loader.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from "vitest";
+import { parseProviderNames, loadProviders } from "../loader.js";
+
+// ---------------------------------------------------------------------------
+// parseProviderNames
+// ---------------------------------------------------------------------------
+
+describe("parseProviderNames", () => {
+  it("parses comma-separated provider names", () => {
+    expect(parseProviderNames("github,slack,stripe")).toEqual(["github", "slack", "stripe"]);
+  });
+
+  it("trims whitespace", () => {
+    expect(parseProviderNames("github, slack , stripe")).toEqual(["github", "slack", "stripe"]);
+  });
+
+  it("lowercases names", () => {
+    expect(parseProviderNames("GitHub,Slack")).toEqual(["github", "slack"]);
+  });
+
+  it("returns empty array for undefined", () => {
+    expect(parseProviderNames(undefined)).toEqual([]);
+  });
+
+  it("returns empty array for empty string", () => {
+    expect(parseProviderNames("")).toEqual([]);
+  });
+
+  it("filters empty entries from double commas", () => {
+    expect(parseProviderNames("github,,slack")).toEqual(["github", "slack"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// loadProviders
+// ---------------------------------------------------------------------------
+
+describe("loadProviders", () => {
+  it("returns an empty array for an unknown provider", async () => {
+    const tools = await loadProviders(["__nonexistent_provider__"]);
+    expect(tools).toEqual([]);
+  });
+
+  it("returns an empty array for an empty provider list", async () => {
+    const tools = await loadProviders([]);
+    expect(tools).toEqual([]);
+  });
+
+  it("loads tools from github provider (integration)", async () => {
+    // This test requires the @utdk/github package to be present in the workspace.
+    // It verifies that the loader correctly converts the OpenAPI doc to MCP tools.
+    const tools = await loadProviders(["github"]);
+
+    expect(tools.length).toBeGreaterThan(0);
+
+    // All tools should have required fields
+    for (const tool of tools) {
+      expect(tool.mcpName).toMatch(/^[a-zA-Z0-9_-]+$/);
+      expect(tool.providerName).toBe("github");
+      expect(tool.description).toBeTruthy();
+      expect(tool.method).toMatch(/^(GET|POST|PUT|PATCH|DELETE)$/);
+      expect(tool.routeTemplate).toMatch(/^https?:\/\//);
+      expect(tool.inputSchema).toBeDefined();
+    }
+  });
+
+  it("loads tools from stripe provider (integration)", async () => {
+    const tools = await loadProviders(["stripe"]);
+
+    expect(tools.length).toBeGreaterThan(0);
+
+    const tool = tools[0];
+    expect(tool).toBeDefined();
+    if (!tool) return;
+
+    expect(tool.providerName).toBe("stripe");
+    expect(tool.inputSchema["type"]).toBe("object");
+  });
+
+  it("loads tools from multiple providers simultaneously", async () => {
+    const tools = await loadProviders(["github", "stripe"]);
+
+    expect(tools.length).toBeGreaterThan(0);
+
+    const githubTools = tools.filter((t) => t.providerName === "github");
+    const stripeTools = tools.filter((t) => t.providerName === "stripe");
+
+    expect(githubTools.length).toBeGreaterThan(0);
+    expect(stripeTools.length).toBeGreaterThan(0);
+  });
+
+  it("tool names are MCP-safe (no dots or slashes)", async () => {
+    const tools = await loadProviders(["github"]);
+    for (const tool of tools) {
+      expect(tool.mcpName).not.toContain(".");
+      expect(tool.mcpName).not.toContain("/");
+    }
+  });
+
+  it("input schemas have type: object", async () => {
+    const tools = await loadProviders(["stripe"]);
+    for (const tool of tools) {
+      const schema = tool.inputSchema;
+      expect(schema["type"]).toBe("object");
+    }
+  });
+
+  it("populates tags from OpenAPI operation tags", async () => {
+    const tools = await loadProviders(["github"]);
+    expect(tools.length).toBeGreaterThan(0);
+
+    // Every tool should have a tags array (may be empty for untagged operations)
+    for (const tool of tools) {
+      expect(Array.isArray(tool.tags)).toBe(true);
+    }
+
+    // At least some tools should have non-empty tags
+    const taggedTools = tools.filter((t) => t.tags.length > 0);
+    expect(taggedTools.length).toBeGreaterThan(0);
+
+    // Tags should be strings
+    for (const tool of taggedTools) {
+      for (const tag of tool.tags) {
+        expect(typeof tag).toBe("string");
+      }
+    }
+  });
+});

package/src/__tests__/meta-tools.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  META_TOOLS,
+  handleListTools,
+  handleSearchTools,
+  handleToolInfo,
+  handleCallTool,
+  type CallToolResult,
+  type ExecuteInput,
+  type ExecuteResult,
+  type ProviderTool,
+} from "../index.js";
+
+// ---------------------------------------------------------------------------
+// Shared test fixtures
+// ---------------------------------------------------------------------------
+
+function makeTool(overrides: Partial<ProviderTool> & { mcpName: string }): ProviderTool {
+  return {
+    utcpName: overrides.mcpName.replace(/__/g, "."),
+    description: "",
+    inputSchema: { type: "object" },
+    providerName: "testprovider",
+    tags: [],
+    method: "GET",
+    routeTemplate: "https://api.example.com/test",
+    contentType: "application/json",
+    pathParamKeys: [],
+    queryParamKeys: [],
+    auth: undefined,
+    ...overrides,
+  };
+}
+
+const reposTool = makeTool({
+  mcpName: "github__repos_list",
+  providerName: "github",
+  description: "List public repositories for the specified user.",
+  tags: ["repos"],
+});
+
+const issuesTool = makeTool({
+  mcpName: "github__issues_list",
+  providerName: "github",
+  description: "List issues assigned to the authenticated user across all visible repositories.",
+  tags: ["issues"],
+});
+
+const prTool = makeTool({
+  mcpName: "github__pulls_list",
+  providerName: "github",
+  description: "List pull requests in a repository.",
+  tags: ["pulls"],
+});
+
+const slackTool = makeTool({
+  mcpName: "slack__messages_send",
+  providerName: "slack",
+  description: "Send a message to a Slack channel.",
+  tags: ["messaging"],
+});
+
+const ALL_TOOLS = [reposTool, issuesTool, prTool, slackTool];
+
+function parseText(result: CallToolResult): unknown {
+  return JSON.parse(result.content[0]!.text);
+}
+
+// ---------------------------------------------------------------------------
+// handleListTools
+// ---------------------------------------------------------------------------
+
+describe("handleListTools", () => {
+  it("returns the names of every tool when given no filter (4 entries)", () => {
+    const result: CallToolResult = handleListTools(ALL_TOOLS, {});
+    const names = parseText(result) as string[];
+    expect(names).toHaveLength(4);
+    expect(names).toEqual(
+      expect.arrayContaining([
+        "github__repos_list",
+        "github__issues_list",
+        "github__pulls_list",
+        "slack__messages_send",
+      ]),
+    );
+    expect(result.isError).toBeFalsy();
+  });
+
+  it("filters to a single provider", () => {
+    const result: CallToolResult = handleListTools(ALL_TOOLS, { provider: "slack" });
+    expect(parseText(result)).toEqual(["slack__messages_send"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// handleSearchTools
+// ---------------------------------------------------------------------------
+
+describe("handleSearchTools", () => {
+  it("returns ranked matches for a keyword query", () => {
+    const result: CallToolResult = handleSearchTools(ALL_TOOLS, { query: "repos" });
+    const matches = parseText(result) as Array<{ name: string }>;
+    expect(matches.length).toBeGreaterThan(0);
+    // The tool whose name contains "repos" ranks first.
+    expect(matches[0]!.name).toBe("github__repos_list");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// handleToolInfo
+// ---------------------------------------------------------------------------
+
+describe("handleToolInfo", () => {
+  it("returns the resolved tool's schema and metadata", () => {
+    const toolMap = new Map(ALL_TOOLS.map((t) => [t.mcpName, t]));
+    const result: CallToolResult = handleToolInfo(toolMap, { tool_name: "github__repos_list" });
+    const info = parseText(result) as {
+      name: string;
+      description: string;
+      provider: string;
+      inputSchema: { type: string };
+    };
+    expect(info.name).toBe("github__repos_list");
+    expect(info.description).toBe("List public repositories for the specified user.");
+    expect(info.provider).toBe("github");
+    expect(info.inputSchema.type).toBe("object");
+    expect(result.isError).toBeFalsy();
+  });
+
+  it("returns an error result for an unknown tool", () => {
+    const toolMap = new Map(ALL_TOOLS.map((t) => [t.mcpName, t]));
+    const result: CallToolResult = handleToolInfo(toolMap, { tool_name: "nope__does_not_exist" });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain("Unknown tool: nope__does_not_exist");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// handleCallTool
+// ---------------------------------------------------------------------------
+
+describe("handleCallTool", () => {
+  it("invokes the injected execute callback with the correct payload and wraps the result in CallToolResult", async () => {
+    const execute = vi.fn(async (_input: ExecuteInput): Promise<ExecuteResult> => ({
+      ok: true as const,
+      data: { id: 1, name: "repo1" },
+    }));
+
+    const result: CallToolResult = await handleCallTool(
+      reposTool,
+      { tool_name: "github__repos_list", arguments: { username: "octocat" } },
+      execute,
+    );
+
+    // execute was called once with { tool, args } where args is the extracted arguments
+    expect(execute).toHaveBeenCalledOnce();
+    expect(execute.mock.calls[0]![0]).toEqual({
+      tool: reposTool,
+      args: { username: "octocat" },
+    });
+
+    // result is a CallToolResult wrapping the data as JSON text
+    expect(result.isError).toBeFalsy();
+    expect(result.content[0]!.type).toBe("text");
+    expect(result.content[0]!.text).toBe(JSON.stringify({ id: 1, name: "repo1" }, null, 2));
+  });
+
+  it("wraps a string result directly without JSON-encoding", async () => {
+    const execute = vi.fn(async (): Promise<ExecuteResult> => ({
+      ok: true as const,
+      data: "plain text output",
+    }));
+    const result: CallToolResult = await handleCallTool(
+      reposTool,
+      { tool_name: "github__repos_list", arguments: {} },
+      execute,
+    );
+    expect(result.content[0]!.text).toBe("plain text output");
+  });
+
+  it("surfaces an execute error as an isError CallToolResult", async () => {
+    const execute = vi.fn(async (): Promise<ExecuteResult> => ({
+      ok: false as const,
+      error: "404 Not Found",
+    }));
+    const result: CallToolResult = await handleCallTool(
+      reposTool,
+      { tool_name: "github__repos_list", arguments: {} },
+      execute,
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toBe("Error calling github__repos_list: 404 Not Found");
+  });
+
+  it("returns an Unknown tool error when the tool is undefined", async () => {
+    const execute = vi.fn(async (): Promise<ExecuteResult> => ({ ok: true as const, data: null }));
+    const result: CallToolResult = await handleCallTool(
+      undefined,
+      { tool_name: "nope__missing" },
+      execute,
+    );
+    expect(execute).not.toHaveBeenCalled();
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toBe("Unknown tool: nope__missing");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// META_TOOLS sanity
+// ---------------------------------------------------------------------------
+
+describe("META_TOOLS", () => {
+  it("defines the 4 meta-tools", () => {
+    expect(META_TOOLS).toHaveLength(4);
+    expect(META_TOOLS.map((t) => t.name).sort()).toEqual([
+      "call_tool",
+      "list_tools",
+      "search_tools",
+      "tool_info",
+    ]);
+  });
+});

package/src/__tests__/search.test.ts

@@ -0,0 +1,243 @@
+import { describe, expect, it } from "vitest";
+import { tokenize, buildTfIdf, searchTools, groupTools } from "../search.js";
+import type { ProviderTool } from "../loader.js";
+
+// ---------------------------------------------------------------------------
+// Shared test fixtures
+// ---------------------------------------------------------------------------
+
+function makeTool(overrides: Partial<ProviderTool> & { mcpName: string }): ProviderTool {
+  return {
+    utcpName: overrides.mcpName.replace(/__/g, "."),
+    description: "",
+    inputSchema: { type: "object" },
+    providerName: "testprovider",
+    tags: [],
+    method: "GET",
+    routeTemplate: "https://api.example.com/test",
+    contentType: "application/json",
+    pathParamKeys: [],
+    queryParamKeys: [],
+    auth: undefined,
+    ...overrides,
+  };
+}
+
+const reposTool = makeTool({
+  mcpName: "github__repos_list",
+  providerName: "github",
+  description: "List public repositories for the specified user.",
+  tags: ["repos"],
+});
+
+const issuesTool = makeTool({
+  mcpName: "github__issues_list",
+  providerName: "github",
+  description: "List issues assigned to the authenticated user across all visible repositories.",
+  tags: ["issues"],
+});
+
+const prTool = makeTool({
+  mcpName: "github__pulls_list",
+  providerName: "github",
+  description: "List pull requests in a repository.",
+  tags: ["pulls"],
+});
+
+const slackTool = makeTool({
+  mcpName: "slack__messages_send",
+  providerName: "slack",
+  description: "Send a message to a Slack channel.",
+  tags: ["messaging"],
+});
+
+const ALL_TOOLS = [reposTool, issuesTool, prTool, slackTool];
+
+// ---------------------------------------------------------------------------
+// tokenize
+// ---------------------------------------------------------------------------
+
+describe("tokenize", () => {
+  it("lowercases and splits on non-alphanumeric chars", () => {
+    expect(tokenize("hello world")).toEqual(["hello", "world"]);
+  });
+
+  it("splits snake_case / double-underscore MCP names", () => {
+    expect(tokenize("github__repos_list")).toEqual(["github", "repos", "list"]);
+  });
+
+  it("splits camelCase boundaries", () => {
+    expect(tokenize("listForUser")).toEqual(["list", "for", "user"]);
+  });
+
+  it("strips punctuation", () => {
+    expect(tokenize("security-advisories")).toEqual(["security", "advisories"]);
+  });
+
+  it("returns empty array for empty string", () => {
+    expect(tokenize("")).toEqual([]);
+  });
+
+  it("filters empty tokens", () => {
+    expect(tokenize("  hello   world  ")).toEqual(["hello", "world"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildTfIdf
+// ---------------------------------------------------------------------------
+
+describe("buildTfIdf", () => {
+  it("returns zero score for empty corpus", () => {
+    const score = buildTfIdf([]);
+    expect(score(reposTool, ["repos"])).toBe(0);
+  });
+
+  it("scores tool with name match higher than description-only match", () => {
+    const tools = [reposTool, issuesTool];
+    const score = buildTfIdf(tools);
+    // "repos" is in reposTool name AND tags but NOT in issuesTool name or tags
+    const reposScore = score(reposTool, ["repos"]);
+    const issuesScore = score(issuesTool, ["repos"]);
+    expect(reposScore).toBeGreaterThan(0);
+    expect(issuesScore).toBe(0);
+  });
+
+  it("returns higher score for rare term (IDF effect)", () => {
+    // "list" appears in all github tools but "pull" only in prTool
+    const tools = [reposTool, issuesTool, prTool];
+    const score = buildTfIdf(tools);
+    const scoreOnPullRare = score(prTool, ["pull"]);
+    const scoreOnListCommon = score(prTool, ["list"]);
+    // "pull" is rarer than "list" so IDF is higher → pull score > list score
+    expect(scoreOnPullRare).toBeGreaterThan(scoreOnListCommon);
+  });
+
+  it("returns positive score for a matching term in description", () => {
+    const tools = [slackTool];
+    const score = buildTfIdf(tools);
+    expect(score(slackTool, ["channel"])).toBeGreaterThan(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// searchTools
+// ---------------------------------------------------------------------------
+
+describe("searchTools", () => {
+  it("returns empty array for empty query", () => {
+    expect(searchTools(ALL_TOOLS, "", undefined, 10)).toEqual([]);
+  });
+
+  it("returns empty array for blank query", () => {
+    expect(searchTools(ALL_TOOLS, "   ", undefined, 10)).toEqual([]);
+  });
+
+  it("finds tools by name keyword", () => {
+    const results = searchTools(ALL_TOOLS, "repos", undefined, 10);
+    expect(results.map((r) => r.name)).toContain("github__repos_list");
+  });
+
+  it("finds tools by tag", () => {
+    const results = searchTools(ALL_TOOLS, "issues", undefined, 10);
+    expect(results.map((r) => r.name)).toContain("github__issues_list");
+  });
+
+  it("finds tools by description keyword", () => {
+    const results = searchTools(ALL_TOOLS, "channel", undefined, 10);
+    expect(results.map((r) => r.name)).toContain("slack__messages_send");
+  });
+
+  it("excludes tools where a query word does not appear anywhere", () => {
+    const results = searchTools(ALL_TOOLS, "nonexistent_xyz", undefined, 10);
+    expect(results).toHaveLength(0);
+  });
+
+  it("requires ALL query words to match", () => {
+    // "repos" matches reposTool, "channel" matches slackTool → no tool matches both
+    const results = searchTools(ALL_TOOLS, "repos channel", undefined, 10);
+    expect(results).toHaveLength(0);
+  });
+
+  it("respects provider filter", () => {
+    const results = searchTools(ALL_TOOLS, "list", "slack", 10);
+    // slackTool description has "list" via "List" — but depends on description
+    // More importantly, github tools should NOT appear
+    expect(results.every((r) => r.name.startsWith("slack__"))).toBe(true);
+  });
+
+  it("respects limit", () => {
+    const results = searchTools(ALL_TOOLS, "list", undefined, 2);
+    expect(results.length).toBeLessThanOrEqual(2);
+  });
+
+  it("returns tags in results", () => {
+    const results = searchTools(ALL_TOOLS, "repos", undefined, 10);
+    const reposResult = results.find((r) => r.name === "github__repos_list");
+    expect(reposResult?.tags).toEqual(["repos"]);
+  });
+
+  it("ranks name matches above description-only matches", () => {
+    // "repos" is in the name of reposTool but only in description of issuesTool
+    const tools = [
+      reposTool,
+      makeTool({
+        mcpName: "github__something_else",
+        providerName: "github",
+        description: "Access repos for any organization.",
+        tags: [],
+      }),
+    ];
+    const results = searchTools(tools, "repos", undefined, 10);
+    // reposTool (name match) should come before the description-only match
+    expect(results[0]?.name).toBe("github__repos_list");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// groupTools
+// ---------------------------------------------------------------------------
+
+describe("groupTools", () => {
+  it("groups by provider", () => {
+    const grouped = groupTools(ALL_TOOLS, "provider");
+    expect(grouped["github"]).toEqual(
+      expect.arrayContaining(["github__repos_list", "github__issues_list", "github__pulls_list"]),
+    );
+    expect(grouped["slack"]).toEqual(["slack__messages_send"]);
+  });
+
+  it("groups by tag", () => {
+    const grouped = groupTools(ALL_TOOLS, "tag");
+    expect(grouped["repos"]).toEqual(["github__repos_list"]);
+    expect(grouped["issues"]).toEqual(["github__issues_list"]);
+    expect(grouped["pulls"]).toEqual(["github__pulls_list"]);
+    expect(grouped["messaging"]).toEqual(["slack__messages_send"]);
+  });
+
+  it("falls back to provider name for tools with no tags when grouping by tag", () => {
+    const noTagTool = makeTool({
+      mcpName: "provider__notag_tool",
+      providerName: "myprovider",
+      tags: [],
+    });
+    const grouped = groupTools([noTagTool], "tag");
+    expect(grouped["myprovider"]).toEqual(["provider__notag_tool"]);
+  });
+
+  it("returns empty object for empty tool list", () => {
+    expect(groupTools([], "provider")).toEqual({});
+    expect(groupTools([], "tag")).toEqual({});
+  });
+
+  it("assigns multi-tag tool to all its tag groups", () => {
+    const multiTagTool = makeTool({
+      mcpName: "github__multi_tool",
+      providerName: "github",
+      tags: ["repos", "admin"],
+    });
+    const grouped = groupTools([multiTagTool], "tag");
+    expect(grouped["repos"]).toContain("github__multi_tool");
+    expect(grouped["admin"]).toContain("github__multi_tool");
+  });
+});

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Public API of @utdk/mcp-core.
+ *
+ * Shared tool catalog + meta-tool handlers consumed by both the stdio MCP
+ * server (@utdk/mcp) and the hosted gateway (Phase 2). Nothing here depends on
+ * a specific transport: tool execution is injected via the {@link Execute}
+ * callback in {@link handleCallTool}.
+ */
+export * from "./loader.js";
+export * from "./search.js";
+export * from "./meta-tools.js";