@tokcalc/mcp-server 0.2.2 → 0.2.4

package/dist/server.js

@@ -16010,11 +16010,11 @@ function handleEstimateCapacity(input) {
       memory: result.confidence.totalVramNeededGb
     },
     assumptions: [
-      `η_mem = 0.65 (typical real-world memory utilization)`,
-      `η_compute = 0.50 (typical compute utilization)`,
+      `η_mem = 0.65 (typical real-world memory utilization)`,
+      `η_compute = 0.50 (typical compute utilization)`,
       `KV cache in FP16 (2 bytes per value)`,
       `Engine: ${input.engine} (affects efficiency factors)`,
-      `Continuous batching: ${input.continuousBatching ? `${input.continuousBatchingMultiplier}× multiplier` : "disabled"}`,
+      `Continuous batching: ${input.continuousBatching ? `${input.continuousBatchingMultiplier}× multiplier` : "disabled"}`,
       `These are planning estimates, not deployment guarantees`
     ],
     catalogVersion: "0.3.0"
@@ -16089,19 +16089,24 @@ function handleRecommendTopology(input) {
   const quant = QUANT_MAP[input.quantization];
   if (!model || !quant)
     return { error: "Unknown model or quantization" };
-  const kvPerRequest = computeKVCacheGb(model, input.contextTokens, input.batchSize);
+  const kvPerRequest = computeKVCacheGb(model, input.contextTokens, 1);
+  const kvPerBatch = computeKVCacheGb(model, input.contextTokens, input.batchSize);
   const results = GPUS.map((g) => {
     const rec = recommendTopology(model, g, input.contextTokens, input.batchSize, quant.bytesPerParam);
-    const maxConcurrent = computeMaxConcurrency(model, g, input.batchSize, input.contextTokens, quant.bytesPerParam);
+    const maxConcurrent = rec.neededGpus > 0 ? computeMaxConcurrency(model, g, rec.neededGpus, input.contextTokens, quant.bytesPerParam) : 0;
     return {
       gpuId: g.id,
       gpuName: g.name,
       vramGb: g.vramGb,
       topology: rec.topology,
       neededGpus: rec.neededGpus,
+      totalVramGb: +(g.vramGb * rec.neededGpus).toFixed(0),
+      vramNeededGb: +(model.paramsB * quant.bytesPerParam + kvPerBatch).toFixed(1),
       fits: rec.fits,
       maxConcurrentUsers: maxConcurrent,
+      maxConcurrentBatchesAtContext: Math.floor(maxConcurrent / Math.max(input.batchSize, 1)),
       kvPerRequestGb: +kvPerRequest.toFixed(2),
+      kvPerBatchGb: +kvPerBatch.toFixed(2),
       reason: rec.reason
     };
   }).filter((r) => r.fits).slice(0, 5);
@@ -16110,11 +16115,12 @@ function handleRecommendTopology(input) {
     model: { name: model.name, paramsB: model.paramsB, activeParamsB: model.activeParamsB, isMoE: model.isMoE },
     context: { tokens: input.contextTokens, label: fmtContext(input.contextTokens), batchSize: input.batchSize },
     recommendations: results,
-    formula: `KV per batch = 2 × ${model.layers} layers × ${model.kvHeads} KV heads × ${model.headDim} head_dim × 2 bytes × ${input.contextTokens} tokens × ${input.batchSize} batch = ${kvPerRequest.toFixed(2)} GB`,
-    assumptions: [`Single GPU unless TP needed`, `KV cache in FP16`, `Model weights + KV × batchSize must fit in total VRAM`, `Catalog version: 0.3.0`]
+    formula: `KV per request = 2 × ${model.layers} layers × ${model.kvHeads} KV heads × ${model.headDim} head_dim × 2 bytes × ${input.contextTokens} tokens = ${kvPerRequest.toFixed(2)} GB; × ${input.batchSize} batch = ${kvPerBatch.toFixed(2)} GB`,
+    assumptions: [`Single GPU unless TP needed`, `KV cache in FP16`, `Model weights + KV × batchSize must fit in total VRAM`, `maxConcurrentUsers is concurrent single-slot requests at this context; concurrent batches = maxConcurrentUsers ÷ ${input.batchSize}`, `Catalog version: 0.3.0`]
   };
 }
 function handleEstimateApiVsSelfHost(input) {
+  const utilizationPct = input.utilization * 100;
   const sh = calculate({
     modelId: input.model,
     gpuId: input.gpu,
@@ -16125,8 +16131,16 @@ function handleEstimateApiVsSelfHost(input) {
     outputTokens: input.outputTokens
   });
   const gpu = GPU_MAP[input.gpu];
+  const model = MODEL_MAP[input.model];
+  if (!sh.vramFits) {
+    return {
+      error: `Self-host infeasible: ${model?.name ?? input.model} at ${input.quantization} on ${input.gpuCount}× ${gpu?.name ?? input.gpu} needs ${sh.totalVramNeededGb.toFixed(1)} GB but only ${((gpu?.vramGb ?? 0) * input.gpuCount).toFixed(0)} GB is available.`,
+      suggestion: `Increase gpuCount, lower the quantization (e.g. fp8/int4), or pick a smaller model. Break-even is undefined until the config fits.`,
+      feasibility: { fits: false, vramNeededGb: +sh.totalVramNeededGb.toFixed(2), vramAvailableGb: +((gpu?.vramGb ?? 0) * input.gpuCount).toFixed(0) }
+    };
+  }
   const effGpuPrice = (gpu?.usdPerHour ?? 0) * input.gpuCount;
-  const effTokens = sh.aggregateTokensPerSec * (input.utilization / 100);
+  const effTokens = sh.aggregateTokensPerSec * input.utilization;
   const selfHostCostPerM = effTokens > 0 ? effGpuPrice / 3600 / effTokens * 1e6 : Infinity;
   const selfHostMonthly = effGpuPrice * 730;
   const apiCostPerRequest = input.inputTokens / 1e6 * input.apiInputPrice + input.outputTokens / 1e6 * input.apiOutputPrice;
@@ -16141,8 +16155,10 @@ function handleEstimateApiVsSelfHost(input) {
       costPerMillionTokens: +selfHostCostPerM.toFixed(2),
       monthlyInfraUsd: +selfHostMonthly.toFixed(2),
       monthlyTotalUsd: +selfHostMonthlyTotal.toFixed(2),
-      utilization: `${input.utilization}%`,
-      throughput: `${fmtTokens(sh.aggregateTokensPerSec)} tok/s`
+      utilization: `${utilizationPct.toLocaleString("en-US")}%`,
+      utilizationNote: "Share of peak fleet throughput actually sold/utilized.",
+      throughput: `${fmtTokens(sh.aggregateTokensPerSec)} tok/s`,
+      effectiveThroughput: `${fmtTokens(effTokens)} tok/s at ${utilizationPct.toLocaleString("en-US")}% utilization`
     },
     api: {
       costPerMillionTokens: input.apiOutputPrice,
@@ -16152,10 +16168,11 @@ function handleEstimateApiVsSelfHost(input) {
     breakEven: {
       requestsPerDay: Math.round(breakEven),
       reached: meetsVolume,
-      explanation: `At ${input.utilization}% utilization with ${input.gpuCount}× ${gpu?.name || input.gpu}, self-hosting breaks even at ${Math.round(breakEven).toLocaleString("en-US")} requests/day.`
+      explanation: `At ${utilizationPct.toLocaleString("en-US")}% utilization with ${input.gpuCount}× ${gpu?.name || input.gpu}, self-hosting breaks even at ${Math.round(breakEven).toLocaleString("en-US")} requests/day.`,
+      requestsPerDayLabel: Math.round(breakEven).toLocaleString("en-US")
     },
     assumptions: [
-      `Self-host throughput: ${fmtTokens(sh.aggregateTokensPerSec)} tok/s at ${input.utilization}% utilization`,
+      `Self-host peak throughput: ${fmtTokens(sh.aggregateTokensPerSec)} tok/s; effective at ${utilizationPct.toLocaleString("en-US")}% utilization = ${fmtTokens(effTokens)} tok/s`,
       `GPU price: $${effGpuPrice}/hr`,
       `API pricing: $${input.apiInputPrice}/M input, $${input.apiOutputPrice}/M output`,
       `730 hours/month`,
@@ -16286,11 +16303,23 @@ var TOOL_DEFINITIONS = [
     inputSchema: formatInputSchema(GetMlperfBenchmarksSchema)
   }
 ];
+var SERVER_VERSION = "0.2.4";
+function withProvenance(result) {
+  return {
+    ...result,
+    provenance: {
+      serverVersion: SERVER_VERSION,
+      catalogVersion: "0.3.0",
+      buildStamp: `tokcalc-mcp/${SERVER_VERSION}`
+    }
+  };
+}
 function createMcpServer() {
-  const server = new Server({ name: "tokcalc", version: "0.2.0" }, {
+  const server = new Server({ name: "tokcalc", version: SERVER_VERSION }, {
     capabilities: {
       tools: {}
-    }
+    },
+    instructions: `tokcalc MCP server ${SERVER_VERSION} — LLM serving capacity planner. ` + `Use list_models / list_gpus to discover canonical IDs before calling ` + `estimate_capacity, compare_gpus, recommend_topology, or ` + `estimate_api_vs_self_host. All estimates are planning projections, not ` + `deployment guarantees. Every response carries provenance.serverVersion.`
   });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOL_DEFINITIONS
@@ -16341,16 +16370,25 @@ function createMcpServer() {
             isError: true
           };
       }
+      const isHandlerError = !!result && typeof result === "object" && "error" in result;
+      const stamped = withProvenance(result);
       return {
         content: [
-          { type: "text", text: JSON.stringify(result, null, 2) }
+          { type: "text", text: JSON.stringify(stamped, null, 2) }
         ],
-        structuredContent: result
+        structuredContent: stamped,
+        ...isHandlerError ? { isError: true } : {}
       };
     } catch (error) {
       return {
         content: [
-          { type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: error instanceof Error ? error.message : String(error),
+              provenance: { serverVersion: SERVER_VERSION, buildStamp: `tokcalc-mcp/${SERVER_VERSION}` }
+            }, null, 2)
+          }
         ],
         isError: true
       };
@@ -16359,5 +16397,6 @@ function createMcpServer() {
   return server;
 }
 export {
+  SERVER_VERSION,
   createMcpServer
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokcalc/mcp-server",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "mcpName": "io.github.stevecrates489-commits/tokcalc",
   "description": "tokcalc MCP server — open-source LLM serving capacity planner for AI agents. v0.2.1: stdio + stateless HTTP transport with bearer API key auth + KV-backed rate limiting + public hosted endpoint. 7 read-only tools: estimate_capacity, compare_gpus, recommend_topology, estimate_api_vs_self_host, list_models, list_gpus, get_mlperf_benchmarks.",
   "type": "module",