@cubis/foundry 0.3.33 → 0.3.35

package/mcp/src/tools/postmanModes.ts

@@ -0,0 +1,28 @@
+/**
+ * Cubis Foundry MCP Server – Postman mode mapping.
+ *
+ * Maps friendly mode names to Postman MCP URLs and back.
+ */
+
+export const POSTMAN_MODES = {
+  minimal: "https://mcp.postman.com/minimal",
+  code: "https://mcp.postman.com/code",
+  full: "https://mcp.postman.com/mcp",
+} as const;
+
+export type PostmanMode = keyof typeof POSTMAN_MODES;
+
+const URL_TO_MODE = new Map<string, PostmanMode>(
+  Object.entries(POSTMAN_MODES).map(([mode, url]) => [
+    url,
+    mode as PostmanMode,
+  ]),
+);
+
+export function urlToMode(url: string): PostmanMode | undefined {
+  return URL_TO_MODE.get(url);
+}
+
+export function isValidMode(mode: string): mode is PostmanMode {
+  return mode in POSTMAN_MODES;
+}

package/mcp/src/tools/postmanSetMode.ts

@@ -0,0 +1,71 @@
+/**
+ * Cubis Foundry MCP Server – postman_set_mode tool.
+ *
+ * Sets the Postman MCP mode in cbx_config.json.
+ */
+
+import { z } from "zod";
+import { writeConfigField } from "../cbxConfig/index.js";
+import type { ConfigScope } from "../cbxConfig/types.js";
+import { invalidInput } from "../utils/errors.js";
+import {
+  isValidMode,
+  POSTMAN_MODES,
+  type PostmanMode,
+} from "./postmanModes.js";
+
+export const postmanSetModeName = "postman_set_mode";
+
+export const postmanSetModeDescription =
+  "Set the Postman MCP mode in cbx_config.json. Modes: minimal, code, full.";
+
+export const postmanSetModeSchema = z.object({
+  mode: z
+    .enum(["minimal", "code", "full"])
+    .describe("Postman MCP mode to set: minimal, code, or full"),
+  scope: z
+    .enum(["global", "project", "auto"])
+    .optional()
+    .describe(
+      "Config scope to write. Default: auto (project if exists, else global)",
+    ),
+});
+
+export function handlePostmanSetMode(
+  args: z.infer<typeof postmanSetModeSchema>,
+) {
+  const { mode } = args;
+  const scope = args.scope ?? "auto";
+
+  if (!isValidMode(mode)) {
+    invalidInput(
+      `Invalid Postman mode: "${mode}". Valid modes: minimal, code, full`,
+    );
+  }
+
+  const url = POSTMAN_MODES[mode as PostmanMode];
+  const result = writeConfigField(
+    "postman.mcpUrl",
+    url,
+    scope as ConfigScope | "auto",
+  );
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            mode,
+            url,
+            scope: result.scope,
+            writtenPath: result.writtenPath,
+            note: "Postman MCP mode updated. Restart your MCP client to pick up the change.",
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}

package/mcp/src/tools/skillBrowseCategory.ts

@@ -0,0 +1,54 @@
+/**
+ * Cubis Foundry MCP Server – skill_browse_category tool.
+ *
+ * Returns all skills in a given category with truncated descriptions.
+ */
+
+import { z } from "zod";
+import type { VaultManifest } from "../vault/types.js";
+import { enrichWithDescriptions } from "../vault/manifest.js";
+import { notFound } from "../utils/errors.js";
+
+export const skillBrowseCategoryName = "skill_browse_category";
+
+export const skillBrowseCategoryDescription =
+  "Browse skills within a specific category. Returns skill IDs and short descriptions.";
+
+export const skillBrowseCategorySchema = z.object({
+  category: z
+    .string()
+    .describe("The category name to browse (from skill_list_categories)"),
+});
+
+export async function handleSkillBrowseCategory(
+  args: z.infer<typeof skillBrowseCategorySchema>,
+  manifest: VaultManifest,
+  summaryMaxLength: number,
+) {
+  const { category } = args;
+
+  if (!manifest.categories.includes(category)) {
+    notFound("Category", category);
+  }
+
+  const matching = manifest.skills.filter((s) => s.category === category);
+  const enriched = await enrichWithDescriptions(matching, summaryMaxLength);
+
+  const skills = enriched.map((s) => ({
+    id: s.id,
+    description: s.description ?? "(no description)",
+  }));
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          { category, skills, count: skills.length },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}

package/mcp/src/tools/skillGet.ts

@@ -0,0 +1,43 @@
+/**
+ * Cubis Foundry MCP Server – skill_get tool.
+ *
+ * Returns the FULL content of a specific skill's SKILL.md file.
+ * This is the ONLY tool that reads full file content (lazy model).
+ */
+
+import { z } from "zod";
+import type { VaultManifest } from "../vault/types.js";
+import { readFullSkillContent } from "../vault/manifest.js";
+import { notFound } from "../utils/errors.js";
+
+export const skillGetName = "skill_get";
+
+export const skillGetDescription =
+  "Get the full content of a specific skill by ID. Returns the complete SKILL.md file content.";
+
+export const skillGetSchema = z.object({
+  id: z.string().describe("The skill ID (directory name) to retrieve"),
+});
+
+export async function handleSkillGet(
+  args: z.infer<typeof skillGetSchema>,
+  manifest: VaultManifest,
+) {
+  const { id } = args;
+
+  const skill = manifest.skills.find((s) => s.id === id);
+  if (!skill) {
+    notFound("Skill", id);
+  }
+
+  const content = await readFullSkillContent(skill.path);
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: content,
+      },
+    ],
+  };
+}

package/mcp/src/tools/skillListCategories.ts

@@ -0,0 +1,40 @@
+/**
+ * Cubis Foundry MCP Server – skill_list_categories tool.
+ *
+ * Returns all discovered skill categories from the vault manifest.
+ */
+
+import { z } from "zod";
+import type { VaultManifest } from "../vault/types.js";
+
+export const skillListCategoriesName = "skill_list_categories";
+
+export const skillListCategoriesDescription =
+  "List all skill categories available in the vault. Returns category names and skill counts.";
+
+export const skillListCategoriesSchema = z.object({});
+
+export function handleSkillListCategories(manifest: VaultManifest) {
+  const categoryCounts: Record<string, number> = {};
+  for (const skill of manifest.skills) {
+    categoryCounts[skill.category] = (categoryCounts[skill.category] ?? 0) + 1;
+  }
+
+  const categories = manifest.categories.map((cat) => ({
+    category: cat,
+    skillCount: categoryCounts[cat] ?? 0,
+  }));
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          { categories, totalSkills: manifest.skills.length },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}

package/mcp/src/tools/skillSearch.ts

@@ -0,0 +1,72 @@
+/**
+ * Cubis Foundry MCP Server – skill_search tool.
+ *
+ * Full-text search across skill IDs and descriptions.
+ * Returns matching skills with truncated descriptions.
+ */
+
+import { z } from "zod";
+import type { VaultManifest } from "../vault/types.js";
+import { enrichWithDescriptions } from "../vault/manifest.js";
+
+export const skillSearchName = "skill_search";
+
+export const skillSearchDescription =
+  "Search skills by keyword. Matches against skill IDs and descriptions. Returns matching skills with short descriptions.";
+
+export const skillSearchSchema = z.object({
+  query: z
+    .string()
+    .min(1)
+    .describe(
+      "Search keyword or phrase to match against skill IDs and descriptions",
+    ),
+});
+
+export async function handleSkillSearch(
+  args: z.infer<typeof skillSearchSchema>,
+  manifest: VaultManifest,
+  summaryMaxLength: number,
+) {
+  const { query } = args;
+  const lower = query.toLowerCase();
+
+  // First pass: match by ID
+  let matches = manifest.skills.filter((s) =>
+    s.id.toLowerCase().includes(lower),
+  );
+
+  // Second pass: also search descriptions if needed (enrich all, then filter)
+  if (matches.length === 0) {
+    const enriched = await enrichWithDescriptions(
+      manifest.skills,
+      summaryMaxLength,
+    );
+    matches = enriched.filter(
+      (s) =>
+        s.id.toLowerCase().includes(lower) ||
+        (s.description && s.description.toLowerCase().includes(lower)),
+    );
+  } else {
+    matches = await enrichWithDescriptions(matches, summaryMaxLength);
+  }
+
+  const results = matches.map((s) => ({
+    id: s.id,
+    category: s.category,
+    description: s.description ?? "(no description)",
+  }));
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          { query, results, count: results.length },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}

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

@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { VaultManifest } from "../vault/types.js";
+import { handleSkillBrowseCategory } from "./skillBrowseCategory.js";
+import { handleSkillGet } from "./skillGet.js";
+import { handleSkillListCategories } from "./skillListCategories.js";
+import { handleSkillSearch } from "./skillSearch.js";
+
+function payload(result: { content: Array<{ text: string }> }): Record<string, unknown> {
+  return JSON.parse(result.content[0].text) as Record<string, unknown>;
+}
+
+function createSkillFile(id: string, description: string, body = "# Content"): string {
+  const dir = mkdtempSync(path.join(os.tmpdir(), `mcp-skill-${id}-`));
+  const file = path.join(dir, "SKILL.md");
+  writeFileSync(
+    file,
+    `---\nname: ${id}\ndescription: ${description}\n---\n${body}\n`,
+    "utf8",
+  );
+  return file;
+}
+
+function createManifest(): VaultManifest {
+  const reactFile = createSkillFile(
+    "react-expert",
+    "React performance and architecture guidance",
+  );
+  const fastapiFile = createSkillFile(
+    "fastapi-expert",
+    "FastAPI async backend patterns",
+  );
+
+  return {
+    categories: ["backend", "frontend"],
+    skills: [
+      { id: "react-expert", category: "frontend", path: reactFile },
+      { id: "fastapi-expert", category: "backend", path: fastapiFile },
+    ],
+  };
+}
+
+describe("skill tools", () => {
+  it("lists categories with skill counts", () => {
+    const manifest = createManifest();
+    const result = handleSkillListCategories(manifest);
+    const data = payload(result);
+
+    expect(data.totalSkills).toBe(2);
+    expect(data.categories).toEqual([
+      { category: "backend", skillCount: 1 },
+      { category: "frontend", skillCount: 1 },
+    ]);
+  });
+
+  it("browses a category with enriched descriptions", async () => {
+    const manifest = createManifest();
+    const result = await handleSkillBrowseCategory(
+      { category: "frontend" },
+      manifest,
+      200,
+    );
+    const data = payload(result);
+
+    expect(data.category).toBe("frontend");
+    expect(data.count).toBe(1);
+    expect(data.skills).toEqual([
+      {
+        id: "react-expert",
+        description: "React performance and architecture guidance",
+      },
+    ]);
+  });
+
+  it("throws when browsing an unknown category", async () => {
+    const manifest = createManifest();
+    await expect(
+      handleSkillBrowseCategory({ category: "mobile" }, manifest, 200),
+    ).rejects.toThrow('Category not found: "mobile"');
+  });
+
+  it("searches by skill id and by description fallback", async () => {
+    const manifest = createManifest();
+
+    const byId = payload(
+      await handleSkillSearch({ query: "react" }, manifest, 200),
+    );
+    expect(byId.count).toBe(1);
+    expect(byId.results).toEqual([
+      {
+        id: "react-expert",
+        category: "frontend",
+        description: "React performance and architecture guidance",
+      },
+    ]);
+
+    const byDescription = payload(
+      await handleSkillSearch({ query: "async backend" }, manifest, 200),
+    );
+    expect(byDescription.count).toBe(1);
+    expect(byDescription.results).toEqual([
+      {
+        id: "fastapi-expert",
+        category: "backend",
+        description: "FastAPI async backend patterns",
+      },
+    ]);
+  });
+
+  it("returns full skill content for skill_get", async () => {
+    const manifest = createManifest();
+    const result = await handleSkillGet({ id: "react-expert" }, manifest);
+
+    expect(result.content[0].text).toContain("# Content");
+    expect(result.content[0].text).toContain("description: React performance");
+  });
+
+  it("throws when skill_get cannot find the requested skill", async () => {
+    const manifest = createManifest();
+    await expect(handleSkillGet({ id: "missing" }, manifest)).rejects.toThrow(
+      'Skill not found: "missing"',
+    );
+  });
+});

package/mcp/src/tools/stitchGetMode.ts

@@ -0,0 +1,58 @@
+/**
+ * Cubis Foundry MCP Server – stitch_get_mode tool.
+ *
+ * Reads the active Stitch profile and its URL from cbx_config.json.
+ * Never exposes apiKey.
+ */
+
+import { z } from "zod";
+import { parseStitchState, readEffectiveConfig } from "../cbxConfig/index.js";
+import type { ConfigScope } from "../cbxConfig/types.js";
+import { configNotFound } from "../utils/errors.js";
+
+export const stitchGetModeName = "stitch_get_mode";
+
+export const stitchGetModeDescription =
+  "Get the active Stitch profile name and URL from cbx_config.json. Never exposes API keys.";
+
+export const stitchGetModeSchema = z.object({
+  scope: z
+    .enum(["global", "project", "auto"])
+    .optional()
+    .describe(
+      "Config scope to read. Default: auto (project if exists, else global)",
+    ),
+});
+
+export function handleStitchGetMode(args: z.infer<typeof stitchGetModeSchema>) {
+  const scope = args.scope ?? "auto";
+  const effective = readEffectiveConfig(scope as ConfigScope | "auto");
+
+  if (!effective) {
+    configNotFound();
+  }
+
+  const stitch = parseStitchState(effective.config);
+  const activeProfileName = stitch.activeProfileName;
+  const profileNames = stitch.profiles.map((profile) => profile.name);
+  const activeUrl = stitch.activeProfile?.url ?? null;
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            activeProfileName,
+            activeUrl,
+            availableProfiles: profileNames,
+            scope: effective.scope,
+            note: "API keys are never exposed through this tool.",
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}

package/mcp/src/tools/stitchGetStatus.ts

@@ -0,0 +1,70 @@
+/**
+ * Cubis Foundry MCP Server – stitch_get_status tool.
+ *
+ * Returns full Stitch configuration status.
+ * Never exposes apiKey values.
+ */
+
+import { z } from "zod";
+import { parseStitchState, readEffectiveConfig } from "../cbxConfig/index.js";
+import type { ConfigScope } from "../cbxConfig/types.js";
+import { configNotFound } from "../utils/errors.js";
+
+export const stitchGetStatusName = "stitch_get_status";
+
+export const stitchGetStatusDescription =
+  "Get full Stitch configuration status including active profile, all profile names, and URLs. Never exposes API keys.";
+
+export const stitchGetStatusSchema = z.object({
+  scope: z
+    .enum(["global", "project", "auto"])
+    .optional()
+    .describe(
+      "Config scope to read. Default: auto (project if exists, else global)",
+    ),
+});
+
+export function handleStitchGetStatus(
+  args: z.infer<typeof stitchGetStatusSchema>,
+) {
+  const scope = args.scope ?? "auto";
+  const effective = readEffectiveConfig(scope as ConfigScope | "auto");
+
+  if (!effective) {
+    configNotFound();
+  }
+
+  const stitch = parseStitchState(effective.config);
+  const activeProfileName = stitch.activeProfileName;
+  const profileSummaries = stitch.profiles.map((profile) => ({
+    name: profile.name,
+    url: profile.url ?? null,
+    apiKeyEnvVar: profile.apiKeyEnvVar,
+    hasApiKey: profile.hasInlineApiKey,
+    hasInlineApiKey: profile.hasInlineApiKey,
+    isActive: profile.name === activeProfileName,
+  }));
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            configured: profileSummaries.length > 0,
+            activeProfileName,
+            profiles: profileSummaries,
+            totalProfiles: profileSummaries.length,
+            mcpUrl: stitch.mcpUrl,
+            useSystemGcloud: Boolean(stitch.useSystemGcloud),
+            scope: effective.scope,
+            configPath: effective.path,
+            note: "API keys are never exposed. Env-var aliases are reported for runtime configuration.",
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}

package/mcp/src/tools/stitchSetProfile.ts

@@ -0,0 +1,82 @@
+/**
+ * Cubis Foundry MCP Server – stitch_set_profile tool.
+ *
+ * Sets the active Stitch profile in cbx_config.json.
+ * Only mutates `stitch.activeProfileName`, never touches apiKey.
+ */
+
+import { z } from "zod";
+import {
+  parseStitchState,
+  readEffectiveConfig,
+  writeConfigField,
+} from "../cbxConfig/index.js";
+import type { ConfigScope } from "../cbxConfig/types.js";
+import { configNotFound, invalidInput } from "../utils/errors.js";
+
+export const stitchSetProfileName = "stitch_set_profile";
+
+export const stitchSetProfileDescription =
+  "Set the active Stitch profile in cbx_config.json. The profile must already exist in the config.";
+
+export const stitchSetProfileSchema = z.object({
+  profileName: z
+    .string()
+    .min(1)
+    .describe("Name of the Stitch profile to activate"),
+  scope: z
+    .enum(["global", "project", "auto"])
+    .optional()
+    .describe(
+      "Config scope to write. Default: auto (project if exists, else global)",
+    ),
+});
+
+export function handleStitchSetProfile(
+  args: z.infer<typeof stitchSetProfileSchema>,
+) {
+  const { profileName } = args;
+  const scope = args.scope ?? "auto";
+
+  // Verify profile exists in config
+  const effective = readEffectiveConfig(scope as ConfigScope | "auto");
+  if (!effective) {
+    configNotFound();
+  }
+
+  const stitch = parseStitchState(effective.config);
+  const profileNames = stitch.profiles.map((profile) => profile.name);
+  const targetProfile =
+    stitch.profiles.find((profile) => profile.name === profileName) ?? null;
+
+  if (!targetProfile) {
+    invalidInput(
+      `Stitch profile "${profileName}" not found. Available profiles: ${profileNames.join(", ") || "(none)"}`,
+    );
+  }
+
+  const result = writeConfigField(
+    "stitch.activeProfileName",
+    profileName,
+    scope as ConfigScope | "auto",
+  );
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(
+          {
+            activeProfileName: profileName,
+            url: targetProfile.url ?? null,
+            scope: result.scope,
+            writtenPath: result.writtenPath,
+            note: "Stitch active profile updated. Restart your MCP client to pick up the change.",
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  };
+}

package/mcp/src/transports/stdio.ts

@@ -0,0 +1,9 @@
+/**
+ * Cubis Foundry MCP Server – stdio transport adapter.
+ */
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+export function createStdioTransport(): StdioServerTransport {
+  return new StdioServerTransport();
+}