@cubis/foundry 0.3.33 → 0.3.35

package/mcp/src/transports/streamableHttp.ts

@@ -0,0 +1,43 @@
+/**
+ * Cubis Foundry MCP Server – Streamable HTTP transport adapter.
+ *
+ * Uses the SDK's StreamableHTTPServerTransport for remote connections.
+ * Binds to localhost by default (security: prevents DNS rebinding).
+ */
+
+import { createServer, type Server } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { logger } from "../utils/logger.js";
+
+export interface HttpTransportOptions {
+  port: number;
+  host: string;
+}
+
+export function createStreamableHttpTransport(options: HttpTransportOptions): {
+  transport: StreamableHTTPServerTransport;
+  httpServer: Server;
+} {
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => crypto.randomUUID(),
+  });
+
+  const httpServer = createServer(async (req, res) => {
+    // Only handle the /mcp endpoint
+    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    if (url.pathname !== "/mcp") {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("Not Found");
+      return;
+    }
+    await transport.handleRequest(req, res);
+  });
+
+  httpServer.listen(options.port, options.host, () => {
+    logger.info(
+      `Streamable HTTP transport listening on http://${options.host}:${options.port}/mcp`,
+    );
+  });
+
+  return { transport, httpServer };
+}

package/mcp/src/upstream/passthrough.ts

@@ -0,0 +1,273 @@
+/**
+ * Cubis Foundry MCP Server – upstream Postman/Stitch passthrough support.
+ */
+
+import { mkdir, 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";
+import {
+  parsePostmanState,
+  parseStitchState,
+  readEffectiveConfig,
+} from "../cbxConfig/index.js";
+import type { CbxConfig } from "../cbxConfig/types.js";
+
+type ServiceId = "postman" | "stitch";
+
+export interface UpstreamToolInfo {
+  name: string;
+  namespacedName: string;
+  description?: string;
+  inputSchema?: unknown;
+  outputSchema?: unknown;
+}
+
+export interface UpstreamCatalog {
+  service: ServiceId;
+  configured: boolean;
+  mcpUrl: string | null;
+  activeProfileName: string | null;
+  envVar: string | null;
+  scope: "global" | "project" | null;
+  configPath: string | null;
+  toolCount: number;
+  tools: UpstreamToolInfo[];
+  discoveryError?: string;
+}
+
+function resolveCatalogDir(configPath: string): string {
+  const configDir = path.dirname(configPath);
+  if (path.basename(configDir) === ".cbx") {
+    return path.join(configDir, "mcp", "catalog");
+  }
+  return path.join(configDir, ".cbx", "mcp", "catalog");
+}
+
+function getServiceAuth(config: CbxConfig, service: ServiceId): {
+  mcpUrl: string | null;
+  activeProfileName: string | null;
+  envVar: string | null;
+  headers: Record<string, string>;
+  configured: boolean;
+  error?: string;
+} {
+  if (service === "postman") {
+    const state = parsePostmanState(config);
+    const activeProfile = state.activeProfile;
+    const envVar = activeProfile?.apiKeyEnvVar ?? "POSTMAN_API_KEY";
+    const token = process.env[envVar]?.trim();
+    if (!token) {
+      return {
+        mcpUrl: state.mcpUrl,
+        activeProfileName: state.activeProfileName,
+        envVar,
+        headers: {},
+        configured: false,
+        error: `Missing Postman key env var: ${envVar}`,
+      };
+    }
+    return {
+      mcpUrl: state.mcpUrl,
+      activeProfileName: state.activeProfileName,
+      envVar,
+      headers: { Authorization: `Bearer ${token}` },
+      configured: Boolean(state.mcpUrl),
+    };
+  }
+
+  const state = parseStitchState(config);
+  const activeProfile = state.activeProfile;
+  const envVar = activeProfile?.apiKeyEnvVar ?? "STITCH_API_KEY";
+  const token = process.env[envVar]?.trim();
+  if (!token && !state.useSystemGcloud) {
+    return {
+      mcpUrl: state.mcpUrl,
+      activeProfileName: state.activeProfileName,
+      envVar,
+      headers: {},
+      configured: false,
+      error: `Missing Stitch key env var: ${envVar}`,
+    };
+  }
+  return {
+    mcpUrl: state.mcpUrl,
+    activeProfileName: state.activeProfileName,
+    envVar,
+    headers: token ? { "X-Goog-Api-Key": token } : {},
+    configured: Boolean(state.mcpUrl),
+  };
+}
+
+async function withUpstreamClient<T>({
+  url,
+  headers,
+  fn,
+}: {
+  url: string;
+  headers: Record<string, string>;
+  fn: (client: Client) => Promise<T>;
+}): Promise<T> {
+  const client = new Client(
+    {
+      name: "cubis-foundry-mcp-passthrough",
+      version: "0.1.0",
+    },
+    {
+      capabilities: {},
+    },
+  );
+  const transport = new StreamableHTTPClientTransport(new URL(url), {
+    requestInit: { headers },
+  });
+  await client.connect(transport);
+  try {
+    return await fn(client);
+  } finally {
+    await client.close();
+  }
+}
+
+async function persistCatalog(catalog: UpstreamCatalog): Promise<void> {
+  if (!catalog.configPath) return;
+  const catalogDir = resolveCatalogDir(catalog.configPath);
+  const catalogPath = path.join(catalogDir, `${catalog.service}.json`);
+  const payload = {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    generatedBy: "cubis-foundry-mcp startup discovery",
+    service: catalog.service,
+    scope: catalog.scope,
+    mcpUrl: catalog.mcpUrl,
+    activeProfileName: catalog.activeProfileName,
+    envVar: catalog.envVar,
+    toolCount: catalog.toolCount,
+    tools: catalog.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description ?? null,
+      inputSchema: tool.inputSchema ?? null,
+      outputSchema: tool.outputSchema ?? null,
+    })),
+    discoveryError: catalog.discoveryError ?? null,
+  };
+  await mkdir(catalogDir, { recursive: true });
+  await writeFile(catalogPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+export async function discoverUpstreamCatalogs(): Promise<{
+  postman: UpstreamCatalog;
+  stitch: UpstreamCatalog;
+}> {
+  const effective = readEffectiveConfig("auto");
+  if (!effective) {
+    const missing: UpstreamCatalog = {
+      service: "postman",
+      configured: false,
+      mcpUrl: null,
+      activeProfileName: null,
+      envVar: null,
+      scope: null,
+      configPath: null,
+      toolCount: 0,
+      tools: [],
+      discoveryError: "cbx_config.json not found",
+    };
+    const missingStitch: UpstreamCatalog = { ...missing, service: "stitch" };
+    return {
+      postman: missing,
+      stitch: missingStitch,
+    };
+  }
+
+  const baseInfo = {
+    scope: effective.scope,
+    configPath: effective.path,
+  } as const;
+
+  const discoverOne = async (service: ServiceId): Promise<UpstreamCatalog> => {
+    const auth = getServiceAuth(effective.config, service);
+    const catalog: UpstreamCatalog = {
+      service,
+      configured: auth.configured,
+      mcpUrl: auth.mcpUrl,
+      activeProfileName: auth.activeProfileName,
+      envVar: auth.envVar,
+      scope: baseInfo.scope,
+      configPath: baseInfo.configPath,
+      toolCount: 0,
+      tools: [],
+      discoveryError: auth.error,
+    };
+
+    if (!auth.configured || !auth.mcpUrl || auth.error) {
+      await persistCatalog(catalog);
+      return catalog;
+    }
+
+    try {
+      const listed = await withUpstreamClient({
+        url: auth.mcpUrl,
+        headers: auth.headers,
+        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 : undefined,
+            inputSchema: tool?.inputSchema ?? undefined,
+            outputSchema: tool?.outputSchema ?? undefined,
+          } satisfies UpstreamToolInfo;
+        })
+        .filter((tool): tool is UpstreamToolInfo => Boolean(tool));
+      catalog.toolCount = catalog.tools.length;
+    } catch (error) {
+      catalog.discoveryError = `Tool discovery failed: ${String(error)}`;
+    }
+
+    await persistCatalog(catalog);
+    return catalog;
+  };
+
+  return {
+    postman: await discoverOne("postman"),
+    stitch: await discoverOne("stitch"),
+  };
+}
+
+export async function callUpstreamTool({
+  service,
+  name,
+  argumentsValue,
+}: {
+  service: ServiceId;
+  name: string;
+  argumentsValue: Record<string, unknown>;
+}) {
+  const effective = readEffectiveConfig("auto");
+  if (!effective) {
+    throw new Error("cbx_config.json not found");
+  }
+  const auth = getServiceAuth(effective.config, service);
+  if (!auth.configured || !auth.mcpUrl) {
+    throw new Error(auth.error || `${service} is not configured`);
+  }
+  if (auth.error) {
+    throw new Error(auth.error);
+  }
+
+  return withUpstreamClient({
+    url: auth.mcpUrl,
+    headers: auth.headers,
+    fn: async (client) =>
+      client.callTool({
+        name,
+        arguments: argumentsValue,
+      }),
+  });
+}

package/mcp/src/utils/errors.ts

@@ -0,0 +1,38 @@
+/**
+ * Cubis Foundry MCP Server – error utilities.
+ *
+ * Provides structured MCP-compatible error helpers.
+ */
+
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+
+/** Throw when a tool receives invalid input that passes Zod but fails domain validation. */
+export function invalidInput(message: string): never {
+  throw new McpError(ErrorCode.InvalidParams, message);
+}
+
+/** Throw when a required config file is missing. */
+export function configNotFound(): never {
+  throw new McpError(
+    ErrorCode.InternalError,
+    "cbx_config.json not found. Run cbx workflows config --scope global --show to diagnose.",
+  );
+}
+
+/** Throw for unknown Postman mode URL found in config. */
+export function unknownPostmanMode(url: string): never {
+  throw new McpError(
+    ErrorCode.InvalidParams,
+    `Unknown Postman MCP URL in config: "${url}". Expected one of: https://mcp.postman.com/minimal, https://mcp.postman.com/code, https://mcp.postman.com/mcp`,
+  );
+}
+
+/** Throw when a vault skill or category is not found. */
+export function notFound(entity: string, id: string): never {
+  throw new McpError(ErrorCode.InvalidParams, `${entity} not found: "${id}"`);
+}
+
+/** Throw for any internal server error with a message. */
+export function internalError(message: string): never {
+  throw new McpError(ErrorCode.InternalError, message);
+}

package/mcp/src/utils/logger.ts

@@ -0,0 +1,63 @@
+/**
+ * Cubis Foundry MCP Server – utilities / structured logger.
+ *
+ * ALL log output goes to stderr so stdio transport stays clean.
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+let currentLevel: LogLevel = "info";
+
+export function setLogLevel(level: LogLevel): void {
+  currentLevel = level;
+}
+
+function shouldLog(level: LogLevel): boolean {
+  return LEVEL_ORDER[level] >= LEVEL_ORDER[currentLevel];
+}
+
+function ts(): string {
+  return new Date().toISOString();
+}
+
+export const logger = {
+  debug(msg: string, data?: unknown): void {
+    if (shouldLog("debug")) {
+      process.stderr.write(
+        `[${ts()}] DEBUG ${msg}${data ? ` ${JSON.stringify(data)}` : ""}\n`,
+      );
+    }
+  },
+  info(msg: string, data?: unknown): void {
+    if (shouldLog("info")) {
+      process.stderr.write(
+        `[${ts()}] INFO  ${msg}${data ? ` ${JSON.stringify(data)}` : ""}\n`,
+      );
+    }
+  },
+  warn(msg: string, data?: unknown): void {
+    if (shouldLog("warn")) {
+      process.stderr.write(
+        `[${ts()}] WARN  ${msg}${data ? ` ${JSON.stringify(data)}` : ""}\n`,
+      );
+    }
+  },
+  error(msg: string, data?: unknown): void {
+    if (shouldLog("error")) {
+      process.stderr.write(
+        `[${ts()}] ERROR ${msg}${data ? ` ${JSON.stringify(data)}` : ""}\n`,
+      );
+    }
+  },
+  /** Raw line to stderr (no timestamp/level prefix). Used for startup banners. */
+  raw(msg: string): void {
+    process.stderr.write(`${msg}\n`);
+  },
+};

package/mcp/src/vault/manifest.test.ts

@@ -0,0 +1,126 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  enrichWithDescriptions,
+  extractDescription,
+  parseDescriptionFromFrontmatter,
+  readFullSkillContent,
+} from "./manifest.js";
+
+const tempDirs: string[] = [];
+
+function createTempDir(prefix: string): string {
+  const dir = mkdtempSync(path.join(os.tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+});
+
+describe("frontmatter description parsing", () => {
+  it("extracts a quoted description", () => {
+    const content = [
+      "---",
+      'name: "react-expert"',
+      'description: "React architecture and performance best practices"',
+      "---",
+      "# React Expert",
+    ].join("\n");
+
+    expect(parseDescriptionFromFrontmatter(content, 200)).toBe(
+      "React architecture and performance best practices",
+    );
+  });
+
+  it("truncates long descriptions with ellipsis", () => {
+    const content = [
+      "---",
+      "name: long-skill",
+      "description: This is a very long description for testing truncation behavior",
+      "---",
+    ].join("\n");
+
+    expect(parseDescriptionFromFrontmatter(content, 24)).toBe(
+      "This is a very long d...",
+    );
+  });
+
+  it("returns undefined when frontmatter description is missing", () => {
+    const content = ["---", "name: no-description", "---", "# Body"].join("\n");
+    expect(parseDescriptionFromFrontmatter(content, 100)).toBeUndefined();
+  });
+});
+
+describe("skill content IO", () => {
+  it("extracts description from file content", async () => {
+    const dir = createTempDir("mcp-manifest-");
+    const file = path.join(dir, "SKILL.md");
+    writeFileSync(
+      file,
+      ["---", "name: test-skill", "description: Fast API design patterns", "---"].join(
+        "\n",
+      ),
+      "utf8",
+    );
+
+    await expect(extractDescription(file, 100)).resolves.toBe(
+      "Fast API design patterns",
+    );
+  });
+
+  it("returns undefined when file cannot be read", async () => {
+    await expect(extractDescription("/missing/skill.md", 100)).resolves.toBeUndefined();
+  });
+
+  it("returns full skill file contents", async () => {
+    const dir = createTempDir("mcp-full-read-");
+    const file = path.join(dir, "SKILL.md");
+    const body = "---\nname: full-read\ndescription: Full body\n---\n# Content";
+    writeFileSync(file, body, "utf8");
+
+    await expect(readFullSkillContent(file)).resolves.toBe(body);
+  });
+});
+
+describe("manifest enrichment", () => {
+  it("enriches missing descriptions and keeps existing descriptions", async () => {
+    const dir = createTempDir("mcp-enrich-");
+    const fileA = path.join(dir, "a.md");
+    const fileB = path.join(dir, "b.md");
+    writeFileSync(
+      fileA,
+      ["---", "name: alpha", "description: Alpha description", "---"].join("\n"),
+      "utf8",
+    );
+    writeFileSync(
+      fileB,
+      ["---", "name: beta", "description: Beta description", "---"].join("\n"),
+      "utf8",
+    );
+
+    const enriched = await enrichWithDescriptions(
+      [
+        { id: "alpha", category: "general", path: fileA },
+        {
+          id: "beta",
+          category: "general",
+          path: fileB,
+          description: "Already populated",
+        },
+      ],
+      100,
+    );
+
+    expect(enriched[0].description).toBe("Alpha description");
+    expect(enriched[1].description).toBe("Already populated");
+  });
+});

package/mcp/src/vault/manifest.ts

@@ -0,0 +1,99 @@
+/**
+ * Cubis Foundry MCP Server – vault manifest.
+ *
+ * Browse/search operations extract frontmatter description only (truncated).
+ * Full SKILL.md content is read only by skill_get.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { SkillPointer, VaultManifest } from "./types.js";
+import { logger } from "../utils/logger.js";
+
+/**
+ * Build a VaultManifest from scanned skill pointers.
+ * Categories are derived from the pointers.
+ */
+export function buildManifest(skills: SkillPointer[]): VaultManifest {
+  const categorySet = new Set<string>();
+  for (const skill of skills) {
+    categorySet.add(skill.category);
+  }
+  return {
+    categories: [...categorySet].sort(),
+    skills,
+  };
+}
+
+/**
+ * Extract the frontmatter `description` from a SKILL.md file.
+ * Reads only the YAML frontmatter block (between `---` delimiters).
+ * Returns the description truncated to maxLength, or undefined if not found.
+ */
+export async function extractDescription(
+  skillPath: string,
+  maxLength: number,
+): Promise<string | undefined> {
+  try {
+    const content = await readFile(skillPath, "utf8");
+    return parseDescriptionFromFrontmatter(content, maxLength);
+  } catch (err) {
+    logger.debug(`Failed to read description from ${skillPath}: ${err}`);
+    return undefined;
+  }
+}
+
+/**
+ * Parse the description field from YAML frontmatter.
+ */
+export function parseDescriptionFromFrontmatter(
+  content: string,
+  maxLength: number,
+): string | undefined {
+  // Match YAML frontmatter block
+  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!fmMatch) return undefined;
+
+  const frontmatter = fmMatch[1];
+
+  // Extract description field (handles both single-line and multi-line)
+  const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+  if (!descMatch) return undefined;
+
+  let desc = descMatch[1].trim();
+  // Remove surrounding quotes if present
+  if (
+    (desc.startsWith('"') && desc.endsWith('"')) ||
+    (desc.startsWith("'") && desc.endsWith("'"))
+  ) {
+    desc = desc.slice(1, -1);
+  }
+
+  if (desc.length > maxLength) {
+    return desc.slice(0, maxLength - 3) + "...";
+  }
+  return desc;
+}
+
+/**
+ * Read the full content of a SKILL.md file.
+ * This is the ONLY function that reads full file content (lazy model).
+ */
+export async function readFullSkillContent(skillPath: string): Promise<string> {
+  return readFile(skillPath, "utf8");
+}
+
+/**
+ * Enrich skill pointers with descriptions (for browse/search results).
+ */
+export async function enrichWithDescriptions(
+  skills: SkillPointer[],
+  maxLength: number,
+): Promise<SkillPointer[]> {
+  return Promise.all(
+    skills.map(async (skill) => {
+      if (skill.description) return skill;
+      const description = await extractDescription(skill.path, maxLength);
+      return { ...skill, description };
+    }),
+  );
+}