@cubis/foundry 0.3.34 → 0.3.36

package/mcp/src/gateway/manager.ts

@@ -0,0 +1,255 @@
+/**
+ * Cubis Foundry MCP Server – upstream passthrough gateway manager.
+ */
+
+import { logger } from "../utils/logger.js";
+import { persistCatalog, resolveCatalogDir } from "./catalog.js";
+import { resolveGatewayConfig } from "./config.js";
+import { SdkUpstreamClientFactory } from "./upstreamClient.js";
+import type {
+  ConnectedUpstreamClient,
+  UpstreamClientFactory,
+  UpstreamCallResult,
+} from "./upstreamClient.js";
+import type { GatewayStatus, UpstreamProvider, UpstreamState, UpstreamTool } from "./types.js";
+
+export interface GatewayManagerOptions {
+  clientFactory?: UpstreamClientFactory;
+}
+
+interface ProviderRuntime {
+  mcpUrl: string | null;
+  headers: Record<string, string> | null;
+  authEnvVar: string | null;
+}
+
+function emptyProviderState(provider: UpstreamProvider): UpstreamState {
+  return {
+    provider,
+    mcpUrl: null,
+    authEnvVar: null,
+    authConfigured: false,
+    available: false,
+    warnings: [],
+    lastError: null,
+    syncedAt: null,
+    tools: [],
+  };
+}
+
+function messageFromError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+function errorResult(message: string): UpstreamCallResult {
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true,
+  };
+}
+
+function normalizeCallResult(result: UpstreamCallResult): UpstreamCallResult {
+  if (Array.isArray(result.content)) {
+    return result;
+  }
+
+  return {
+    content: [{ type: "text", text: JSON.stringify(result) }],
+    isError: result.isError ?? false,
+    structuredContent: result.structuredContent,
+  };
+}
+
+function normalizeArgs(args: unknown): Record<string, unknown> {
+  if (!args || typeof args !== "object" || Array.isArray(args)) {
+    return {};
+  }
+  return args as Record<string, unknown>;
+}
+
+export class GatewayManager {
+  private readonly clientFactory: UpstreamClientFactory;
+  private readonly providerRuntime: Record<UpstreamProvider, ProviderRuntime> = {
+    postman: { mcpUrl: null, headers: null, authEnvVar: null },
+    stitch: { mcpUrl: null, headers: null, authEnvVar: null },
+  };
+  private readonly providerState: Record<UpstreamProvider, UpstreamState> = {
+    postman: emptyProviderState("postman"),
+    stitch: emptyProviderState("stitch"),
+  };
+
+  private scope: GatewayStatus["scope"] = null;
+  private configPath: string | null = null;
+  private catalogDir = resolveCatalogDir(null, null);
+
+  constructor(options?: GatewayManagerOptions) {
+    this.clientFactory = options?.clientFactory ?? new SdkUpstreamClientFactory();
+  }
+
+  async initialize(): Promise<void> {
+    const resolved = resolveGatewayConfig("auto");
+    this.scope = resolved.scope;
+    this.configPath = resolved.configPath;
+    this.catalogDir = resolveCatalogDir(resolved.scope, resolved.configPath);
+
+    await Promise.all([
+      this.syncProvider("postman", resolved.providers.postman),
+      this.syncProvider("stitch", resolved.providers.stitch),
+    ]);
+  }
+
+  getCatalogDir(): string {
+    return this.catalogDir;
+  }
+
+  getStatus(): GatewayStatus {
+    return {
+      scope: this.scope,
+      configPath: this.configPath,
+      catalogDir: this.catalogDir,
+      generatedAt: new Date().toISOString(),
+      providers: {
+        postman: this.providerState.postman,
+        stitch: this.providerState.stitch,
+      },
+    };
+  }
+
+  listEnabledTools(provider: UpstreamProvider): Record<string, unknown> {
+    const state = this.providerState[provider];
+    return {
+      provider,
+      available: state.available,
+      enabledCount: state.tools.length,
+      enabledTools: state.tools.map((tool) => `${provider}.${tool.name}`),
+      upstreamTools: state.tools,
+      warnings: state.warnings,
+      lastError: state.lastError,
+      syncedAt: state.syncedAt,
+      mcpUrl: state.mcpUrl,
+      authEnvVar: state.authEnvVar,
+      authConfigured: state.authConfigured,
+      catalogDir: this.catalogDir,
+    };
+  }
+
+  getDynamicTools(provider: UpstreamProvider): UpstreamTool[] {
+    return [...this.providerState[provider].tools];
+  }
+
+  async callTool(
+    provider: UpstreamProvider,
+    upstreamToolName: string,
+    args: unknown,
+  ): Promise<UpstreamCallResult> {
+    const runtime = this.providerRuntime[provider];
+
+    if (!runtime.mcpUrl) {
+      return errorResult(`${provider} upstream MCP URL is not configured.`);
+    }
+    if (!runtime.headers) {
+      return errorResult(
+        `${provider} upstream auth is not configured via env var alias (${runtime.authEnvVar ?? "missing alias"}).`,
+      );
+    }
+
+    let client: ConnectedUpstreamClient | null = null;
+    try {
+      client = await this.clientFactory.connect({
+        mcpUrl: runtime.mcpUrl,
+        headers: runtime.headers,
+      });
+
+      const result = await client.callTool(
+        upstreamToolName,
+        normalizeArgs(args),
+      );
+      return normalizeCallResult(result);
+    } catch (error) {
+      const message = `${provider}.${upstreamToolName} failed: ${messageFromError(error)}`;
+      logger.warn(message);
+      return errorResult(message);
+    } finally {
+      if (client) {
+        try {
+          await client.close();
+        } catch {
+          // best-effort close
+        }
+      }
+    }
+  }
+
+  private async syncProvider(
+    provider: UpstreamProvider,
+    resolved: {
+      mcpUrl: string | null;
+      authHeader: Record<string, string> | null;
+      authEnvVar: string | null;
+      warnings: string[];
+    },
+  ): Promise<void> {
+    const state = emptyProviderState(provider);
+    state.mcpUrl = resolved.mcpUrl;
+    state.authEnvVar = resolved.authEnvVar;
+    state.authConfigured = !!resolved.authHeader;
+    state.warnings = [...resolved.warnings];
+
+    this.providerRuntime[provider] = {
+      mcpUrl: resolved.mcpUrl,
+      headers: resolved.authHeader,
+      authEnvVar: resolved.authEnvVar,
+    };
+
+    if (!resolved.mcpUrl || !resolved.authHeader) {
+      this.providerState[provider] = state;
+      return;
+    }
+
+    let client: ConnectedUpstreamClient | null = null;
+    try {
+      client = await this.clientFactory.connect({
+        mcpUrl: resolved.mcpUrl,
+        headers: resolved.authHeader,
+      });
+
+      const tools = await client.listTools();
+      const syncedAt = new Date().toISOString();
+      state.tools = tools;
+      state.available = true;
+      state.syncedAt = syncedAt;
+
+      persistCatalog(this.catalogDir, {
+        provider,
+        mcpUrl: resolved.mcpUrl,
+        syncedAt,
+        tools: tools.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+        })),
+      });
+    } catch (error) {
+      state.lastError = messageFromError(error);
+      state.warnings.push(
+        `${provider} upstream unavailable: ${state.lastError}`,
+      );
+      state.available = false;
+      state.tools = [];
+      logger.warn(`${provider} gateway init failed: ${state.lastError}`);
+    } finally {
+      if (client) {
+        try {
+          await client.close();
+        } catch {
+          // best-effort close
+        }
+      }
+    }
+
+    this.providerState[provider] = state;
+  }
+}

package/mcp/src/gateway/types.ts

@@ -0,0 +1,54 @@
+/**
+ * Cubis Foundry MCP Server – upstream gateway types.
+ */
+
+import type { ConfigScope } from "../cbxConfig/types.js";
+
+export type UpstreamProvider = "postman" | "stitch";
+
+export interface UpstreamTool {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+}
+
+export interface UpstreamConfig {
+  provider: UpstreamProvider;
+  mcpUrl: string | null;
+  authHeader: Record<string, string> | null;
+  authEnvVar: string | null;
+  scope: ConfigScope | null;
+  configPath: string | null;
+  warnings: string[];
+}
+
+export interface UpstreamState {
+  provider: UpstreamProvider;
+  mcpUrl: string | null;
+  authEnvVar: string | null;
+  authConfigured: boolean;
+  available: boolean;
+  warnings: string[];
+  lastError: string | null;
+  syncedAt: string | null;
+  tools: UpstreamTool[];
+}
+
+export interface GatewayStatus {
+  scope: ConfigScope | null;
+  configPath: string | null;
+  catalogDir: string;
+  generatedAt: string;
+  providers: Record<UpstreamProvider, UpstreamState>;
+}
+
+export interface CatalogPayload {
+  provider: UpstreamProvider;
+  mcpUrl: string;
+  syncedAt: string;
+  tools: Array<{
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+  }>;
+}

package/mcp/src/gateway/upstreamClient.ts

@@ -0,0 +1,80 @@
+/**
+ * Cubis Foundry MCP Server – upstream MCP client abstraction.
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { UpstreamTool } from "./types.js";
+
+export interface UpstreamCallResult {
+  content: Array<Record<string, unknown>>;
+  isError?: boolean;
+  structuredContent?: Record<string, unknown>;
+}
+
+export interface ConnectedUpstreamClient {
+  listTools(): Promise<UpstreamTool[]>;
+  callTool(toolName: string, args: Record<string, unknown>): Promise<UpstreamCallResult>;
+  close(): Promise<void>;
+}
+
+export interface UpstreamClientConnectParams {
+  mcpUrl: string;
+  headers: Record<string, string>;
+}
+
+export interface UpstreamClientFactory {
+  connect(params: UpstreamClientConnectParams): Promise<ConnectedUpstreamClient>;
+}
+
+function toObjectSchema(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as Record<string, unknown>;
+}
+
+export class SdkUpstreamClientFactory implements UpstreamClientFactory {
+  async connect(
+    params: UpstreamClientConnectParams,
+  ): Promise<ConnectedUpstreamClient> {
+    const client = new Client(
+      {
+        name: "cubis-foundry-mcp-gateway",
+        version: "0.1.0",
+      },
+      { capabilities: {} },
+    );
+
+    const transport = new StreamableHTTPClientTransport(new URL(params.mcpUrl), {
+      requestInit: {
+        headers: params.headers,
+      },
+    });
+
+    await client.connect(transport);
+
+    return {
+      async listTools(): Promise<UpstreamTool[]> {
+        const listed = await client.listTools();
+        return listed.tools.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: toObjectSchema(tool.inputSchema),
+        }));
+      },
+      async callTool(
+        toolName: string,
+        args: Record<string, unknown>,
+      ): Promise<UpstreamCallResult> {
+        return (await client.callTool({
+          name: toolName,
+          arguments: args,
+        })) as UpstreamCallResult;
+      },
+      async close(): Promise<void> {
+        await client.close();
+      },
+    };
+  }
+}

package/mcp/src/index.ts

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * Cubis Foundry MCP Server – entry point.
+ *
+ * Usage:
+ *   cubis-mcp                          # stdio (default)
+ *   cubis-mcp --transport stdio        # explicit stdio
+ *   cubis-mcp --transport http         # Streamable HTTP
+ *   cubis-mcp --scan-only              # scan vault and exit
+ */
+
+import { loadServerConfig } from "./config/index.js";
+import { scanVaultRoots } from "./vault/scanner.js";
+import { buildManifest, enrichWithDescriptions } from "./vault/manifest.js";
+import { createServer } from "./server.js";
+import { createStdioTransport } from "./transports/stdio.js";
+import { createStreamableHttpTransport } from "./transports/streamableHttp.js";
+import { logger, setLogLevel } from "./utils/logger.js";
+import {
+  parsePostmanState,
+  parseStitchState,
+  readEffectiveConfig,
+} from "./cbxConfig/index.js";
+import { urlToMode } from "./tools/postmanModes.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ─── Arg parsing ─────────────────────────────────────────────
+
+function parseArgs(argv: string[]): {
+  transport: "stdio" | "http";
+  scanOnly: boolean;
+  debug: boolean;
+  configPath?: string;
+} {
+  let transport: "stdio" | "http" = "stdio";
+  let scanOnly = false;
+  let debug = false;
+  let configPath: string | undefined;
+
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--transport" && argv[i + 1]) {
+      const val = argv[++i];
+      if (val === "http" || val === "streamable-http") {
+        transport = "http";
+      } else if (val === "stdio") {
+        transport = "stdio";
+      } else {
+        logger.error(`Unknown transport: ${val}. Use "stdio" or "http".`);
+        process.exit(1);
+      }
+    } else if (arg === "--scan-only") {
+      scanOnly = true;
+    } else if (arg === "--debug") {
+      debug = true;
+    } else if (arg === "--config" && argv[i + 1]) {
+      configPath = argv[++i];
+    }
+  }
+
+  return { transport, scanOnly, debug, configPath };
+}
+
+// ─── Startup banner ──────────────────────────────────────────
+
+function printStartupBanner(
+  skillCount: number,
+  categoryCount: number,
+  transportName: string,
+): void {
+  logger.raw("┌──────────────────────────────────────────────┐");
+  logger.raw("│  Cubis Foundry MCP Server                    │");
+  logger.raw("├──────────────────────────────────────────────┤");
+  logger.raw(`│  Vault: 2004/35/~245/~80,160/99.7%           │`);
+  logger.raw(`│  Skills loaded: ${String(skillCount).padEnd(29)}│`);
+  logger.raw(`│  Categories: ${String(categoryCount).padEnd(32)}│`);
+  logger.raw(`│  Transport: ${transportName.padEnd(33)}│`);
+  logger.raw("└──────────────────────────────────────────────┘");
+}
+
+function printConfigStatus(): void {
+  try {
+    const effective = readEffectiveConfig("auto");
+    if (!effective) {
+      logger.warn(
+        "cbx_config.json not found. Postman/Stitch tools will return config-not-found errors.",
+      );
+      return;
+    }
+
+    const config = effective.config;
+
+    // Postman status
+    const postmanState = parsePostmanState(config);
+    const postmanUrl = postmanState.mcpUrl;
+    if (postmanUrl) {
+      const mode = urlToMode(postmanUrl) ?? "unknown";
+      logger.info(`Postman mode: ${mode} (${postmanUrl})`);
+    } else {
+      logger.info("Postman: not configured");
+    }
+
+    // Stitch status
+    const stitchState = parseStitchState(config);
+    const stitchProfile = stitchState.activeProfileName;
+    if (stitchProfile && stitchState.activeProfile?.url) {
+      const url = stitchState.activeProfile.url ?? "(no URL)";
+      logger.info(`Stitch profile: ${stitchProfile} (${url})`);
+    } else {
+      logger.info("Stitch: not configured");
+    }
+
+    logger.info(`Config scope: ${effective.scope} (${effective.path})`);
+  } catch {
+    logger.warn("Failed to read cbx_config.json status");
+  }
+}
+
+// ─── Main ────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv);
+
+  if (args.debug) {
+    setLogLevel("debug");
+  }
+
+  // Load server config
+  const serverConfig = loadServerConfig(args.configPath);
+
+  // Resolve vault roots relative to the mcp package root.
+  // `index.ts` is in `<pkg>/src` during dev and `<pkg>/dist` after build.
+  const basePath = path.resolve(__dirname, "..");
+  const skills = await scanVaultRoots(serverConfig.vault.roots, basePath);
+  const manifest = buildManifest(skills);
+
+  // Enrich with descriptions for faster browse/search at runtime
+  await enrichWithDescriptions(
+    manifest.skills,
+    serverConfig.vault.summaryMaxLength,
+  );
+
+  // Scan-only mode: print and exit
+  if (args.scanOnly) {
+    logger.info(
+      `Scan complete: ${manifest.skills.length} skills in ${manifest.categories.length} categories`,
+    );
+    for (const cat of manifest.categories) {
+      const count = manifest.skills.filter((s) => s.category === cat).length;
+      logger.info(`  ${cat}: ${count} skills`);
+    }
+    process.exit(0);
+  }
+
+  // Print startup banner
+  const transportName =
+    args.transport === "http"
+      ? `Streamable HTTP :${serverConfig.transport.http?.port ?? 3100}`
+      : "stdio";
+  printStartupBanner(
+    manifest.skills.length,
+    manifest.categories.length,
+    transportName,
+  );
+  printConfigStatus();
+
+  // Create MCP server
+  const mcpServer = await createServer({ config: serverConfig, manifest });
+
+  // Connect transport
+  if (args.transport === "http") {
+    const httpOpts = {
+      port: serverConfig.transport.http?.port ?? 3100,
+      host: serverConfig.transport.http?.host ?? "127.0.0.1",
+    };
+    const { transport, httpServer } = createStreamableHttpTransport(httpOpts);
+    await mcpServer.connect(transport);
+
+    // Graceful shutdown
+    const shutdown = async () => {
+      logger.info("Shutting down HTTP transport...");
+      httpServer.close();
+      await mcpServer.close();
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  } else {
+    const transport = createStdioTransport();
+    await mcpServer.connect(transport);
+
+    // Graceful shutdown
+    const shutdown = async () => {
+      logger.info("Shutting down stdio transport...");
+      await mcpServer.close();
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  }
+
+  logger.info("MCP server ready. Waiting for connections...");
+}
+
+main().catch((err) => {
+  logger.error(`Fatal startup error: ${err}`);
+  process.exit(1);
+});