@cubis/foundry 0.3.46 → 0.3.48

package/mcp/src/tools/registry.ts

@@ -0,0 +1,318 @@
+/**
+ * Cubis Foundry MCP Server – declarative tool registry.
+ *
+ * Defines all built-in tools in a single registry array.
+ * Server.ts reads from this registry to auto-register tools,
+ * eliminating per-tool import boilerplate.
+ *
+ * When adding a new tool:
+ *   1. Create toolName.ts with name/description/schema/handler exports
+ *   2. Add a ToolRegistryEntry here
+ *   3. Done — server.ts picks it up automatically.
+ */
+
+import { z } from "zod";
+import type { VaultManifest } from "../vault/types.js";
+import type { ConfigScope } from "../cbxConfig/types.js";
+
+// ─── Core types ─────────────────────────────────────────────
+
+export type ToolCategory = "skill" | "postman" | "stitch";
+
+export interface ToolRegistryEntry {
+  /** Tool name exposed to MCP clients. */
+  name: string;
+  /** One-line description for MCP discovery. */
+  description: string;
+  /** Zod schema (the `.shape` is extracted at registration time). */
+  schema: z.ZodObject<z.ZodRawShape>;
+  /** Tool category for grouping and documentation. */
+  category: ToolCategory;
+  /**
+   * Handler factory.  Receives shared runtime context and returns the
+   * concrete async handler that server.tool() expects.
+   */
+  createHandler: (
+    ctx: ToolRuntimeContext,
+  ) => (args: unknown) => Promise<unknown>;
+}
+
+export interface ToolRuntimeContext {
+  manifest: VaultManifest;
+  charsPerToken: number;
+  summaryMaxLength: number;
+  defaultConfigScope: ConfigScope | "auto";
+}
+
+// ─── Tool imports ───────────────────────────────────────────
+
+import {
+  skillListCategoriesName,
+  skillListCategoriesDescription,
+  skillListCategoriesSchema,
+  handleSkillListCategories,
+} from "./skillListCategories.js";
+
+import {
+  skillBrowseCategoryName,
+  skillBrowseCategoryDescription,
+  skillBrowseCategorySchema,
+  handleSkillBrowseCategory,
+} from "./skillBrowseCategory.js";
+
+import {
+  skillSearchName,
+  skillSearchDescription,
+  skillSearchSchema,
+  handleSkillSearch,
+} from "./skillSearch.js";
+
+import {
+  skillGetName,
+  skillGetDescription,
+  skillGetSchema,
+  handleSkillGet,
+} from "./skillGet.js";
+
+import {
+  skillBudgetReportName,
+  skillBudgetReportDescription,
+  skillBudgetReportSchema,
+  handleSkillBudgetReport,
+} from "./skillBudgetReport.js";
+
+import {
+  postmanGetModeName,
+  postmanGetModeDescription,
+  postmanGetModeSchema,
+  handlePostmanGetMode,
+} from "./postmanGetMode.js";
+
+import {
+  postmanSetModeName,
+  postmanSetModeDescription,
+  postmanSetModeSchema,
+  handlePostmanSetMode,
+} from "./postmanSetMode.js";
+
+import {
+  postmanGetStatusName,
+  postmanGetStatusDescription,
+  postmanGetStatusSchema,
+  handlePostmanGetStatus,
+} from "./postmanGetStatus.js";
+
+import {
+  stitchGetModeName,
+  stitchGetModeDescription,
+  stitchGetModeSchema,
+  handleStitchGetMode,
+} from "./stitchGetMode.js";
+
+import {
+  stitchSetProfileName,
+  stitchSetProfileDescription,
+  stitchSetProfileSchema,
+  handleStitchSetProfile,
+} from "./stitchSetProfile.js";
+
+import {
+  stitchGetStatusName,
+  stitchGetStatusDescription,
+  stitchGetStatusSchema,
+  handleStitchGetStatus,
+} from "./stitchGetStatus.js";
+
+// ─── Scope helper ───────────────────────────────────────────
+
+function withDefaultScope(
+  args: unknown,
+  defaultScope: ConfigScope | "auto",
+): Record<string, unknown> {
+  const safeArgs =
+    args && typeof args === "object" ? (args as Record<string, unknown>) : {};
+  return {
+    ...safeArgs,
+    scope: typeof safeArgs.scope === "string" ? safeArgs.scope : defaultScope,
+  };
+}
+
+// ─── Registry ───────────────────────────────────────────────
+
+export const TOOL_REGISTRY: readonly ToolRegistryEntry[] = [
+  // ── Skill vault tools ─────────────────────────────────────
+  {
+    name: skillListCategoriesName,
+    description: skillListCategoriesDescription,
+    schema: skillListCategoriesSchema,
+    category: "skill",
+    createHandler: (ctx) => async () =>
+      handleSkillListCategories(ctx.manifest, ctx.charsPerToken),
+  },
+  {
+    name: skillBrowseCategoryName,
+    description: skillBrowseCategoryDescription,
+    schema: skillBrowseCategorySchema,
+    category: "skill",
+    createHandler: (ctx) => async (args) =>
+      handleSkillBrowseCategory(
+        args as z.infer<typeof skillBrowseCategorySchema>,
+        ctx.manifest,
+        ctx.summaryMaxLength,
+        ctx.charsPerToken,
+      ),
+  },
+  {
+    name: skillSearchName,
+    description: skillSearchDescription,
+    schema: skillSearchSchema,
+    category: "skill",
+    createHandler: (ctx) => async (args) =>
+      handleSkillSearch(
+        args as z.infer<typeof skillSearchSchema>,
+        ctx.manifest,
+        ctx.summaryMaxLength,
+        ctx.charsPerToken,
+      ),
+  },
+  {
+    name: skillGetName,
+    description: skillGetDescription,
+    schema: skillGetSchema,
+    category: "skill",
+    createHandler: (ctx) => async (args) =>
+      handleSkillGet(
+        args as z.infer<typeof skillGetSchema>,
+        ctx.manifest,
+        ctx.charsPerToken,
+      ),
+  },
+  {
+    name: skillBudgetReportName,
+    description: skillBudgetReportDescription,
+    schema: skillBudgetReportSchema,
+    category: "skill",
+    createHandler: (ctx) => async (args) =>
+      handleSkillBudgetReport(
+        args as z.infer<typeof skillBudgetReportSchema>,
+        ctx.manifest,
+        ctx.charsPerToken,
+      ),
+  },
+
+  // ── Postman tools ─────────────────────────────────────────
+  {
+    name: postmanGetModeName,
+    description: postmanGetModeDescription,
+    schema: postmanGetModeSchema,
+    category: "postman",
+    createHandler: (ctx) => async (args) =>
+      handlePostmanGetMode(
+        withDefaultScope(args, ctx.defaultConfigScope) as z.infer<
+          typeof postmanGetModeSchema
+        >,
+      ),
+  },
+  {
+    name: postmanSetModeName,
+    description: postmanSetModeDescription,
+    schema: postmanSetModeSchema,
+    category: "postman",
+    createHandler: (ctx) => async (args) =>
+      handlePostmanSetMode(
+        withDefaultScope(args, ctx.defaultConfigScope) as z.infer<
+          typeof postmanSetModeSchema
+        >,
+      ),
+  },
+  {
+    name: postmanGetStatusName,
+    description: postmanGetStatusDescription,
+    schema: postmanGetStatusSchema,
+    category: "postman",
+    createHandler: (ctx) => async (args) =>
+      handlePostmanGetStatus(
+        withDefaultScope(args, ctx.defaultConfigScope) as z.infer<
+          typeof postmanGetStatusSchema
+        >,
+      ),
+  },
+
+  // ── Stitch tools ──────────────────────────────────────────
+  {
+    name: stitchGetModeName,
+    description: stitchGetModeDescription,
+    schema: stitchGetModeSchema,
+    category: "stitch",
+    createHandler: (ctx) => async (args) =>
+      handleStitchGetMode(
+        withDefaultScope(args, ctx.defaultConfigScope) as z.infer<
+          typeof stitchGetModeSchema
+        >,
+      ),
+  },
+  {
+    name: stitchSetProfileName,
+    description: stitchSetProfileDescription,
+    schema: stitchSetProfileSchema,
+    category: "stitch",
+    createHandler: (ctx) => async (args) =>
+      handleStitchSetProfile(
+        withDefaultScope(args, ctx.defaultConfigScope) as z.infer<
+          typeof stitchSetProfileSchema
+        >,
+      ),
+  },
+  {
+    name: stitchGetStatusName,
+    description: stitchGetStatusDescription,
+    schema: stitchGetStatusSchema,
+    category: "stitch",
+    createHandler: (ctx) => async (args) =>
+      handleStitchGetStatus(
+        withDefaultScope(args, ctx.defaultConfigScope) as z.infer<
+          typeof stitchGetStatusSchema
+        >,
+      ),
+  },
+];
+
+// ─── Helpers ────────────────────────────────────────────────
+
+/** Get tools filtered by category. */
+export function getToolsByCategory(
+  category: ToolCategory,
+): ToolRegistryEntry[] {
+  return TOOL_REGISTRY.filter((t) => t.category === category);
+}
+
+/** Get all registered tool names. */
+export function getRegisteredToolNames(): string[] {
+  return TOOL_REGISTRY.map((t) => t.name);
+}
+
+/** Build a summary of the registry for documentation/rule-file generation. */
+export function buildRegistrySummary(): {
+  categories: Record<
+    string,
+    { tools: Array<{ name: string; description: string }> }
+  >;
+  totalTools: number;
+} {
+  const categories: Record<
+    string,
+    { tools: Array<{ name: string; description: string }> }
+  > = {};
+
+  for (const tool of TOOL_REGISTRY) {
+    if (!categories[tool.category]) {
+      categories[tool.category] = { tools: [] };
+    }
+    categories[tool.category].tools.push({
+      name: tool.name,
+      description: tool.description,
+    });
+  }
+
+  return { categories, totalTools: TOOL_REGISTRY.length };
+}

package/mcp/src/tools/skillGet.ts

@@ -7,8 +7,8 @@
 
 import { z } from "zod";
 import type { VaultManifest } from "../vault/types.js";
-import { readFullSkillContent } from "../vault/manifest.js";
-import { notFound } from "../utils/errors.js";
+import { readSkillContentWithReferences } from "../vault/manifest.js";
+import { invalidInput, notFound } from "../utils/errors.js";
 import {
   buildSkillToolMetrics,
   estimateTokensFromText,
@@ -17,10 +17,16 @@ import {
 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.";
+  "Get full content of a specific skill by ID. Returns SKILL.md content and optionally direct referenced markdown files.";
 
 export const skillGetSchema = z.object({
   id: z.string().describe("The skill ID (directory name) to retrieve"),
+  includeReferences: z
+    .boolean()
+    .optional()
+    .describe(
+      "Whether to include direct local markdown references from SKILL.md (default: true)",
+    ),
 });
 
 export async function handleSkillGet(
@@ -28,14 +34,38 @@ export async function handleSkillGet(
   manifest: VaultManifest,
   charsPerToken: number,
 ) {
-  const { id } = args;
+  const { id, includeReferences = true } = args;
+
+  if (id.startsWith("workflow-") || id.startsWith("agent-")) {
+    invalidInput(
+      `Skill id "${id}" appears to be a wrapper id. Use workflow/agent routing (for example $workflow-implement-track or $agent-backend-specialist) and call skill_get only for concrete skill ids.`,
+    );
+  }
 
   const skill = manifest.skills.find((s) => s.id === id);
   if (!skill) {
     notFound("Skill", id);
   }
 
-  const content = await readFullSkillContent(skill.path);
+  const { skillContent, references } = await readSkillContentWithReferences(
+    skill.path,
+    includeReferences,
+  );
+  const referenceSection =
+    references.length > 0
+      ? [
+          "",
+          "## Referenced Files",
+          "",
+          ...references.flatMap((ref) => [
+            `### ${ref.relativePath}`,
+            "",
+            ref.content.trimEnd(),
+            "",
+          ]),
+        ].join("\n")
+      : "";
+  const content = `${skillContent}${referenceSection}`;
   const loadedSkillEstimatedTokens = estimateTokensFromText(
     content,
     charsPerToken,
@@ -55,6 +85,7 @@ export async function handleSkillGet(
       },
     ],
     structuredContent: {
+      references: references.map((ref) => ({ path: ref.relativePath })),
       metrics,
     },
   };

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { mkdtempSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import type { VaultManifest } from "../vault/types.js";
@@ -147,6 +147,134 @@ describe("skill tools", () => {
     expect(toolMetrics.loadedSkillEstimatedTokens).toBeGreaterThan(0);
   });
 
+  it("includes referenced markdown files in skill_get by default", async () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), "mcp-skill-ref-default-"));
+    const skillFile = path.join(dir, "SKILL.md");
+    const referencesDir = path.join(dir, "references");
+    mkdirSync(referencesDir, { recursive: true });
+    writeFileSync(
+      skillFile,
+      [
+        "---",
+        "name: referenced-skill",
+        "description: skill with refs",
+        "---",
+        "# Skill",
+        "See [Guide](references/guide.md).",
+      ].join("\n"),
+      "utf8",
+    );
+    writeFileSync(
+      path.join(referencesDir, "guide.md"),
+      "# Guide\nReferenced content",
+      "utf8",
+    );
+
+    const skillBytes = statSync(skillFile).size;
+    const manifest: VaultManifest = {
+      categories: ["general"],
+      skills: [
+        {
+          id: "referenced-skill",
+          category: "general",
+          path: skillFile,
+          fileBytes: skillBytes,
+        },
+      ],
+      fullCatalogBytes: skillBytes,
+      fullCatalogEstimatedTokens: Math.ceil(skillBytes / 4),
+    };
+
+    const result = await handleSkillGet({ id: "referenced-skill" }, manifest, 4);
+    expect(result.content[0].text).toContain("## Referenced Files");
+    expect(result.content[0].text).toContain("### references/guide.md");
+    expect(result.content[0].text).toContain("Referenced content");
+  });
+
+  it("skips referenced markdown files when includeReferences is false", async () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), "mcp-skill-ref-skip-"));
+    const skillFile = path.join(dir, "SKILL.md");
+    const referencesDir = path.join(dir, "references");
+    mkdirSync(referencesDir, { recursive: true });
+    writeFileSync(
+      skillFile,
+      [
+        "---",
+        "name: referenced-skill-no-refs",
+        "description: skill with refs",
+        "---",
+        "# Skill",
+        "See [Guide](references/guide.md).",
+      ].join("\n"),
+      "utf8",
+    );
+    writeFileSync(path.join(referencesDir, "guide.md"), "# Guide", "utf8");
+
+    const skillBytes = statSync(skillFile).size;
+    const manifest: VaultManifest = {
+      categories: ["general"],
+      skills: [
+        {
+          id: "referenced-skill-no-refs",
+          category: "general",
+          path: skillFile,
+          fileBytes: skillBytes,
+        },
+      ],
+      fullCatalogBytes: skillBytes,
+      fullCatalogEstimatedTokens: Math.ceil(skillBytes / 4),
+    };
+
+    const result = await handleSkillGet(
+      { id: "referenced-skill-no-refs", includeReferences: false },
+      manifest,
+      4,
+    );
+    expect(result.content[0].text).not.toContain("## Referenced Files");
+    expect(result.content[0].text).not.toContain("### references/guide.md");
+  });
+
+  it("loads sibling markdown files when SKILL.md has no explicit links", async () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), "mcp-skill-ref-fallback-"));
+    const skillFile = path.join(dir, "SKILL.md");
+    writeFileSync(
+      skillFile,
+      [
+        "---",
+        "name: sibling-fallback-skill",
+        "description: fallback sibling",
+        "---",
+        "# Skill",
+      ].join("\n"),
+      "utf8",
+    );
+    writeFileSync(path.join(dir, "overview.md"), "# Overview\nSibling", "utf8");
+
+    const skillBytes = statSync(skillFile).size;
+    const manifest: VaultManifest = {
+      categories: ["general"],
+      skills: [
+        {
+          id: "sibling-fallback-skill",
+          category: "general",
+          path: skillFile,
+          fileBytes: skillBytes,
+        },
+      ],
+      fullCatalogBytes: skillBytes,
+      fullCatalogEstimatedTokens: Math.ceil(skillBytes / 4),
+    };
+
+    const result = await handleSkillGet(
+      { id: "sibling-fallback-skill" },
+      manifest,
+      4,
+    );
+    expect(result.content[0].text).toContain("## Referenced Files");
+    expect(result.content[0].text).toContain("### overview.md");
+    expect(result.content[0].text).toContain("Sibling");
+  });
+
   it("throws when skill_get cannot find the requested skill", async () => {
     const manifest = createManifest();
     await expect(handleSkillGet({ id: "missing" }, manifest, 4)).rejects.toThrow(
@@ -154,6 +282,20 @@ describe("skill tools", () => {
     );
   });
 
+  it("throws a wrapper guidance error when skill_get receives workflow id", async () => {
+    const manifest = createManifest();
+    await expect(
+      handleSkillGet({ id: "workflow-implement-track" }, manifest, 4),
+    ).rejects.toThrow("appears to be a wrapper id");
+  });
+
+  it("throws a wrapper guidance error when skill_get receives agent id", async () => {
+    const manifest = createManifest();
+    await expect(
+      handleSkillGet({ id: "agent-backend-specialist" }, manifest, 4),
+    ).rejects.toThrow("appears to be a wrapper id");
+  });
+
   it("returns consolidated budget rollup for selected and loaded skills", () => {
     const manifest = createManifest();
     const result = handleSkillBudgetReport(

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

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it } from "vitest";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import {
@@ -8,6 +8,7 @@ import {
   extractDescription,
   parseDescriptionFromFrontmatter,
   readFullSkillContent,
+  readSkillContentWithReferences,
 } from "./manifest.js";
 
 const tempDirs: string[] = [];
@@ -90,6 +91,75 @@ describe("skill content IO", () => {
 
     await expect(readFullSkillContent(file)).resolves.toBe(body);
   });
+
+  it("loads direct local markdown references from SKILL.md", async () => {
+    const dir = createTempDir("mcp-refs-read-");
+    const file = path.join(dir, "SKILL.md");
+    const refsDir = path.join(dir, "references");
+    const refFile = path.join(refsDir, "guide.md");
+    const nestedRefFile = path.join(dir, "notes.md");
+
+    writeFileSync(
+      file,
+      [
+        "---",
+        "name: ref-read",
+        "description: Read refs",
+        "---",
+        "# Skill",
+        "See [Guide](references/guide.md).",
+        "See [Notes](notes.md#section).",
+        "Ignore [External](https://example.com).",
+      ].join("\n"),
+      "utf8",
+    );
+    mkdirSync(refsDir, { recursive: true });
+    writeFileSync(refFile, "# Guide\nReference body", "utf8");
+    writeFileSync(nestedRefFile, "# Notes\nMore details", "utf8");
+
+    const result = await readSkillContentWithReferences(file, true);
+    expect(result.skillContent).toContain("# Skill");
+    expect(result.references).toEqual([
+      { relativePath: "references/guide.md", content: "# Guide\nReference body" },
+      { relativePath: "notes.md", content: "# Notes\nMore details" },
+    ]);
+  });
+
+  it("skips references when includeReferences is false", async () => {
+    const dir = createTempDir("mcp-refs-skip-");
+    const file = path.join(dir, "SKILL.md");
+    const refFile = path.join(dir, "reference.md");
+    writeFileSync(
+      file,
+      ["---", "name: skip", "description: skip", "---", "[Ref](reference.md)"].join(
+        "\n",
+      ),
+      "utf8",
+    );
+    writeFileSync(refFile, "ref", "utf8");
+
+    const result = await readSkillContentWithReferences(file, false);
+    expect(result.references).toEqual([]);
+  });
+
+  it("falls back to sibling markdown files when SKILL.md has no links", async () => {
+    const dir = createTempDir("mcp-refs-fallback-");
+    const file = path.join(dir, "SKILL.md");
+    const siblingRef = path.join(dir, "overview.md");
+    writeFileSync(
+      file,
+      ["---", "name: fallback", "description: fallback", "---", "# Skill"].join(
+        "\n",
+      ),
+      "utf8",
+    );
+    writeFileSync(siblingRef, "# Overview\nSibling content", "utf8");
+
+    const result = await readSkillContentWithReferences(file, true);
+    expect(result.references).toEqual([
+      { relativePath: "overview.md", content: "# Overview\nSibling content" },
+    ]);
+  });
 });
 
 describe("manifest enrichment", () => {