@cubis/foundry 0.3.50 → 0.3.52

package/mcp/dist/index.js

@@ -1539,7 +1539,7 @@ var TOOL_REGISTRY = [
 ];
 
 // src/upstream/passthrough.ts
-import { mkdir, writeFile } from "fs/promises";
+import { mkdir, readFile as readFile2, writeFile } from "fs/promises";
 import path6 from "path";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
@@ -1550,6 +1550,45 @@ function resolveCatalogDir(configPath) {
   }
   return path6.join(configDir, ".cbx", "mcp", "catalog");
 }
+function buildPassthroughAliasName(service, toolName) {
+  const normalizedTool = String(toolName || "").trim().replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "").replace(/_+/g, "_").toLowerCase();
+  if (!normalizedTool) return `${service}_tool`;
+  return `${service}_${normalizedTool}`;
+}
+function buildUpstreamToolInfo(service, tool) {
+  const name = typeof tool?.name === "string" ? tool.name.trim() : "";
+  if (!name) return null;
+  const namespacedName = `${service}.${name}`;
+  const aliasNames = [buildPassthroughAliasName(service, name)];
+  return {
+    name,
+    namespacedName,
+    aliasNames,
+    description: typeof tool?.description === "string" ? tool.description : void 0,
+    inputSchema: tool?.inputSchema ?? void 0,
+    outputSchema: tool?.outputSchema ?? void 0
+  };
+}
+async function loadCachedCatalogTools({
+  service,
+  scope,
+  configPath
+}) {
+  if (!configPath) return [];
+  const catalogDir = resolveCatalogDir(configPath);
+  const catalogPath = path6.join(catalogDir, `${service}.json`);
+  try {
+    const raw = await readFile2(catalogPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (scope && typeof parsed.scope === "string" && parsed.scope.trim() && parsed.scope !== scope) {
+      return [];
+    }
+    const tools = Array.isArray(parsed.tools) ? parsed.tools : [];
+    return tools.map((tool) => buildUpstreamToolInfo(service, tool)).filter((tool) => Boolean(tool));
+  } catch {
+    return [];
+  }
+}
 function getServiceAuth(config, service) {
   if (service === "postman") {
     const state2 = parsePostmanState(config);
@@ -1646,8 +1685,8 @@ async function persistCatalog(catalog) {
   await writeFile(catalogPath, `${JSON.stringify(payload, null, 2)}
 `, "utf8");
 }
-async function discoverUpstreamCatalogs() {
-  const effective = readEffectiveConfig("auto");
+async function discoverUpstreamCatalogs(scope = "auto") {
+  const effective = readEffectiveConfig(scope);
   if (!effective) {
     const missing = {
       service: "postman",
@@ -1686,6 +1725,16 @@ async function discoverUpstreamCatalogs() {
       discoveryError: auth.error
     };
     if (!auth.configured || !auth.mcpUrl || auth.error) {
+      const cachedTools = await loadCachedCatalogTools({
+        service,
+        scope: baseInfo.scope,
+        configPath: baseInfo.configPath
+      });
+      if (cachedTools.length > 0) {
+        catalog.tools = cachedTools;
+        catalog.toolCount = cachedTools.length;
+        catalog.discoveryError = auth.error ? `${auth.error} (using cached tool catalog)` : "Upstream not configured; using cached tool catalog";
+      }
       await persistCatalog(catalog);
       return catalog;
     }
@@ -1696,20 +1745,20 @@ async function discoverUpstreamCatalogs() {
         fn: async (client) => client.listTools()
       });
       const rawTools = Array.isArray(listed.tools) ? listed.tools : [];
-      catalog.tools = rawTools.map((tool) => {
-        const name = typeof tool?.name === "string" ? tool.name.trim() : "";
-        if (!name) return null;
-        return {
-          name,
-          namespacedName: `${service}.${name}`,
-          description: typeof tool?.description === "string" ? tool.description : void 0,
-          inputSchema: tool?.inputSchema ?? void 0,
-          outputSchema: tool?.outputSchema ?? void 0
-        };
-      }).filter((tool) => Boolean(tool));
+      catalog.tools = rawTools.map((tool) => buildUpstreamToolInfo(service, tool || {})).filter((tool) => Boolean(tool));
       catalog.toolCount = catalog.tools.length;
     } catch (error) {
       catalog.discoveryError = `Tool discovery failed: ${String(error)}`;
+      const cachedTools = await loadCachedCatalogTools({
+        service,
+        scope: baseInfo.scope,
+        configPath: baseInfo.configPath
+      });
+      if (cachedTools.length > 0) {
+        catalog.tools = cachedTools;
+        catalog.toolCount = cachedTools.length;
+        catalog.discoveryError = `${catalog.discoveryError} (using cached tool catalog)`;
+      }
     }
     await persistCatalog(catalog);
     return catalog;
@@ -1722,9 +1771,10 @@ async function discoverUpstreamCatalogs() {
 async function callUpstreamTool({
   service,
   name,
-  argumentsValue
+  argumentsValue,
+  scope = "auto"
 }) {
-  const effective = readEffectiveConfig("auto");
+  const effective = readEffectiveConfig(scope);
   if (!effective) {
     throw new Error("cbx_config.json not found");
   }
@@ -1799,40 +1849,52 @@ async function createServer({
   logger.debug(
     `Registered ${TOOL_REGISTRY.length} built-in tools from registry`
   );
-  const upstreamCatalogs = await discoverUpstreamCatalogs();
+  const upstreamCatalogs = await discoverUpstreamCatalogs(defaultConfigScope);
   const dynamicSchema = z13.object({}).passthrough();
+  const registeredDynamicToolNames = /* @__PURE__ */ new Set();
   for (const catalog of [upstreamCatalogs.postman, upstreamCatalogs.stitch]) {
     for (const tool of catalog.tools) {
-      const namespaced = tool.namespacedName;
-      server.registerTool(
-        namespaced,
-        {
-          description: `[${catalog.service} passthrough] ${tool.description || tool.name}`,
-          inputSchema: dynamicSchema,
-          annotations: {}
-        },
-        async (args) => {
-          try {
-            const result = await callUpstreamTool({
-              service: catalog.service,
-              name: tool.name,
-              argumentsValue: args && typeof args === "object" ? args : {}
-            });
-            return {
-              // SDK content is typed broadly; cast to the expected array shape.
-              content: result.content ?? [],
-              structuredContent: result.structuredContent,
-              isError: Boolean(result.isError)
-            };
-          } catch (error) {
-            return toolCallErrorResult({
-              service: catalog.service,
-              namespacedName: namespaced,
-              error
-            });
-          }
+      const registrationNames = [tool.namespacedName, ...tool.aliasNames || []];
+      const uniqueRegistrationNames = [...new Set(registrationNames)];
+      for (const registrationName of uniqueRegistrationNames) {
+        if (registeredDynamicToolNames.has(registrationName)) {
+          logger.warn(
+            `Skipping duplicate dynamic tool registration name '${registrationName}' from ${catalog.service}.${tool.name}`
+          );
+          continue;
         }
-      );
+        registeredDynamicToolNames.add(registrationName);
+        server.registerTool(
+          registrationName,
+          {
+            description: `[${catalog.service} passthrough] ${tool.description || tool.name}`,
+            inputSchema: dynamicSchema,
+            annotations: {}
+          },
+          async (args) => {
+            try {
+              const result = await callUpstreamTool({
+                service: catalog.service,
+                name: tool.name,
+                argumentsValue: args && typeof args === "object" ? args : {},
+                scope: defaultConfigScope
+              });
+              return {
+                // SDK content is typed broadly; cast to the expected array shape.
+                content: result.content ?? [],
+                structuredContent: result.structuredContent,
+                isError: Boolean(result.isError)
+              };
+            } catch (error) {
+              return toolCallErrorResult({
+                service: catalog.service,
+                namespacedName: registrationName,
+                error
+              });
+            }
+          }
+        );
+      }
     }
   }
   return server;

package/mcp/src/server.ts

@@ -92,49 +92,61 @@ export async function createServer({
   );
 
   // ─── Dynamic upstream passthrough tools ────────────────────
-  const upstreamCatalogs = await discoverUpstreamCatalogs();
+  const upstreamCatalogs = await discoverUpstreamCatalogs(defaultConfigScope);
   const dynamicSchema = z.object({}).passthrough();
+  const registeredDynamicToolNames = new Set<string>();
 
   for (const catalog of [upstreamCatalogs.postman, upstreamCatalogs.stitch]) {
     for (const tool of catalog.tools) {
-      const namespaced = tool.namespacedName;
-      server.registerTool(
-        namespaced,
-        {
-          description: `[${catalog.service} passthrough] ${tool.description || tool.name}`,
-          inputSchema: dynamicSchema,
-          annotations: {},
-        },
-        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>),
-            });
-            return {
-              // 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) {
-            return toolCallErrorResult({
-              service: catalog.service,
-              namespacedName: namespaced,
-              error,
-            });
-          }
-        },
-      );
+      const registrationNames = [tool.namespacedName, ...(tool.aliasNames || [])];
+      const uniqueRegistrationNames = [...new Set(registrationNames)];
+      for (const registrationName of uniqueRegistrationNames) {
+        if (registeredDynamicToolNames.has(registrationName)) {
+          logger.warn(
+            `Skipping duplicate dynamic tool registration name '${registrationName}' from ${catalog.service}.${tool.name}`,
+          );
+          continue;
+        }
+        registeredDynamicToolNames.add(registrationName);
+        server.registerTool(
+          registrationName,
+          {
+            description: `[${catalog.service} passthrough] ${tool.description || tool.name}`,
+            inputSchema: dynamicSchema,
+            annotations: {},
+          },
+          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>),
+                scope: defaultConfigScope,
+              });
+              return {
+                // 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) {
+              return toolCallErrorResult({
+                service: catalog.service,
+                namespacedName: registrationName,
+                error,
+              });
+            }
+          },
+        );
+      }
     }
   }
 

package/mcp/src/upstream/passthrough.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildPassthroughAliasName,
+  buildUpstreamToolInfo,
+} from "./passthrough.js";
+
+describe("upstream passthrough aliasing", () => {
+  it("builds deterministic underscore aliases for postman tools", () => {
+    expect(buildPassthroughAliasName("postman", "runCollection")).toBe(
+      "postman_run_collection",
+    );
+    expect(buildPassthroughAliasName("postman", "get-workspaces")).toBe(
+      "postman_get_workspaces",
+    );
+  });
+
+  it("maps upstream tools to namespaced + alias registrations", () => {
+    const info = buildUpstreamToolInfo("stitch", {
+      name: "list_tools",
+      description: "List available tools",
+    });
+
+    expect(info).toMatchObject({
+      name: "list_tools",
+      namespacedName: "stitch.list_tools",
+      aliasNames: ["stitch_list_tools"],
+      description: "List available tools",
+    });
+  });
+});

package/mcp/src/upstream/passthrough.ts

@@ -2,7 +2,7 @@
  * Cubis Foundry MCP Server – upstream Postman/Stitch passthrough support.
  */
 
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
@@ -11,13 +11,14 @@ import {
   parseStitchState,
   readEffectiveConfig,
 } from "../cbxConfig/index.js";
-import type { CbxConfig } from "../cbxConfig/types.js";
+import type { CbxConfig, ConfigScope } from "../cbxConfig/types.js";
 
 type ServiceId = "postman" | "stitch";
 
 export interface UpstreamToolInfo {
   name: string;
   namespacedName: string;
+  aliasNames: string[];
   description?: string;
   inputSchema?: unknown;
   outputSchema?: unknown;
@@ -44,6 +45,86 @@ function resolveCatalogDir(configPath: string): string {
   return path.join(configDir, ".cbx", "mcp", "catalog");
 }
 
+export function buildPassthroughAliasName(
+  service: ServiceId,
+  toolName: string,
+): string {
+  const normalizedTool = String(toolName || "")
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .replace(/_+/g, "_")
+    .toLowerCase();
+  if (!normalizedTool) return `${service}_tool`;
+  return `${service}_${normalizedTool}`;
+}
+
+export function buildUpstreamToolInfo(
+  service: ServiceId,
+  tool: {
+    name?: unknown;
+    description?: unknown;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+  },
+): UpstreamToolInfo | null {
+  const name = typeof tool?.name === "string" ? tool.name.trim() : "";
+  if (!name) return null;
+  const namespacedName = `${service}.${name}`;
+  const aliasNames = [buildPassthroughAliasName(service, name)];
+  return {
+    name,
+    namespacedName,
+    aliasNames,
+    description:
+      typeof tool?.description === "string" ? tool.description : undefined,
+    inputSchema: tool?.inputSchema ?? undefined,
+    outputSchema: tool?.outputSchema ?? undefined,
+  };
+}
+
+async function loadCachedCatalogTools({
+  service,
+  scope,
+  configPath,
+}: {
+  service: ServiceId;
+  scope: ConfigScope | null;
+  configPath: string | null;
+}): Promise<UpstreamToolInfo[]> {
+  if (!configPath) return [];
+  const catalogDir = resolveCatalogDir(configPath);
+  const catalogPath = path.join(catalogDir, `${service}.json`);
+  try {
+    const raw = await readFile(catalogPath, "utf8");
+    const parsed = JSON.parse(raw) as {
+      scope?: string;
+      tools?: Array<{
+        name?: unknown;
+        description?: unknown;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
+      }>;
+    };
+    if (
+      scope &&
+      typeof parsed.scope === "string" &&
+      parsed.scope.trim() &&
+      parsed.scope !== scope
+    ) {
+      // Cross-scope catalogs can be stale for the active config.
+      return [];
+    }
+    const tools = Array.isArray(parsed.tools) ? parsed.tools : [];
+    return tools
+      .map((tool) => buildUpstreamToolInfo(service, tool))
+      .filter((tool): tool is UpstreamToolInfo => Boolean(tool));
+  } catch {
+    return [];
+  }
+}
+
 function getServiceAuth(config: CbxConfig, service: ServiceId): {
   mcpUrl: string | null;
   activeProfileName: string | null;
@@ -154,11 +235,13 @@ async function persistCatalog(catalog: UpstreamCatalog): Promise<void> {
   await writeFile(catalogPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
 }
 
-export async function discoverUpstreamCatalogs(): Promise<{
+export async function discoverUpstreamCatalogs(
+  scope: ConfigScope | "auto" = "auto",
+): Promise<{
   postman: UpstreamCatalog;
   stitch: UpstreamCatalog;
 }> {
-  const effective = readEffectiveConfig("auto");
+  const effective = readEffectiveConfig(scope);
   if (!effective) {
     const missing: UpstreamCatalog = {
       service: "postman",
@@ -200,6 +283,18 @@ export async function discoverUpstreamCatalogs(): Promise<{
     };
 
     if (!auth.configured || !auth.mcpUrl || auth.error) {
+      const cachedTools = await loadCachedCatalogTools({
+        service,
+        scope: baseInfo.scope,
+        configPath: baseInfo.configPath,
+      });
+      if (cachedTools.length > 0) {
+        catalog.tools = cachedTools;
+        catalog.toolCount = cachedTools.length;
+        catalog.discoveryError = auth.error
+          ? `${auth.error} (using cached tool catalog)`
+          : "Upstream not configured; using cached tool catalog";
+      }
       await persistCatalog(catalog);
       return catalog;
     }
@@ -212,22 +307,21 @@ export async function discoverUpstreamCatalogs(): Promise<{
       });
       const rawTools = Array.isArray(listed.tools) ? listed.tools : [];
       catalog.tools = rawTools
-        .map((tool) => {
-          const name = typeof tool?.name === "string" ? tool.name.trim() : "";
-          if (!name) return null;
-          return {
-            name,
-            namespacedName: `${service}.${name}`,
-            description:
-              typeof tool?.description === "string" ? tool.description : undefined,
-            inputSchema: tool?.inputSchema ?? undefined,
-            outputSchema: tool?.outputSchema ?? undefined,
-          } satisfies UpstreamToolInfo;
-        })
+        .map((tool) => buildUpstreamToolInfo(service, tool || {}))
         .filter((tool): tool is UpstreamToolInfo => Boolean(tool));
       catalog.toolCount = catalog.tools.length;
     } catch (error) {
       catalog.discoveryError = `Tool discovery failed: ${String(error)}`;
+      const cachedTools = await loadCachedCatalogTools({
+        service,
+        scope: baseInfo.scope,
+        configPath: baseInfo.configPath,
+      });
+      if (cachedTools.length > 0) {
+        catalog.tools = cachedTools;
+        catalog.toolCount = cachedTools.length;
+        catalog.discoveryError = `${catalog.discoveryError} (using cached tool catalog)`;
+      }
     }
 
     await persistCatalog(catalog);
@@ -244,12 +338,14 @@ export async function callUpstreamTool({
   service,
   name,
   argumentsValue,
+  scope = "auto",
 }: {
   service: ServiceId;
   name: string;
   argumentsValue: Record<string, unknown>;
+  scope?: ConfigScope | "auto";
 }) {
-  const effective = readEffectiveConfig("auto");
+  const effective = readEffectiveConfig(scope);
   if (!effective) {
     throw new Error("cbx_config.json not found");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubis/foundry",
-  "version": "0.3.50",
+  "version": "0.3.52",
   "description": "Cubis Foundry CLI for workflow-first AI agent environments",
   "type": "module",
   "bin": {

package/workflows/skills/postman/SKILL.md

@@ -1,17 +1,86 @@
 ---
 name: postman
-description: Automate API testing and collection management with Postman MCP. Use for workspace, collection, environment, and mock operations.
+description: Automate API testing and collection management with Postman MCP using full-mode defaults and workspace-aware execution.
 ---
 
-# Postman MCP
+# Postman MCP Skill
 
-Use this skill when you need to work with Postman through MCP tools.
+Use this skill when you need Postman workspace, collection, environment, or run operations through MCP.
 
-## Required Environment Variables
+References:
+- [Full-Mode Setup](./references/full-mode-setup.md)
+- [Workspace Policy](./references/workspace-policy.md)
+- [Troubleshooting](./references/troubleshooting.md)
 
-- `POSTMAN_API_KEY_<PROFILE>` for authenticated Postman access.
+## MCP-First Rule
 
-## Notes
+- Prefer Postman MCP tools for all Postman operations.
+- Accept both dynamic naming styles from clients:
+  - dotted: `postman.<tool>`
+  - alias: `postman_<tool>`
+- Do not use Newman/Postman CLI fallback unless the user explicitly asks for fallback.
+- If required Postman MCP tools are unavailable, report discovery/remediation steps first.
+
+## Setup Baseline
+
+1. Install with Postman enabled and explicit full mode:
+   - `cbx workflows install --platform <codex|antigravity|copilot> --scope global --bundle agent-environment-setup --postman --postman-mode full --mcp-runtime docker --mcp-fallback local --mcp-tool-sync --yes`
+2. Persist env aliases once (no per-session re-export):
+   - `cbx workflows config keys persist-env --service postman --scope global`
+3. Verify mode/config:
+   - `cbx workflows config --scope global --show`
+   - `cbx mcp tools sync --service postman --scope global`
+   - `cbx mcp tools list --service postman --scope global`
+
+## Preflight
+
+1. Read Postman status first:
+   - Call `postman_get_status`.
+2. Ensure mode is `full`:
+   - If not, call `postman_set_mode` with `mode: full`.
+3. Discover upstream tools:
+   - Confirm required tools exist before execution (for example workspaces/collections/runs).
+
+## Default Workspace Policy
+
+Resolve workspace in this order:
+
+1. User-provided workspace ID.
+2. `postman_get_status.defaultWorkspaceId`.
+3. Auto-detect from workspace listing:
+   - If exactly one workspace exists, use it and state that choice.
+4. If multiple workspaces and no default:
+   - Ask user to choose one.
+   - Recommend persisting it with:
+     - `cbx workflows config --scope global --workspace-id <workspace-id>`
+
+When a Postman tool requires a workspace argument, always pass the resolved workspace ID explicitly.
+
+## Common Workflows
+
+### Collection Run
+
+1. Resolve workspace ID (policy above).
+2. Resolve `collectionId` and optional `environmentId`.
+3. Call Postman run tool (`postman.runCollection` or alias equivalent).
+4. Return a concise run summary:
+   - total requests
+   - passed/failed tests
+   - failing request/test names
+   - proposed fix path for failures
+
+## Failure Handling
+
+If dynamic Postman tools are missing:
+
+1. Verify env alias expected by config is set.
+2. Resync catalog:
+   - `cbx mcp tools sync --service postman --scope global`
+   - `cbx mcp tools list --service postman --scope global`
+3. Recreate runtime if needed:
+   - `cbx mcp runtime up --scope global --name cbx-mcp --replace --port 3310 --skills-root ~/.agents/skills`
+
+## Security Notes
 
 - Use environment variables for secrets. Do not inline API keys.
-- Prefer tool discovery (`getEnabledTools`) before making assumptions about available tool sets.
+- Never print or persist raw key values in logs, docs, or responses.

package/workflows/skills/postman/references/full-mode-setup.md

@@ -0,0 +1,36 @@
+# Postman Full-Mode Setup
+
+Use CLI mode flags instead of manual `jq` edits.
+
+## Install/Upgrade with Full Mode
+
+```bash
+cbx workflows install \
+  --platform codex \
+  --scope global \
+  --bundle agent-environment-setup \
+  --postman \
+  --postman-mode full \
+  --mcp-runtime docker \
+  --mcp-fallback local \
+  --mcp-tool-sync \
+  --overwrite \
+  --yes
+```
+
+## Change Mode Later
+
+```bash
+cbx workflows config --scope global --platform codex --postman-mode full
+```
+
+This updates:
+- `cbx_config.json` Postman URL
+- managed Postman MCP definition under `.cbx/mcp/<platform>/postman.json`
+- platform MCP runtime target patch (when platform is resolvable)
+
+## Persist Env Aliases
+
+```bash
+cbx workflows config keys persist-env --service postman --scope global
+```