@tanqory/dev-mcp 0.0.0-stage → 0.1.0

package/src/server.mjs

@@ -0,0 +1,595 @@
+/**
+ * @tanqory/dev-mcp: the local MCP server for theme development (SPEC §3A). Knowledge and eyes for a coding agent
+ * that already has a shell: docs and schemas matched to the theme's installed packages, kit examples, a two-step
+ * section scaffold, the CLI's checks as structured JSON, and pages and screenshots of the running dev server.
+ *
+ * It never calls a model, never takes a store id (the store comes from tanqory.config.json and the CLI login), never
+ * publishes anything, and writes only inside the open theme, only after a confirmed plan.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { Browser, BrowserUnavailable, VIEWPORTS } from './browser.mjs'
+import { CliError, runCli } from './cli.mjs'
+import { DOCS, DocCorpus } from './docs.mjs'
+import { DevServerError, devGet, readDevServer, requireDevServer } from './devserver.mjs'
+import { kitCatalogue, kitExamples } from './kit.mjs'
+import { registerPrompts } from './prompts.mjs'
+import { LAYOUTS, ScaffoldError, planSection, writeSection } from './scaffold.mjs'
+import { SCHEMA_KINDS, getSchema } from './schemas.mjs'
+import { loadTheme } from './theme.mjs'
+import { validateManifestFile } from './manifest.mjs'
+
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+
+const INSTRUCTIONS = `Tanqory theme development (Theme ABI v2). Use these tools, not only the shell, for every theme change:
+1. Start the dev server in the background and keep it running: \`npm run dev -- --mock\` (plain \`npm run dev\` when signed in). dev_server_status says when it is up.
+2. New section: scaffold_section (plan, then confirm with the planDigest). Kit APIs: search_docs / get_kit_example, not node_modules.
+3. Look at your work: screenshot (desktop and mobile, th and en) and get_page (HTML + console errors).
+4. Verify with check_theme, not \`npm run check\`: fix every failure it reports, including ones you did not cause, until passed is true.
+5. Stop the dev server with \`npm run dev -- --stop\` (the pid in .tanqory/dev-server.json). Never pkill, killall or a pid found by name.
+You are not done until check_theme passes and you have seen the change in a screenshot. Every storefront function (cart, variants, search, filters, markets, forms, SEO, i18n, live edit) comes from @tanqory/theme-kit; the theme owns markup and CSS. This server never calls a model, never takes a store id and never publishes.`
+
+const errorSchema = z.object({ code: z.string(), message: z.string(), hint: z.string().optional() }).passthrough()
+const base = { ok: z.boolean().describe('false when the tool could not do what was asked; see error'), error: errorSchema.optional() }
+
+const json = (v) => JSON.stringify(v, null, 2)
+const done = (structured, text) => ({ content: [{ type: 'text', text: text ?? json(structured) }], structuredContent: { ok: true, ...structured } })
+const fail = (code, message, hint, extra = {}) => {
+  const error = { code, message, ...(hint ? { hint } : {}), ...extra }
+  return { isError: true, content: [{ type: 'text', text: `${code}: ${message}${hint ? `\nWhat to do: ${hint}` : ''}` }], structuredContent: { ok: false, error } }
+}
+const fromError = (e) => {
+  if (e instanceof CliError || e instanceof DevServerError || e instanceof ScaffoldError || e instanceof BrowserUnavailable) {
+    const { code, hint, message, ...rest } = e
+    const extra = {}
+    for (const k of ['stderr', 'exitCode', 'planDigest', 'written']) if (rest[k] !== undefined) extra[k] = rest[k]
+    return fail(code, message, hint, extra)
+  }
+  return fail('internal_error', e?.message ?? String(e), 'This is a bug in @tanqory/dev-mcp; the message above says where.')
+}
+const guard = (fn) => async (args, extra) => {
+  try {
+    return await fn(args ?? {}, extra)
+  } catch (e) {
+    return fromError(e)
+  }
+}
+
+const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+
+const failureSchema = z
+  .object({
+    tier: z.string(),
+    checkId: z.string(),
+    route: z.string().optional(),
+    locale: z.string().optional(),
+    message: z.string(),
+    hint: z.string().optional(),
+    file: z.string().optional(),
+    line: z.number().optional(),
+  })
+  .passthrough()
+
+/** Shape a `theme check --json` envelope into the tool result. */
+function checkResult(env, requestedTier) {
+  if (!env.data && env.error) return fail(env.error.code ?? 'check_failed', env.error.message ?? 'theme check failed', env.error.hint ?? 'Run `tanqory theme check` in a terminal for the full output.', { stderr: env.stderrTail })
+  const data = env.data ?? {}
+  const failures = Array.isArray(data.failures) ? data.failures : []
+  const shown = failures.slice(0, 60)
+  const tiers = data.tiers ?? {}
+  const passed = env.ok && failures.length === 0
+  const lines = [
+    `tanqory theme check${requestedTier ? ` --tier ${requestedTier}` : ''}: ${passed ? 'PASSED' : `FAILED (${failures.length} failure${failures.length === 1 ? '' : 's'})`}`,
+    ...Object.entries(tiers).map(([t, v]) => `  ${t}: ${typeof v === 'object' && v ? (v.passed === true ? 'passed' : v.passed === false ? 'failed' : json(v)) : String(v)}`),
+    ...shown.map((f) => `- [${f.tier}] ${f.checkId}${f.file ? ` ${f.file}${f.line ? `:${f.line}` : ''}` : ''}${f.route ? ` route ${f.route}` : ''}${f.locale ? ` (${f.locale})` : ''}: ${f.message}${f.hint ? `\n    fix: ${f.hint}` : ''}`),
+    ...(failures.length > shown.length ? [`… ${failures.length - shown.length} more (structuredContent.failures is complete)`] : []),
+    ...(passed
+      ? ['Next: if you have not looked at your change yet, call screenshot on the page you changed (viewport desktop and mobile). Stop the dev server with `npm run dev -- --stop` when you are finished, never pkill.']
+      : ['Fix every failure above, including ones you did not cause (look a check up with search_docs {query: "<checkId>"}), then call check_theme again.']),
+  ]
+  return {
+    content: [{ type: 'text', text: lines.join('\n') }],
+    structuredContent: { ok: true, passed, tiers, failures, failureCount: failures.length, ...(env.error ? { cliError: env.error } : {}) },
+  }
+}
+
+/**
+ * @param {{ cwd?: string, cli?: { command: string, args?: string[], via?: string }, log?: (msg: string) => void }} [options]
+ */
+export function createTanqoryMcpServer(options = {}) {
+  const cwd = options.cwd ?? process.cwd()
+  const log = options.log ?? ((m) => process.stderr.write(`[tanqory-mcp] ${m}\n`))
+  const theme = loadTheme(cwd)
+  const corpus = new DocCorpus(theme)
+  const browser = new Browser(theme.root, log)
+  const cliOpts = { root: theme.root, cli: options.cli }
+  const server = new McpServer({ name: 'tanqory', title: 'Tanqory theme development', version: VERSION }, { instructions: INSTRUCTIONS, capabilities: { logging: {} } })
+
+  const needTheme = () => {
+    if (!theme.root) throw new ScaffoldError('no_theme', 'No theme is open: this server was started outside a theme folder.', 'Start the agent in the theme root (the folder with tanqory.config.json), or set TANQORY_THEME_DIR.')
+    return theme.root
+  }
+
+  // ── docs ──────────────────────────────────────────────────────────────────
+  server.registerTool(
+    'search_docs',
+    {
+      title: 'Search the theme platform docs',
+      description:
+        "Full-text search (BM25, offline, deterministic) over the docs that match this theme's installed packages: the Theme ABI v2 contract, the kit's headless API, the storefront-tier check spec, the manifest / field-type / limits / capabilities references, the kit strings and this theme's AGENTS.md. Use it before writing code and to look up a failing check id. Returns ranked sections with a snippet and a `path` to pass to get_doc. Never uses the network.",
+      inputSchema: {
+        query: z.string().min(1).max(400).describe('Words to find, e.g. "variant picker ?variant=", "cart:add hook", "editor:live-edit", "data:inventory"'),
+        limit: z.number().int().min(1).max(20).optional().describe('How many results (default 8)'),
+      },
+      outputSchema: {
+        ...base,
+        results: z.array(z.object({ path: z.string(), title: z.string(), document: z.string(), score: z.number(), snippet: z.string(), source: z.string(), version: z.string().nullable() })).optional(),
+      },
+      annotations: READ,
+    },
+    guard(async ({ query, limit }) => {
+      const results = await corpus.search(query, limit ?? 8)
+      const text = results.length
+        ? results.map((r, i) => `${i + 1}. ${r.title} — ${r.document}\n   path: ${r.path}  (${r.source}${r.version ? ` ${r.version}` : ''})\n   ${r.snippet.replace(/\n/g, '\n   ')}`).join('\n')
+        : `No match for "${query}". Try other words, or list the documents with get_doc {path: "index"}.`
+      return done({ results }, text)
+    }),
+  )
+
+  server.registerTool(
+    'get_doc',
+    {
+      title: 'Read a doc or one section of it',
+      description:
+        'Read a document from the docs corpus by path: a document id (e.g. "kit/headless-api", "abi/contract", "conformance/storefront-tier", "abi/field-types", "theme/agents") or one section of it ("abi/contract#7-3-editor-contract"), as returned by search_docs. Path "index" lists every document. Long documents are paginated: pass nextOffset back as offset. The answer names its source: "installed" (the theme\'s node_modules, matches the versions it builds with) or "bundled" (this package\'s copy, used when the installed package lacks the file).',
+      inputSchema: {
+        path: z.string().min(1).describe('A doc id, doc#section, a tanqory://docs/… URI, or "index"'),
+        offset: z.number().int().min(0).optional().describe('Character offset to continue from (nextOffset of the previous call)'),
+        maxChars: z.number().int().min(500).max(40000).optional().describe('Characters to return (default 12000)'),
+      },
+      outputSchema: {
+        ...base,
+        path: z.string().optional(),
+        title: z.string().optional(),
+        source: z.string().optional(),
+        package: z.string().nullable().optional(),
+        version: z.string().nullable().optional(),
+        installedVersion: z.string().nullable().optional(),
+        totalChars: z.number().optional(),
+        offset: z.number().optional(),
+        nextOffset: z.number().nullable().optional(),
+        text: z.string().optional(),
+        sections: z.array(z.string()).optional(),
+        documents: z.array(z.object({ path: z.string(), title: z.string(), summary: z.string(), source: z.string(), package: z.string().nullable(), version: z.string().nullable(), sections: z.number(), uri: z.string() })).optional(),
+      },
+      annotations: READ,
+    },
+    guard(async ({ path, offset, maxChars }) => {
+      if (path === 'index' || path === '') {
+        const documents = await corpus.list()
+        return done({ documents }, documents.map((d) => `${d.path} — ${d.title} (${d.source}${d.version ? ` ${d.version}` : ''}, ${d.sections} sections)\n  ${d.summary}`).join('\n'))
+      }
+      const r = await corpus.get(path, { offset: offset ?? 0, maxChars: maxChars ?? 12000 })
+      if (r.error === 'unknown_doc') return fail('unknown_doc', `No document "${path}".`, `Known documents: ${r.known.join(', ')}.`)
+      if (r.error === 'unknown_section') return fail('unknown_section', `No section "${path}".`, `Sections: ${r.known.slice(0, 60).join(', ')}`)
+      const head = `# ${r.title}\n(${r.path} · ${r.source}${r.package ? ` ${r.package}@${r.version}` : ''}${r.source === 'bundled' && r.installedVersion && r.installedVersion !== r.version ? ` · the theme has ${r.installedVersion} installed; this copy may differ` : ''} · chars ${r.offset}–${r.offset + r.text.length} of ${r.totalChars}${r.nextOffset !== null ? ` · continue with offset ${r.nextOffset}` : ''})\n\n`
+      return done(r, head + r.text)
+    }),
+  )
+
+  server.registerTool(
+    'get_schema',
+    {
+      title: 'Get a schema a theme author writes against',
+      description: `The exact shape of one thing a theme declares or produces, from the installed packages: ${SCHEMA_KINDS.map((k) => `"${k}"`).join(', ')}. "section"/"block" give the defineSection/defineBlock TypeScript declarations plus the manifest component schema; "field-registry" every setting type with its stored value and constraints; "locale" the locales/<lang>.json shape and the kit's own keys; "content-document" templates/*.json and regions/*.json. Read-only.`,
+      inputSchema: { kind: z.enum(SCHEMA_KINDS).describe('Which schema') },
+      outputSchema: { ...base, kind: z.string().optional(), source: z.string().nullable().optional(), version: z.string().nullable().optional(), schema: z.any().optional(), types: z.string().nullable().optional(), registry: z.string().nullable().optional(), kitKeys: z.array(z.string()).optional(), notes: z.array(z.string()).optional() },
+      annotations: READ,
+    },
+    guard(async ({ kind }) => {
+      const r = await getSchema(corpus, kind)
+      if (!r) return fail('unknown_kind', `No schema "${kind}".`, `One of: ${SCHEMA_KINDS.join(', ')}.`)
+      return done(r)
+    }),
+  )
+
+  // ── kit ───────────────────────────────────────────────────────────────────
+  const catalogue = async () => {
+    const d = DOCS.find((x) => x.id === 'kit/headless-api')
+    const ex = DOCS.find((x) => x.id === 'kit/exports')
+    const docText = await corpus.read(d)
+    const exportsText = await corpus.read(ex)
+    return kitCatalogue({ docText: docText?.text, exportsDts: exportsText?.text, installedVersion: theme.versions['@tanqory/theme-kit'], source: docText?.source })
+  }
+
+  server.registerTool(
+    'list_kit_components',
+    {
+      title: 'List the kit API',
+      description:
+        "Every hook, primitive, declaration helper and AI role of @tanqory/theme-kit (headless), from the installed kit's docs and export list: name, kind, signature, what it renders and does. Use it to find the kit piece for a storefront function before writing any of your own (cart, variants, filters, search, localization, forms, consent, SEO). Then get_kit_example {name} for real code.",
+      inputSchema: { kind: z.enum(['hook', 'primitive', 'declaration', 'helper', 'ai-role', 'entry', 'build']).optional().describe('Only this kind') },
+      outputSchema: {
+        ...base,
+        kitVersion: z.string().nullable().optional(),
+        docSource: z.string().nullable().optional(),
+        components: z.array(z.object({ name: z.string(), kind: z.string(), signature: z.string(), summary: z.string(), importFrom: z.string(), exported: z.boolean().nullable() })).optional(),
+        undocumentedExports: z.array(z.string()).optional(),
+      },
+      annotations: READ,
+    },
+    guard(async ({ kind }) => {
+      const c = await catalogue()
+      const components = kind ? c.components.filter((x) => x.kind === kind) : c.components
+      const text = [`@tanqory/theme-kit ${c.kitVersion ?? '(not installed: bundled docs)'} — ${components.length} entries`, ...components.map((x) => `- ${x.name} [${x.kind}] ${x.signature}\n    ${x.summary}`), c.undocumentedExports.length ? `Also exported (see kit/exports): ${c.undocumentedExports.join(', ')}` : ''].join('\n')
+      return done({ ...c, components }, text)
+    }),
+  )
+
+  server.registerTool(
+    'get_kit_example',
+    {
+      title: 'Real code using a kit API',
+      description:
+        "Working snippets that use one kit API (e.g. ProductForm, VariantPicker, FacetFilters, CartDrawer, NewsletterForm, useCollection, defineSection, field): first from this theme's own src/, then from the Blank starter that `npm create tanqory-theme` writes (code that builds and passes every check). Each snippet is the whole enclosing declaration with its file and line numbers, plus the kit's description of the API.",
+      inputSchema: { name: z.string().min(1).max(80).describe('Kit name, e.g. "VariantPicker", "useCart", "defineSection", "ai.hero"'), limit: z.number().int().min(1).max(4).optional().describe('Snippets per source (default 2)') },
+      outputSchema: {
+        ...base,
+        name: z.string().optional(),
+        api: z.any().optional(),
+        examples: z.array(z.object({ origin: z.string(), file: z.string(), startLine: z.number(), endLine: z.number(), import: z.string().nullable(), code: z.string() })).optional(),
+      },
+      annotations: READ,
+    },
+    guard(async ({ name, limit }) => {
+      const c = await catalogue()
+      const api = c.components.find((x) => x.name.toLowerCase() === name.toLowerCase()) ?? null
+      const canonical = api?.name ?? name
+      const examples = kitExamples({ name: canonical, themeRoot: theme.root, limit: limit ?? 2 })
+      if (!api && !examples.length) return fail('unknown_kit_name', `"${name}" is not a kit API this server knows and no code uses it.`, 'list_kit_components lists every name; search_docs finds prose.')
+      const text = [
+        api ? `${api.name} [${api.kind}] — import from ${api.importFrom}\n${api.signature}\n${api.summary}` : `${name}: not in the kit docs; usages found in code:`,
+        ...examples.map((e) => `\n--- ${e.origin}: ${e.file}:${e.startLine}-${e.endLine}${e.import ? `\n${e.import}` : ''}\n${e.code}`),
+        examples.length ? '' : '\n(no usage in the theme or the Blank starter)',
+      ].join('\n')
+      return done({ name: canonical, api, examples }, text)
+    }),
+  )
+
+  // ── scaffold ──────────────────────────────────────────────────────────────
+  const fileChange = z.object({ path: z.string(), action: z.enum(['create', 'modify']), summary: z.string(), content: z.string().optional() })
+  server.registerTool(
+    'scaffold_section',
+    {
+      title: 'Scaffold a kit-wired section (two-step)',
+      description: `Create a new section in the open theme (Blank layout: src/theme.tsx with defineTheme): src/sections/<type>.tsx (defineSection with a settings schema, presets[0] for the editor's Add-section preview, kit primitives only, no inline styles), its registration in src/theme.tsx, locale keys in locales/en.json AND locales/th.json, CSS appended to src/styles/theme.css, and a vitest stub in tests/sections/. Optionally adds an instance to a template's starter content.
+Two steps: call WITHOUT confirm to get the plan (every file, full new contents, planDigest; nothing is written). Then call again with the SAME arguments plus confirm: true and that planDigest to write exactly that plan. If the theme changed in between, it refuses with plan_changed. Layouts: ${LAYOUTS.join(', ')} (inferred from name + purpose when omitted). It never deletes a file and never touches anything outside the theme. Refuses for a Nova-fork layout. After writing: npm run build, npm test, check_theme.`,
+      inputSchema: {
+        name: z.string().min(1).max(60).describe('Human name; the section type is its kebab-case ("Lookbook" → "lookbook")'),
+        purpose: z.string().min(1).max(300).describe('One sentence: what it shows (becomes the editor description)'),
+        layout: z.enum(LAYOUTS).optional().describe('Markup pattern; inferred when omitted'),
+        template: z.string().max(60).optional().describe('Also place it in templates/<template>.json main region (e.g. "index")'),
+        titleTh: z.string().max(60).optional().describe('Thai name for the th label key (else the English name is used and flagged as a translation to do)'),
+        confirm: z.boolean().optional().describe('true = write the plan identified by planDigest'),
+        planDigest: z.string().optional().describe('From the plan step; required with confirm: true'),
+      },
+      outputSchema: {
+        ...base,
+        mode: z.enum(['plan', 'written']).optional(),
+        type: z.string().optional(),
+        layout: z.string().optional(),
+        planDigest: z.string().optional(),
+        changes: z.array(fileChange).optional(),
+        written: z.array(z.object({ path: z.string(), action: z.string(), bytes: z.number() })).optional(),
+        localeKeys: z.array(z.string()).optional(),
+        translationTodo: z.array(z.string()).optional(),
+        nextSteps: z.array(z.string()).optional(),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    },
+    guard(async ({ confirm, planDigest, ...input }) => {
+      if (!confirm) {
+        const p = planSection(theme, input)
+        const text = [
+          `PLAN (nothing written) for section "${p.type}" (layout ${p.layout}). To write it, call scaffold_section again with the same arguments plus confirm: true, planDigest: "${p.planDigest}".`,
+          ...p.changes.map((c) => `- ${c.action} ${c.path}: ${c.summary}`),
+          ...(p.translationTodo.length ? [`Translation to do: ${p.translationTodo.join('; ')}`] : []),
+          '',
+          ...p.changes.filter((c) => c.action === 'create').map((c) => `--- ${c.path}\n${c.content}`),
+        ].join('\n')
+        return done({ mode: 'plan', type: p.type, layout: p.layout, planDigest: p.planDigest, changes: p.changes.map(({ added, ...c }) => (c.action === 'create' ? c : { ...c, content: undefined })), localeKeys: p.localeKeys, translationTodo: p.translationTodo, nextSteps: p.nextSteps }, text)
+      }
+      if (!planDigest) return fail('plan_digest_required', 'confirm: true needs the planDigest of a plan you reviewed.', 'Call scaffold_section without confirm first.')
+      const r = writeSection(theme, input, planDigest)
+      return done(
+        { mode: 'written', type: r.type, layout: r.layout, planDigest: r.planDigest, written: r.written, localeKeys: r.localeKeys, translationTodo: r.translationTodo, nextSteps: r.nextSteps },
+        [`Wrote section "${r.type}":`, ...r.written.map((w) => `- ${w.action} ${w.path} (${w.bytes} B)`), 'Next:', ...r.nextSteps.map((s) => `- ${s}`)].join('\n'),
+      )
+    }),
+  )
+
+  // ── checks ────────────────────────────────────────────────────────────────
+  server.registerTool(
+    'validate_manifest',
+    {
+      title: 'Validate the built manifest',
+      description:
+        "Validate dist/abi/manifest.json (written by `npm run build`) with the theme's own @tanqory/theme-abi validateManifest, plus the JCS byte rule. Fast, no browser. Each problem names the JSON path and, for a component, the src/ file:line that declares it (the manifest is generated from your declarations; fix those, never the JSON). It does not rebuild: run `npm run build` first. For the full platform checks use check_theme.",
+      inputSchema: {},
+      outputSchema: { ...base, valid: z.boolean().optional(), manifestPath: z.string().optional(), abiVersion: z.string().nullable().optional(), errors: z.array(z.object({ path: z.string(), message: z.string(), code: z.string().optional(), file: z.string().optional(), line: z.number().optional(), hint: z.string().optional() })).optional() },
+      annotations: READ,
+    },
+    guard(async () => {
+      const r = await validateManifestFile(needTheme(), theme.versions['@tanqory/theme-abi'])
+      if (r.error) return fail(r.error.code, r.error.message, r.error.hint)
+      const text = r.valid ? `manifest valid (${r.manifestPath}, @tanqory/theme-abi ${r.abiVersion})` : [`manifest INVALID: ${r.errors.length} problem(s)`, ...r.errors.map((e) => `- ${e.path}: ${e.message}${e.file ? ` (${e.file}:${e.line})` : ''}${e.hint ? `\n    fix: ${e.hint}` : ''}`)].join('\n')
+      return done(r, text)
+    }),
+  )
+
+  const checkInput = { tier: z.enum(['security', 'storefront', 'budgets', 'all']).optional().describe('One tier, or all (default: what the CLI runs by default: all)') }
+  const checkOutput = { ...base, passed: z.boolean().optional(), tiers: z.record(z.any()).optional(), failures: z.array(failureSchema).optional(), failureCount: z.number().optional(), cliError: z.any().optional() }
+  const CHECK_ANN = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+
+  server.registerTool(
+    'check_theme',
+    {
+      title: 'Run tanqory theme check',
+      description:
+        'Run `tanqory theme check --json` in the theme (the same checks the platform runs before it accepts a build): security (the 9 ABI suites), storefront (works like a real store: variants, cart, checkout hand-off, sort/filter/pagination, search, th/en strings, markets, SEO, a11y, live edit) and budgets. Returns every failure with tier, checkId, message, fix hint and file:line when known. Side effects are local only: it writes the generated dist/ and reports/. Takes minutes for all tiers. Needs Tanqory CLI v2.',
+      inputSchema: checkInput,
+      outputSchema: checkOutput,
+      annotations: CHECK_ANN,
+    },
+    guard(async ({ tier }) => {
+      needTheme()
+      const env = await runCli(['theme', 'check', ...(tier ? ['--tier', tier] : [])], cliOpts)
+      return checkResult(env, tier)
+    }),
+  )
+
+  server.registerTool(
+    'run_storefront_checks',
+    {
+      title: 'Run the storefront-ready checks',
+      description:
+        'Only the storefront tier: `tanqory theme check --tier storefront --json` (a shopper picks a variant, adds to cart, edits lines, reaches checkout, sorts, filters, pages, searches, switches market and language; keyboard and axe; the merchant live-edits it). Same result shape as check_theme. Use it while iterating on storefront behaviour; run check_theme (all tiers) before saying done.',
+      inputSchema: {},
+      outputSchema: checkOutput,
+      annotations: CHECK_ANN,
+    },
+    guard(async () => {
+      needTheme()
+      return checkResult(await runCli(['theme', 'check', '--tier', 'storefront'], cliOpts), 'storefront')
+    }),
+  )
+
+  // ── dev server ────────────────────────────────────────────────────────────
+  server.registerTool(
+    'dev_server_status',
+    {
+      title: 'Is `tanqory theme dev` running?',
+      description:
+        "Read .tanqory/dev-server.json and ask the running dev server for /__tq/status: url, store, mode (store = real dev-store data, mock = fixture data), the theme it serves and its last build with errors (file:line). Never starts or stops the dev server; when it is not running the answer says how to start it (in the background: `npm run dev -- --mock`).",
+      inputSchema: {},
+      outputSchema: {
+        ...base,
+        running: z.boolean().optional(),
+        reason: z.string().optional(),
+        hint: z.string().optional(),
+        url: z.string().optional(),
+        port: z.number().optional(),
+        mode: z.string().optional(),
+        store: z.any().optional(),
+        startedAt: z.string().optional(),
+        theme: z.any().optional(),
+        lastBuild: z.any().optional(),
+      },
+      annotations: READ,
+    },
+    guard(async () => {
+      const s = readDevServer(theme.root)
+      if (!s.running) return done({ running: false, reason: s.reason, hint: s.hint }, `Dev server not running (${s.reason}). ${s.hint}`)
+      const { url, port, store, mode, startedAt } = s.record
+      const st = await devGet(url, '/__tq/status', { timeoutMs: 5000 })
+      const b = st.body ?? {}
+      const errs = b.lastBuild?.errors ?? []
+      const text = [`Dev server ${url} (${mode}${store?.handle ? `, store ${store.handle}` : ''}) serving ${b.theme?.name ?? '?'}`, `last build: ${b.lastBuild?.ok === false ? 'FAILED' : 'ok'}${b.lastBuild?.at ? ` at ${b.lastBuild.at}` : ''}`, ...errs.map((e) => `- ${e.file ?? '?'}${e.line ? `:${e.line}` : ''}: ${e.message}`)].join('\n')
+      return done({ running: true, url, port, mode, store, startedAt, theme: b.theme, lastBuild: b.lastBuild }, text)
+    }),
+  )
+
+  const pageArgs = {
+    path: z.string().regex(/^\//, 'must start with /').max(500).describe('Storefront path, e.g. "/", "/products/linen-shirt", "/collections/all?sort=price-asc"'),
+    locale: z.string().max(10).optional().describe('Language, e.g. "th" or "en"'),
+    market: z.string().max(20).optional().describe('Market / country, e.g. "TH", "JP"'),
+  }
+  const viewportArg = z.union([z.enum(['mobile', 'desktop']), z.object({ width: z.number().int().min(240).max(2560), height: z.number().int().min(240).max(2560) })])
+  const browserUrl = (origin, { path, locale, market }) => {
+    const u = new URL(path, origin)
+    if (locale) u.searchParams.set('locale', locale)
+    if (market && /^[A-Za-z]{2}$/.test(market)) u.searchParams.set('country', market.toUpperCase())
+    return u.href
+  }
+
+  server.registerTool(
+    'get_page',
+    {
+      title: 'Rendered page from the dev server',
+      description:
+        'Render one storefront page on the running `tanqory theme dev` server (GET /__tq/page) and load it in headless Chromium: status, the server-rendered HTML (truncated to maxHtmlChars), server logs, and console errors / uncaught exceptions / failed requests from the browser after hydration. Use it to assert markup (data-tq-node, data-tq-* hooks, JSON-LD, lang) and to catch runtime errors. Needs the dev server running (dev_server_status).',
+      inputSchema: { ...pageArgs, viewport: viewportArg.optional().describe('Browser viewport (default desktop)'), maxHtmlChars: z.number().int().min(0).max(200000).optional().describe('HTML characters to return (default 20000; 0 = none)') },
+      outputSchema: {
+        ...base,
+        url: z.string().optional(),
+        status: z.number().nullable().optional(),
+        html: z.string().optional(),
+        htmlLength: z.number().optional(),
+        serverLogs: z.array(z.any()).optional(),
+        consoleErrors: z.array(z.any()).optional(),
+        browser: z.object({ available: z.boolean(), reason: z.string().optional() }).optional(),
+      },
+      annotations: READ,
+    },
+    guard(async ({ path, locale, market, viewport, maxHtmlChars }) => {
+      const rec = requireDevServer(theme.root)
+      const q = new URLSearchParams({ path, ...(locale ? { locale } : {}), ...(market ? { market } : {}) })
+      const page = (await devGet(rec.url, `/__tq/page?${q}`)).body ?? {}
+      const html = typeof page.html === 'string' ? page.html : ''
+      const max = maxHtmlChars ?? 20000
+      const consoleErrors = [...(page.consoleErrors ?? []).map((m) => (typeof m === 'string' ? { kind: 'server-reported', message: m } : m))]
+      let browserInfo = { available: true }
+      try {
+        const r = await browser.withPage(browserUrl(rec.url, { path, locale, market }), { viewport: viewport ?? 'desktop' }, async () => null)
+        consoleErrors.push(...r.errors.map((e) => ({ ...e, kind: `browser-${e.kind}` })))
+      } catch (e) {
+        if (!(e instanceof BrowserUnavailable)) throw e
+        browserInfo = { available: false, reason: `${e.message} ${e.hint}` }
+      }
+      const result = { url: browserUrl(rec.url, { path, locale, market }), status: page.status ?? null, html: html.slice(0, max), htmlLength: html.length, serverLogs: page.serverLogs ?? [], consoleErrors, browser: browserInfo }
+      const text = [`${path} → ${result.status}${locale ? ` (${locale})` : ''}${market ? ` market ${market}` : ''}; HTML ${html.length} chars${html.length > max ? ` (first ${max} shown)` : ''}`, consoleErrors.length ? `console errors (${consoleErrors.length}):\n${consoleErrors.map((e) => `- [${e.kind}] ${e.message}`).join('\n')}` : 'no console errors', browserInfo.available ? '' : `browser not available: ${browserInfo.reason}`, max ? `\n${result.html}` : ''].filter(Boolean).join('\n')
+      return done(result, text)
+    }),
+  )
+
+  server.registerTool(
+    'screenshot',
+    {
+      title: 'Screenshot a page of the dev server',
+      description:
+        'A PNG of one storefront page from the running `tanqory theme dev`, taken in local headless Chromium (Playwright), returned as an image so you can see your UI. mobile = 390×844 @2x touch, desktop = 1280×900. fullPage captures up to 4 viewport heights. Also reports console errors. Downloads Chromium once if it is missing. Needs the dev server running.',
+      inputSchema: { ...pageArgs, viewport: viewportArg.describe('mobile | desktop | {width, height}'), fullPage: z.boolean().optional().describe('Whole page (capped at 4 viewport heights) instead of the first screen') },
+      outputSchema: { ...base, url: z.string().optional(), status: z.number().nullable().optional(), viewport: z.object({ width: z.number(), height: z.number() }).optional(), bytes: z.number().optional(), consoleErrors: z.array(z.any()).optional() },
+      annotations: READ,
+    },
+    guard(async ({ path, locale, market, viewport, fullPage }) => {
+      const rec = requireDevServer(theme.root)
+      const url = browserUrl(rec.url, { path, locale, market })
+      const r = await browser.withPage(url, { viewport }, async (page) => {
+        if (!fullPage) return page.screenshot({ type: 'png' })
+        const vh = page.viewportSize().height
+        const h = await page.evaluate(() => document.documentElement.scrollHeight)
+        return page.screenshot({ type: 'png', fullPage: true, clip: { x: 0, y: 0, width: page.viewportSize().width, height: Math.min(h, vh * 4) } })
+      })
+      const png = r.result
+      const structured = { ok: true, url, status: r.status, viewport: r.viewport, bytes: png.length, consoleErrors: r.errors }
+      return {
+        content: [
+          { type: 'image', data: png.toString('base64'), mimeType: 'image/png' },
+          { type: 'text', text: `${url} → ${r.status} · ${r.viewport.width}×${r.viewport.height}${fullPage ? ' full page' : ''} · ${png.length} B · ${r.errors.length ? `console errors: ${r.errors.map((e) => e.message).join(' | ')}` : 'no console errors'}` },
+        ],
+        structuredContent: structured,
+      }
+    }),
+  )
+
+  // ── stores ────────────────────────────────────────────────────────────────
+  server.registerTool(
+    'list_dev_stores',
+    {
+      title: 'List your development stores',
+      description:
+        "The development stores your Tanqory login can use (`tanqory stores --json`), and which one this theme is linked to (tanqory.config.json). Read-only; it never creates a store and never takes a store id. When you are not logged in the answer says to run `tanqory login` in a terminal.",
+      inputSchema: {},
+      outputSchema: { ...base, stores: z.array(z.any()).optional(), linked: z.any().optional(), raw: z.any().optional() },
+      annotations: { ...READ, openWorldHint: true },
+    },
+    guard(async () => {
+      const env = await runCli(['stores'], cliOpts)
+      if (!env.ok) return fail(env.error?.code ?? 'stores_failed', env.error?.message ?? '`tanqory stores` failed', env.error?.hint ?? 'Run `tanqory login` in a terminal, then try again.')
+      const stores = Array.isArray(env.data) ? env.data : Array.isArray(env.data?.stores) ? env.data.stores : []
+      const linked = theme.config?.store ?? null
+      return done({ stores, linked, raw: Array.isArray(env.data) ? undefined : env.data }, [`${stores.length} store(s); this theme is linked to: ${linked ? json(linked) : 'none (tanqory.config.json store is null)'}`, ...stores.map((s) => `- ${s.handle ?? s.name ?? s.id}${s.name && s.handle ? ` (${s.name})` : ''}${s.type ? ` [${s.type}]` : ''}`)].join('\n'))
+    }),
+  )
+
+  server.registerTool(
+    'get_store_data_summary',
+    {
+      title: 'What the dev store has to design against',
+      description:
+        'From the running dev server (GET /__tq/store-summary): the products, collections, markets/currencies, languages, menus, pages and blogs of the store `tanqory theme dev` serves (the linked dev store, or the fixture store in mock mode), so you design against real handles and data shapes. Read-only. Needs the dev server running.',
+      inputSchema: {},
+      outputSchema: { ...base, mode: z.string().optional(), store: z.any().optional(), summary: z.any().optional() },
+      annotations: READ,
+    },
+    guard(async () => {
+      const rec = requireDevServer(theme.root)
+      const r = await devGet(rec.url, '/__tq/store-summary')
+      if (r.status === 404) return fail('store_summary_unavailable', 'This dev server has no /__tq/store-summary.', 'Update @tanqory/cli and restart `tanqory theme dev`.')
+      return done({ mode: rec.mode, store: rec.store, summary: r.body })
+    }),
+  )
+
+  // ── draft push (backend not live yet: typed refusals) ─────────────────────
+  const REFUSAL = {
+    code: 'draft_push_unavailable',
+    message:
+      "Pushing a theme draft is not available yet: the platform's sandboxed build lane for developer themes, draft install and preview channel are not live. Nothing was uploaded, built, installed or published, and no preview URL exists.",
+    hint: 'Keep developing locally: `tanqory theme dev` + check_theme until every tier passes. When `tanqory theme push` ships, this tool will wrap it with the same two-step confirm.',
+    instead: ['tanqory theme dev (localhost with store data)', 'check_theme (all tiers)', 'screenshot / get_page against the dev server'],
+  }
+  const refusalOut = { ...base, refused: z.literal(true).optional() }
+  const refuse = () => ({ isError: true, content: [{ type: 'text', text: `${REFUSAL.code}: ${REFUSAL.message}\nWhat to do instead: ${REFUSAL.instead.join('; ')}. ${REFUSAL.hint}` }], structuredContent: { ok: false, refused: true, error: REFUSAL } })
+
+  server.registerTool(
+    'push_draft',
+    {
+      title: 'Push the theme as an unpublished draft (not available yet)',
+      description: `Would upload the theme for a sandboxed platform build and install it as an UNPUBLISHED draft on your dev store (two-step: a plan, then confirm). ALWAYS REFUSES TODAY with ${REFUSAL.code}: the platform build lane is not live. It never uploads, never installs, never publishes, and never returns a preview URL. Do not report a push as done.`,
+      inputSchema: { confirm: z.boolean().optional().describe('Second step (refused today)'), planDigest: z.string().optional() },
+      outputSchema: refusalOut,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    },
+    guard(async () => refuse()),
+  )
+  server.registerTool(
+    'get_build_status',
+    {
+      title: 'Status of a pushed draft build (not available yet)',
+      description: `Would report the platform build of a pushed draft. ALWAYS REFUSES TODAY with ${REFUSAL.code}: no draft can be pushed yet, so no build exists.`,
+      inputSchema: { buildId: z.string().max(100).optional() },
+      outputSchema: refusalOut,
+      annotations: { ...READ, openWorldHint: true },
+    },
+    guard(async () => refuse()),
+  )
+  server.registerTool(
+    'get_preview_url',
+    {
+      title: 'Preview URL of a draft (not available yet)',
+      description: `Would return the shareable preview and editor URLs of a pushed draft. ALWAYS REFUSES TODAY with ${REFUSAL.code}: there is no draft and no preview URL. Never invent one; localhost (dev_server_status) is the only preview today.`,
+      inputSchema: {},
+      outputSchema: refusalOut,
+      annotations: { ...READ, openWorldHint: true },
+    },
+    guard(async () => refuse()),
+  )
+
+  // ── resources: every document as tanqory://docs/<id> ──────────────────────
+  const resources = [...DOCS]
+  if (theme.root && existsSync(join(theme.root, 'AGENTS.md'))) resources.unshift({ id: 'theme/agents', title: "This theme's agent instructions (AGENTS.md)", summary: 'The rules, commands and layout of the open theme.', kind: 'markdown' })
+  for (const d of resources) {
+    server.registerResource(
+      d.id.replace(/\//g, '-'),
+      `tanqory://docs/${d.id}`,
+      { title: d.title, description: d.summary, mimeType: d.kind === 'json' ? 'application/json' : d.kind === 'typescript' ? 'text/x-typescript' : 'text/markdown' },
+      async (uri) => {
+        const r = await corpus.get(d.id, { maxChars: 2_000_000 })
+        if (r.error) throw new Error(`${uri.href} is not available in this theme`)
+        return { contents: [{ uri: uri.href, mimeType: d.kind === 'json' ? 'application/json' : d.kind === 'typescript' ? 'text/x-typescript' : 'text/markdown', text: r.text }] }
+      },
+    )
+  }
+
+  registerPrompts(server)
+
+  const close = server.close.bind(server)
+  server.close = async () => {
+    await browser.close()
+    await close()
+  }
+  return { server, theme, browser }
+}