gamekit777 0.1.0

package/studio/src/mcp.ts

@@ -0,0 +1,357 @@
+/* MCP 工具面。AI 通过它创作、校验、调参、建表、驱动预览、触发发布。
+ *
+ * 不提供文件读写——Claude Code 自带的更好用。这里只有它做不到的事。
+ * 每个工具都返回 structuredContent（给程序）+ 一段中文 markdown（给模型），
+ * 长任务默认等到结束（上限几分钟），等不完就把 jobId 交出去让它 job_status 轮询。 */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import type { Engine } from './engine.ts';
+import type { Job } from './jobs.ts';
+import type { ProbeResult } from './probe.ts';
+import { scaffold } from './scaffold.ts';
+import type { SolveReport } from './solver.ts';
+import type { TaskResult } from './tasks.ts';
+
+type ToolOut = { content: { type: 'text'; text: string }[]; structuredContent?: Record<string, unknown>; isError?: boolean };
+
+const out = (text: string, structured?: unknown): ToolOut => ({
+  content: [{ type: 'text', text }],
+  ...(structured !== undefined ? { structuredContent: JSON.parse(JSON.stringify(structured, (_k, v: unknown) => (typeof v === 'bigint' ? v.toString() : v))) as Record<string, unknown> } : {}),
+});
+const fail = (text: string): ToolOut => ({ content: [{ type: 'text', text: `✗ ${text}` }], isError: true });
+
+const pct = (ppm: number): string => `${(ppm / 1e4).toFixed(2)}%`;
+const x = (centi: number): string => `${(centi / 100).toFixed(2)}x`;
+
+const JOB_WAIT_MS = 240_000;
+
+async function awaitJob<T>(engine: Engine, job: Job<T>, render: (r: T) => string, extra?: (r: T) => unknown): Promise<ToolOut> {
+  const j = await engine.jobs.wait<T>(job.id, JOB_WAIT_MS).catch(() => job);
+  if (j.status === 'running') {
+    return out(`任务 ${j.id} 还在跑（${j.progress.at(-1) ?? ''}）。用 job_status 轮询。`, { jobId: j.id, status: 'running' });
+  }
+  if (j.status !== 'done' || j.result === null) return fail(`${j.kind} 失败：${j.error ?? '未知错误'}\n\n进度：\n${j.progress.map((p) => `  · ${p}`).join('\n')}`);
+  return out(render(j.result), extra ? extra(j.result) : j.result);
+}
+
+/* ── 渲染 ── */
+
+function renderProbe(r: ProbeResult): string {
+  const v = { 'single-table': '✅ 一张表', 'multi-table': '✅ 多张表', infeasible: '❌ 打不成表' }[r.verdict];
+  const lines = [
+    `## 打表可行性：${v}`, '', r.verdictReason, '',
+    `- config 组合：${Number(r.configCombinations).toLocaleString()}`,
+    `- 不同赔付分布：${r.distinctDistributions ?? '?'}${r.distinctIsUpperBound ? '（上界）' : ''}`,
+    `- 影响分布的字段：${r.distributionFields.join('、') || '（无）'}`,
+    `- 影响这一局但不影响分布的字段：${r.freeFields.join('、') || '（无）'}`,
+    `- modes：${r.hasModes ? `已声明（${r.modeKeys.join('、')}）` : '未声明'}`,
+    '', '### 硬门槛',
+    ...r.gates.map((g) => `- ${g.ok ? '✓' : '✗'} ${g.name}：${g.detail}`),
+  ];
+  if (r.modeIssues.length) lines.push('', '### modes 声明问题', ...r.modeIssues.map((i) => `- ${i.level === 'error' ? '❌' : '⚠️'} ${i.message}`));
+  lines.push('', '### 逐字段', '| 字段 | 取值数 | 影响分布 | 逐局变化率 | 最大σ | 备注 |', '|---|---|---|---|---|---|');
+  for (const f of r.fields) {
+    lines.push(`| ${f.key} | ${f.cardinality} | ${f.affectsDistribution === null ? '—' : f.affectsDistribution ? '是' : '否'} | ${f.perSeedChangeRate === null ? '—' : `${(f.perSeedChangeRate * 100).toFixed(0)}%`} | ${f.maxSigma?.toFixed(1) ?? '—'} | ${f.note ?? ''} |`);
+  }
+  if (r.baseline) {
+    lines.push('', '### 默认配置的分布',
+      `- ${r.baseline.distinctPayouts} 种赔付，命中率 ${pct(r.baseline.hitRatePpm)}，最大 ${x(r.baseline.maxPayoutCenti)}`,
+      `- 最稀有档位 ${x(r.baseline.rarest.payoutCenti)}，概率 ${(r.baseline.rarest.probability * 100).toFixed(4)}%——要采到 30 个样本约需 ${r.baseline.simsForRarest.toLocaleString()} 局`);
+  }
+  lines.push('', `### book 建议：\`${r.book.suggestion}\``, r.book.reason, '', `_${(r.millis / 1000).toFixed(1)}s_`);
+  return lines.join('\n');
+}
+
+function renderSolve(r: SolveReport & { mode: string; rtpRangePpm: [number, number] }): string {
+  if (r.failure) return `## ❌ 求解失败（${r.failure.kind}）\n\n${r.failure.detail}\n\n可达 RTP 区间：[${pct(r.rtpRangePpm[0])}, ${pct(r.rtpRangePpm[1])}]`;
+  const lines = [
+    `## ${r.converged ? '✅ 收敛' : '⚠️ 未收敛'}（mode ${r.mode}）`, '',
+    `- 残差 ${r.residual.toExponential(2)}，${r.iterations} 次迭代，${r.millis.toFixed(1)} ms`,
+    `- 实算 RTP ${pct(Math.round(r.achieved!.rtp * 1e6))}`,
+  ];
+  if (r.hardest) lines.push(`- 最吃力的约束：${r.hardest.label}（θ=${r.hardest.theta.toFixed(3)}）`);
+  if (r.dropped.length) lines.push(`- ⚠️ 被判冗余丢弃的约束：${r.dropped.join('、')}——这些目标没有生效`);
+  if (r.achieved!.segments.length) {
+    lines.push('', '| 段 | 命中 | RTP 份额 | 平均赢 | 中位数 | 均值/中位 |', '|---|---|---|---|---|---|');
+    for (const s of r.achieved!.segments) lines.push(`| ${s.name} | 每 ${s.hitRate.toFixed(1)} 局 | ${pct(Math.round(s.rtp * 1e6))} | ${x(s.avgWin)} | ${x(s.median)} | ${s.meanToMedian.toFixed(2)} |`);
+  }
+  if (r.thin.length) lines.push('', `⚠️ ${r.thin.length} 个档位样本不足（<30 局）：${r.thin.slice(0, 5).map((t) => `${x(t.payoutCenti)}×${t.samples}局`).join('、')}`);
+  if (r.distorted.length) lines.push(`⚠️ ${r.distorted.length} 个档位被大幅改权：${r.distorted.slice(0, 5).map((t) => `${x(t.payoutCenti)} ×${t.distortion.toFixed(1)}`).join('、')}`);
+  return lines.join('\n');
+}
+
+function renderTask(r: TaskResult): string {
+  const head = `## ${r.ok ? '✅' : '❌'} bun run ${r.task}（${(r.durationMs / 1000).toFixed(1)}s${r.timedOut ? '，超时' : ''}）`;
+  if (r.ok) return `${head}\n\n${r.output.split('\n').slice(-12).join('\n')}`;
+  return `${head}\n\n### 抽出的问题\n${r.issues.map((i) => `- ${i}`).join('\n') || '（没抽出来，看完整输出）'}\n\n### 完整输出\n\`\`\`\n${r.output}\n\`\`\``;
+}
+
+/* 客户端在 initialize 时拿到的说明。写游戏的知识不在工具描述里——工具是手，这段和游戏目录里的
+   CLAUDE.md 才是脑子。Claude Code 会自动读 cwd 的 CLAUDE.md，别的 MCP 客户端只有这一段 */
+const INSTRUCTIONS = [
+  'GameKit studio：这个 MCP 服务对应 cwd 里的一个 GameKit 游戏目录。',
+  '平台不执行游戏代码：打包时用 game.ts 里的 round() 采样出权重表，运行时按权重抽一行、查表赔付，浏览器用 restore() 还原演出。',
+  '',
+  '开始前先读游戏目录里的 CLAUDE.md（清单字段、round() 的硬约束、schema、modes/book/restore 怎么选、演出侧约定）。',
+  '没有这个文件就先调 game_info，再读 game.ts 和 src/rules/。',
+  '',
+  '工作流：改 src/rules/ 或 game.ts → run_task check/verify/test → probe_table（能不能打表、modes 写哪些键、book 怎么选）',
+  '→ preview_play 在预览里演几局 → case_add 存值得盯的局面 → build_table 建表 → publish_dry_run → publish（作者在页面确认）。',
+  '',
+  '铁律：round() 是同步纯函数、只用注入的 rng；payout 是整数分且是注额的精确线性函数；restore 返回的 payout 必须等于 (bet/100)×payoutCenti，对不上就抛。',
+  '不写 normalize/validate/modeOf，不加 meta 或版本号；已发布 mode 的解码逻辑不能改，要改就换 slug。',
+].join('\n');
+
+/* ── 注册 ── */
+
+export function createMcpServer(engine: Engine): McpServer {
+  const s = new McpServer({ name: 'gamekit-studio', version: '0.1.0' }, { instructions: INSTRUCTIONS });
+  const modesArg = z.array(z.string()).optional().describe('只处理这些 mode；不给就是全部');
+
+  s.registerTool('game_info', {
+    description: '当前游戏目录的全貌：清单（slug / rtp / sims / modes / book）、schema、规则指纹、已建的表、预览连接状态、studio 页面地址。AI 的第一跳。',
+    inputSchema: {},
+  }, async () => {
+    const i = await engine.info();
+    const sn = i.snapshot;
+    const sp = sn.spec;
+    const lines = [
+      `## ${sp.title}（${sp.slug}）`, '',
+      `- 目录：${i.gameDir}`, `- 规则指纹 ${i.fingerprint}`,
+      `- 目标 RTP ${(sp.rtp * 100).toFixed(2)}%，每表采样 ${sp.sims} 局，book ${sp.book}，autoplay ${sp.autoplay ? '开' : '关'}`,
+      `- modes：${sp.modeKeys.length ? `${sp.modes.length} 个，由 ${sp.modeKeys.join('、')} 决定` : '单表 base'}`,
+      `- 已建的表（当前指纹）：${i.artifacts.length ? i.artifacts.map((a) => `${a.mode}(${pct(a.computedRtpPpm)})`).join('、') : '无'}`,
+      `- case：${i.cases} 条（${i.caseFile}）`,
+      `- 预览：${i.previewConnected ? '已连接' : '未连接'}——页面 ${i.urls.studio}`,
+      '', '### schema', '| 字段 | 类型 | 默认 | 影响结果 | 渲染 | devOnly |', '|---|---|---|---|---|---|',
+    ];
+    const guide = existsSync(join(i.gameDir, 'CLAUDE.md'));
+    const tail = ['', '### 下一步',
+      guide ? `- 先读 ${join(i.gameDir, 'CLAUDE.md')}：清单字段、round() 的硬约束、modes/book/restore 怎么选、演出侧约定`
+        : '- 这个目录没有 CLAUDE.md（写给 AI 的开发指南）。读 game.ts 和 src/rules/ 之前先记住：round() 纯函数只用注入 rng，payout 整数分，restore 的 payout 必须等于 (bet/100)×payoutCenti',
+      '- 改了规则先 run_task verify，再 probe_table 看 modes / book 该怎么写，然后 preview_play'];
+    for (const [k, f] of Object.entries(sn.schema)) {
+      const range = f.kind === 'int' || f.kind === 'number' ? `${f.min}..${f.max}` : f.kind === 'enum' ? f.options.map((o) => o.value).join('/') : f.kind === 'pick' ? `从 ${f.of.length} 选 ${f.count}` : '';
+      lines.push(`| ${k} | ${f.kind} ${range} | ${JSON.stringify(f.default)} | ${f.affectsOutcome ? '是' : '否'} | ${f.ui} | ${f.devOnly ? '是' : ''} |`);
+    }
+    lines.push(...tail);
+    return out(lines.join('\n'), { ...i, guide: guide ? join(i.gameDir, 'CLAUDE.md') : null });
+  });
+
+  s.registerTool('scaffold', {
+    description: '在当前目录下新建一个游戏（一个能跑的抛硬币），写好 package.json 并 bun install。之后请在那个目录里重启 studio。',
+    inputSchema: {
+      id: z.string().describe('小写短横线形式，同时是包名、目录名和 CSS 命名空间'),
+      title: z.string().optional(),
+      dest: z.string().optional().describe('目标目录，默认 <cwd>/<id>'),
+    },
+  }, async (a) => {
+    try {
+      const r = await scaffold({ id: a.id, title: a.title, dest: a.dest }, process.cwd());
+      return out(`## ✅ 已生成 ${r.dest}\n\n${r.files} 个文件，依赖${r.installed ? '已装' : '未装'}。\n\n${r.next.map((n) => `- ${n}`).join('\n')}`, r);
+    } catch (e) { return fail(e instanceof Error ? e.message : String(e)); }
+  });
+
+  s.registerTool('run_task', {
+    description: '在游戏目录里跑 bun run check / test / verify / build，返回结构化的失败信息。',
+    inputSchema: { task: z.enum(['check', 'test', 'verify', 'build']) },
+  }, async (a) => awaitJob(engine, engine.task(a.task), renderTask));
+
+  s.registerTool('probe_table', {
+    description: '打表可行性探测：数 config 组合、逐字段判是否影响赔付分布、数不同分布有几种、校验 modes 声明、给 book 编码建议。改了 rules/ 之后都该跑一遍。',
+    inputSchema: {
+      sims: z.number().int().min(1000).max(200_000).optional().describe('每个取值采多少局，默认 20000'),
+      maxValuesPerField: z.number().int().min(2).max(8).optional(),
+    },
+  }, async (a) => awaitJob(engine, engine.probe(a), renderProbe));
+
+  s.registerTool('sample', {
+    description: '按清单的 modes 采样并缓存（按规则指纹）。建表和调参都会自动采，这个工具只是预热。',
+    inputSchema: { modes: modesArg, sims: z.number().int().optional() },
+  }, async (a) => awaitJob(engine, engine.sample(a.modes ?? null, a.sims ?? null), (r) => `已采样 ${r.modes.join('、')}，每个 ${r.sims} 局`));
+
+  s.registerTool('solve_params', {
+    description: '调参：给 RTP 和分段目标（命中率 / RTP 份额 / 波动率），毫秒级返回权重与实算报告。不建表。分段必须按赔付区间划分。',
+    inputSchema: {
+      mode: z.string().optional().describe('不给就是第一个 mode'),
+      sims: z.number().int().optional(),
+      totalRtpPpm: z.number().int().describe('目标总 RTP，ppm，如 970000'),
+      segments: z.array(z.object({
+        name: z.string(),
+        payoutRange: z.tuple([z.number(), z.number()]).describe('赔付区间 [lo, hi]，centi'),
+        oneIn: z.number().optional().describe('每 N 局中一次'),
+        rtpPpm: z.number().int().optional().describe('该段的 RTP 份额，ppm'),
+        meanToMedian: z.tuple([z.number(), z.number()]).optional().describe('波动率：均值/中位数 区间'),
+      })).default([]),
+    },
+  }, async (a) => {
+    try {
+      const r = await engine.solve(a.mode ?? null, a.sims ?? null, { totalRtpPpm: a.totalRtpPpm, segments: a.segments });
+      return out(renderSolve(r), r);
+    } catch (e) { return fail(e instanceof Error ? e.message : String(e)); }
+  });
+
+  s.registerTool('build_table', {
+    description: '建表：采样（缓存）→ 求解 → 量化 → 编码 → 本地终验 → 落盘到 .studio/build/<指纹>/。预览的表模型和发布上传吃同一份产物。',
+    inputSchema: {
+      modes: modesArg,
+      sims: z.number().int().optional(),
+      rtpPpm: z.number().int().optional().describe('覆盖目标 RTP'),
+      segments: z.array(z.object({ name: z.string(), members: z.array(z.number().int()), mass: z.number().optional(), rtp: z.number().optional(), median: z.number().optional() })).optional()
+        .describe('solve_params 返回的 segments，原样带过来'),
+    },
+  }, async (a) => awaitJob(engine, engine.build(a.modes ?? null, { sims: a.sims, declaredRtpPpm: a.rtpPpm, segments: a.segments }), (arts) =>
+    [`## ✅ 建好 ${arts.length} 张表`, '', '| mode | 行数 | 声明 RTP | 实算 RTP | 最大赔付 | 命中率 | sha256 |', '|---|---|---|---|---|---|---|',
+      ...arts.map((t) => `| ${t.mode} | ${t.rowCount.toLocaleString()} | ${pct(t.declaredRtpPpm)} | ${pct(t.computedRtpPpm)} | ${x(t.maxPayoutCenti)} | ${pct(t.hitRatePpm)} | ${t.contentHash.slice(0, 12)}… |`),
+      ...(arts.some((t) => t.stats.thin.length) ? ['', `⚠️ 有档位样本不足：${arts.flatMap((t) => t.stats.thin.map((p) => `${t.mode} ${x(p.payoutCenti)}×${p.samples}`)).slice(0, 8).join('、')}`] : []),
+    ].join('\n')));
+
+  s.registerTool('publish_dry_run', {
+    description: '发布前体检（本地部分）：当前指纹下有哪些表、最低实算 RTP 是否低于声明。登录态和 slug 占用要在 studio 页面上看。',
+    inputSchema: { modes: modesArg },
+  }, async (a) => {
+    const i = await engine.info();
+    const arts = i.artifacts.filter((t) => !a.modes || a.modes.includes(t.mode));
+    const spec = i.snapshot.spec;
+    const declared = Math.round(spec.rtp * 1e6);
+    const issues: string[] = [];
+    if (arts.length === 0) issues.push('当前指纹下没有任何已建的表——先 build_table');
+    const missing = spec.modes.filter((m) => !arts.some((t) => t.mode === m.name)).map((m) => m.name);
+    if (missing.length && !a.modes) issues.push(`这些 mode 还没建表：${missing.join('、')}`);
+    const lowest = arts.reduce<number | null>((m, t) => (m === null || t.computedRtpPpm < m ? t.computedRtpPpm : m), null);
+    if (lowest !== null && lowest + 100 < declared) issues.push(`游戏声明 ${pct(declared)}，但最低的表只有 ${pct(lowest)}——大厅里的声明不能高于任何一个 mode 实际能给的，发布会被拒`);
+    const ok = issues.length === 0;
+    return out([`## ${ok ? '✅ 本地体检通过' : '❌ 本地体检有问题'}`, '', ...(ok ? [`${arts.length} 张表就绪：${arts.map((t) => t.mode).join('、')}`] : issues.map((x) => `- ${x}`)),
+      '', '登录态、slug 是否被占、哪些 mode 已经锁死——这些要连平台才知道，在 studio 页面的「发布」面板里看。'].join('\n'),
+      { ok, issues, artifacts: arts.map((t) => ({ mode: t.mode, computedRtpPpm: t.computedRtpPpm, rows: t.rowCount })) });
+  });
+
+  s.registerTool('publish', {
+    description: '请求发布。上传要用作者在 studio 页面上登录的身份，所以这里只是把请求排进页面的待审批队列，作者点确认后才真正上传。发布不可逆。',
+    inputSchema: { modes: modesArg, note: z.string().optional().describe('给作者看的说明') },
+  }, async (a) => {
+    const req = engine.requestPublish(a.modes ?? null, a.note ?? null, 'mcp');
+    const t0 = Date.now();
+    while (Date.now() - t0 < 120_000) {
+      const cur = engine.publishRequests().find((r) => r.id === req.id)!;
+      if (cur.status !== 'awaiting-approval' && cur.status !== 'running') {
+        return out(`## 发布请求 ${cur.id}：${cur.status}\n\n${cur.progress.map((p) => `- ${p}`).join('\n')}${cur.error ? `\n\n错误：${cur.error}` : ''}`, cur);
+      }
+      await new Promise((r) => setTimeout(r, 1000));
+    }
+    return out(`## 发布请求 ${req.id} 等待作者确认\n\n请作者打开 ${engine.urls.studio} 的「发布」面板点确认。之后用 job_status 不行，用 publish_dry_run 或 game_info 看状态。`, req);
+  });
+
+  s.registerTool('preview_state', {
+    description: '预览页的当前状态：连没连、当前 config / mode / 注额 / 余额、已加载的表、最近几局、控制台报错。',
+    inputSchema: {},
+  }, async () => {
+    engine.touch();
+    const p = engine.preview;
+    if (!engine.bus.previewConnected) return out(`预览页没连着。请在浏览器打开 ${engine.urls.studio}`, { connected: false });
+    return out([`## 预览（本地表模型）`, `- mode ${p.mode}，注额 ${p.bet}，余额 ${p.balance}`, `- config ${JSON.stringify(p.config)}`,
+      `- 最近 ${p.recent.length} 局`, ...(p.lastError ? [`- ⚠️ 最近错误：${p.lastError}`] : []),
+      ...(p.consoleErrors.length ? ['', '### 控制台报错', ...p.consoleErrors.slice(-5).map((e) => `- ${e}`)] : [])].join('\n'), p);
+  });
+
+  s.registerTool('preview_set', {
+    description: '改预览的设置：config、注额、客户端种子、造型、极速。局中/自动中会被平台否决，rejected 里会说。',
+    inputSchema: {
+      config: z.record(z.string(), z.unknown()).optional(),
+      bet: z.number().int().optional().describe('最小货币单位（分）'),
+      clientSeed: z.string().optional(),
+      skin: z.string().optional(),
+      turbo: z.boolean().optional(),
+    },
+  }, async (a) => {
+    try {
+      const r = await engine.previewCommand<{ applied: string[]; rejected: { key: string; reason: string }[] }>({ t: 'set', ...a });
+      return out(`应用：${r.applied.join('、') || '（无）'}${r.rejected.length ? `\n否决：${r.rejected.map((x) => `${x.key}（${x.reason}）`).join('、')}` : ''}`, r);
+    } catch (e) { return fail(e instanceof Error ? e.message : String(e)); }
+  });
+
+  s.registerTool('preview_play', {
+    description: '在预览里演几局并拿回每局结果（本地表模型：就地建表、按权重抽行、restore 还原）。给 seed 就复现那一局，给 simId 就直接演表里第 N 行。animate=false 跳过动画。',
+    inputSchema: {
+      rounds: z.number().int().min(1).max(50).default(1),
+      bet: z.number().int().optional(),
+      seed: z.object({ server: z.string(), client: z.string(), nonce: z.number().int() }).optional(),
+      simId: z.number().int().optional(),
+      animate: z.boolean().default(true),
+    },
+  }, async (a) => {
+    try {
+      const r = await engine.previewCommand<{ rounds: { payout: number; multiplier: number; payoutCenti: number; mode: string; checks: { label: string; ok: boolean }[]; simId: number | null; seed: unknown }[]; wallet: { balance: number }; errors: string[] }>({ t: 'play', ...a }, 30_000 + a.rounds * 8_000);
+      const lines = [`## 演了 ${r.rounds.length} 局，余额 ${r.wallet.balance}`, '', '| # | mode | 倍数 | 赔付 | 校验 | simId |', '|---|---|---|---|---|---|'];
+      r.rounds.forEach((x, i) => lines.push(`| ${i + 1} | ${x.mode} | ${x.multiplier.toFixed(2)}x | ${x.payout} | ${x.checks.every((c) => c.ok) ? '✓' : '✗ ' + x.checks.filter((c) => !c.ok).map((c) => c.label).join('、')} | ${x.simId ?? ''} |`));
+      if (r.errors.length) lines.push('', '### 错误', ...r.errors.map((e) => `- ${e}`));
+      return out(lines.join('\n'), r);
+    } catch (e) { return fail(e instanceof Error ? e.message : String(e)); }
+  });
+
+  s.registerTool('case_list', { description: '列出 studio/cases.jsonl 里的 case。', inputSchema: {} }, async () => {
+    const cs = engine.cases.list();
+    return out(cs.length ? ['| id | 标题 | 定位 | 期望 |', '|---|---|---|---|', ...cs.map((c) => `| ${c.id} | ${c.title} | ${c.table ? `表 ${c.table.mode}#${c.table.simId}` : ''}${c.seed ? ' 种子' : ''} | ${x(c.expect.payoutCenti)} |`)].join('\n') : '还没有 case。用 case_add 或在预览里「存为 case」。', { cases: cs });
+  });
+
+  s.registerTool('case_add', {
+    description: '记一条 case：给 config + （seed 或 table:{mode,simId}），studio 跑一遍算出期望值存进 cases.jsonl。作者点播、AI 单测、结果漂移护栏三用。',
+    inputSchema: {
+      title: z.string(), tags: z.array(z.string()).optional(), note: z.string().optional(),
+      config: z.record(z.string(), z.unknown()), bet: z.number().int().default(100),
+      seed: z.object({ server: z.string(), client: z.string(), nonce: z.number().int() }).optional(),
+      table: z.object({ mode: z.string(), simId: z.number().int() }).optional(),
+    },
+  }, async (a) => {
+    try {
+      const rec = await engine.caseAdd({ ...a, origin: 'mcp' });
+      return out(`## ✅ 已记 case ${rec.id}「${rec.title}」\n\n期望 ${x(rec.expect.payoutCenti)}，outcomeHash ${rec.expect.outcomeHash ?? '-'}，restoreHash ${rec.expect.restoreHash ?? '-'}`, rec);
+    } catch (e) { return fail(e instanceof Error ? e.message : String(e)); }
+  });
+
+  s.registerTool('case_run', {
+    description: '跑 case：直接跑 round() 比 payout + outcomeHash，表模型走 restore 比 payout + restoreHash。任何结果变化都是 fail——有意改规则就 case_bless 接受（前提是这个 mode 没发布过）。顺带验 rules/ 没偷用随机源。',
+    inputSchema: { ids: z.array(z.string()).optional(), model: z.enum(['formula', 'table', 'both']).default('both') },
+  }, async (a) => {
+    try {
+      const r = await engine.caseRun(a);
+      const lines = [`## ${r.fail || r.error ? '❌' : '✅'} ${r.total} 条：${r.pass} 过，${r.fail} 败，${r.skipped} 跳过，${r.error} 错`, ''];
+      for (const x of r.results) if (x.status !== 'pass') lines.push(`- **${x.status}** ${x.id}「${x.title}」[${x.model}]：${x.detail}`);
+      if (r.fail) lines.push('', 'fail 的那些：结果变了。是 bug 就修；是有意改的规则且这个 mode 没发布过，用 case_bless 接受；已发布过的 mode 解码逻辑不能改，要改就换 slug。');
+      return out(lines.join('\n'), r);
+    } catch (e) { return fail(e instanceof Error ? e.message : String(e)); }
+  });
+
+  s.registerTool('case_bless', {
+    description: '接受 fail case 的新结果（用当前代码重跑，把期望值更新）。这是显式的确认动作——只对没发布过的 mode 这么做。',
+    inputSchema: { ids: z.array(z.string()).min(1) },
+  }, async (a) => {
+    try {
+      const r = await engine.caseRun({ ids: a.ids, model: 'both' });
+      const byId = new Map<string, { payoutCenti: number; outcomeHash?: string; restoreHash?: string }>();
+      for (const x of r.results) if (x.actual) byId.set(x.id, { ...(byId.get(x.id) ?? { payoutCenti: x.actual.payoutCenti }), ...x.actual });
+      const n = engine.cases.bless([...byId].map(([id, actual]) => {
+        const old = engine.cases.get(id)!;
+        return { id, expect: { ...old.expect, ...actual } };
+      }));
+      return out(`已更新 ${n} 条 case 的期望值`, { blessed: n });
+    } catch (e) { return fail(e instanceof Error ? e.message : String(e)); }
+  });
+
+  s.registerTool('job_status', { description: '查长任务。', inputSchema: { id: z.string() } }, async (a) => {
+    const j = engine.jobs.get(a.id);
+    if (!j) return fail(`没有 job ${a.id}`);
+    return out(`## ${j.kind} ${j.id}：${j.status}\n\n${j.progress.map((p) => `- ${p}`).join('\n')}${j.error ? `\n\n错误：${j.error}` : ''}`, j);
+  });
+
+  return s;
+}
+
+export async function serveStdio(engine: Engine): Promise<McpServer> {
+  const server = createMcpServer(engine);
+  await server.connect(new StdioServerTransport());
+  return server;
+}