@cubis/foundry 0.3.46 → 0.3.48

package/mcp/src/server.ts

@@ -1,8 +1,8 @@
 /**
  * Cubis Foundry MCP Server – server factory.
  *
- * Creates and configures the McpServer instance with built-in tools plus
- * dynamic Postman/Stitch passthrough namespaces.
+ * Creates and configures the McpServer instance with built-in tools
+ * (via declarative registry) plus dynamic Postman/Stitch passthrough namespaces.
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -10,59 +10,12 @@ import { z } from "zod";
 import type { ServerConfig } from "./config/schema.js";
 import type { ConfigScope } from "./cbxConfig/types.js";
 import type { VaultManifest } from "./vault/types.js";
-import {
-  // Skill tools
-  skillListCategoriesName,
-  skillListCategoriesDescription,
-  skillListCategoriesSchema,
-  handleSkillListCategories,
-  skillBrowseCategoryName,
-  skillBrowseCategoryDescription,
-  skillBrowseCategorySchema,
-  handleSkillBrowseCategory,
-  skillSearchName,
-  skillSearchDescription,
-  skillSearchSchema,
-  handleSkillSearch,
-  skillGetName,
-  skillGetDescription,
-  skillGetSchema,
-  handleSkillGet,
-  skillBudgetReportName,
-  skillBudgetReportDescription,
-  skillBudgetReportSchema,
-  handleSkillBudgetReport,
-  // Postman tools
-  postmanGetModeName,
-  postmanGetModeDescription,
-  postmanGetModeSchema,
-  handlePostmanGetMode,
-  postmanSetModeName,
-  postmanSetModeDescription,
-  postmanSetModeSchema,
-  handlePostmanSetMode,
-  postmanGetStatusName,
-  postmanGetStatusDescription,
-  postmanGetStatusSchema,
-  handlePostmanGetStatus,
-  // Stitch tools
-  stitchGetModeName,
-  stitchGetModeDescription,
-  stitchGetModeSchema,
-  handleStitchGetMode,
-  stitchSetProfileName,
-  stitchSetProfileDescription,
-  stitchSetProfileSchema,
-  handleStitchSetProfile,
-  stitchGetStatusName,
-  stitchGetStatusDescription,
-  stitchGetStatusSchema,
-  handleStitchGetStatus,
-} from "./tools/index.js";
+import { TOOL_REGISTRY, type ToolRuntimeContext } from "./tools/registry.js";
 import {
   callUpstreamTool,
   discoverUpstreamCatalogs,
 } from "./upstream/passthrough.js";
+import { logger } from "./utils/logger.js";
 
 export interface CreateServerOptions {
   config: ServerConfig;
@@ -102,137 +55,37 @@ export async function createServer({
   config,
   manifest,
   defaultConfigScope = "auto",
-}: CreateServerOptions): McpServer {
+}: CreateServerOptions): Promise<McpServer> {
   const server = new McpServer({
     name: config.server.name,
     version: config.server.version,
   });
 
-  const maxLen = config.vault.summaryMaxLength;
-  const charsPerToken = config.telemetry?.charsPerToken ?? 4;
-  const withDefaultScope = (
-    args: Record<string, unknown> | undefined,
-  ): Record<string, unknown> => {
-    const safeArgs = args ?? {};
-    return {
-      ...safeArgs,
-      scope:
-        typeof safeArgs.scope === "string" ? safeArgs.scope : defaultConfigScope,
-    };
-  };
-
-  // ─── Skill vault tools ───────────────────────────────────────
-
-  server.tool(
-    skillListCategoriesName,
-    skillListCategoriesDescription,
-    skillListCategoriesSchema.shape,
-    async () => handleSkillListCategories(manifest, charsPerToken),
-  );
-
-  server.tool(
-    skillBrowseCategoryName,
-    skillBrowseCategoryDescription,
-    skillBrowseCategorySchema.shape,
-    async (args) =>
-      handleSkillBrowseCategory(args, manifest, maxLen, charsPerToken),
-  );
-
-  server.tool(
-    skillSearchName,
-    skillSearchDescription,
-    skillSearchSchema.shape,
-    async (args) => handleSkillSearch(args, manifest, maxLen, charsPerToken),
-  );
-
-  server.tool(
-    skillGetName,
-    skillGetDescription,
-    skillGetSchema.shape,
-    async (args) => handleSkillGet(args, manifest, charsPerToken),
-  );
-
-  server.tool(
-    skillBudgetReportName,
-    skillBudgetReportDescription,
-    skillBudgetReportSchema.shape,
-    async (args) => handleSkillBudgetReport(args, manifest, charsPerToken),
-  );
+  // ─── Built-in tools from declarative registry ─────────────
 
-  // ─── Postman tools ──────────────────────────────────────────
-
-  server.tool(
-    postmanGetModeName,
-    postmanGetModeDescription,
-    postmanGetModeSchema.shape,
-    async (args) =>
-      handlePostmanGetMode(
-        withDefaultScope(args as Record<string, unknown>) as z.infer<
-          typeof postmanGetModeSchema
-        >,
-      ),
-  );
-
-  server.tool(
-    postmanSetModeName,
-    postmanSetModeDescription,
-    postmanSetModeSchema.shape,
-    async (args) =>
-      handlePostmanSetMode(
-        withDefaultScope(args as Record<string, unknown>) as z.infer<
-          typeof postmanSetModeSchema
-        >,
-      ),
-  );
-
-  server.tool(
-    postmanGetStatusName,
-    postmanGetStatusDescription,
-    postmanGetStatusSchema.shape,
-    async (args) =>
-      handlePostmanGetStatus(
-        withDefaultScope(args as Record<string, unknown>) as z.infer<
-          typeof postmanGetStatusSchema
-        >,
-      ),
-  );
-
-  // ─── Stitch tools ──────────────────────────────────────────
-
-  server.tool(
-    stitchGetModeName,
-    stitchGetModeDescription,
-    stitchGetModeSchema.shape,
-    async (args) =>
-      handleStitchGetMode(
-        withDefaultScope(args as Record<string, unknown>) as z.infer<
-          typeof stitchGetModeSchema
-        >,
-      ),
-  );
+  const runtimeCtx: ToolRuntimeContext = {
+    manifest,
+    charsPerToken: config.telemetry?.charsPerToken ?? 4,
+    summaryMaxLength: config.vault.summaryMaxLength,
+    defaultConfigScope,
+  };
 
-  server.tool(
-    stitchSetProfileName,
-    stitchSetProfileDescription,
-    stitchSetProfileSchema.shape,
-    async (args) =>
-      handleStitchSetProfile(
-        withDefaultScope(args as Record<string, unknown>) as z.infer<
-          typeof stitchSetProfileSchema
-        >,
-      ),
-  );
+  for (const entry of TOOL_REGISTRY) {
+    const handler = entry.createHandler(runtimeCtx);
+    // Cast is safe: registry handler signatures are compatible at runtime.
+    // The overload ambiguity arises because an empty ZodRawShape `{}`
+    // is structurally assignable to the annotations object overload.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (server as any).tool(
+      entry.name,
+      entry.description,
+      entry.schema.shape,
+      handler,
+    );
+  }
 
-  server.tool(
-    stitchGetStatusName,
-    stitchGetStatusDescription,
-    stitchGetStatusSchema.shape,
-    async (args) =>
-      handleStitchGetStatus(
-        withDefaultScope(args as Record<string, unknown>) as z.infer<
-          typeof stitchGetStatusSchema
-        >,
-      ),
+  logger.debug(
+    `Registered ${TOOL_REGISTRY.length} built-in tools from registry`,
   );
 
   // ─── Dynamic upstream passthrough tools ────────────────────
@@ -242,21 +95,30 @@ export async function createServer({
   for (const catalog of [upstreamCatalogs.postman, upstreamCatalogs.stitch]) {
     for (const tool of catalog.tools) {
       const namespaced = tool.namespacedName;
-      server.tool(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (server as any).tool(
         namespaced,
         `[${catalog.service} passthrough] ${tool.description || tool.name}`,
         dynamicArgsShape,
-        async (args) => {
+        async (args: Record<string, unknown>) => {
           try {
             const result = await callUpstreamTool({
               service: catalog.service,
               name: tool.name,
               argumentsValue:
-                args && typeof args === "object" ? args : ({} as Record<string, unknown>),
+                args && typeof args === "object"
+                  ? args
+                  : ({} as Record<string, unknown>),
             });
             return {
-              content: result.content ?? [],
-              structuredContent: result.structuredContent,
+              // SDK content is typed broadly; cast to the expected array shape.
+              content: (result.content ?? []) as Array<{
+                type: string;
+                [k: string]: unknown;
+              }>,
+              structuredContent: result.structuredContent as
+                | Record<string, unknown>
+                | undefined,
               isError: Boolean(result.isError),
             };
           } catch (error) {

package/mcp/src/tools/future/README.md

@@ -16,6 +16,6 @@ When adding a new tool:
 
 1. Create `toolName.ts` in `../` (parent `tools/` directory)
 2. Export name, description, schema, and handler
-3. Register in `../index.ts` barrel export
-4. Register in `../../server.ts` with `mcpServer.tool()`
-5. Add tests in `../../__tests__/tools/`
+3. Add a `ToolRegistryEntry` in `../registry.ts` (this auto-registers the tool)
+4. Add tests in a `toolName.test.ts` file
+5. Run `npm run generate:mcp-manifest` to update the build-time manifest

package/mcp/src/tools/index.ts

@@ -3,8 +3,22 @@
  *
  * Central registry exporting all tool metadata and handlers.
  * Used by server.ts to register tools with McpServer.
+ *
+ * The declarative registry (registry.ts) is the preferred way to register
+ * new tools. Individual tool exports are kept for backward compatibility
+ * and direct unit testing.
  */
 
+export {
+  TOOL_REGISTRY,
+  getToolsByCategory,
+  getRegisteredToolNames,
+  buildRegistrySummary,
+  type ToolCategory,
+  type ToolRegistryEntry,
+  type ToolRuntimeContext,
+} from "./registry.js";
+
 export {
   skillListCategoriesName,
   skillListCategoriesDescription,

package/mcp/src/tools/registry.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import {
+  TOOL_REGISTRY,
+  getToolsByCategory,
+  getRegisteredToolNames,
+  buildRegistrySummary,
+  type ToolRegistryEntry,
+  type ToolRuntimeContext,
+} from "./registry.js";
+import type { VaultManifest } from "../vault/types.js";
+
+function createTestContext(): ToolRuntimeContext {
+  const manifest: VaultManifest = {
+    categories: ["frontend", "backend"],
+    skills: [
+      {
+        id: "react-expert",
+        category: "frontend",
+        path: "/tmp/react-expert/SKILL.md",
+        fileBytes: 100,
+      },
+    ],
+    fullCatalogBytes: 100,
+    fullCatalogEstimatedTokens: 25,
+  };
+
+  return {
+    manifest,
+    charsPerToken: 4,
+    summaryMaxLength: 200,
+    defaultConfigScope: "auto",
+  };
+}
+
+describe("tool registry", () => {
+  it("contains all expected built-in tools", () => {
+    const names = getRegisteredToolNames();
+    expect(names).toContain("skill_list_categories");
+    expect(names).toContain("skill_browse_category");
+    expect(names).toContain("skill_search");
+    expect(names).toContain("skill_get");
+    expect(names).toContain("skill_budget_report");
+    expect(names).toContain("postman_get_mode");
+    expect(names).toContain("postman_set_mode");
+    expect(names).toContain("postman_get_status");
+    expect(names).toContain("stitch_get_mode");
+    expect(names).toContain("stitch_set_profile");
+    expect(names).toContain("stitch_get_status");
+  });
+
+  it("has exactly 11 built-in tools", () => {
+    expect(TOOL_REGISTRY).toHaveLength(11);
+  });
+
+  it("has no duplicate tool names", () => {
+    const names = getRegisteredToolNames();
+    const unique = new Set(names);
+    expect(unique.size).toBe(names.length);
+  });
+
+  it("every entry has required fields", () => {
+    for (const entry of TOOL_REGISTRY) {
+      expect(entry.name).toBeTruthy();
+      expect(entry.description).toBeTruthy();
+      expect(entry.schema).toBeTruthy();
+      expect(entry.category).toMatch(/^(skill|postman|stitch)$/);
+      expect(typeof entry.createHandler).toBe("function");
+    }
+  });
+
+  it("filters by category", () => {
+    const skillTools = getToolsByCategory("skill");
+    expect(skillTools).toHaveLength(5);
+    expect(skillTools.every((t) => t.category === "skill")).toBe(true);
+
+    const postmanTools = getToolsByCategory("postman");
+    expect(postmanTools).toHaveLength(3);
+
+    const stitchTools = getToolsByCategory("stitch");
+    expect(stitchTools).toHaveLength(3);
+  });
+
+  it("creates handlers from runtime context", () => {
+    const ctx = createTestContext();
+    for (const entry of TOOL_REGISTRY) {
+      const handler = entry.createHandler(ctx);
+      expect(typeof handler).toBe("function");
+    }
+  });
+
+  it("skill_list_categories handler returns valid result from registry", async () => {
+    const ctx = createTestContext();
+    const entry = TOOL_REGISTRY.find(
+      (t) => t.name === "skill_list_categories",
+    )!;
+    const handler = entry.createHandler(ctx);
+    const result = (await handler({})) as {
+      content: Array<{ text: string }>;
+    };
+    const data = JSON.parse(result.content[0].text);
+    expect(data.totalSkills).toBe(1);
+  });
+
+  it("buildRegistrySummary produces correct structure", () => {
+    const summary = buildRegistrySummary();
+    expect(summary.totalTools).toBe(11);
+    expect(summary.categories).toHaveProperty("skill");
+    expect(summary.categories).toHaveProperty("postman");
+    expect(summary.categories).toHaveProperty("stitch");
+    expect(summary.categories.skill.tools).toHaveLength(5);
+    expect(summary.categories.postman.tools).toHaveLength(3);
+    expect(summary.categories.stitch.tools).toHaveLength(3);
+  });
+
+  it("each schema has a valid .shape property", () => {
+    for (const entry of TOOL_REGISTRY) {
+      expect(entry.schema.shape).toBeDefined();
+      expect(typeof entry.schema.shape).toBe("object");
+    }
+  });
+});