@cubis/foundry 0.3.34 → 0.3.36

package/mcp/src/server.ts

@@ -0,0 +1,219 @@
+/**
+ * Cubis Foundry MCP Server – server factory.
+ *
+ * Creates and configures the McpServer instance with built-in tools plus
+ * dynamic Postman/Stitch passthrough namespaces.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ServerConfig } from "./config/schema.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,
+  // 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 {
+  callUpstreamTool,
+  discoverUpstreamCatalogs,
+} from "./upstream/passthrough.js";
+
+export interface CreateServerOptions {
+  config: ServerConfig;
+  manifest: VaultManifest;
+}
+
+function toolCallErrorResult({
+  service,
+  namespacedName,
+  error,
+}: {
+  service: "postman" | "stitch";
+  namespacedName: string;
+  error: unknown;
+}) {
+  return {
+    isError: true as const,
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            service,
+            tool: namespacedName,
+            error: String(error),
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}
+
+export async function createServer({
+  config,
+  manifest,
+}: CreateServerOptions): McpServer {
+  const server = new McpServer({
+    name: config.server.name,
+    version: config.server.version,
+  });
+
+  const maxLen = config.vault.summaryMaxLength;
+
+  // ─── Skill vault tools ───────────────────────────────────────
+
+  server.tool(
+    skillListCategoriesName,
+    skillListCategoriesDescription,
+    skillListCategoriesSchema.shape,
+    async () => handleSkillListCategories(manifest),
+  );
+
+  server.tool(
+    skillBrowseCategoryName,
+    skillBrowseCategoryDescription,
+    skillBrowseCategorySchema.shape,
+    async (args) => handleSkillBrowseCategory(args, manifest, maxLen),
+  );
+
+  server.tool(
+    skillSearchName,
+    skillSearchDescription,
+    skillSearchSchema.shape,
+    async (args) => handleSkillSearch(args, manifest, maxLen),
+  );
+
+  server.tool(
+    skillGetName,
+    skillGetDescription,
+    skillGetSchema.shape,
+    async (args) => handleSkillGet(args, manifest),
+  );
+
+  // ─── Postman tools ──────────────────────────────────────────
+
+  server.tool(
+    postmanGetModeName,
+    postmanGetModeDescription,
+    postmanGetModeSchema.shape,
+    async (args) => handlePostmanGetMode(args),
+  );
+
+  server.tool(
+    postmanSetModeName,
+    postmanSetModeDescription,
+    postmanSetModeSchema.shape,
+    async (args) => handlePostmanSetMode(args),
+  );
+
+  server.tool(
+    postmanGetStatusName,
+    postmanGetStatusDescription,
+    postmanGetStatusSchema.shape,
+    async (args) => handlePostmanGetStatus(args),
+  );
+
+  // ─── Stitch tools ──────────────────────────────────────────
+
+  server.tool(
+    stitchGetModeName,
+    stitchGetModeDescription,
+    stitchGetModeSchema.shape,
+    async (args) => handleStitchGetMode(args),
+  );
+
+  server.tool(
+    stitchSetProfileName,
+    stitchSetProfileDescription,
+    stitchSetProfileSchema.shape,
+    async (args) => handleStitchSetProfile(args),
+  );
+
+  server.tool(
+    stitchGetStatusName,
+    stitchGetStatusDescription,
+    stitchGetStatusSchema.shape,
+    async (args) => handleStitchGetStatus(args),
+  );
+
+  // ─── Dynamic upstream passthrough tools ────────────────────
+  const upstreamCatalogs = await discoverUpstreamCatalogs();
+  const dynamicArgsShape = z.object({}).passthrough().shape;
+
+  for (const catalog of [upstreamCatalogs.postman, upstreamCatalogs.stitch]) {
+    for (const tool of catalog.tools) {
+      const namespaced = tool.namespacedName;
+      server.tool(
+        namespaced,
+        `[${catalog.service} passthrough] ${tool.description || tool.name}`,
+        dynamicArgsShape,
+        async (args) => {
+          try {
+            const result = await callUpstreamTool({
+              service: catalog.service,
+              name: tool.name,
+              argumentsValue:
+                args && typeof args === "object" ? args : ({} as Record<string, unknown>),
+            });
+            return {
+              content: result.content ?? [],
+              structuredContent: result.structuredContent,
+              isError: Boolean(result.isError),
+            };
+          } catch (error) {
+            return toolCallErrorResult({
+              service: catalog.service,
+              namespacedName: namespaced,
+              error,
+            });
+          }
+        },
+      );
+    }
+  }
+
+  return server;
+}

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

@@ -0,0 +1,166 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { POSTMAN_MODES } from "./postmanModes.js";
+import { handlePostmanGetMode } from "./postmanGetMode.js";
+import { handlePostmanGetStatus } from "./postmanGetStatus.js";
+import { handlePostmanSetMode } from "./postmanSetMode.js";
+import { handleStitchGetMode } from "./stitchGetMode.js";
+import { handleStitchGetStatus } from "./stitchGetStatus.js";
+import { handleStitchSetProfile } from "./stitchSetProfile.js";
+
+let tempHomeDir = "";
+let workspaceDir = "";
+const originalHome = process.env.HOME;
+const originalCwd = process.cwd();
+
+function payload(result: { content: Array<{ text: string }> }): Record<string, unknown> {
+  return JSON.parse(result.content[0].text) as Record<string, unknown>;
+}
+
+function projectConfigPath(): string {
+  return path.join(workspaceDir, "cbx_config.json");
+}
+
+function writeProjectConfig(value: unknown): void {
+  const file = projectConfigPath();
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(value, null, 2) + "\n", "utf8");
+}
+
+function readProjectConfig(): Record<string, unknown> {
+  return JSON.parse(readFileSync(projectConfigPath(), "utf8")) as Record<string, unknown>;
+}
+
+beforeEach(() => {
+  tempHomeDir = mkdtempSync(path.join(os.tmpdir(), "mcp-home-tools-"));
+  workspaceDir = mkdtempSync(path.join(os.tmpdir(), "mcp-workspace-tools-"));
+  process.env.HOME = tempHomeDir;
+  process.chdir(workspaceDir);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  if (originalHome === undefined) {
+    delete process.env.HOME;
+  } else {
+    process.env.HOME = originalHome;
+  }
+  rmSync(tempHomeDir, { recursive: true, force: true });
+  rmSync(workspaceDir, { recursive: true, force: true });
+});
+
+describe("postman tools", () => {
+  it("throws when config is missing", () => {
+    expect(() => handlePostmanGetMode({ scope: "project" })).toThrow(
+      "cbx_config.json not found",
+    );
+  });
+
+  it("writes and reads a Postman mode in project scope", () => {
+    writeProjectConfig({});
+
+    const setResult = payload(
+      handlePostmanSetMode({ mode: "full", scope: "project" }),
+    );
+    expect(setResult).toMatchObject({
+      mode: "full",
+      url: POSTMAN_MODES.full,
+      scope: "project",
+    });
+
+    const file = readProjectConfig();
+    expect(file).toMatchObject({ postman: { mcpUrl: POSTMAN_MODES.full } });
+
+    const mode = payload(handlePostmanGetMode({ scope: "project" }));
+    expect(mode).toMatchObject({
+      mode: "full",
+      url: POSTMAN_MODES.full,
+      scope: "project",
+    });
+  });
+
+  it("reports unknown Postman URL values as domain errors", () => {
+    writeProjectConfig({ postman: { mcpUrl: "https://example.com/custom" } });
+
+    expect(() => handlePostmanGetMode({ scope: "project" })).toThrow(
+      'Unknown Postman MCP URL in config: "https://example.com/custom"',
+    );
+  });
+
+  it("returns full Postman status payload", () => {
+    writeProjectConfig({
+      postman: {
+        mcpUrl: POSTMAN_MODES.code,
+        defaultWorkspaceId: "ws_42",
+      },
+    });
+
+    const status = payload(handlePostmanGetStatus({ scope: "project" }));
+    expect(status).toMatchObject({
+      configured: true,
+      mode: "code",
+      url: POSTMAN_MODES.code,
+      defaultWorkspaceId: "ws_42",
+      scope: "project",
+    });
+  });
+});
+
+describe("stitch tools", () => {
+  it("validates that target stitch profile exists", () => {
+    writeProjectConfig({
+      stitch: {
+        activeProfileName: "prod",
+        profiles: {
+          prod: { url: "https://prod.stitch" },
+        },
+      },
+    });
+
+    expect(() =>
+      handleStitchSetProfile({ profileName: "staging", scope: "project" }),
+    ).toThrow('Stitch profile "staging" not found');
+  });
+
+  it("updates active profile and exposes only safe status fields", () => {
+    writeProjectConfig({
+      stitch: {
+        activeProfileName: "prod",
+        profiles: {
+          prod: { url: "https://prod.stitch", apiKey: "secret-value" },
+          staging: { url: "https://staging.stitch" },
+        },
+      },
+    });
+
+    const setResult = payload(
+      handleStitchSetProfile({ profileName: "staging", scope: "project" }),
+    );
+    expect(setResult).toMatchObject({
+      activeProfileName: "staging",
+      url: "https://staging.stitch",
+      scope: "project",
+    });
+
+    const mode = payload(handleStitchGetMode({ scope: "project" }));
+    expect(mode).toMatchObject({
+      activeProfileName: "staging",
+      activeUrl: "https://staging.stitch",
+      availableProfiles: ["prod", "staging"],
+      scope: "project",
+    });
+
+    const status = payload(handleStitchGetStatus({ scope: "project" }));
+    expect(status).toMatchObject({
+      configured: true,
+      activeProfileName: "staging",
+      totalProfiles: 2,
+      scope: "project",
+    });
+    const statusText = JSON.stringify(status);
+    expect(statusText).not.toContain("secret-value");
+    expect(statusText).toContain('"hasApiKey":true');
+  });
+});

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

@@ -0,0 +1,21 @@
+# Future Tools
+
+This directory is reserved for tools that are planned but not yet implemented.
+
+## Roadmap
+
+- **workflow_list** – List available workflows
+- **workflow_run** – Execute a workflow by name
+- **config_validate** – Validate cbx workspace configuration
+- **skill_install** – Install skills to a workspace
+- **skill_diff** – Compare skill versions across roots
+
+## Contributing
+
+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/`

package/mcp/src/tools/future/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Future tools placeholder.
+ *
+ * This directory is reserved for tools planned but not yet implemented.
+ * See README.md for the roadmap.
+ */
+
+export {};

package/mcp/src/tools/index.ts

@@ -0,0 +1,76 @@
+/**
+ * Cubis Foundry MCP Server – tool registry.
+ *
+ * Central registry exporting all tool metadata and handlers.
+ * Used by server.ts to register tools with McpServer.
+ */
+
+export {
+  skillListCategoriesName,
+  skillListCategoriesDescription,
+  skillListCategoriesSchema,
+  handleSkillListCategories,
+} from "./skillListCategories.js";
+
+export {
+  skillBrowseCategoryName,
+  skillBrowseCategoryDescription,
+  skillBrowseCategorySchema,
+  handleSkillBrowseCategory,
+} from "./skillBrowseCategory.js";
+
+export {
+  skillSearchName,
+  skillSearchDescription,
+  skillSearchSchema,
+  handleSkillSearch,
+} from "./skillSearch.js";
+
+export {
+  skillGetName,
+  skillGetDescription,
+  skillGetSchema,
+  handleSkillGet,
+} from "./skillGet.js";
+
+export {
+  postmanGetModeName,
+  postmanGetModeDescription,
+  postmanGetModeSchema,
+  handlePostmanGetMode,
+} from "./postmanGetMode.js";
+
+export {
+  postmanSetModeName,
+  postmanSetModeDescription,
+  postmanSetModeSchema,
+  handlePostmanSetMode,
+} from "./postmanSetMode.js";
+
+export {
+  postmanGetStatusName,
+  postmanGetStatusDescription,
+  postmanGetStatusSchema,
+  handlePostmanGetStatus,
+} from "./postmanGetStatus.js";
+
+export {
+  stitchGetModeName,
+  stitchGetModeDescription,
+  stitchGetModeSchema,
+  handleStitchGetMode,
+} from "./stitchGetMode.js";
+
+export {
+  stitchSetProfileName,
+  stitchSetProfileDescription,
+  stitchSetProfileSchema,
+  handleStitchSetProfile,
+} from "./stitchSetProfile.js";
+
+export {
+  stitchGetStatusName,
+  stitchGetStatusDescription,
+  stitchGetStatusSchema,
+  handleStitchGetStatus,
+} from "./stitchGetStatus.js";

package/mcp/src/tools/mcpGateway.ts

@@ -0,0 +1,44 @@
+/**
+ * Cubis Foundry MCP Server – gateway status and enabled-tool discovery tools.
+ */
+
+import { z } from "zod";
+import type { GatewayManager } from "../gateway/manager.js";
+
+export const postmanListEnabledToolsName = "postman_list_enabled_tools";
+export const postmanListEnabledToolsDescription =
+  "List currently enabled Postman upstream passthrough tools and gateway warnings.";
+export const postmanListEnabledToolsSchema = z.object({});
+
+export const stitchListEnabledToolsName = "stitch_list_enabled_tools";
+export const stitchListEnabledToolsDescription =
+  "List currently enabled Stitch upstream passthrough tools and gateway warnings.";
+export const stitchListEnabledToolsSchema = z.object({});
+
+export const mcpGatewayStatusName = "mcp_gateway_status";
+export const mcpGatewayStatusDescription =
+  "Get passthrough gateway status for Postman and Stitch, including warnings and catalog location.";
+export const mcpGatewayStatusSchema = z.object({});
+
+function text(data: unknown) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(data, null, 2),
+      },
+    ],
+  };
+}
+
+export function handlePostmanListEnabledTools(gateway: GatewayManager) {
+  return text(gateway.listEnabledTools("postman"));
+}
+
+export function handleStitchListEnabledTools(gateway: GatewayManager) {
+  return text(gateway.listEnabledTools("stitch"));
+}
+
+export function handleMcpGatewayStatus(gateway: GatewayManager) {
+  return text(gateway.getStatus());
+}

package/mcp/src/tools/postmanGetMode.ts

@@ -0,0 +1,82 @@
+/**
+ * Cubis Foundry MCP Server – postman_get_mode tool.
+ *
+ * Reads the current Postman mode from cbx_config.json.
+ */
+
+import { z } from "zod";
+import { parsePostmanState, readEffectiveConfig } from "../cbxConfig/index.js";
+import type { ConfigScope } from "../cbxConfig/types.js";
+import { configNotFound, unknownPostmanMode } from "../utils/errors.js";
+import { urlToMode, POSTMAN_MODES } from "./postmanModes.js";
+
+export const postmanGetModeName = "postman_get_mode";
+
+export const postmanGetModeDescription =
+  "Get the current Postman MCP mode from cbx_config.json. Returns the friendly mode name and URL.";
+
+export const postmanGetModeSchema = z.object({
+  scope: z
+    .enum(["global", "project", "auto"])
+    .optional()
+    .describe(
+      "Config scope to read. Default: auto (project if exists, else global)",
+    ),
+});
+
+export function handlePostmanGetMode(
+  args: z.infer<typeof postmanGetModeSchema>,
+) {
+  const scope = args.scope ?? "auto";
+  const effective = readEffectiveConfig(scope as ConfigScope | "auto");
+
+  if (!effective) {
+    configNotFound();
+  }
+
+  const postmanState = parsePostmanState(effective.config);
+  const url = postmanState.mcpUrl;
+  if (!url) {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify(
+            {
+              mode: null,
+              url: null,
+              scope: effective.scope,
+              message:
+                "Postman mcpUrl not configured. Use postman_set_mode to set one.",
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  }
+
+  const mode = urlToMode(url);
+  if (!mode) {
+    unknownPostmanMode(url);
+  }
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            mode,
+            url,
+            scope: effective.scope,
+            availableModes: Object.keys(POSTMAN_MODES),
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}

package/mcp/src/tools/postmanGetStatus.ts

@@ -0,0 +1,65 @@
+/**
+ * Cubis Foundry MCP Server – postman_get_status tool.
+ *
+ * Returns the full Postman configuration status (mode, URL, workspace ID).
+ */
+
+import { z } from "zod";
+import { parsePostmanState, readEffectiveConfig } from "../cbxConfig/index.js";
+import type { ConfigScope } from "../cbxConfig/types.js";
+import { configNotFound } from "../utils/errors.js";
+import { urlToMode, POSTMAN_MODES } from "./postmanModes.js";
+
+export const postmanGetStatusName = "postman_get_status";
+
+export const postmanGetStatusDescription =
+  "Get full Postman configuration status including mode, URL, and workspace ID.";
+
+export const postmanGetStatusSchema = z.object({
+  scope: z
+    .enum(["global", "project", "auto"])
+    .optional()
+    .describe(
+      "Config scope to read. Default: auto (project if exists, else global)",
+    ),
+});
+
+export function handlePostmanGetStatus(
+  args: z.infer<typeof postmanGetStatusSchema>,
+) {
+  const scope = args.scope ?? "auto";
+  const effective = readEffectiveConfig(scope as ConfigScope | "auto");
+
+  if (!effective) {
+    configNotFound();
+  }
+
+  const postman = parsePostmanState(effective.config);
+  const activeProfile = postman.activeProfile;
+  const url = postman.mcpUrl ?? null;
+  const mode = url ? (urlToMode(url) ?? "unknown") : null;
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            configured: !!url,
+            mode,
+            url,
+            defaultWorkspaceId: activeProfile?.workspaceId ?? null,
+            activeProfileName: postman.activeProfileName,
+            profileCount: postman.profiles.length,
+            apiKeyEnvVar: activeProfile?.apiKeyEnvVar ?? null,
+            scope: effective.scope,
+            configPath: effective.path,
+            availableModes: Object.keys(POSTMAN_MODES),
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}