@tokcalc/mcp-server 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (192) hide show
  1. package/.zscripts/build.sh +175 -0
  2. package/.zscripts/database-runtime-build.sh +33 -0
  3. package/.zscripts/dev.pid +1 -0
  4. package/.zscripts/dev.sh +154 -0
  5. package/.zscripts/mini-services-build.sh +78 -0
  6. package/.zscripts/mini-services-install.sh +65 -0
  7. package/.zscripts/mini-services-start.sh +123 -0
  8. package/.zscripts/python-runtime-build.sh +120 -0
  9. package/.zscripts/start.sh +145 -0
  10. package/CAPACITY_STUDY.md +283 -0
  11. package/CODE_OF_CONDUCT.md +55 -0
  12. package/CONTRIBUTING.md +177 -0
  13. package/Caddyfile +23 -0
  14. package/LICENSE +204 -0
  15. package/README.md +406 -86
  16. package/bun.lock +1965 -0
  17. package/components.json +21 -0
  18. package/db/custom.db +0 -0
  19. package/download/README.md +1 -0
  20. package/download/tokcalc-dark-calculator.png +0 -0
  21. package/download/tokcalc-dark-default.png +0 -0
  22. package/download/tokcalc-demo.webm +0 -0
  23. package/download/tokcalc-github-link.png +0 -0
  24. package/download/tokcalc-hydration-fixed.png +0 -0
  25. package/download/tokcalc-issue-resolved.png +0 -0
  26. package/download/tokcalc-light-mode.png +0 -0
  27. package/download/tokcalc-light-reference.png +0 -0
  28. package/download/tokcalc-long-context-qwen.png +0 -0
  29. package/download/tokcalc-long-context.png +0 -0
  30. package/download/tokcalc-og-image-preview.png +0 -0
  31. package/download/tokcalc-phase2-3.png +0 -0
  32. package/download/tokcalc-plain-english.png +0 -0
  33. package/download/tokcalc-preview.png +0 -0
  34. package/download/tokcalc-share-bvb.png +0 -0
  35. package/download/tokcalc-share-feature.png +0 -0
  36. package/download/tokcalc-tab-build-vs-buy.png +0 -0
  37. package/download/tokcalc-tab-calculator.png +0 -0
  38. package/download/tokcalc-tab-reference.png +0 -0
  39. package/eslint.config.mjs +50 -0
  40. package/examples/websocket/frontend.tsx +196 -0
  41. package/examples/websocket/server.ts +138 -0
  42. package/mini-services/.gitkeep +0 -0
  43. package/mini-services/mcp-server/README.md +86 -0
  44. package/mini-services/mcp-server/bun.lock +202 -0
  45. package/mini-services/mcp-server/index.ts +504 -0
  46. package/mini-services/mcp-server/package.json +40 -0
  47. package/next.config.ts +12 -0
  48. package/package.json +92 -35
  49. package/postcss.config.mjs +5 -0
  50. package/prisma/schema.prisma +32 -0
  51. package/public/google6f58ca6be85fa903.html +1 -0
  52. package/public/logo.svg +29 -0
  53. package/public/manifest.json +51 -0
  54. package/public/og-icon-256.png +0 -0
  55. package/public/og.png +0 -0
  56. package/public/robots.txt +25 -0
  57. package/public/sitemap.xml +23 -0
  58. package/public/tokcalc-demo.gif +0 -0
  59. package/scripts/og-template.html +120 -0
  60. package/scripts/render-og.mjs +43 -0
  61. package/server.json +21 -0
  62. package/src/app/api/pricing/aws/route.ts +186 -0
  63. package/src/app/api/pricing/azure/route.ts +168 -0
  64. package/src/app/api/pricing/gcp/route.ts +230 -0
  65. package/src/app/api/pricing/vast-ai/route.ts +164 -0
  66. package/src/app/api/route.ts +5 -0
  67. package/src/app/compare/h100-vs-h200/layout.tsx +30 -0
  68. package/src/app/compare/h100-vs-h200/page.tsx +328 -0
  69. package/src/app/globals.css +122 -0
  70. package/src/app/layout.tsx +276 -0
  71. package/src/app/page.tsx +2670 -0
  72. package/src/components/azure-live-pricing.tsx +185 -0
  73. package/src/components/benchmark-import.tsx +340 -0
  74. package/src/components/confidence-badge.tsx +116 -0
  75. package/src/components/live-pricing-comparison.tsx +241 -0
  76. package/src/components/theme-provider.tsx +11 -0
  77. package/src/components/theme-toggle.tsx +55 -0
  78. package/src/components/ui/accordion.tsx +66 -0
  79. package/src/components/ui/alert-dialog.tsx +157 -0
  80. package/src/components/ui/alert.tsx +66 -0
  81. package/src/components/ui/aspect-ratio.tsx +11 -0
  82. package/src/components/ui/avatar.tsx +53 -0
  83. package/src/components/ui/badge.tsx +46 -0
  84. package/src/components/ui/breadcrumb.tsx +109 -0
  85. package/src/components/ui/button.tsx +59 -0
  86. package/src/components/ui/calendar.tsx +213 -0
  87. package/src/components/ui/card.tsx +92 -0
  88. package/src/components/ui/carousel.tsx +241 -0
  89. package/src/components/ui/chart.tsx +353 -0
  90. package/src/components/ui/checkbox.tsx +32 -0
  91. package/src/components/ui/collapsible.tsx +33 -0
  92. package/src/components/ui/command.tsx +184 -0
  93. package/src/components/ui/context-menu.tsx +252 -0
  94. package/src/components/ui/dialog.tsx +143 -0
  95. package/src/components/ui/drawer.tsx +135 -0
  96. package/src/components/ui/dropdown-menu.tsx +257 -0
  97. package/src/components/ui/form.tsx +167 -0
  98. package/src/components/ui/hover-card.tsx +44 -0
  99. package/src/components/ui/input-otp.tsx +77 -0
  100. package/src/components/ui/input.tsx +21 -0
  101. package/src/components/ui/label.tsx +24 -0
  102. package/src/components/ui/menubar.tsx +276 -0
  103. package/src/components/ui/navigation-menu.tsx +168 -0
  104. package/src/components/ui/pagination.tsx +127 -0
  105. package/src/components/ui/popover.tsx +48 -0
  106. package/src/components/ui/progress.tsx +31 -0
  107. package/src/components/ui/radio-group.tsx +45 -0
  108. package/src/components/ui/resizable.tsx +56 -0
  109. package/src/components/ui/scroll-area.tsx +58 -0
  110. package/src/components/ui/select.tsx +185 -0
  111. package/src/components/ui/separator.tsx +28 -0
  112. package/src/components/ui/sheet.tsx +139 -0
  113. package/src/components/ui/sidebar.tsx +726 -0
  114. package/src/components/ui/skeleton.tsx +13 -0
  115. package/src/components/ui/slider.tsx +63 -0
  116. package/src/components/ui/sonner.tsx +25 -0
  117. package/src/components/ui/switch.tsx +31 -0
  118. package/src/components/ui/table.tsx +116 -0
  119. package/src/components/ui/tabs.tsx +66 -0
  120. package/src/components/ui/textarea.tsx +18 -0
  121. package/src/components/ui/toast.tsx +129 -0
  122. package/src/components/ui/toaster.tsx +35 -0
  123. package/src/components/ui/toggle-group.tsx +73 -0
  124. package/src/components/ui/toggle.tsx +47 -0
  125. package/src/components/ui/tooltip.tsx +61 -0
  126. package/src/components/vast-ai-live-pricing.tsx +176 -0
  127. package/src/hooks/use-mobile.ts +19 -0
  128. package/src/hooks/use-toast.ts +194 -0
  129. package/src/lib/benchmark-parser-sglang.ts +150 -0
  130. package/src/lib/benchmark-parser-tokcalc.ts +247 -0
  131. package/src/lib/benchmark-parser-trtllm.ts +152 -0
  132. package/src/lib/benchmark-parser-vllm.ts +198 -0
  133. package/src/lib/benchmark-schema.ts +263 -0
  134. package/src/lib/db.ts +13 -0
  135. package/src/lib/engine-presets.ts +183 -0
  136. package/src/lib/price-schema.ts +141 -0
  137. package/src/lib/token-calc.ts +808 -0
  138. package/src/lib/track.ts +31 -0
  139. package/src/lib/url-state.ts +256 -0
  140. package/src/lib/utils.ts +6 -0
  141. package/tailwind.config.ts +64 -0
  142. package/tests/database-runtime-build.sh +75 -0
  143. package/tests/python-runtime-build.sh +64 -0
  144. package/tests/python-runtime-container.sh +31 -0
  145. package/tool-results/bash_1789888171144_2c5381860539.txt +161 -0
  146. package/tool-results/bash_1789888175925_49c53ba3c61b.txt +191 -0
  147. package/tool-results/bash_1789888181202_49c53ba3c61b.txt +191 -0
  148. package/tool-results/bash_1789888195219_4a86a5c91411.txt +200 -0
  149. package/tool-results/bash_1789888203128_6cca13c71b47.txt +199 -0
  150. package/tool-results/bash_1789929256963_2a52aff0d0a8.txt +160 -0
  151. package/tool-results/read_1789888151021_69f58eec6a5b.txt +653 -0
  152. package/tool-results/read_1789888153837_1d3a8bfc2a94.txt +653 -0
  153. package/tool-results/read_1789888163087_ccc406d47505.txt +122 -0
  154. package/tool-results/read_1789888167347_67d1d7c9830a.txt +122 -0
  155. package/tool-results/read_1789929252529_d90e8f383a25.txt +285 -0
  156. package/tsconfig.json +42 -0
  157. package/upload/Pasted Content_1789887800864.txt +652 -0
  158. package/upload/Pasted Content_1789887909561.txt +652 -0
  159. package/upload/Pasted Content_1789887918428.txt +652 -0
  160. package/upload/Pasted Content_1789887959420.txt +652 -0
  161. package/upload/Pasted Content_1789888020485.txt +652 -0
  162. package/upload/Pasted Content_1789888058079.txt +652 -0
  163. package/upload/Pasted Content_1789888885033.txt +686 -0
  164. package/upload/Pasted Content_1789928912741.txt +285 -0
  165. package/upload/Pasted Content_1789928938402.txt +285 -0
  166. package/upload/Pasted Content_1789929160389.txt +285 -0
  167. package/upload/Pasted Content_1789929176660.txt +285 -0
  168. package/upload/issue_vision.json +28 -0
  169. package/upload/pasted_image_1789883175209.png +0 -0
  170. package/upload/pasted_image_1789899056690.png +0 -0
  171. package/upload/pasted_image_1789900371483.png +0 -0
  172. package/upload/pasted_image_1789900472823.png +0 -0
  173. package/upload/pasted_image_1789900490374.png +0 -0
  174. package/upload/pasted_image_1789900585552.png +0 -0
  175. package/upload/pasted_image_1789900606519.png +0 -0
  176. package/upload/pasted_image_1789901598705.png +0 -0
  177. package/upload/pasted_image_1789901613545.png +0 -0
  178. package/upload/pasted_image_1789978382674.png +0 -0
  179. package/upload/pasted_image_1789978392749.png +0 -0
  180. package/upload/pasted_image_1789978474879.png +0 -0
  181. package/upload/pasted_image_1789978523652.png +0 -0
  182. package/upload/pasted_image_1789984219089.png +0 -0
  183. package/upload/pasted_image_1789984491896.png +0 -0
  184. package/upload/pasted_image_1789985017950.png +0 -0
  185. package/upload/pasted_image_1789985036765.png +0 -0
  186. package/upload/pasted_image_1789985049848.png +0 -0
  187. package/upload/pasted_image_1790002427833.png +0 -0
  188. package/upload/pasted_image_1790002659944.png +0 -0
  189. package/upload/pasted_image_1790037038476.png +0 -0
  190. package/upload/screenshot_analysis.json +28 -0
  191. package/upload/vision_output.json +28 -0
  192. package/dist/index.js +0 -21014
@@ -0,0 +1,504 @@
1
+ /**
2
+ * tokcalc MCP Server — local stdio transport.
3
+ *
4
+ * Exposes 6 read-only planning tools for AI agents (Cursor, Claude Desktop, Cline):
5
+ * 1. estimate_capacity — VRAM/KV/throughput/latency/cost for one config
6
+ * 2. compare_gpus — ranked GPU comparison for one workload
7
+ * 3. recommend_topology — TP/CP topology recommendation
8
+ * 4. estimate_api_vs_self_host — break-even analysis
9
+ * 5. list_models — discover supported model IDs
10
+ * 6. list_gpus — discover supported GPU IDs
11
+ */
12
+
13
+ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
14
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
15
+ import {
16
+ CallToolRequestSchema,
17
+ ListToolsRequestSchema,
18
+ } from "@modelcontextprotocol/sdk/types.js";
19
+ import { z } from "zod";
20
+ import { zodToJsonSchema } from "zod-to-json-schema";
21
+
22
+ // Import tokcalc's calculation engine + catalog (shared with the web app)
23
+ import {
24
+ calculate,
25
+ fmtTokens,
26
+ fmtBytes,
27
+ fmtMs,
28
+ fmtMoney,
29
+ GPUS,
30
+ MODELS,
31
+ QUANT_MAP,
32
+ GPU_MAP,
33
+ MODEL_MAP,
34
+ computeMaxConcurrency,
35
+ computeKVCacheGb,
36
+ recommendTopology,
37
+ fmtContext,
38
+ type Quantization,
39
+ } from "../../src/lib/token-calc.ts";
40
+
41
+ // Helper function to format Zod schema for MCP protocol compliance (Strips $schema meta-tag)
42
+ function formatInputSchema(schema: z.ZodTypeAny) {
43
+ const json = zodToJsonSchema(schema, {
44
+ target: "jsonSchema7",
45
+ $refStrategy: "none",
46
+ }) as Record<string, any>;
47
+
48
+ delete json["$schema"];
49
+
50
+ return {
51
+ type: "object",
52
+ properties: json.properties || {},
53
+ required: json.required || [],
54
+ ...json,
55
+ };
56
+ }
57
+
58
+ // ============================================================
59
+ // TOOL SCHEMAS
60
+ // ============================================================
61
+
62
+ const ModelIdSchema = z.string().describe("Canonical tokcalc model ID (e.g. 'llama3-8b'). Call list_models first if unknown.");
63
+ const GpuIdSchema = z.string().describe("Canonical tokcalc GPU ID (e.g. 'h100-sxm'). Call list_gpus first if unknown.");
64
+ const QuantSchema = z.enum(["fp32","fp16","bf16","int8","int4","gguf-q2k","gguf-q3km","gguf-q4km","gguf-q5km","gguf-q6k","gguf-q8","gptq4","awq4","exl2-6bpw","fp8","nvfp4"]);
65
+
66
+ const EstimateCapacitySchema = z.object({
67
+ model: ModelIdSchema,
68
+ gpu: GpuIdSchema,
69
+ quantization: QuantSchema.default("fp16"),
70
+ gpuCount: z.number().int().min(1).max(256).default(1),
71
+ batchSize: z.number().int().min(1).max(10000).default(1),
72
+ promptTokens: z.number().int().min(1).max(2000000).default(500),
73
+ outputTokens: z.number().int().min(1).max(200000).default(200),
74
+ engine: z.enum(["generic","vllm","sglang","trtllm","llamacpp"]).default("generic"),
75
+ continuousBatching: z.boolean().default(false),
76
+ continuousBatchingMultiplier: z.number().min(1).max(10).default(1.5),
77
+ reasoningTokens: z.number().int().min(0).max(1000000).default(0),
78
+ });
79
+
80
+ const CompareGpusSchema = z.object({
81
+ model: ModelIdSchema,
82
+ quantization: QuantSchema.default("fp16"),
83
+ gpuCount: z.number().int().min(1).max(8).default(1),
84
+ batchSize: z.number().int().min(1).max(1000).default(8),
85
+ promptTokens: z.number().int().min(1).max(2000000).default(500),
86
+ outputTokens: z.number().int().min(1).max(200000).default(200),
87
+ sortBy: z.enum(["lowest_cost","highest_throughput","best_value"]).default("best_value"),
88
+ limit: z.number().int().min(1).max(30).default(10),
89
+ });
90
+
91
+ const RecommendTopologySchema = z.object({
92
+ model: ModelIdSchema,
93
+ quantization: QuantSchema.default("fp16"),
94
+ contextTokens: z.number().int().min(1024).max(2000000).default(8192),
95
+ batchSize: z.number().int().min(1).max(1000).default(1),
96
+ });
97
+
98
+ const EstimateApiVsSelfHostSchema = z.object({
99
+ model: ModelIdSchema,
100
+ gpu: GpuIdSchema,
101
+ quantization: QuantSchema.default("fp16"),
102
+ gpuCount: z.number().int().min(1).max(64).default(1),
103
+ inputTokens: z.number().int().min(1).max(2000000).default(500),
104
+ outputTokens: z.number().int().min(1).max(200000).default(200),
105
+ requestsPerDay: z.number().int().min(1).max(100000000).default(1000),
106
+ utilization: z.number().min(0.05).max(1).default(0.5),
107
+ apiModel: z.string().default("gpt-4o-mini"),
108
+ apiInputPrice: z.number().min(0).default(0.15),
109
+ apiOutputPrice: z.number().min(0).default(0.60),
110
+ });
111
+
112
+ const ListModelsSchema = z.object({
113
+ family: z.string().optional().describe("Filter by model family (e.g. 'Llama', 'Qwen')"),
114
+ category: z.enum(["text","vlm","embedding","code","reasoning"]).optional(),
115
+ isMoE: z.boolean().optional(),
116
+ });
117
+
118
+ const ListGpusSchema = z.object({
119
+ vendor: z.string().optional().describe("Filter by vendor (e.g. 'NVIDIA', 'AMD')"),
120
+ category: z.enum(["datacenter","workstation","consumer","mac","tpu","lpu","wse","legacy"]).optional(),
121
+ minVramGb: z.number().optional(),
122
+ });
123
+
124
+ // ============================================================
125
+ // TOOL HANDLERS
126
+ // ============================================================
127
+
128
+ function handleEstimateCapacity(input: z.infer<typeof EstimateCapacitySchema>) {
129
+ const result = calculate({
130
+ modelId: input.model,
131
+ gpuId: input.gpu,
132
+ quantization: input.quantization as Quantization,
133
+ numGpus: input.gpuCount,
134
+ batchSize: input.batchSize,
135
+ promptTokens: input.promptTokens,
136
+ outputTokens: input.outputTokens,
137
+ engineId: input.engine,
138
+ effMem: undefined,
139
+ useContinuousBatching: input.continuousBatching,
140
+ continuousBatchingMultiplier: input.continuousBatchingMultiplier,
141
+ reasoningTokens: input.reasoningTokens,
142
+ });
143
+
144
+ const model = MODEL_MAP[input.model];
145
+ const gpu = GPU_MAP[input.gpu];
146
+
147
+ return {
148
+ summary: `${model?.name || input.model} on ${gpu?.name || input.gpu} (${input.quantization}): ${fmtTokens(result.decodeTokensPerSec)} tok/s decode, ${fmtMs(result.ttftMs)} TTFT, ${fmtBytes(result.totalVramNeededGb)} VRAM needed, ${fmtMoney(result.costPerMillionOutputTokens)}/M tokens`,
149
+ feasibility: {
150
+ modelFits: result.vramFits,
151
+ fitsWithKvCache: result.vramFits,
152
+ blockingReasons: result.vramFits ? [] : [`Needs ${fmtBytes(result.totalVramNeededGb)} but only ${gpu?.vramGb * input.gpuCount} GB available`],
153
+ warnings: result.longContextWarning ? [result.longContextWarning] : [],
154
+ },
155
+ performance: {
156
+ outputTokensPerSecond: {
157
+ low: Math.round(result.decodeTokensPerSec * 0.7),
158
+ expected: Math.round(result.decodeTokensPerSec),
159
+ high: Math.round(result.decodeTokensPerSec * 1.3),
160
+ },
161
+ aggregateTokensPerSecond: Math.round(result.aggregateTokensPerSec),
162
+ ttftMs: { expected: Math.round(result.ttftMs) },
163
+ itlMs: { expected: Math.round(result.itlMs) },
164
+ totalLatencyMs: Math.round(result.totalLatencyMs),
165
+ },
166
+ memory: {
167
+ modelWeightsGb: +result.modelSizeGb.toFixed(2),
168
+ kvCacheGb: +result.kvCacheTotalGb.toFixed(2),
169
+ totalRequiredGb: +result.totalVramNeededGb.toFixed(2),
170
+ availableGb: gpu ? gpu.vramGb * input.gpuCount : 0,
171
+ utilizationPct: +((result.totalVramNeededGb / ((gpu?.vramGb || 1) * input.gpuCount)) * 100).toFixed(1),
172
+ },
173
+ cost: {
174
+ gpuHourlyUsd: result.costPerHour,
175
+ costPerMillionTokens: result.costPerMillionOutputTokens,
176
+ costPerRequest: result.costPerRequest,
177
+ },
178
+ confidence: {
179
+ throughput: result.confidence.decodeTokensPerSec,
180
+ latency: result.confidence.totalLatencyMs,
181
+ memory: result.confidence.totalVramNeededGb,
182
+ },
183
+ assumptions: [
184
+ `η_mem = 0.65 (typical real-world memory utilization)`,
185
+ `η_compute = 0.50 (typical compute utilization)`,
186
+ `KV cache in FP16 (2 bytes per value)`,
187
+ `Engine: ${input.engine} (affects efficiency factors)`,
188
+ `Continuous batching: ${input.continuousBatching ? `${input.continuousBatchingMultiplier}× multiplier` : "disabled"}`,
189
+ `These are planning estimates, not deployment guarantees`,
190
+ ],
191
+ catalogVersion: "0.3.0",
192
+ };
193
+ }
194
+
195
+ function handleCompareGpus(input: z.infer<typeof CompareGpusSchema>) {
196
+ const model = MODEL_MAP[input.model];
197
+ const quant = QUANT_MAP[input.quantization as Quantization];
198
+ if (!model || !quant) return { error: "Unknown model or quantization", models: Object.keys(MODEL_MAP).slice(0, 10) };
199
+
200
+ const candidates = GPUS.filter(g => g.vramGb * input.gpuCount >= model.activeParamsB * quant.bytesPerParam);
201
+
202
+ const results = candidates.map(g => {
203
+ const r = calculate({
204
+ modelId: input.model,
205
+ gpuId: g.id,
206
+ quantization: input.quantization as Quantization,
207
+ numGpus: input.gpuCount,
208
+ batchSize: input.batchSize,
209
+ promptTokens: input.promptTokens,
210
+ outputTokens: input.outputTokens,
211
+ });
212
+ return {
213
+ gpuId: g.id,
214
+ gpuName: g.name,
215
+ vendor: g.vendor,
216
+ vramGb: g.vramGb * input.gpuCount,
217
+ modelFits: r.vramFits,
218
+ outputTokensPerSecond: Math.round(r.decodeTokensPerSec),
219
+ aggregateTokensPerSecond: Math.round(r.aggregateTokensPerSec),
220
+ ttftMs: Math.round(r.ttftMs),
221
+ costPerMillionTokens: +r.costPerMillionOutputTokens.toFixed(2),
222
+ gpuHourlyUsd: r.costPerHour,
223
+ confidence: r.confidence.decodeTokensPerSec,
224
+ };
225
+ });
226
+
227
+ const sorted = results.sort((a, b) => {
228
+ if (input.sortBy === "lowest_cost") return a.costPerMillionTokens - b.costPerMillionTokens;
229
+ if (input.sortBy === "highest_throughput") return b.aggregateTokensPerSecond - a.aggregateTokensPerSecond;
230
+ return (b.aggregateTokensPerSecond / Math.max(b.costPerMillionTokens, 0.001)) - (a.aggregateTokensPerSecond / Math.max(a.costPerMillionTokens, 0.001));
231
+ }).slice(0, input.limit);
232
+
233
+ return {
234
+ summary: `Compared ${results.length} GPUs for ${model.name} (${quant.label}). Cheapest: ${sorted[0]?.gpuName} at $${sorted[0]?.costPerMillionTokens}/M tokens.`,
235
+ comparisons: sorted,
236
+ totalCandidates: results.length,
237
+ sortBy: input.sortBy,
238
+ assumptions: [`Region: us-east-1 (default)`, `On-demand pricing`, `η_mem = 0.65`, `Catalog version: 0.3.0`],
239
+ };
240
+ }
241
+
242
+ function handleRecommendTopology(input: z.infer<typeof RecommendTopologySchema>) {
243
+ const model = MODEL_MAP[input.model];
244
+ const quant = QUANT_MAP[input.quantization as Quantization];
245
+ if (!model || !quant) return { error: "Unknown model or quantization" };
246
+
247
+ const results = GPUS.map(g => {
248
+ const rec = recommendTopology(model, g, input.contextTokens, input.batchSize, quant.bytesPerParam);
249
+ const maxConcurrent = computeMaxConcurrency(model, g, 1, input.contextTokens, quant.bytesPerParam);
250
+ const kvPerRequest = computeKVCacheGb(model, input.contextTokens, 1);
251
+ return {
252
+ gpuId: g.id,
253
+ gpuName: g.name,
254
+ vramGb: g.vramGb,
255
+ topology: rec.topology,
256
+ neededGpus: rec.neededGpus,
257
+ fits: rec.fits,
258
+ maxConcurrentUsers: maxConcurrent,
259
+ kvPerRequestGb: +kvPerRequest.toFixed(2),
260
+ reason: rec.reason,
261
+ };
262
+ }).filter(r => r.fits).slice(0, 5);
263
+
264
+ return {
265
+ summary: `For ${model.name} at ${fmtContext(input.contextTokens)} context: ${results.length} feasible topology options across ${GPUS.length} GPUs.`,
266
+ model: { name: model.name, paramsB: model.paramsB, activeParamsB: model.activeParamsB, isMoE: model.isMoE },
267
+ context: { tokens: input.contextTokens, label: fmtContext(input.contextTokens) },
268
+ recommendations: results,
269
+ formula: `KV per request = 2 × ${model.layers} layers × ${model.kvHeads} KV heads × ${model.headDim} head_dim × 2 bytes × ${input.contextTokens} tokens = ${computeKVCacheGb(model, input.contextTokens, 1).toFixed(2)} GB`,
270
+ assumptions: [`Single GPU unless TP needed`, `KV cache in FP16`, `Model weights + KV must fit in total VRAM`, `Catalog version: 0.3.0`],
271
+ };
272
+ }
273
+
274
+ function handleEstimateApiVsSelfHost(input: z.infer<typeof EstimateApiVsSelfHostSchema>) {
275
+ const sh = calculate({
276
+ modelId: input.model,
277
+ gpuId: input.gpu,
278
+ quantization: input.quantization as Quantization,
279
+ numGpus: input.gpuCount,
280
+ batchSize: 8,
281
+ promptTokens: input.inputTokens,
282
+ outputTokens: input.outputTokens,
283
+ });
284
+
285
+ const gpu = GPU_MAP[input.gpu];
286
+ const effGpuPrice = (gpu?.usdPerHour ?? 0) * input.gpuCount;
287
+ const effTokens = sh.aggregateTokensPerSec * (input.utilization / 100);
288
+ const selfHostCostPerM = effTokens > 0 ? (effGpuPrice / 3600 / effTokens) * 1e6 : Infinity;
289
+ const selfHostMonthly = effGpuPrice * 730;
290
+
291
+ const apiCostPerRequest = (input.inputTokens / 1e6) * input.apiInputPrice + (input.outputTokens / 1e6) * input.apiOutputPrice;
292
+ const apiMonthly = apiCostPerRequest * input.requestsPerDay * 30;
293
+ const selfHostMonthlyTotal = selfHostMonthly;
294
+
295
+ const breakEven = apiCostPerRequest > 0 ? selfHostMonthly / (30 * apiCostPerRequest) : Infinity;
296
+
297
+ const cheaper = selfHostCostPerM < input.apiOutputPrice;
298
+ const meetsVolume = input.requestsPerDay > breakEven;
299
+
300
+ return {
301
+ summary: cheaper && meetsVolume
302
+ ? `Self-hosting is cheaper at ${input.requestsPerDay.toLocaleString()} req/day. $${selfHostCostPerM.toFixed(2)}/M vs $${input.apiOutputPrice}/M API.`
303
+ : !meetsVolume
304
+ ? `Not enough volume. Need ${Math.round(breakEven).toLocaleString()} req/day to break even (currently ${input.requestsPerDay.toLocaleString()}).`
305
+ : `API is cheaper. Self-host $${selfHostCostPerM.toFixed(2)}/M vs API $${input.apiOutputPrice}/M.`,
306
+ selfHost: {
307
+ costPerMillionTokens: +selfHostCostPerM.toFixed(2),
308
+ monthlyInfraUsd: +selfHostMonthly.toFixed(2),
309
+ monthlyTotalUsd: +selfHostMonthlyTotal.toFixed(2),
310
+ utilization: `${input.utilization}%`,
311
+ throughput: `${fmtTokens(sh.aggregateTokensPerSec)} tok/s`,
312
+ },
313
+ api: {
314
+ costPerMillionTokens: input.apiOutputPrice,
315
+ monthlyUsd: +apiMonthly.toFixed(2),
316
+ model: input.apiModel,
317
+ },
318
+ breakEven: {
319
+ requestsPerDay: Math.round(breakEven),
320
+ reached: meetsVolume,
321
+ explanation: `At ${input.utilization}% utilization with ${input.gpuCount}× ${gpu?.name || input.gpu}, self-hosting breaks even at ${Math.round(breakEven).toLocaleString()} requests/day.`,
322
+ },
323
+ assumptions: [
324
+ `Self-host throughput: ${fmtTokens(sh.aggregateTokensPerSec)} tok/s at ${input.utilization}% utilization`,
325
+ `GPU price: $${effGpuPrice}/hr`,
326
+ `API pricing: $${input.apiInputPrice}/M input, $${input.apiOutputPrice}/M output`,
327
+ `730 hours/month`,
328
+ `Catalog version: 0.3.0`,
329
+ ],
330
+ };
331
+ }
332
+
333
+ function handleListModels(input: z.infer<typeof ListModelsSchema>) {
334
+ let filtered = MODELS;
335
+ if (input.family) filtered = filtered.filter(m => m.family === input.family);
336
+ if (input.category) filtered = filtered.filter(m => m.category === input.category);
337
+ if (input.isMoE !== undefined) filtered = filtered.filter(m => m.isMoE === input.isMoE);
338
+
339
+ return {
340
+ count: filtered.length,
341
+ models: filtered.map(m => ({
342
+ id: m.id,
343
+ name: m.name,
344
+ family: m.family,
345
+ category: m.category,
346
+ paramsB: m.paramsB,
347
+ activeParamsB: m.activeParamsB,
348
+ isMoE: m.isMoE,
349
+ layers: m.layers,
350
+ maxContext: m.maxContext,
351
+ })),
352
+ catalogVersion: "0.3.0",
353
+ };
354
+ }
355
+
356
+ function handleListGpus(input: z.infer<typeof ListGpusSchema>) {
357
+ let filtered = GPUS;
358
+ if (input.vendor) filtered = filtered.filter(g => g.vendor === input.vendor);
359
+ if (input.category) filtered = filtered.filter(g => g.category === input.category);
360
+ if (input.minVramGb) filtered = filtered.filter(g => g.vramGb >= input.minVramGb);
361
+
362
+ return {
363
+ count: filtered.length,
364
+ gpus: filtered.map(g => ({
365
+ id: g.id,
366
+ name: g.name,
367
+ vendor: g.vendor,
368
+ category: g.category,
369
+ memBandwidthGbps: g.memBandwidthGbps,
370
+ flopsTflops: g.flopsTflops,
371
+ vramGb: g.vramGb,
372
+ nvlinkGbps: g.nvlinkGbps,
373
+ usdPerHour: g.usdPerHour,
374
+ year: g.year,
375
+ note: g.note,
376
+ })),
377
+ catalogVersion: "0.3.0",
378
+ };
379
+ }
380
+
381
+ // ============================================================
382
+ // TOOL DEFINITIONS
383
+ // ============================================================
384
+
385
+ const TOOL_DEFINITIONS = [
386
+ {
387
+ name: "estimate_capacity",
388
+ description: "Estimate whether an LLM-serving configuration fits in memory and can meet throughput and latency targets. Returns VRAM/KV-cache breakdown, throughput and latency ranges, concurrency, cost, confidence, assumptions, and sources.",
389
+ inputSchema: formatInputSchema(EstimateCapacitySchema),
390
+ },
391
+ {
392
+ name: "compare_gpus",
393
+ description: "Compare supported GPU or cloud SKU options for the same LLM workload. Use before recommending hardware.",
394
+ inputSchema: formatInputSchema(CompareGpusSchema),
395
+ },
396
+ {
397
+ name: "recommend_topology",
398
+ description: "Recommend feasible GPU/topology designs including tensor parallelism and context parallel (RingAttention) when needed.",
399
+ inputSchema: formatInputSchema(RecommendTopologySchema),
400
+ },
401
+ {
402
+ name: "estimate_api_vs_self_host",
403
+ description: "Compare monthly token-based API costs with self-hosted GPU infrastructure under stated utilization assumptions.",
404
+ inputSchema: formatInputSchema(EstimateApiVsSelfHostSchema),
405
+ },
406
+ {
407
+ name: "list_models",
408
+ description: "List tokcalc-supported model IDs and metadata. Use before estimating if the requested model is ambiguous or unknown.",
409
+ inputSchema: formatInputSchema(ListModelsSchema),
410
+ },
411
+ {
412
+ name: "list_gpus",
413
+ description: "List GPU and cloud SKU IDs, memory, bandwidth, pricing, and categories.",
414
+ inputSchema: formatInputSchema(ListGpusSchema),
415
+ },
416
+ ];
417
+
418
+ // ============================================================
419
+ // MCP SERVER SETUP
420
+ // ============================================================
421
+
422
+ const server = new Server(
423
+ { name: "tokcalc", version: "0.1.2" },
424
+ {
425
+ capabilities: {
426
+ tools: {},
427
+ },
428
+ }
429
+ );
430
+
431
+ // Handle ListTools
432
+ server.setRequestHandler(ListToolsRequestSchema, async () => ({
433
+ tools: TOOL_DEFINITIONS,
434
+ }));
435
+
436
+ // Handle CallTool
437
+ server.setRequestHandler(CallToolRequestSchema, async (request) => {
438
+ const { name, arguments: args } = request.params;
439
+
440
+ try {
441
+ let result: unknown;
442
+
443
+ switch (name) {
444
+ case "estimate_capacity": {
445
+ const input = EstimateCapacitySchema.parse(args);
446
+ result = handleEstimateCapacity(input);
447
+ break;
448
+ }
449
+ case "compare_gpus": {
450
+ const input = CompareGpusSchema.parse(args);
451
+ result = handleCompareGpus(input);
452
+ break;
453
+ }
454
+ case "recommend_topology": {
455
+ const input = RecommendTopologySchema.parse(args);
456
+ result = handleRecommendTopology(input);
457
+ break;
458
+ }
459
+ case "estimate_api_vs_self_host": {
460
+ const input = EstimateApiVsSelfHostSchema.parse(args);
461
+ result = handleEstimateApiVsSelfHost(input);
462
+ break;
463
+ }
464
+ case "list_models": {
465
+ const input = ListModelsSchema.parse(args);
466
+ result = handleListModels(input);
467
+ break;
468
+ }
469
+ case "list_gpus": {
470
+ const input = ListGpusSchema.parse(args);
471
+ result = handleListGpus(input);
472
+ break;
473
+ }
474
+ default:
475
+ return {
476
+ content: [{ type: "text", text: `Unknown tool: ${name}` }],
477
+ isError: true,
478
+ };
479
+ }
480
+
481
+ return {
482
+ content: [
483
+ { type: "text", text: JSON.stringify(result, null, 2) },
484
+ ],
485
+ structuredContent: result,
486
+ };
487
+ } catch (error) {
488
+ return {
489
+ content: [
490
+ { type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` },
491
+ ],
492
+ isError: true,
493
+ };
494
+ }
495
+ });
496
+
497
+ // ============================================================
498
+ // START SERVER (stdio transport)
499
+ // ============================================================
500
+
501
+ const transport = new StdioServerTransport();
502
+ await server.connect(transport);
503
+
504
+ console.error("tokcalc MCP server started (stdio transport) — 6 tools available");
@@ -0,0 +1,40 @@
1
+ {
2
+ "name": "@tokcalc/mcp-server",
3
+ "version": "0.1.2",
4
+ "description": "tokcalc MCP server — open-source LLM serving capacity planner for AI agents (Cursor, Claude Desktop, Cline). 6 read-only tools: estimate_capacity, compare_gpus, recommend_topology, estimate_api_vs_self_host, list_models, list_gpus.",
5
+ "type": "module",
6
+ "license": "Apache-2.0",
7
+ "bin": {
8
+ "tokcalc-mcp": "./dist/index.js",
9
+ "tokcalc-mcp-server": "./dist/index.js",
10
+ "mcp-server": "./dist/index.js"
11
+ },
12
+ "files": [
13
+ "dist/",
14
+ "README.md"
15
+ ],
16
+ "keywords": [
17
+ "mcp",
18
+ "model-context-protocol",
19
+ "llm",
20
+ "inference",
21
+ "capacity-planner",
22
+ "gpu",
23
+ "vllm",
24
+ "h100",
25
+ "h200",
26
+ "tokcalc"
27
+ ],
28
+ "repository": {
29
+ "type": "git",
30
+ "url": "https://github.com/stevecrates489-commits/tokcalc"
31
+ },
32
+ "homepage": "https://tokcalc.vercel.app",
33
+ "engines": {
34
+ "node": ">=18"
35
+ },
36
+ "dependencies": {
37
+ "@modelcontextprotocol/sdk": "^1.30.1",
38
+ "zod-to-json-schema": "^3.25.2"
39
+ }
40
+ }
package/next.config.ts ADDED
@@ -0,0 +1,12 @@
1
+ import type { NextConfig } from "next";
2
+
3
+ const nextConfig: NextConfig = {
4
+ output: "standalone",
5
+ /* config options here */
6
+ typescript: {
7
+ ignoreBuildErrors: true,
8
+ },
9
+ reactStrictMode: false,
10
+ };
11
+
12
+ export default nextConfig;
package/package.json CHANGED
@@ -1,40 +1,97 @@
1
1
  {
2
2
  "name": "@tokcalc/mcp-server",
3
- "version": "0.1.1",
4
- "description": "tokcalc MCP server — open-source LLM serving capacity planner for AI agents (Cursor, Claude Desktop, Cline). 6 read-only tools: estimate_capacity, compare_gpus, recommend_topology, estimate_api_vs_self_host, list_models, list_gpus.",
5
- "type": "module",
6
- "license": "Apache-2.0",
7
- "bin": {
8
- "tokcalc-mcp": "./dist/index.js",
9
- "tokcalc-mcp-server": "./dist/index.js",
10
- "mcp-server": "./dist/index.js"
11
- },
12
- "files": [
13
- "dist/",
14
- "README.md"
15
- ],
16
- "keywords": [
17
- "mcp",
18
- "model-context-protocol",
19
- "llm",
20
- "inference",
21
- "capacity-planner",
22
- "gpu",
23
- "vllm",
24
- "h100",
25
- "h200",
26
- "tokcalc"
27
- ],
28
- "repository": {
29
- "type": "git",
30
- "url": "https://github.com/stevecrates489-commits/tokcalc"
31
- },
32
- "homepage": "https://tokcalc.vercel.app",
33
- "engines": {
34
- "node": ">=18"
3
+ "version": "0.1.3",
4
+ "mcpName": "io.github.stevecrates489-commits/tokcalc",
5
+ "private": false,
6
+ "scripts": {
7
+ "dev": "next dev -p 3000 2>&1 | tee dev.log",
8
+ "build": "next build",
9
+ "vercel-build": "next build",
10
+ "start": "NODE_ENV=production bun .next/standalone/server.js 2>&1 | tee server.log",
11
+ "lint": "eslint .",
12
+ "postinstall": "prisma generate || true",
13
+ "db:push": "prisma db push --accept-data-loss",
14
+ "db:generate": "prisma generate",
15
+ "db:migrate": "prisma migrate dev",
16
+ "db:reset": "prisma migrate reset"
35
17
  },
36
18
  "dependencies": {
37
- "@modelcontextprotocol/sdk": "^1.30.1",
38
- "zod-to-json-schema": "^3.25.2"
19
+ "@dnd-kit/core": "^6.3.1",
20
+ "@dnd-kit/sortable": "^10.0.0",
21
+ "@dnd-kit/utilities": "^3.2.2",
22
+ "@hookform/resolvers": "^5.1.1",
23
+ "@mdxeditor/editor": "^3.39.1",
24
+ "@prisma/client": "^6.11.1",
25
+ "@radix-ui/react-accordion": "^1.2.11",
26
+ "@radix-ui/react-alert-dialog": "^1.1.14",
27
+ "@radix-ui/react-aspect-ratio": "^1.1.7",
28
+ "@radix-ui/react-avatar": "^1.1.10",
29
+ "@radix-ui/react-checkbox": "^1.3.2",
30
+ "@radix-ui/react-collapsible": "^1.1.11",
31
+ "@radix-ui/react-context-menu": "^2.2.15",
32
+ "@radix-ui/react-dialog": "^1.1.14",
33
+ "@radix-ui/react-dropdown-menu": "^2.1.15",
34
+ "@radix-ui/react-hover-card": "^1.1.14",
35
+ "@radix-ui/react-label": "^2.1.7",
36
+ "@radix-ui/react-menubar": "^1.1.15",
37
+ "@radix-ui/react-navigation-menu": "^1.2.13",
38
+ "@radix-ui/react-popover": "^1.1.14",
39
+ "@radix-ui/react-progress": "^1.1.7",
40
+ "@radix-ui/react-radio-group": "^1.3.7",
41
+ "@radix-ui/react-scroll-area": "^1.2.9",
42
+ "@radix-ui/react-select": "^2.2.5",
43
+ "@radix-ui/react-separator": "^1.1.7",
44
+ "@radix-ui/react-slider": "^1.3.5",
45
+ "@radix-ui/react-slot": "^1.2.3",
46
+ "@radix-ui/react-switch": "^1.2.5",
47
+ "@radix-ui/react-tabs": "^1.1.12",
48
+ "@radix-ui/react-toast": "^1.2.14",
49
+ "@radix-ui/react-toggle": "^1.1.9",
50
+ "@radix-ui/react-toggle-group": "^1.1.10",
51
+ "@radix-ui/react-tooltip": "^1.2.7",
52
+ "@reactuses/core": "^6.0.5",
53
+ "@tanstack/react-query": "^5.82.0",
54
+ "@tanstack/react-table": "^8.21.3",
55
+ "class-variance-authority": "^0.7.1",
56
+ "clsx": "^2.1.1",
57
+ "cmdk": "^1.1.1",
58
+ "date-fns": "^4.1.0",
59
+ "embla-carousel-react": "^8.6.0",
60
+ "framer-motion": "^12.23.2",
61
+ "input-otp": "^1.4.2",
62
+ "lucide-react": "^0.525.0",
63
+ "next": "^16.1.1",
64
+ "next-auth": "^4.24.11",
65
+ "next-intl": "^4.3.4",
66
+ "next-themes": "^0.4.6",
67
+ "prisma": "^6.11.1",
68
+ "react": "^19.0.0",
69
+ "react-day-picker": "^9.8.0",
70
+ "react-dom": "^19.0.0",
71
+ "react-hook-form": "^7.60.0",
72
+ "react-markdown": "^10.1.0",
73
+ "react-resizable-panels": "^3.0.3",
74
+ "react-syntax-highlighter": "^15.6.1",
75
+ "recharts": "^2.15.4",
76
+ "sharp": "^0.34.3",
77
+ "sonner": "^2.0.6",
78
+ "tailwind-merge": "^3.3.1",
79
+ "tailwindcss-animate": "^1.0.7",
80
+ "uuid": "^11.1.0",
81
+ "vaul": "^1.1.2",
82
+ "z-ai-web-dev-sdk": "^0.0.18",
83
+ "zod": "^4.0.2",
84
+ "zustand": "^5.0.6"
85
+ },
86
+ "devDependencies": {
87
+ "@tailwindcss/postcss": "^4",
88
+ "@types/react": "^19",
89
+ "@types/react-dom": "^19",
90
+ "bun-types": "^1.3.4",
91
+ "eslint": "^9",
92
+ "eslint-config-next": "^16.1.1",
93
+ "tailwindcss": "^4",
94
+ "tw-animate-css": "^1.3.5",
95
+ "typescript": "^5"
39
96
  }
40
- }
97
+ }