@tanqory/dev-mcp 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tanqory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# @tanqory/dev-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The local [Model Context Protocol](https://modelcontextprotocol.io) server for building Tanqory storefront themes
+(Theme ABI v2, `@tanqory/theme-kit`) with a coding agent: Claude Code, Codex, VS Code / Copilot, Gemini CLI, Cursor.
+
+The agent already has a shell, so the Tanqory CLI stays the engine. This server is the knowledge-and-eyes layer:
+
+- docs and schemas that match the versions your theme installed;
+- real kit examples;
+- a two-step section scaffold;
+- the CLI's checks as structured JSON;
+- rendered pages and screenshots of your running dev server.
+
+It runs on your machine over stdio. It never calls an AI model and never takes a store id: the store comes from
+`tanqory.config.json` and your CLI login. It never publishes anything, and it writes files only inside the open
+theme, only after you confirm a plan.
+
+## Setup
+
+A theme from `npm create tanqory-theme` is already configured. To configure one by hand, run the server from the
+theme folder:
+
+```jsonc
+// .mcp.json (Claude Code)
+{ "mcpServers": { "tanqory": { "command": "npx", "args": ["-y", "@tanqory/cli", "mcp"] } } }
+```
+
+```toml
+# .codex/config.toml (Codex)
+[mcp_servers.tanqory]
+command = "npx"
+args = ["-y", "@tanqory/cli", "mcp"]
+```
+
+`tanqory mcp` (from `@tanqory/cli`) starts this server and passes itself as the CLI to call. To run the server on
+its own, use `npx -y @tanqory/dev-mcp`. It then looks for the CLI in the theme's `node_modules/.bin`, then on
+`PATH`. Node 20 or newer.
+
+## Tools
+
+Every tool returns text for the model plus `structuredContent` that matches its declared `outputSchema`. A failure
+comes back as `isError: true` with `{ ok: false, error: { code, message, hint } }`. The `hint` always says what to do
+next.
+
+| Tool                                                                                    | What it does                                                                                                                                                                                                                                                                                                                                                         |
+| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `search_docs {query, limit?}`                                                           | BM25 search, offline and deterministic. It covers the ABI v2 contract, the kit's headless API, the storefront-tier check spec, the field-type registry, the limits, the capabilities, the kit strings and the theme's own `AGENTS.md`. Returns ranked sections, each with a `path`.                                                                                  |
+| `get_doc {path, offset?, maxChars?}`                                                    | One document, or one `doc#section`, with pagination. `path: "index"` lists every document. Each answer names its source: `installed` (your `node_modules`) or `bundled` (this package's copy).                                                                                                                                                                       |
+| `get_schema {kind}`                                                                     | `manifest`, `section`, `block`, `field-registry`, `theme-settings`, `content-document`, `locale`, `ai-profile`, `storefront-report` or `conformance-report`.                                                                                                                                                                                                         |
+| `list_kit_components {kind?}`                                                           | Every kit hook, primitive, declaration helper and AI role, checked against the installed kit's exports.                                                                                                                                                                                                                                                              |
+| `get_kit_example {name, limit?}`                                                        | The real code that uses one kit API, with file and line numbers. It looks in your theme's `src/` first, then in the Blank starter.                                                                                                                                                                                                                                   |
+| `scaffold_section {name, purpose, layout?, template?, titleTh?, confirm?, planDigest?}` | **Two steps.** The first call returns the full plan and a `planDigest`, and writes nothing. The second call (`confirm: true` + `planDigest`) writes exactly that plan, which covers: the section file, its registration in `src/theme.tsx`, en and th locale keys, CSS, a vitest stub and, optionally, starter content. If the theme changed in between, it refuses. |
+| `validate_manifest`                                                                     | Checks `dist/abi/manifest.json` with the theme's own `validateManifest` plus the JCS byte rule. Problems are traced to the `src/` file and line that declares them.                                                                                                                                                                                                  |
+| `check_theme {tier?}`                                                                   | Runs `tanqory theme check --json`. The tiers are security (the 9 ABI suites), storefront and budgets. Each failure carries `tier`, `checkId`, `message` and `hint`, plus `file:line` when known.                                                                                                                                                                     |
+| `run_storefront_checks`                                                                 | Runs `tanqory theme check --tier storefront --json`.                                                                                                                                                                                                                                                                                                                 |
+| `dev_server_status`                                                                     | Reads `.tanqory/dev-server.json` and `GET /__tq/status`, then reports the URL, the store, the mode and the last build's errors. It never starts the server for you.                                                                                                                                                                                                  |
+| `get_page {path, locale?, market?, viewport?, maxHtmlChars?}`                           | Gets the server-rendered HTML from `GET /__tq/page`. It also loads the page in headless Chromium and collects console errors.                                                                                                                                                                                                                                        |
+| `screenshot {path, viewport, locale?, market?, fullPage?}`                              | Returns a PNG, as an MCP image block, from local Playwright.                                                                                                                                                                                                                                                                                                         |
+| `list_dev_stores`                                                                       | Runs `tanqory stores --json` and reports the store this theme is linked to.                                                                                                                                                                                                                                                                                          |
+| `get_store_data_summary`                                                                | Calls `GET /__tq/store-summary` on the dev server: the products, collections, markets, languages and content you can design against.                                                                                                                                                                                                                                 |
+| `push_draft`, `get_build_status`, `get_preview_url`                                     | **Always refuse today** with `draft_push_unavailable`. The platform's build lane for developer themes is not live yet. These tools never upload, never install, never publish and never invent a URL.                                                                                                                                                                |
+
+**Prompts:** `new-theme`, `new-section`, `fix-check-report` and `port-from-another-template-language`.
+
+**Resources:** every document, as `tanqory://docs/<id>` (for example `tanqory://docs/abi/contract`).
+
+## Environment
+
+| Variable                            | Effect                                                                                               |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `TANQORY_THEME_DIR`                 | The theme root, when the server is not started inside the theme                                      |
+| `TANQORY_CLI`                       | The CLI to call: a path to its binary or `.mjs` file, or a JSON array `["cmd", "arg"]`               |
+| `TANQORY_CHROMIUM_PATH`             | Use this Chrome or Chromium instead of Playwright's                                                  |
+| `TANQORY_MCP_NO_BROWSER_DOWNLOAD=1` | Never download Chromium. By default it is downloaded once, on the first screenshot, if it is missing |
+
+## Contract with the CLI
+
+`tanqory <cmd> --json` prints exactly one object on stdout:
+`{ ok, command, data?, error?: { code, message, hint? } }`.
+
+`theme check` puts `{ tiers, failures: [{ tier, checkId, route?, locale?, message, hint, file?, line? }] }` in
+`data`.
+
+`tanqory theme dev` writes `.tanqory/dev-server.json` (`{ pid, url, port, store, mode, startedAt }`) and serves
+three routes:
+
+- `/__tq/status`
+- `/__tq/page?path=&locale=&market=`
+- `/__tq/store-summary`
+
+Only loopback URLs are used.
+
+## License
+
+MIT

package/bin/tanqory-dev-mcp.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// The Tanqory theme-development MCP server on stdio. Configure your agent host to run `npx -y @tanqory/dev-mcp`
+// (or `npx -y @tanqory/cli mcp`) in the theme folder.
+import { main } from '../src/index.mjs'
+
+if (process.argv.includes('--version')) {
+  const { VERSION } = await import('../src/server.mjs')
+  process.stdout.write(`${VERSION}\n`)
+} else if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  process.stdout.write('tanqory-dev-mcp: the Tanqory theme-development MCP server (stdio). Run it from an MCP host in the theme folder.\n')
+} else {
+  main().catch((e) => {
+    process.stderr.write(`[tanqory-mcp] failed to start: ${e?.stack ?? e}\n`)
+    process.exit(1)
+  })
+}

package/bundled/examples/blank/config/settings.json

@@ -0,0 +1,3 @@
+{
+  "width": "normal"
+}

package/bundled/examples/blank/locales/en.json

@@ -0,0 +1,22 @@
+{
+  "theme.nav.main": "Main menu",
+  "theme.footer.menu": "More",
+  "theme.footer.rights": "© {name}. All rights reserved.",
+  "theme.price.from": "From {price}",
+  "theme.shelf.viewAll": "View all",
+  "theme.shelf.empty": "No products in this collection yet.",
+  "theme.product.missing": "This product is not available.",
+  "theme.collection.kicker": "Collection",
+  "theme.collection.none": "This collection is empty for now.",
+  "theme.cart.continue": "Continue shopping",
+  "theme.cart.view": "View cart",
+  "theme.cart.taxes": "Taxes and shipping are calculated at checkout.",
+  "theme.drawer.qty": "Qty {count}",
+  "theme.journal.read": "Read more",
+  "theme.journal.back": "Back to {blog}",
+  "theme.journal.by": "By {author}",
+  "theme.notFound.title": "Page not found",
+  "theme.notFound.body": "The link may be old, or the page has moved.",
+  "theme.notFound.home": "Back to the home page",
+  "seo.homeDescription": "{name}: shop online."
+}

package/bundled/examples/blank/locales/th.json

@@ -0,0 +1,22 @@
+{
+  "theme.nav.main": "เมนูหลัก",
+  "theme.footer.menu": "เพิ่มเติม",
+  "theme.footer.rights": "© {name} สงวนลิขสิทธิ์",
+  "theme.price.from": "เริ่มต้น {price}",
+  "theme.shelf.viewAll": "ดูทั้งหมด",
+  "theme.shelf.empty": "ยังไม่มีสินค้าในคอลเลกชันนี้",
+  "theme.product.missing": "สินค้านี้ไม่มีจำหน่าย",
+  "theme.collection.kicker": "คอลเลกชัน",
+  "theme.collection.none": "คอลเลกชันนี้ยังไม่มีสินค้า",
+  "theme.cart.continue": "เลือกซื้อสินค้าต่อ",
+  "theme.cart.view": "ดูตะกร้า",
+  "theme.cart.taxes": "ภาษีและค่าจัดส่งคำนวณตอนชำระเงิน",
+  "theme.drawer.qty": "จำนวน {count}",
+  "theme.journal.read": "อ่านต่อ",
+  "theme.journal.back": "กลับไปที่ {blog}",
+  "theme.journal.by": "โดย {author}",
+  "theme.notFound.title": "ไม่พบหน้าที่คุณกำลังหา",
+  "theme.notFound.body": "ลิงก์อาจเก่าแล้ว หรือหน้านี้ถูกย้ายไป",
+  "theme.notFound.home": "กลับหน้าแรก",
+  "seo.homeDescription": "{name}: ช้อปออนไลน์"
+}

package/bundled/examples/blank/regions/footer.json

@@ -0,0 +1,35 @@
+{
+  "contentVersion": 1,
+  "region": "footer",
+  "sections": [
+    {
+      "id": "footer",
+      "type": "footer",
+      "blocks": [
+        {
+          "id": "footer-brand",
+          "type": "footer-brand",
+          "settings": {
+            "tagline": "Made in small batches."
+          }
+        },
+        {
+          "id": "footer-menu",
+          "type": "footer-menu",
+          "settings": {
+            "heading": "Explore",
+            "menu": "main-menu"
+          }
+        },
+        {
+          "id": "footer-menu-2",
+          "type": "footer-menu",
+          "settings": {
+            "heading": "Help",
+            "menu": "footer"
+          }
+        }
+      ]
+    }
+  ]
+}

package/bundled/examples/blank/regions/header.json

@@ -0,0 +1,13 @@
+{
+  "contentVersion": 1,
+  "region": "header",
+  "sections": [
+    {
+      "id": "header",
+      "type": "header",
+      "settings": {
+        "menu": "main-menu"
+      }
+    }
+  ]
+}

package/bundled/examples/blank/src/bundle.ts

@@ -0,0 +1,15 @@
+/** What the kit runtime is handed: the theme and its strings (store-independent, module scope). */
+import type { ThemeBundle } from '@tanqory/theme-kit/headless'
+import theme from './theme'
+
+export const bundle: ThemeBundle = {
+  theme,
+  templates: {},
+  groups: {},
+  // The build lays locales/*.json over the kit's own strings into generated/locales.
+  locales: import.meta.glob('./generated/locales/*.json', { eager: true }),
+  settings: {},
+  settingsSchema: {},
+  customSections: {},
+  manifest: null,
+}

package/bundled/examples/blank/src/components/parts.tsx

@@ -0,0 +1,32 @@
+/** Small shared parts: the product card and the product grid. */
+import { Image, formatMoney, useTranslate, type Product } from '@tanqory/theme-kit/headless'
+
+export const cx = (...names: Array<string | false | null | undefined>): string => names.filter(Boolean).join(' ')
+
+export function ProductCard({ product, eager = false }: { product: Product; eager?: boolean }): JSX.Element {
+  const t = useTranslate()
+  const min = product.priceRange.min
+  const ranged = product.priceRange.max.amount > min.amount
+  return (
+    <li className="t-card">
+      <a className="t-card__link" href={product.url}>
+        <span className="t-card__frame">
+          <Image image={product.featuredImage} alt="" className="t-card__img" loading={eager ? 'eager' : 'lazy'} sizes="(max-width: 720px) 50vw, 25vw" fallback={<span className="t-card__img t-card__img--empty" />} />
+        </span>
+        <span className="t-card__title">{product.title}</span>
+        <span className="t-card__price">
+          {ranged ? t('theme.price.from', { price: formatMoney(min) }) : formatMoney(min)}
+          {product.available ? null : <span className="t-card__flag"> · {t('product.soldOut')}</span>}
+        </span>
+      </a>
+    </li>
+  )
+}
+
+export function Grid({ products, busy, eager = 0 }: { products: readonly Product[]; busy?: boolean; eager?: number }): JSX.Element {
+  return (
+    <ul className="t-grid" aria-busy={busy || undefined}>
+      {products.map((p, i) => <ProductCard key={p.id} product={p} eager={i < eager} />)}
+    </ul>
+  )
+}

package/bundled/examples/blank/src/entry.client.tsx

@@ -0,0 +1,6 @@
+/** The browser entry: hydrates what the server rendered; on the editor canvas, live edits apply in place. */
+import { hydrate } from '@tanqory/theme-kit/client'
+import { bundle } from './bundle'
+import './styles/theme.css'
+
+hydrate({ bundle })

package/bundled/examples/blank/src/entry.server.tsx

@@ -0,0 +1,13 @@
+/**
+ * The serve entry (Theme ABI v2 §1): `render(request, ctx)` + `manifest`, built into one file with no imports.
+ * The render is the kit's; `storefront` turns on what the headless API needs, and `plan.localization` lists the
+ * store's countries for the header's market selector.
+ */
+import type { ThemeManifest } from '@tanqory/theme-abi'
+import { createRender } from '@tanqory/theme-kit/server'
+import { bundle } from './bundle'
+import manifestJson from './generated/manifest.json'
+
+export const manifest = manifestJson as unknown as ThemeManifest
+
+export const render = createRender({ manifest, bundle, storefront: { plan: { localization: true, recommendations: true } } })

package/bundled/examples/blank/src/sections/chrome.tsx

@@ -0,0 +1,132 @@
+/** The header and the footer, shared by every page. */
+import { useId, useState } from 'react'
+import {
+  CartToggle,
+  Image,
+  LocalizationForm,
+  SearchForm,
+  ai,
+  defineBlock,
+  defineSection,
+  field,
+  useMenu,
+  useShop,
+  useTranslate,
+  type BlockInstance,
+} from '@tanqory/theme-kit/headless'
+import { cx } from '../components/parts'
+
+function Masthead({ settings }: { settings: { menu: string; tagline: string } }): JSX.Element {
+  const shop = useShop()
+  const menu = useMenu(settings.menu)
+  const t = useTranslate()
+  const navId = useId()
+  const [open, setOpen] = useState(false)
+  return (
+    <header className="t-mast">
+      <a className="t-mast__brand" href="/">
+        {shop.logo ? <Image image={shop.logo} alt={shop.name} className="t-mast__logo" loading="eager" /> : shop.name}
+      </a>
+      {settings.tagline ? <p className="t-mast__tagline">{settings.tagline}</p> : null}
+      <button type="button" className="t-mast__menu" data-tq-action="menu:open" aria-expanded={open} aria-controls={navId} onClick={() => setOpen((o) => !o)}>
+        {t(open ? 'menu.closeMenu' : 'menu.menu')}
+      </button>
+      <nav id={navId} className={cx('t-mast__nav', open && 'is-open')} aria-label={t('theme.nav.main')}>
+        <ul>
+          {(menu?.items ?? []).map((item) => (
+            <li key={`${item.title}-${item.url}`}>
+              <a href={item.url ?? '/'} aria-current={item.active ? 'page' : undefined}>
+                {item.title}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </nav>
+      <div className="t-mast__tools">
+        <SearchForm className="t-find" inputClassName="t-find__input" submit={false} resultsClassName="t-find__results" limit={5} />
+        <LocalizationForm className="t-locale" label="hidden" selectClassName="t-locale__select" />
+        <CartToggle className="t-mast__cart" />
+      </div>
+    </header>
+  )
+}
+
+export const header = defineSection({
+  type: 'header',
+  title: 'Header',
+  description: 'The shop name, the main menu, search, region and the cart.',
+  category: 'chrome',
+  zone: 'header',
+  settings: {
+    menu: field.resource('menu', 'main-menu', { label: 'Menu' }),
+    tagline: field.text('', { label: 'Tagline' }),
+    // The data plan's convention: the header shows the market selector.
+    showLocale: field.boolean(true, { label: 'Show country and language' }),
+  },
+  ai: ai.headerMenu('menu'),
+  component: Masthead,
+})
+
+const footerMenu = defineBlock({
+  type: 'footer-menu',
+  title: 'Menu column',
+  settings: { heading: field.text('', { label: 'Heading' }), menu: field.resource('menu', 'footer', { label: 'Menu' }) },
+})
+const footerBrand = defineBlock({
+  type: 'footer-brand',
+  title: 'Brand',
+  settings: { tagline: field.textarea('', { label: 'Tagline' }) },
+})
+
+function MenuColumn({ block }: { block: BlockInstance }): JSX.Element | null {
+  const menu = useMenu(String(block.settings.menu ?? ''))
+  const t = useTranslate()
+  if (!menu) return null
+  const heading = String(block.settings.heading ?? '') || menu.title
+  return (
+    <nav className="t-foot__col" aria-label={heading || t('theme.footer.menu')}>
+      {heading ? <h2 className="t-foot__heading">{heading}</h2> : null}
+      <ul>
+        {menu.items.map((i) => (
+          <li key={`${i.title}-${i.url}`}>
+            <a href={i.url ?? '/'}>{i.title}</a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  )
+}
+
+function Colophon({ blocks }: { blocks: BlockInstance[] }): JSX.Element {
+  const shop = useShop()
+  const t = useTranslate()
+  return (
+    <footer className="t-foot">
+      <div className="t-foot__cols">
+        {blocks.map((b, i) =>
+          b.type === 'footer-brand' ? (
+            <div key={i} className="t-foot__brand">
+              <p className="t-foot__name">{shop.name}</p>
+              {b.settings.tagline ? <p className="t-foot__tagline">{String(b.settings.tagline)}</p> : null}
+            </div>
+          ) : (
+            <MenuColumn key={i} block={b} />
+          ),
+        )}
+      </div>
+      <p className="t-foot__legal">{t('theme.footer.rights', { name: shop.name })}</p>
+    </footer>
+  )
+}
+
+export const footer = defineSection({
+  type: 'footer',
+  title: 'Footer',
+  description: 'The shop name, menu columns and the legal line.',
+  category: 'chrome',
+  zone: 'footer',
+  settings: {},
+  blocks: [footerBrand, footerMenu],
+  ai: [ai.footerMenu('menu', { block: 'footer-menu' }), ai.footerBrand({ block: 'footer-brand' })],
+  component: Colophon,
+})