@cubis/foundry 0.3.40 → 0.3.42

package/mcp/src/index.ts

@@ -6,6 +6,8 @@
  *   cubis-mcp                          # stdio (default)
  *   cubis-mcp --transport stdio        # explicit stdio
  *   cubis-mcp --transport http         # Streamable HTTP
+ *   cubis-mcp --scope global           # default config scope for built-in config tools
+ *   cubis-mcp --host 0.0.0.0 --port 3100
  *   cubis-mcp --scan-only              # scan vault and exit
  */
 
@@ -31,13 +33,19 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 function parseArgs(argv: string[]): {
   transport: "stdio" | "http";
+  scope: "auto" | "global" | "project";
   scanOnly: boolean;
   debug: boolean;
+  port?: number;
+  host?: string;
   configPath?: string;
 } {
   let transport: "stdio" | "http" = "stdio";
+  let scope: "auto" | "global" | "project" = "auto";
   let scanOnly = false;
   let debug = false;
+  let port: number | undefined;
+  let host: string | undefined;
   let configPath: string | undefined;
 
   for (let i = 2; i < argv.length; i++) {
@@ -52,6 +60,23 @@ function parseArgs(argv: string[]): {
         logger.error(`Unknown transport: ${val}. Use "stdio" or "http".`);
         process.exit(1);
       }
+    } else if (arg === "--scope" && argv[i + 1]) {
+      const val = argv[++i];
+      if (val === "auto" || val === "global" || val === "project") {
+        scope = val;
+      } else {
+        logger.error(`Unknown scope: ${val}. Use "auto", "global", or "project".`);
+        process.exit(1);
+      }
+    } else if (arg === "--port" && argv[i + 1]) {
+      const val = Number.parseInt(argv[++i], 10);
+      if (!Number.isInteger(val) || val <= 0 || val > 65535) {
+        logger.error(`Invalid port: ${argv[i]}. Use an integer from 1 to 65535.`);
+        process.exit(1);
+      }
+      port = val;
+    } else if (arg === "--host" && argv[i + 1]) {
+      host = argv[++i];
     } else if (arg === "--scan-only") {
       scanOnly = true;
     } else if (arg === "--debug") {
@@ -61,7 +86,7 @@ function parseArgs(argv: string[]): {
     }
   }
 
-  return { transport, scanOnly, debug, configPath };
+  return { transport, scope, scanOnly, debug, port, host, configPath };
 }
 
 // ─── Startup banner ──────────────────────────────────────────
@@ -81,9 +106,9 @@ function printStartupBanner(
   logger.raw("└──────────────────────────────────────────────┘");
 }
 
-function printConfigStatus(): void {
+function printConfigStatus(scope: "auto" | "global" | "project"): void {
   try {
-    const effective = readEffectiveConfig("auto");
+    const effective = readEffectiveConfig(scope);
     if (!effective) {
       logger.warn(
         "cbx_config.json not found. Postman/Stitch tools will return config-not-found errors.",
@@ -135,7 +160,8 @@ async function main(): Promise<void> {
   // `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);
+  const charsPerToken = serverConfig.telemetry.charsPerToken;
+  const manifest = buildManifest(skills, charsPerToken);
 
   // Enrich with descriptions for faster browse/search at runtime
   await enrichWithDescriptions(
@@ -156,25 +182,30 @@ async function main(): Promise<void> {
   }
 
   // Print startup banner
+  const resolvedHttpPort = args.port ?? serverConfig.transport.http?.port ?? 3100;
   const transportName =
     args.transport === "http"
-      ? `Streamable HTTP :${serverConfig.transport.http?.port ?? 3100}`
+      ? `Streamable HTTP :${resolvedHttpPort}`
       : "stdio";
   printStartupBanner(
     manifest.skills.length,
     manifest.categories.length,
     transportName,
   );
-  printConfigStatus();
+  printConfigStatus(args.scope);
 
   // Create MCP server
-  const mcpServer = await createServer({ config: serverConfig, manifest });
+  const mcpServer = await createServer({
+    config: serverConfig,
+    manifest,
+    defaultConfigScope: args.scope,
+  });
 
   // Connect transport
   if (args.transport === "http") {
     const httpOpts = {
-      port: serverConfig.transport.http?.port ?? 3100,
-      host: serverConfig.transport.http?.host ?? "127.0.0.1",
+      port: resolvedHttpPort,
+      host: args.host ?? serverConfig.transport.http?.host ?? "127.0.0.1",
     };
     const { transport, httpServer } = createStreamableHttpTransport(httpOpts);
     await mcpServer.connect(transport);

package/mcp/src/server.ts

@@ -8,6 +8,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import type { ServerConfig } from "./config/schema.js";
+import type { ConfigScope } from "./cbxConfig/types.js";
 import type { VaultManifest } from "./vault/types.js";
 import {
   // Skill tools
@@ -27,6 +28,10 @@ import {
   skillGetDescription,
   skillGetSchema,
   handleSkillGet,
+  skillBudgetReportName,
+  skillBudgetReportDescription,
+  skillBudgetReportSchema,
+  handleSkillBudgetReport,
   // Postman tools
   postmanGetModeName,
   postmanGetModeDescription,
@@ -62,6 +67,7 @@ import {
 export interface CreateServerOptions {
   config: ServerConfig;
   manifest: VaultManifest;
+  defaultConfigScope?: ConfigScope | "auto";
 }
 
 function toolCallErrorResult({
@@ -95,6 +101,7 @@ function toolCallErrorResult({
 export async function createServer({
   config,
   manifest,
+  defaultConfigScope = "auto",
 }: CreateServerOptions): McpServer {
   const server = new McpServer({
     name: config.server.name,
@@ -102,6 +109,17 @@ export async function createServer({
   });
 
   const maxLen = config.vault.summaryMaxLength;
+  const charsPerToken = config.telemetry?.charsPerToken ?? 4;
+  const withDefaultScope = (
+    args: Record<string, unknown> | undefined,
+  ): Record<string, unknown> => {
+    const safeArgs = args ?? {};
+    return {
+      ...safeArgs,
+      scope:
+        typeof safeArgs.scope === "string" ? safeArgs.scope : defaultConfigScope,
+    };
+  };
 
   // ─── Skill vault tools ───────────────────────────────────────
 
@@ -109,28 +127,36 @@ export async function createServer({
     skillListCategoriesName,
     skillListCategoriesDescription,
     skillListCategoriesSchema.shape,
-    async () => handleSkillListCategories(manifest),
+    async () => handleSkillListCategories(manifest, charsPerToken),
   );
 
   server.tool(
     skillBrowseCategoryName,
     skillBrowseCategoryDescription,
     skillBrowseCategorySchema.shape,
-    async (args) => handleSkillBrowseCategory(args, manifest, maxLen),
+    async (args) =>
+      handleSkillBrowseCategory(args, manifest, maxLen, charsPerToken),
   );
 
   server.tool(
     skillSearchName,
     skillSearchDescription,
     skillSearchSchema.shape,
-    async (args) => handleSkillSearch(args, manifest, maxLen),
+    async (args) => handleSkillSearch(args, manifest, maxLen, charsPerToken),
   );
 
   server.tool(
     skillGetName,
     skillGetDescription,
     skillGetSchema.shape,
-    async (args) => handleSkillGet(args, manifest),
+    async (args) => handleSkillGet(args, manifest, charsPerToken),
+  );
+
+  server.tool(
+    skillBudgetReportName,
+    skillBudgetReportDescription,
+    skillBudgetReportSchema.shape,
+    async (args) => handleSkillBudgetReport(args, manifest, charsPerToken),
   );
 
   // ─── Postman tools ──────────────────────────────────────────
@@ -139,21 +165,36 @@ export async function createServer({
     postmanGetModeName,
     postmanGetModeDescription,
     postmanGetModeSchema.shape,
-    async (args) => handlePostmanGetMode(args),
+    async (args) =>
+      handlePostmanGetMode(
+        withDefaultScope(args as Record<string, unknown>) as z.infer<
+          typeof postmanGetModeSchema
+        >,
+      ),
   );
 
   server.tool(
     postmanSetModeName,
     postmanSetModeDescription,
     postmanSetModeSchema.shape,
-    async (args) => handlePostmanSetMode(args),
+    async (args) =>
+      handlePostmanSetMode(
+        withDefaultScope(args as Record<string, unknown>) as z.infer<
+          typeof postmanSetModeSchema
+        >,
+      ),
   );
 
   server.tool(
     postmanGetStatusName,
     postmanGetStatusDescription,
     postmanGetStatusSchema.shape,
-    async (args) => handlePostmanGetStatus(args),
+    async (args) =>
+      handlePostmanGetStatus(
+        withDefaultScope(args as Record<string, unknown>) as z.infer<
+          typeof postmanGetStatusSchema
+        >,
+      ),
   );
 
   // ─── Stitch tools ──────────────────────────────────────────
@@ -162,21 +203,36 @@ export async function createServer({
     stitchGetModeName,
     stitchGetModeDescription,
     stitchGetModeSchema.shape,
-    async (args) => handleStitchGetMode(args),
+    async (args) =>
+      handleStitchGetMode(
+        withDefaultScope(args as Record<string, unknown>) as z.infer<
+          typeof stitchGetModeSchema
+        >,
+      ),
   );
 
   server.tool(
     stitchSetProfileName,
     stitchSetProfileDescription,
     stitchSetProfileSchema.shape,
-    async (args) => handleStitchSetProfile(args),
+    async (args) =>
+      handleStitchSetProfile(
+        withDefaultScope(args as Record<string, unknown>) as z.infer<
+          typeof stitchSetProfileSchema
+        >,
+      ),
   );
 
   server.tool(
     stitchGetStatusName,
     stitchGetStatusDescription,
     stitchGetStatusSchema.shape,
-    async (args) => handleStitchGetStatus(args),
+    async (args) =>
+      handleStitchGetStatus(
+        withDefaultScope(args as Record<string, unknown>) as z.infer<
+          typeof stitchGetStatusSchema
+        >,
+      ),
   );
 
   // ─── Dynamic upstream passthrough tools ────────────────────

package/mcp/src/telemetry/tokenBudget.ts

@@ -0,0 +1,114 @@
+/**
+ * Cubis Foundry MCP Server – deterministic token budget estimator.
+ *
+ * Estimates tokens by character count using a configurable chars/token ratio.
+ * This is intentionally model-agnostic and marked as estimated.
+ */
+
+export const TOKEN_ESTIMATOR_VERSION = "char-estimator-v1";
+
+export function normalizeCharsPerToken(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) return 4;
+  return value;
+}
+
+export function estimateTokensFromCharCount(
+  charCount: number,
+  charsPerToken: number,
+): number {
+  const safeChars = Math.max(0, Math.ceil(charCount));
+  const ratio = normalizeCharsPerToken(charsPerToken);
+  return Math.ceil(safeChars / ratio);
+}
+
+export function estimateTokensFromText(
+  text: string,
+  charsPerToken: number,
+): number {
+  return estimateTokensFromCharCount(text.length, charsPerToken);
+}
+
+/**
+ * Byte-size estimation is used for pointer-only operations where file content
+ * is intentionally not loaded.
+ */
+export function estimateTokensFromBytes(
+  byteCount: number,
+  charsPerToken: number,
+): number {
+  return estimateTokensFromCharCount(byteCount, charsPerToken);
+}
+
+export function estimateSavings(
+  fullCatalogEstimatedTokens: number,
+  usedEstimatedTokens: number,
+): { estimatedSavingsTokens: number; estimatedSavingsPercent: number } {
+  const full = Math.max(0, Math.ceil(fullCatalogEstimatedTokens));
+  const used = Math.max(0, Math.ceil(usedEstimatedTokens));
+  if (full <= 0) {
+    return {
+      estimatedSavingsTokens: 0,
+      estimatedSavingsPercent: 0,
+    };
+  }
+
+  const estimatedSavingsTokens = Math.max(0, full - used);
+  const estimatedSavingsPercent = Number(
+    ((estimatedSavingsTokens / full) * 100).toFixed(2),
+  );
+  return {
+    estimatedSavingsTokens,
+    estimatedSavingsPercent,
+  };
+}
+
+export interface SkillToolMetrics {
+  estimatorVersion: string;
+  charsPerToken: number;
+  fullCatalogEstimatedTokens: number;
+  responseEstimatedTokens: number;
+  selectedSkillsEstimatedTokens: number | null;
+  loadedSkillEstimatedTokens: number | null;
+  estimatedSavingsVsFullCatalog: number;
+  estimatedSavingsVsFullCatalogPercent: number;
+  estimated: true;
+}
+
+export function buildSkillToolMetrics({
+  charsPerToken,
+  fullCatalogEstimatedTokens,
+  responseEstimatedTokens,
+  selectedSkillsEstimatedTokens = null,
+  loadedSkillEstimatedTokens = null,
+}: {
+  charsPerToken: number;
+  fullCatalogEstimatedTokens: number;
+  responseEstimatedTokens: number;
+  selectedSkillsEstimatedTokens?: number | null;
+  loadedSkillEstimatedTokens?: number | null;
+}): SkillToolMetrics {
+  const usedEstimatedTokens =
+    loadedSkillEstimatedTokens ??
+    selectedSkillsEstimatedTokens ??
+    responseEstimatedTokens;
+  const savings = estimateSavings(fullCatalogEstimatedTokens, usedEstimatedTokens);
+
+  return {
+    estimatorVersion: TOKEN_ESTIMATOR_VERSION,
+    charsPerToken: normalizeCharsPerToken(charsPerToken),
+    fullCatalogEstimatedTokens: Math.max(0, fullCatalogEstimatedTokens),
+    responseEstimatedTokens: Math.max(0, responseEstimatedTokens),
+    selectedSkillsEstimatedTokens:
+      selectedSkillsEstimatedTokens === null
+        ? null
+        : Math.max(0, selectedSkillsEstimatedTokens),
+    loadedSkillEstimatedTokens:
+      loadedSkillEstimatedTokens === null
+        ? null
+        : Math.max(0, loadedSkillEstimatedTokens),
+    estimatedSavingsVsFullCatalog: savings.estimatedSavingsTokens,
+    estimatedSavingsVsFullCatalogPercent: savings.estimatedSavingsPercent,
+    estimated: true,
+  };
+}
+

package/mcp/src/tools/index.ts

@@ -33,6 +33,13 @@ export {
   handleSkillGet,
 } from "./skillGet.js";
 
+export {
+  skillBudgetReportName,
+  skillBudgetReportDescription,
+  skillBudgetReportSchema,
+  handleSkillBudgetReport,
+} from "./skillBudgetReport.js";
+
 export {
   postmanGetModeName,
   postmanGetModeDescription,

package/mcp/src/tools/skillBrowseCategory.ts

@@ -8,6 +8,11 @@ import { z } from "zod";
 import type { VaultManifest } from "../vault/types.js";
 import { enrichWithDescriptions } from "../vault/manifest.js";
 import { notFound } from "../utils/errors.js";
+import {
+  buildSkillToolMetrics,
+  estimateTokensFromBytes,
+  estimateTokensFromText,
+} from "../telemetry/tokenBudget.js";
 
 export const skillBrowseCategoryName = "skill_browse_category";
 
@@ -24,6 +29,7 @@ export async function handleSkillBrowseCategory(
   args: z.infer<typeof skillBrowseCategorySchema>,
   manifest: VaultManifest,
   summaryMaxLength: number,
+  charsPerToken: number,
 ) {
   const { category } = args;
 
@@ -38,17 +44,28 @@ export async function handleSkillBrowseCategory(
     id: s.id,
     description: s.description ?? "(no description)",
   }));
+  const payload = { category, skills, count: skills.length };
+  const text = JSON.stringify(payload, null, 2);
+  const selectedSkillsEstimatedTokens = matching.reduce(
+    (sum, skill) => sum + estimateTokensFromBytes(skill.fileBytes, charsPerToken),
+    0,
+  );
+  const metrics = buildSkillToolMetrics({
+    charsPerToken,
+    fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
+    responseEstimatedTokens: estimateTokensFromText(text, charsPerToken),
+    selectedSkillsEstimatedTokens,
+  });
 
   return {
     content: [
       {
         type: "text" as const,
-        text: JSON.stringify(
-          { category, skills, count: skills.length },
-          null,
-          2,
-        ),
+        text,
       },
     ],
+    structuredContent: {
+      metrics,
+    },
   };
 }

package/mcp/src/tools/skillBudgetReport.ts

@@ -0,0 +1,128 @@
+/**
+ * Cubis Foundry MCP Server – skill_budget_report tool.
+ *
+ * Aggregates selected/loaded skill IDs into a deterministic context budget
+ * summary using estimated token counts.
+ */
+
+import { z } from "zod";
+import type { VaultManifest } from "../vault/types.js";
+import {
+  TOKEN_ESTIMATOR_VERSION,
+  estimateSavings,
+  estimateTokensFromBytes,
+} from "../telemetry/tokenBudget.js";
+
+export const skillBudgetReportName = "skill_budget_report";
+
+export const skillBudgetReportDescription =
+  "Report estimated context/token budget for selected and loaded skills compared to the full skill catalog.";
+
+export const skillBudgetReportSchema = z.object({
+  selectedSkillIds: z
+    .array(z.string())
+    .default([])
+    .describe("Skill IDs selected after search/browse."),
+  loadedSkillIds: z
+    .array(z.string())
+    .default([])
+    .describe("Skill IDs loaded via skill_get."),
+});
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values.map((value) => String(value)))];
+}
+
+export function handleSkillBudgetReport(
+  args: z.infer<typeof skillBudgetReportSchema>,
+  manifest: VaultManifest,
+  charsPerToken: number,
+) {
+  const selectedSkillIds = uniqueStrings(args.selectedSkillIds ?? []);
+  const loadedSkillIds = uniqueStrings(args.loadedSkillIds ?? []);
+  const skillById = new Map(manifest.skills.map((skill) => [skill.id, skill]));
+
+  const selectedSkills = selectedSkillIds
+    .map((id) => {
+      const skill = skillById.get(id);
+      if (!skill) return null;
+      return {
+        id: skill.id,
+        category: skill.category,
+        estimatedTokens: estimateTokensFromBytes(skill.fileBytes, charsPerToken),
+      };
+    })
+    .filter((item): item is NonNullable<typeof item> => Boolean(item));
+
+  const loadedSkills = loadedSkillIds
+    .map((id) => {
+      const skill = skillById.get(id);
+      if (!skill) return null;
+      return {
+        id: skill.id,
+        category: skill.category,
+        estimatedTokens: estimateTokensFromBytes(skill.fileBytes, charsPerToken),
+      };
+    })
+    .filter((item): item is NonNullable<typeof item> => Boolean(item));
+
+  const unknownSelectedSkillIds = selectedSkillIds.filter(
+    (id) => !skillById.has(id),
+  );
+  const unknownLoadedSkillIds = loadedSkillIds.filter((id) => !skillById.has(id));
+
+  const selectedSkillsEstimatedTokens = selectedSkills.reduce(
+    (sum, skill) => sum + skill.estimatedTokens,
+    0,
+  );
+  const loadedSkillsEstimatedTokens = loadedSkills.reduce(
+    (sum, skill) => sum + skill.estimatedTokens,
+    0,
+  );
+
+  const usedEstimatedTokens =
+    loadedSkills.length > 0
+      ? loadedSkillsEstimatedTokens
+      : selectedSkillsEstimatedTokens;
+  const savings = estimateSavings(
+    manifest.fullCatalogEstimatedTokens,
+    usedEstimatedTokens,
+  );
+
+  const selectedIdSet = new Set(selectedSkills.map((skill) => skill.id));
+  const loadedIdSet = new Set(loadedSkills.map((skill) => skill.id));
+  const skippedSkills = manifest.skills
+    .filter((skill) => !selectedIdSet.has(skill.id) && !loadedIdSet.has(skill.id))
+    .map((skill) => skill.id)
+    .sort((a, b) => a.localeCompare(b));
+
+  const payload = {
+    skillLog: {
+      selectedSkills,
+      loadedSkills,
+      skippedSkills,
+      unknownSelectedSkillIds,
+      unknownLoadedSkillIds,
+    },
+    contextBudget: {
+      estimatorVersion: TOKEN_ESTIMATOR_VERSION,
+      charsPerToken,
+      fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
+      selectedSkillsEstimatedTokens,
+      loadedSkillsEstimatedTokens,
+      estimatedSavingsTokens: savings.estimatedSavingsTokens,
+      estimatedSavingsPercent: savings.estimatedSavingsPercent,
+      estimated: true,
+    },
+  };
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+    structuredContent: payload,
+  };
+}

package/mcp/src/tools/skillGet.ts

@@ -9,6 +9,10 @@ import { z } from "zod";
 import type { VaultManifest } from "../vault/types.js";
 import { readFullSkillContent } from "../vault/manifest.js";
 import { notFound } from "../utils/errors.js";
+import {
+  buildSkillToolMetrics,
+  estimateTokensFromText,
+} from "../telemetry/tokenBudget.js";
 
 export const skillGetName = "skill_get";
 
@@ -22,6 +26,7 @@ export const skillGetSchema = z.object({
 export async function handleSkillGet(
   args: z.infer<typeof skillGetSchema>,
   manifest: VaultManifest,
+  charsPerToken: number,
 ) {
   const { id } = args;
 
@@ -31,6 +36,16 @@ export async function handleSkillGet(
   }
 
   const content = await readFullSkillContent(skill.path);
+  const loadedSkillEstimatedTokens = estimateTokensFromText(
+    content,
+    charsPerToken,
+  );
+  const metrics = buildSkillToolMetrics({
+    charsPerToken,
+    fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
+    responseEstimatedTokens: loadedSkillEstimatedTokens,
+    loadedSkillEstimatedTokens,
+  });
 
   return {
     content: [
@@ -39,5 +54,8 @@ export async function handleSkillGet(
         text: content,
       },
     ],
+    structuredContent: {
+      metrics,
+    },
   };
 }

package/mcp/src/tools/skillListCategories.ts

@@ -6,6 +6,10 @@
 
 import { z } from "zod";
 import type { VaultManifest } from "../vault/types.js";
+import {
+  buildSkillToolMetrics,
+  estimateTokensFromText,
+} from "../telemetry/tokenBudget.js";
 
 export const skillListCategoriesName = "skill_list_categories";
 
@@ -14,7 +18,10 @@ export const skillListCategoriesDescription =
 
 export const skillListCategoriesSchema = z.object({});
 
-export function handleSkillListCategories(manifest: VaultManifest) {
+export function handleSkillListCategories(
+  manifest: VaultManifest,
+  charsPerToken: number,
+) {
   const categoryCounts: Record<string, number> = {};
   for (const skill of manifest.skills) {
     categoryCounts[skill.category] = (categoryCounts[skill.category] ?? 0) + 1;
@@ -24,17 +31,23 @@ export function handleSkillListCategories(manifest: VaultManifest) {
     category: cat,
     skillCount: categoryCounts[cat] ?? 0,
   }));
+  const payload = { categories, totalSkills: manifest.skills.length };
+  const text = JSON.stringify(payload, null, 2);
+  const metrics = buildSkillToolMetrics({
+    charsPerToken,
+    fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
+    responseEstimatedTokens: estimateTokensFromText(text, charsPerToken),
+  });
 
   return {
     content: [
       {
         type: "text" as const,
-        text: JSON.stringify(
-          { categories, totalSkills: manifest.skills.length },
-          null,
-          2,
-        ),
+        text,
       },
     ],
+    structuredContent: {
+      metrics,
+    },
   };
 }