@scayver/specshot-mcp-server 0.11.0 → 0.14.0

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.
@@ -0,0 +1,99 @@
1
+ // GENERATED FILE: do not edit by hand. Tool descriptions, from the hosted registry in apps/web/src/lib/mcp-http-tools.ts.
2
+ //
3
+ // apps/mcp-server publishes standalone to npm, so it cannot import @specshot/shared or the hosted
4
+ // registry. This copy is written from them by apps/web/src/lib/__tests__/mcp-stdio-sync.test.ts,
5
+ // which fails whenever the two differ. To regenerate after changing the source:
6
+ // cd apps/web && SPECSHOT_WRITE_GENERATED=1 npx vitest run src/lib/__tests__/mcp-stdio-sync.test.ts
7
+ /**
8
+ * The description is the only thing an agent reads to decide whether and how to call a tool, so
9
+ * both transports must say the same thing. Every stdio registration reads its text from here.
10
+ */
11
+ export const TOOL_DESCRIPTIONS = {
12
+ "add_build_note": "Append a timestamped build note to a concept. Requires a read/write token.",
13
+ "add_design_comment": "Add a comment pin to the design, tied to a section and/or layer id, or to one element by elementPath. Use this to flag something or leave a note the user will see on the canvas. An elementPath (same-tag steps from the body, main[1]/section[2]/h2[1], with the conceptId of the design) pins the note to that element at every width, and is refused when the stored design has no such element. Requires a read/write token.",
14
+ "add_image": "Add an image you made elsewhere to a project, as base64 in data (a data URL or bare base64). PNG, JPEG or WEBP up to 10 MB, and about 2.9 MB through this endpoint's request limit, so prefer JPEG or WEBP for photos. Links are not accepted: send the bytes. The image is ready at once, appears in the project's Images sheet, and its placeableUrl can go straight into a design. Requires a read/write token.",
15
+ "check_built_page": "Compare the page built on the client's WordPress site with the approved design. SpecShot opens the built page's public address, the one a connected WordPress site reported when the page was built in Etch (you never pass an address), screenshots it in a server browser at 1440 and 390 px wide, renders the approved design at the same widths, aligns the two at the top and compares them pixel by pixel. Returns score (the share of differing pixels, 0 to 1, with a tolerance for antialiasing; 0.01 or less matches), and for each width its score, the height difference, a per-section breakdown and signed links to the built screenshot, the approved render and a difference image where red marks what changed, valid for one hour, plus any pins the client left on the built page. It returns the latest check of the current approved version when there is one; set refresh to true to check again. Works only for an approved design with a built page recorded, and only when the SpecShot owner has turned server renders on; otherwise the error says why. Read only.",
16
+ "close_frame": "Remove a frame you placed from the user's canvas board, by frameKey (see list_frames). You can only close agent-placed frames: a frame the user added is theirs. Requires a read/write token.",
17
+ "complete_project_task": "Mark a task done. A task already done stays as it is. To open it again, or to drop it, use update_project_task with status todo or canceled. The activity feed says your agent marked it done. Requires a read/write token.",
18
+ "create_agent_task": "Create an agent task so the user can see what you are doing and why. Reference the exact target with sectionUid and/or layerUid. Requires a read/write token.",
19
+ "create_design_version": "Create a NEW design version. It never overwrites existing or approved work: it always adds a version, so the original is preserved. Send the built html (and optional css), a change summary, and the parent version it was revised from. SpecShot also checks the design law on every save and returns designLaw: a 0 to 100 score and findings, each with a code, a severity and a fix. Fix every block finding (clear slop: emoji icons, placeholder image hosts, lorem, no fluid type at all) and revise before you tell the user the design is ready; warn findings are worth the next revision. A save is never refused for a finding. Requires a read/write token.",
20
+ "create_frame": "Place a design on the user's canvas board, beside what they are already looking at. This is how your work becomes VISIBLE: save_wireframe stores a design, create_frame makes it appear on screen. publish_page_version does both in one call and is the better default for a new page. Call it once per variation. Set viewport to show it at a phone (390px), tablet (768px), or desktop (1440px) width. Omit x and y to auto-place it to the right of everything else. A board holds 12 frames. Requires a read/write token.",
21
+ "create_page": "Add a page the brief implies. Read get_project_intelligence first, decide the sitemap the brief calls for, then call this once per page. A duplicate slug returns the existing page, so re-running the same sitemap is safe. The returned page id is what a design concept is later built for. A page has a KIND: 'screens' is a page of the site (the default, and most pages), 'foundations' holds the brand rendered as a design system, 'components' holds the reusable library. A project may have any number of any kind, including none. Prefer building a foundations page and a components page BEFORE the screens that depend on them, so every screen composes from one set of tokens and one set of components instead of re-authoring the header on every page. Before building the page, load the design skills for its required sections with get_skill (list_skills names them). Requires a read/write token.",
22
+ "create_project_task": "Add a task for a person on a project: a teammate or the client. Send a title. Send notes, pageId, dueOn (a date like 2026-11-05) and assignee (a teammate's userId from list_project_tasks, or client, with contactId to name a person at the client) only when a person asked for them: never make up a date or an assignee. A viewer cannot be given a task. A client's task shows in their portal with a Done button. The activity feed says your agent added it. Requires a read/write token.",
23
+ "extract_concept_sections": "Turn an existing design concept into stable, selectable sections and layers with copyable ids (SS-SEC-*, SS-LYR-*), derived from the concept's own structure. Idempotent: safe to call more than once, it will not duplicate. It also does NOT re-derive: on a concept that already has sections it leaves them alone, because section names come from the rendered preview in a browser and there is no browser on the server. The way to keep sections in step with a revision is to pass `sections` to publish_page_version and revise_wireframe. Requires a read/write token.",
24
+ "generate_image": "Generate an image for a project with the workspace's own OpenAI or Google key. Returns at once with the image row in status \"generating\"; then call get_image with its id every few seconds until it is \"ready\" (use its placeableUrl in a design) or \"failed\" (error says why). Set parentId to make a variation of an image (same prompt) or an edit of it (new prompt). The image appears live in the project's Images sheet. Images carry no text, logos or real people unless the prompt asks for words. Requires a read/write token.",
25
+ "get_agent_tasks": "The agent tasks for a project, newest first: what is queued, running, or waiting for the user. Optionally filter by status or conceptId.",
26
+ "get_approved_concept": "The most recently approved concept for a project, as a full build package. Start here to build the approved design.",
27
+ "get_brand_system": "The brand tokens (colors, typography, spacing, radius, animation) for a project, plus `contrast`: every text-on-background pair measured to WCAG, failures first, and the readable text color for each brand color. Never set body text on a pair below 4.5:1. `platform` carries the brand's framework and CSS variable prefix; an Etch build gives every design variable that prefix. In black-and-white mode, build with its typography, spacing and radius; its colors wait for the color pass.",
28
+ "get_comments_for_section": "Read comment pins. Filter by sectionUid to get feedback on one section, by conceptId, or by status (open, in_review, accepted, rejected, resolved, needs_clarification). A pin placed on an element carries elementPath, the element as same-tag steps from the body (main[1]/section[2]/h2[1]), and anchorWidth, the frame width in px it was placed at: the exact element the person means, at the width they saw. A reply carries parentCommentId and its thread's anchor.",
29
+ "get_concept": "One concept's full Design Context Package: brief, brand, sources, preview, a ready-to-paste build prompt, and two grades of its markup: premiumQuality (the premium bar) and designLaw (the law check, findings with a code, a severity and a fix).",
30
+ "get_design_layers": "The Photoshop-style layer tree for a project. Optionally filter by conceptId or by sectionId (the section's uuid, from get_design_sections).",
31
+ "get_design_screenshot": "Look at a design the way people will see it. SpecShot renders the design's latest markup in a server browser, through the same sanitized preview as the canvas, at the width you ask for (default 1440, from 320 to 2560), and returns url: a signed link to the PNG, valid for one hour. To crop to one section, give section a section id such as SS-SEC-HERO-001. Use it after a save to check spacing, contrast and breakpoints before you tell the user a page is ready. Very tall pages are cut at 16000 px and say truncated. Works only when the SpecShot owner has turned server renders on; otherwise the error says so. Read only.",
32
+ "get_design_sections": "A project's design sections, each with its stable copyable section id (for example SS-SEC-HERO-001), name, type, order, and preview. Optionally filter by conceptId.",
33
+ "get_design_tokens": "Call this before building a saved design in code, to reuse its exact colors, type, spacing and radii instead of guessing them from a screenshot. Read from the design's own CSS. Returns `declared`: the CSS custom properties the design declares on :root, html or body, with `media` when one applies only under a media query; `css`: the unconditional ones as a ready-to-paste :root block; and `used`: the colors, fonts (first family), fontSizes, fontWeights, lineHeights, radii, shadows and spacing its CSS actually uses, most-used first. Each used value names the custom properties it was reached through in `vars`: paste `css` into the build and write var(--name) rather than the raw value. A color matching the project's brand palette names that brand token in `token`. Read `warnings`.",
34
+ "get_design_versions": "A project's design versions, newest first, each with its version number, parent, change summary, and status. Optionally filter by conceptId.",
35
+ "get_discovery_answers": "Read the project's discovery questions and answers. These drive the wireframe and the design, so read them before building or revising anything.",
36
+ "get_etch_audit": "Audit a client's Etch site through the Etch Connector. Returns `script`: save it as `fileName` and run `command` with the tab's name (from `npx @digital-gravy/etch-connector tabs`) in place of `<tab>`, after the user runs `npx @digital-gravy/etch-connector serve`, turns on Settings > AI > AI Connector in Etch, saves their work and clicks Etch's AI button. The script opens every page and template in turn, then the page it started on, and reports: classes on blocks with no style record (a builder save can drop them), SpecShot's own styles, stylesheets and components that nothing uses (`specshot.unused`), where each SpecShot component is used (`specshot.usage`), and assets outside a collection. It changes nothing by default and never offers the site's own items. To remove SpecShot's own unused items, show the user `specshot.unused` and ask; only after they say yes, call get_etch_audit again with `remove` set to the keys they confirmed (from `removable`) and run that script. It removes an item only when a fresh read still finds it SpecShot's own and unused. An empty `removable` means the read had a gap (`scanned.gaps`), and nothing may be removed.",
37
+ "get_etch_build": "Build a SpecShot design into a live Etch builder tab (Etch for WordPress or Etch Studio) through the Etch Connector. First the user must run `npx @digital-gravy/etch-connector serve`, turn on Settings > AI > AI Connector in Etch, open the target page and click Etch's AI button; `npx @digital-gravy/etch-connector tabs` lists the connected tabs by name. Every eval names the tab with `-t <tab>` and a timeout in milliseconds. Check the connection first: save `check.script` as specshot-etch-check.js and run `npx @digital-gravy/etch-connector eval -t <tab> -f specshot-etch-check.js --timeout 30000` (`commands.check`). It changes nothing and returns the Etch profile: the product, Etch's and the API's versions, the capabilities, whether Automatic.css is active (Etch's acss skill), and `agent`, which must be idle before you build. Then save `script` to a file and run `npx @digital-gravy/etch-connector eval -t <tab> -f <file> --timeout 180000` (`commands.run`). The script refuses to build while another agent works in the tab; if you set Etch's AI state yourself, set ignoreAgentState: true in its OPTIONS. The script keeps the design's structure, classes and tokens, never overwrites a style or variable the site already has (it renames its own class instead), and re-running it replaces only this design's earlier build. Every variable the design declares, and every brand token, carries the project prefix (`summary.prefix`: --space-m becomes --<prefix>-space-m), so nothing collides with ACSS or another project's design; `summary.renamedVariables` counts them. It also carries the design's project brand: each brand token becomes an Etch variable and the design's matching variables point at it; `context` says which tokens and which Etch rules apply, so tell the user. Use dryRun:true to preview. `assets` are temporary SpecShot image links: download each, upload it (`npx @digital-gravy/etch-connector upload <file> --alt <text>` on Etch Studio, or the WordPress media library), then call this tool again with `media`, each asset key with its id (`{\"img-1\":{\"id\":123}}`; a background image may take `url` instead), and the script arrives with every image bound, nothing to edit. The SpecShot extension uploads and binds them in one click. Read `warnings` and pass them on to the user.",
38
+ "get_font_faces": "Call this before building any page, to embed real typefaces. The preview strips every external font, so a face you name but do not embed renders as a fallback and the design looks cheap for a reason nobody can see. Pass up to 3 Google Fonts families as \"Family:400,600\" (or \"Family:400:italic\"); returns `css`, @font-face rules with the Latin subset as data: URIs, to paste at the top of your <style>. Two families and three or four weights in total is right; every weight adds to every page. Take the families from the client, never from a default pairing: the faces the brand names (get_brand_system), else the faces the client's captures use (get_wireframe_context lists each capture's fonts), else a Google Fonts pairing that matches the character of the references. Never Inter, Roboto, Arial, Geist, Fraunces, Plus Jakarta Sans or Space Grotesk by reflex (a client's own brand face is the exception). Read `missing` for anything that could not be embedded.",
39
+ "get_handoff_package": "The complete handoff package to BUILD a project's approved concept: the brief, goals, audience, brand system, the sections with their stable ids, the per-section copy, the open feedback to resolve, the decisions and memory to honor, the acceptance criteria, and a ready-to-paste buildInstruction. This is the single read you need before implementing. Optionally target a specific conceptId.",
40
+ "get_image": "One project image by id: its status (generating, ready or failed), the error when it failed, and when ready a placeableUrl to put in a design, a ready <img> as html, and a viewUrl (signed, one hour) to look at it.",
41
+ "get_layer_by_uid": "Get one layer by its layer id (for example SS-LYR-HEADLINE-001), with its style, layout, and animation data.",
42
+ "get_messages": "Read the conversation thread on a concept, including any feedback the human left in the SpecShot portal. Read it to see new human feedback before revising.",
43
+ "get_next_action": "The project's next action only: what to do now, whose turn it is, and the tool `call` with its arguments filled in. The cheap way to check back while it is the team's or the client's turn. Call get_project_state for the pages behind it. Read-only.",
44
+ "get_premium_exemplar": "Call this once before you design your first page, to see the premium bar met rather than described. Returns a complete living page for a fictional brand that meets the living page standard and all twelve points of the production gate in the premium_craft prompt: `html` (one document, one style block: layered elevation, a hero image spot with a drawn fallback and floating chips, a bento, a moving band of the brand's names, full-bleed media, a sticky stack, a booking form, a load entrance, reveals that differ by section, moving figures and the full interaction system, all written to survive SpecShot's preview), `sections` (each section's layout type, ground and how it meets the bar), `gate` (the twelve questions answered for this page), `adapt` (what to take into a client build) and `fonts` (get_font_faces specs to render it). Study the moves; never ship its brand, copy or numbers. Pass part: \"breakdown\" to skip the markup.",
45
+ "get_project_copy": "Read the project's per-section copywriting (headlines, body, CTAs, labels), with each block's status and version.",
46
+ "get_project_intelligence": "Read the FULL Project Intelligence Pack for a project: the brief, discovery answers, business and page goals, target audience, brand tokens, captured screenshots, inspiration, pages, every concept with the approved one flagged, section requirements, decisions, constraints, platform preferences, open questions, agent instructions, and acceptance criteria. It opens with clientRules: the client's answers that are rules (off-limits, what they may not legally say, how the site should come across, the brand assets they have) and the agency's instructions. Those beat every default and your own taste, but never the boundary against copying another company's work or the anti-slop bans. Read this before making any change, so you work from the shared source of truth rather than a bare prompt.",
47
+ "get_project_memory": "The project's durable decisions and memory: approved decisions, rejected directions, and brand, copy, layout, and platform rules. Honor these in every revision.",
48
+ "get_project_references": "What to design toward on a project: the versions people pinned as \"more like this\", and the taste they stated, newest first. Call it before you design or revise a page. Pass versionId from references to read that pinned version's markup and study its spacing, type, density and tone; never reuse its copy. Read-only.",
49
+ "get_project_state": "Call this first on any project. Returns the whole project as the team sees it: its stage (discovery, scope, design, review, build, live), every page's state and detail (for example review / changes_asked, with the client's note), whose turn it is (team, client, agent or nobody), and `next`: the one thing to do now, with the exact tool `call` and its arguments filled in (and `then`, the call after it). When `next.actor` is not \"agent\" it is someone else's turn: wait and check back with get_next_action instead of guessing, unless a person asked you to do that work. `yourTurn` names your own next step when there is one. Approving, sending to a client and confirming a page live are for people only (`humanOnly`). Read-only.",
50
+ "get_prototype": "Read the project as a click-through prototype: for every site page, the design it shows, where each of its links and data-ss-action elements goes (other pages, with how many links and their text), which links are broken and why (no page has that address, points nowhere, refused script, an in-page target that is missing, an action the player cannot read), the links that leave the site, and orphanPages that no other page links to. Links resolve by page slug: href=\"/about\", \"about.html\" and \"./about\" all open the about page, \"#pricing\" scrolls to id=\"pricing\" on the same page, and a link to the project's live site address opens the page it names. Explicit interactions are attributes the player reads, never script: data-ss-action=\"page:<slug>\", \"design:<id>\", \"back\", \"toggle:<selector>\" (sets data-ss-open on the target, so style the open state with [data-ss-open]) or \"scroll:<selector>\", with data-ss-on=\"click\" (the default) or \"key:<Key>\". A selector is one class, id or attribute. Pass approved: true to read the approved designs instead of the newest. guidance says what to fix first, and playUrl opens the player. Read only.",
51
+ "get_section_by_uid": "One section by its section id (for example SS-SEC-HERO-001), together with its layers. Use this when the user points you at a specific section id.",
52
+ "get_selected_design_version": "Get the version to build: the latest approved one, or the most recent if none is approved. Optionally scope to a conceptId.",
53
+ "get_selection": "What the user has selected on the SpecShot build canvas RIGHT NOW: the project, the design they have open, the active frame and its width, and the exact section or layer they have highlighted (with its stable id, SS-SEC-... / SS-LYR-...). Call this FIRST whenever the user says \"this section\", \"this screen\", \"here\", or \"what I'm looking at\" — it resolves the reference without asking them. Returns selection: null with a hint when no canvas is open. Reports ageSeconds and stale so you can tell a live selection from a forgotten tab. Read-only.",
54
+ "get_seo_audit": "One SEO audit: its score and how the score is made, the score by category, robots.txt and the sitemap, the checklist's counts by status, and the plan to 100, step by step: each step's fixId, title, severity, status, the points it adds, the score after it, how many pages it covers and whether the Etch Connector can make it. Read only.",
55
+ "get_site_kit": "The project's site system, the kit every page of a whole site is composed from: the approved one, or the newest draft when none is approved, with its tokens, :root, kit CSS, header, footer, navigation and components (each with its props, slots and definition), what is missing from it and its findings, and promptBlock, the kit exactly as every page's prompt reads it. A newer draft beside an approved kit comes back as draft. Sized for your context: the embedded faces are left out, since SpecShot puts them on every page, and long parts are clipped with their full size given. detail: \"full\" returns the whole kit CSS, header, footer and component markup. Read-only.",
56
+ "get_site_plan": "Call this first on a whole-site build. Returns the project's site map (each page with its family, its path and whether it is approved), its page families (job, hero archetype, signature interaction, section plan, kit components, pilot and status) with the plan's findings and readiness, the site system's approved version and newest draft with their findings, the open site run (agent-driven or SpecShot's own) with its counts and what it waits on, which reference goes to the whole site, to a family or to a page, and whether the plan includes whole-site generation. `next` names the one thing to do now. Titles are the client's words, quoted as data. Read-only.",
57
+ "get_skill": "Load one SpecShot design skill in full by its id (list_skills names them): the rules and short examples for building that part of a page well in SpecShot's system (Etch, BEM, the fluid token contract, ACSS mapped by the export). Load the skill for each section kind before you build it, and again before you revise it. The design law still governs, and the client's rules beat both.",
58
+ "get_wireframe_context": "START HERE before building any design for a project. Returns the approved copy to use verbatim (copyBlocks), the sections the owner captured as reference with the real text that was on them, inspiration screens (each with the layout read from its image, when one was read, as reference structure to learn from and never to copy), the real brand fonts, colors and spacing, the page list, and the full build instruction that defines what done looks like: the design law (full fidelity, real type and copy, real SVG icons, the canonical token names with fluid type and space, the Etch rules, the anti-slop list, never bare skeletons). `etch.prefix` is the prefix every token you declare carries when the page is built in Etch. `skills.perPage` names the design skills that fit each page (load each with get_skill) and `workflow` is the order of work. Build one full-fidelity design per page from this and publish each with publish_page_version, which saves AND puts it on the owner's canvas. Everything you need to build something the client will actually approve, instead of guessing.",
59
+ "get_wireframes": "List the project's saved wireframes with type, status, and version.",
60
+ "link_concept_page": "File an existing design concept under a project page, or move it. Pass conceptId and either pageSlug or pageId (both from get_wireframe_context / get_project_intelligence). Pass pageId:null to unfile. Use this when you saved a concept without a page, or to refile a variation under the right page. The owner's Pages hub groups concepts by the page they realize. Requires a read/write token.",
61
+ "list_components": "The project's shared component library, and what has DRIFTED. A website's pages share a nav, a footer, a button scale, a card — and an agent writing each page independently re-authors all of them until the header on Pricing is no longer the header on Home. Call this BEFORE building another page: reuse a component that already exists instead of inventing a fourth header. The drift list names the components carrying different markup on different pages, biggest group first, because the biggest group is almost always the intended version.",
62
+ "list_concepts": "List design concepts and saved wireframes in your workspace, newest first. Filter by projectId or status.",
63
+ "list_frames": "The frames on the user's canvas board: what each points at, where it sits, how wide it is, who placed it, and whether you may close it. Call it before create_frame to see how many of the 12 slots are free, and to get the frameKey close_frame needs.",
64
+ "list_images": "A project's images, newest first, with status, prompt, size, placeableUrl (for designs) and viewUrl (to look). generator.provider says which key would make new ones (null: none, so generate_image will refuse). Pass since (nextSince from the last call) to get only what changed.",
65
+ "list_inspiration": "List inspiration screenshots saved to a project, optionally filtered by folder.",
66
+ "list_project_tasks": "List a project's tasks for people, the team's and the client's, each with its status, assignee, due date and page. filter is open (the default), mine (the open tasks of the person whose token this is), done or all; pageId keeps one page's tasks. Also returns the teammates a task can go to (never a viewer), the client's contacts, each page's due date and owner, the review rounds with their answer-by dates and the target launch. Your own queue is get_agent_tasks, not this. Read only.",
67
+ "list_projects": "List the projects in your SpecShot workspace, newest first.",
68
+ "list_seo_audits": "List the workspace's SEO audits, newest first: each one's start address, scope (one page or the whole site), status, score from 0 to 100, pages read and when it finished. Filter by projectId. An archived audit is left out; get_seo_audit still reads it by its id. Read only.",
69
+ "list_seo_fixes": "The checklist items of an SEO audit, in plan order, open ones by default (status: open, fixed, ignored, verified or all), paged with limit (up to 25) and offset. Pass page, a full address, for the items on that page alone. Each item has its fixId, title, severity, the pages it covers, the facts to ask a person for (gaps) and instruction: the exact change, where to make it, how to check it worked and what never to do. Make only the change an instruction names; ask the person for every [ASK] fact and never guess one. Read only. Part of the Pro plan.",
70
+ "list_skills": "List SpecShot's design skills: short, rule-dense guides for one part of a page each (the hero, pricing, navigation, footers, forms, cards, buttons, typography, color and contrast, motion, accessibility, responsive behavior, the Etch and ACSS build, and more), each with when to load it. Call it before you plan a page, then load the skills for the sections and parts you are about to build with get_skill. get_wireframe_context also recommends the skills for each page. Returns `skills` (id, title, kind, when), the short page `workflow`, and the prompts that carry the full workflow.",
71
+ "list_wordpress_sites": "List the WordPress sites connected to a project through the SpecShot plugin: each site's address, name, versions (WordPress, PHP, Etch, ACSS, plugin), whether Automatic.css (ACSS) is detected, when it was last seen and how many builds it reported. followsAcss true means the site's builds follow ACSS: design with ACSS tokens read undeclared with a literal fallback (var(--space-m, 1.5rem)) and never redeclare ACSS names. guidance says what to do in one sentence. Read only.",
72
+ "next_site_page": "The next page of the project's agent-driven site run, with everything it needs in one call. The first time, start: true starts a run of every page that is not approved yet (with pageIds, only those): the site system first when the project has none, then each family's pilot, then the family's other pages. Each call claims one item through the same queue and leases as SpecShot's own worker and returns the item (its page, family, plan and pilot), the instructions, the text blocks in reading order (the site brief with the client's rules first, the kit, the family template with the pilot's <main>, the family's skills, the TYPE FACTS, and the page's own facts, copy and site map), the references by scope with links to open, the placeable images and the exact call to make. For a page, write only mainHtml and pageCss and publish them with publish_page_version and the itemId. For the site system item, write the style guide and save it with save_site_kit. A page you hold comes back until you publish it, and another: true claims one more beside it, up to the run's concurrency. known takes the fingerprints of blocks you already hold, which then come back as same: true. When the run waits on a person (the site system's approval or a family's pilot) it says so in waitingOn: a person approves in SpecShot or presses Continue without the client's approval, and you cannot pass a gate yourself. Your hold on a page lasts 16 minutes and renews each time you read or publish it. Requires a read/write token and an owner, admin or editor seat.",
73
+ "post_message": "Reply in a concept's conversation thread. Use this to answer the human's feedback, explain what you changed, or ask a question. The human sees it in the SpecShot portal. Requires a read/write token.",
74
+ "publish_page_version": "SAVE A DESIGN AND MAKE IT VISIBLE, in one call. Prefer this over save_wireframe: saving alone does NOT put the design on the owner's canvas, and an agent that saves without placing reports success on work nobody can see. Takes the same arguments as save_wireframe. SEND THE WHOLE PAGE, header to footer, every section in order: every save replaces the page, so a lone section sent as the page becomes the page. Publishing over the page's open draft replaces it, and a publish that would shrink it to a fragment is REFUSED unless allowShrink is true. Returns the concept, the frame, a canvas link, and — when the board could not accept it — says so plainly instead of implying it is visible. The save always succeeds or fails on its own merits: a full board never loses the design. Retrying the same publish inside ten minutes returns the SAME design instead of a duplicate, so change the name for a genuine second variation. Like save_wireframe, the response carries qualityWarnings and premium, a 0 to 100 readiness score against the premium bar; fix each failing point and publish again. SpecShot also checks the design law on every save and returns designLaw: a 0 to 100 score and findings, each with a code, a severity and a fix. Fix every block finding (clear slop: emoji icons, placeholder image hosts, lorem, no fluid type at all) and revise before you tell the user the design is ready; warn findings are worth the next revision. A save is never refused for a finding. It also renders the design 1440 and 390 px wide with scripts off, the way every preview shows it, and returns layoutCheck: a 0 to 100 score and findings in the same shape (content past the screen edge, content the next section covers, text invisible without a script, a heading off the content edge, section rhythm, column balance and more). Fix every block finding there too before you call the page ready. layoutCheck is absent when the server could not render the design. SITE MODE, for a page of an agent-driven site run: send projectId, itemId (from next_site_page), mainHtml and pageCss instead of name, html and css. SpecShot composes the whole page from the site kit (its :root, kit CSS, the header with this page marked, the footer and the agency credit; any :root, header or footer you wrote is removed), saves it as the item's page's next version, checks it against the law, the rendered layout and the kit (site.consistency), and marks the run's item. A first publish with a block finding keeps the page yours for one fix; the next publish finishes it, done, or flagged with a block finding left. finish: true finishes it at once. Requires a read/write token.",
75
+ "reply_to_comment": "Reply in a comment thread on a design, as the agent: say what you changed, ask what the person meant, or say why you did not. Pass the commentId of any comment in the thread (get_comments_for_section lists them); the reply goes under the thread's first comment and inherits its place on the design: the design, the section and the element pin (elementPath, anchorWidth). The people on the project read it on the canvas and in their comment digest. Closing the thread stays with resolve_design_comment, and closing a client's feedback stays with a person. Requires a read/write token.",
76
+ "reserve_section_uid": "Reserve the next unused stable id for a project. kind is SEC (section), LYR (layer), or CMP (component); type is the section or layer type (for example hero, headline, button). Returns an id like SS-SEC-HERO-002.",
77
+ "resolve_design_comment": "Move a feedback pin through its workflow. On feedback left by a CLIENT you may only set in_review — closing it is a person's decision and anything else is refused. Requires a read/write token.",
78
+ "restore_design_version": "Put a saved version of a design back as its current markup, for example when the person says \"go back to v3\". Find the version with get_design_versions and pass its id as versionId. The markup it replaces is saved first as a new version, and the result names it in undo, so a restore can always be taken back. Refused while the design is in front of the client in an open review round. Requires a read/write token.",
79
+ "revise_wireframe": "Revise a saved design's html/css in response to feedback, at full fidelity. Read the feedback first (get_messages), change what was asked, keep everything else, and SEND THE WHOLE PAGE back, header to footer: every revision replaces the page, and one that would shrink it to a fragment is REFUSED unless allowShrink is true. ALWAYS pass baseVersion: it is the only thing standing between you and silently discarding another agent's work on the same design. Pass sections too — the revised page's section names in document order — or the owner's selectable sections stay as the first build left them and any section you added never becomes clickable. Each revision is saved as a NEW design version and the previous one is kept, so the owner can put them side by side on the canvas; read them back with get_design_versions. Pass overwrite: true ONLY if the owner asked you to replace the design without keeping a version. The owner is notified. The response says whether the result is stored, versioned, filed and sections-in-step. The response may include qualityWarnings and a premium readiness score; keep revising until the warnings are gone or explicitly justified. SpecShot also checks the design law on every save and returns designLaw: a 0 to 100 score and findings, each with a code, a severity and a fix. Fix every block finding (clear slop: emoji icons, placeholder image hosts, lorem, no fluid type at all) and revise before you tell the user the design is ready; warn findings are worth the next revision. A save is never refused for a finding. Requires a read/write token.",
80
+ "save_decision": "Record taste a person stated in your chat, in their own words, for example \"the client wants real photos of the team, never stock\". It is kept as the project's taste: get_project_references returns it on every later page, and SpecShot may suggest a rule from it that a person accepts or dismisses. Say who said it with saidBy (client or agency), and name the page with pageId or the design with conceptId when it is about one. Save only what a person said, never your own opinion. Requires a read/write token.",
81
+ "save_site_kit": "Save the site system: one complete style-guide document every page of the site is built from. The site header and footer sit outside <main>; one <style> opens with the token :root; inside <main> each part (buttons, text links, form controls with their error and success states on one labeled board, card variants, a section intro, a media frame, a quote, a stat, an FAQ disclosure, a pricing tier, breadcrumbs, pagination and a call-to-action band) has its root marked data-component and each changing element data-prop. SpecShot embeds the faces --font-display and --font-text name, saves it as \"Site system vN\" under the Foundations page (the next version of the same design while the kit is still a draft), places it on the canvas, reads the kit off it into a draft site kit, and returns the extraction, kitFindings (every part a page needs that it could not read), designLaw, layoutCheck and findings by severity. In an agent-driven run send the site system item's itemId from next_site_page: a first save with a block finding keeps the item yours for one fix, and the next save finishes it. Nothing here approves the kit; a person does that in SpecShot. Requires a read/write token and an owner, admin or editor seat.",
82
+ "save_wireframe": "Save a full design you built into SpecShot. SEND THE WHOLE PAGE, header to footer, every section in order: every save replaces the page, so a lone section sent as the page becomes the page. PREFER publish_page_version: it takes the same arguments, saves the same way, and also places the design on the owner's canvas — save_wireframe stores it and places nothing, so the response says plainly that it is NOT visible. CALL get_wireframe_context FIRST and build from what it returns: the approved copy (copyBlocks), the sections the owner captured as reference with their real text, the brand tokens, and the page list. A design built without it will be rejected, because it will not match the project. Build FULL FIDELITY, the way the design_law prompt describes: real brand fonts embedded, the palette the build instruction sets, the canonical token names, fluid type and space, real SVG icons, real content, never a bare skeleton. Use the REAL copy, never lorem ipsum, because a client approves this. File it under the page it realizes by passing pageSlug (from get_wireframe_context), so the owner sees every version of a page side by side. Saving is also what makes the design's sections selectable, so the client can click a section and leave feedback on it. STUDY the inspiration images from get_wireframe_context before building, and use your frontend-design skill if you have one. The response may include qualityWarnings (placeholder copy, palette problems, missing SVG): fix them with revise_wireframe before telling the user the design is done. It also carries premium, a 0 to 100 readiness score against the premium bar (slabs, rhythm, depth, imagery, display face, motion); each failing point is a qualityWarning with its fix. SpecShot also checks the design law on every save and returns designLaw: a 0 to 100 score and findings, each with a code, a severity and a fix. Fix every block finding (clear slop: emoji icons, placeholder image hosts, lorem, no fluid type at all) and revise before you tell the user the design is ready; warn findings are worth the next revision. A save is never refused for a finding. You build the html; SpecShot stores it as given and calls no AI provider for this save. Requires a read/write token.",
83
+ "set_agent_status": "Post one line saying what you are doing on a project, for example \"Revising the pricing cards for phones\". People see it on the canvas, beside a placeholder frame where your next version will land, and in the project's activity. Name the page with pageId or the design with conceptId so the line shows on that page. Post a new line when your step changes, and send state \"done\" when you finish. A new line replaces your last one. Requires a read/write token.",
84
+ "set_page_families": "Create, regroup and edit a project's page families: the groups whose pages share one job, one hero archetype, one signature interaction and one section plan, each made from its approved pilot page. groupByCode: true groups every page in no family by its address, with no AI, and never moves a page a person placed. families: each entry edits a family by id, or makes one by name, with any of key, name, job, heroArchetype, signatureInteraction, sectionPlan (the family's sections in order, each with a key, name, layout, purpose, kit components and whether it is optional), kitComponents, pages to move into it (ids or slugs) and pilot (a page id or slug, or null). order lists families to put first, in the order a run makes them. The whole change is checked first, as the Families sheet checks a save: a change that adds an error to the plan (two families sharing a hero archetype, adjacent sections sharing a layout, a page in two families, a pilot outside its family, a component the kit lacks) is refused with its findings and nothing is written. Returns the families, the pages, the findings and readiness. Requires a read/write token.",
85
+ "set_page_schedule": "Set or clear a page's due date (dueOn: a date, or none) and its owner (ownerUserId: a teammate's userId, or none). Send one or both. The owner is a teammate who edits, never a viewer. Both are the team's own: the client never sees them. A date never moves the page or decides on it. Requires a read/write token.",
86
+ "set_project_intelligence": "Fill or update the project brief. This is how a client intake, a form, a markdown answer sheet, or a conversation becomes the structured brief the whole build reads from. Call get_project_intelligence first, then write only the fields you have. Omitted fields stay untouched. Discovery question and answer pairs append by default. Requires a read/write token.",
87
+ "set_round_due_date": "Set or clear the date the client is asked to answer an open review round by (dueOn: a date, or none). The client sees it in their portal. Pass roundId from list_project_tasks; without it, the one open round is used. A closed round has no date to set. Requires a read/write token.",
88
+ "set_target_launch": "Set or clear the project's target launch date (targetLaunchOn: a date like 2026-12-01, or none). The client sees it in their portal. Set only a date a person gave you. Requires a read/write token.",
89
+ "stream_design": "Write a design onto the canvas section by section, so people watch it fill in while you work. Start with action start: give pageId or pageSlug for the page it lands on (a new design for that page, named with name), or conceptId to revise that design (with the baseVersion you read), and the page's css if it has one. The result gives you a streamId. Then call action section once per section, in page order, with the streamId, the section's name, its html and its own css if any. Each section appears at once in a placeholder frame on the canvas, drawn through the same sanitizer as every saved design. Finish with action done and the streamId: SpecShot saves the sections as one new version, the way publish_page_version or revise_wireframe would, and answers with the same designLaw and quality report. Nothing is saved before done. A stream with no new section for two minutes closes and saves nothing. Only the agent that started a stream can add to it. Limits: 60 sections, 1,000 KB of markup in one section, 3,500 KB in the whole design. Requires a read/write token.",
90
+ "update_agent_task": "Update an agent task: set its status (draft, queued, running, waiting_for_user, completed, failed, canceled), record an output summary, or link the design version it produced. Requires a read/write token.",
91
+ "update_concept_status": "Update the status of a concept: 'sent' when you start building, 'built' when the build is complete, with an optional build note. Refused if the concept renders empty: markup with no text and no images cannot be reported as built, so fix the design rather than retrying. Never mark a design built while its designLaw has a block finding. Requires a read/write token.",
92
+ "update_design_layer": "Edit a layer in the panel: rename, hide or show, lock or unlock, or reorder. Pass the layer's uuid (the id field from get_design_layers, not the SS-LYR uid). A locked layer only accepts an unlock. Requires a read/write token.",
93
+ "update_design_section": "Quick-edit a section: rename it, change its order, or set its status (use status \"hidden\" to hide it and \"draft\" to show it again). Pass the section's uuid (the id field from get_design_sections, not the SS-SEC uid). Requires a read/write token.",
94
+ "update_project_task": "Change a task. Only the fields you send change: title, notes (empty to clear), status (todo, doing, done or canceled), assignee (a teammate's userId, client, or none), contactId, dueOn (a date, or none to clear it) and pageId (or none for the whole project). A viewer cannot be given a task. The activity feed says your agent changed it. Requires a read/write token.",
95
+ "update_seo_fix": "Mark an SEO checklist item fixed, ignored, or open again, with a note on what you changed (up to 2,000 characters). An item marked fixed is recorded as fixed by the agent; a recheck of the audit marks it verified when the problem is gone. Call it only once the change is live on the site. Requires a read/write token. Part of the Pro plan.",
96
+ };
97
+ export function toolDescription(name) {
98
+ return TOOL_DESCRIPTIONS[name] ?? `SpecShot tool ${name}.`;
99
+ }
@@ -0,0 +1,81 @@
1
+ import { z } from "zod";
2
+ import { toolDescription } from "../tool-descriptions.js";
3
+ function ok(data) {
4
+ return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
5
+ }
6
+ function fail(message) {
7
+ return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
8
+ }
9
+ const path = (projectId, rest) => `/api/mcp/projects/${encodeURIComponent(projectId)}/${rest}`;
10
+ /**
11
+ * The agent loop and design memory (docs/CANVAS-DOOP-PLAN.md section 4.6), over the REST routes
12
+ * under /api/mcp/projects/[id]. The hosted twin is apps/web/src/lib/mcp/tools-agent-loop.ts; the
13
+ * parity test holds the two to the same names, and each description comes from the generated
14
+ * tool-descriptions.ts, so the two transports cannot drift. The server checks every argument.
15
+ */
16
+ export function registerAgentLoopTools(server, client) {
17
+ server.tool("set_agent_status", toolDescription("set_agent_status"), {
18
+ projectId: z.string(),
19
+ status: z.string(),
20
+ state: z.enum(["working", "done"]).optional(),
21
+ pageId: z.string().optional(),
22
+ conceptId: z.string().optional(),
23
+ }, async ({ projectId, ...rest }) => {
24
+ try {
25
+ return ok(await client.post(path(projectId, "agent-status"), rest));
26
+ }
27
+ catch (e) {
28
+ return fail(e instanceof Error ? e.message : "Failed to post the status.");
29
+ }
30
+ });
31
+ server.tool("restore_design_version", toolDescription("restore_design_version"), { projectId: z.string(), versionId: z.string() }, async ({ projectId, versionId }) => {
32
+ try {
33
+ return ok(await client.post(path(projectId, "restore"), { versionId }));
34
+ }
35
+ catch (e) {
36
+ return fail(e instanceof Error ? e.message : "Failed to restore the version.");
37
+ }
38
+ });
39
+ server.tool("save_decision", toolDescription("save_decision"), {
40
+ projectId: z.string(),
41
+ statement: z.string(),
42
+ saidBy: z.enum(["client", "agency"]).optional(),
43
+ pageId: z.string().optional(),
44
+ conceptId: z.string().optional(),
45
+ }, async ({ projectId, ...rest }) => {
46
+ try {
47
+ return ok(await client.post(path(projectId, "decisions"), rest));
48
+ }
49
+ catch (e) {
50
+ return fail(e instanceof Error ? e.message : "Failed to save the decision.");
51
+ }
52
+ });
53
+ server.tool("stream_design", toolDescription("stream_design"), {
54
+ action: z.enum(["start", "section", "done"]),
55
+ projectId: z.string(),
56
+ streamId: z.string().optional(),
57
+ name: z.string().optional(),
58
+ html: z.string().optional(),
59
+ css: z.string().optional(),
60
+ pageId: z.string().optional(),
61
+ pageSlug: z.string().optional(),
62
+ conceptId: z.string().optional(),
63
+ baseVersion: z.number().optional(),
64
+ allowShrink: z.boolean().optional(),
65
+ }, async ({ projectId, ...rest }) => {
66
+ try {
67
+ return ok(await client.post(path(projectId, "stream"), rest));
68
+ }
69
+ catch (e) {
70
+ return fail(e instanceof Error ? e.message : "Failed to stream the design.");
71
+ }
72
+ });
73
+ server.tool("get_project_references", toolDescription("get_project_references"), { projectId: z.string(), versionId: z.string().optional() }, async ({ projectId, versionId }) => {
74
+ try {
75
+ return ok(await client.get(path(projectId, "references"), { versionId }));
76
+ }
77
+ catch (e) {
78
+ return fail(e instanceof Error ? e.message : "Failed to read the project's references.");
79
+ }
80
+ });
81
+ }
@@ -1,4 +1,5 @@
1
1
  import { z } from "zod";
2
+ import { toolDescription } from "../tool-descriptions.js";
2
3
  function ok(data) {
3
4
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
4
5
  }
@@ -6,7 +7,7 @@ function fail(message) {
6
7
  return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
7
8
  }
8
9
  export function registerBrandTools(server, client) {
9
- server.tool("get_brand_system", "Get the brand system (colors, typography, spacing, radius, animation tokens) for a project.", { projectId: z.string() }, async ({ projectId }) => {
10
+ server.tool("get_brand_system", toolDescription("get_brand_system"), { projectId: z.string() }, async ({ projectId }) => {
10
11
  try {
11
12
  const data = await client.get("/api/mcp/brand-systems", { projectId });
12
13
  return ok(data);
@@ -1,4 +1,5 @@
1
1
  import { z } from "zod";
2
+ import { toolDescription } from "../tool-descriptions.js";
2
3
  function ok(data) {
3
4
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
4
5
  }
@@ -6,7 +7,7 @@ function fail(message) {
6
7
  return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
7
8
  }
8
9
  export function registerCanvasTools(server, client) {
9
- server.tool("get_selection", 'What the user has selected on the SpecShot build canvas RIGHT NOW: the project, the design they have open, the active frame and its width, and the exact section or layer they have highlighted (with its stable id, SS-SEC-... / SS-LYR-...). Call this FIRST whenever the user says "this section", "this screen", "here", or "what I\'m looking at" — it resolves the reference without asking them. Returns selection: null with a hint when no canvas is open. Reports ageSeconds and stale so you can tell a live selection from a forgotten tab. Read-only.', { projectId: z.string().optional() }, async ({ projectId }) => {
10
+ server.tool("get_selection", toolDescription("get_selection"), { projectId: z.string().optional() }, async ({ projectId }) => {
10
11
  try {
11
12
  return ok(await client.get("/api/mcp/canvas", { action: "selection", projectId }));
12
13
  }
@@ -14,7 +15,7 @@ export function registerCanvasTools(server, client) {
14
15
  return fail(e instanceof Error ? e.message : "Failed to read the selection.");
15
16
  }
16
17
  });
17
- server.tool("list_frames", "The frames on the user's canvas board: what each points at, where it sits, how wide it is, who placed it, and whether you may close it. Call it before create_frame to see how many of the 6 slots are free, and to get the frameKey close_frame needs.", { projectId: z.string(), boardConceptId: z.string().optional() }, async ({ projectId, boardConceptId }) => {
18
+ server.tool("list_frames", toolDescription("list_frames"), { projectId: z.string(), boardConceptId: z.string().optional() }, async ({ projectId, boardConceptId }) => {
18
19
  try {
19
20
  return ok(await client.get("/api/mcp/canvas", { action: "frames", projectId, boardConceptId }));
20
21
  }
@@ -22,7 +23,7 @@ export function registerCanvasTools(server, client) {
22
23
  return fail(e instanceof Error ? e.message : "Failed to list frames.");
23
24
  }
24
25
  });
25
- server.tool("create_frame", "Place a design on the user's canvas board, beside what they are already looking at. This is how your work becomes VISIBLE: save_wireframe stores a design, create_frame makes it appear on screen. publish_page_version does both in one call and is the better default for a new page. Call it once per variation. Set viewport to show it at a phone (390px), tablet (768px), or desktop (1440px) width. Omit x and y to auto-place it to the right of everything else. A board holds 6 frames. Requires a read/write token.", {
26
+ server.tool("create_frame", toolDescription("create_frame"), {
26
27
  projectId: z.string(),
27
28
  boardConceptId: z.string().optional(),
28
29
  sourceConceptId: z.string().optional(),
@@ -39,7 +40,7 @@ export function registerCanvasTools(server, client) {
39
40
  return fail(e instanceof Error ? e.message : "Failed to create the frame.");
40
41
  }
41
42
  });
42
- server.tool("close_frame", "Remove a frame you placed from the user's canvas board, by frameKey (see list_frames). You can only close agent-placed frames: a frame the user added is theirs. Requires a read/write token.", { projectId: z.string(), boardConceptId: z.string().optional(), frameKey: z.string() }, async (args) => {
43
+ server.tool("close_frame", toolDescription("close_frame"), { projectId: z.string(), boardConceptId: z.string().optional(), frameKey: z.string() }, async (args) => {
43
44
  try {
44
45
  return ok(await client.post("/api/mcp/canvas", { action: "close_frame", ...args }));
45
46
  }
@@ -1,4 +1,5 @@
1
1
  import { z } from "zod";
2
+ import { toolDescription } from "../tool-descriptions.js";
2
3
  function ok(data) {
3
4
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
4
5
  }
@@ -6,7 +7,7 @@ function fail(message) {
6
7
  return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
7
8
  }
8
9
  export function registerConceptTools(server, client) {
9
- server.tool("list_concepts", "List design concepts in this SpecShot workspace. Filter by status to find approved concepts ready to build.", {
10
+ server.tool("list_concepts", toolDescription("list_concepts"), {
10
11
  projectId: z.string().optional(),
11
12
  status: z.enum(["draft", "reviewing", "approved", "sent", "built", "archived"]).optional(),
12
13
  }, async ({ projectId, status }) => {
@@ -18,7 +19,7 @@ export function registerConceptTools(server, client) {
18
19
  return fail(e instanceof Error ? e.message : "Failed to list concepts.");
19
20
  }
20
21
  });
21
- server.tool("get_concept", "Get a single design concept with its full Design Context Package — brand tokens, inspiration sources, transformation spec, and a ready-to-paste build prompt.", { conceptId: z.string() }, async ({ conceptId }) => {
22
+ server.tool("get_concept", toolDescription("get_concept"), { conceptId: z.string() }, async ({ conceptId }) => {
22
23
  try {
23
24
  const data = await client.get(`/api/mcp/concepts/${conceptId}`);
24
25
  return ok(data);
@@ -27,7 +28,7 @@ export function registerConceptTools(server, client) {
27
28
  return fail(e instanceof Error ? e.message : "Failed to get concept.");
28
29
  }
29
30
  });
30
- server.tool("get_approved_concept", "Get the most recently approved design concept for a project. Use this to start building immediately after the user approves a design in SpecShot.", { projectId: z.string() }, async ({ projectId }) => {
31
+ server.tool("get_approved_concept", toolDescription("get_approved_concept"), { projectId: z.string() }, async ({ projectId }) => {
31
32
  try {
32
33
  const list = await client.get("/api/mcp/concepts", {
33
34
  projectId,
@@ -44,7 +45,64 @@ export function registerConceptTools(server, client) {
44
45
  return fail(e instanceof Error ? e.message : "Failed to get the approved concept.");
45
46
  }
46
47
  });
47
- server.tool("update_concept_status", "Update the status of a concept. Use 'sent' when you start building, 'built' when the build is complete. Refused if the concept renders empty — markup with no text and no images cannot be reported as built, so fix the design rather than retrying.", {
48
+ server.tool("get_etch_build", toolDescription("get_etch_build"), {
49
+ conceptId: z.string(),
50
+ projectId: z.string().optional(),
51
+ mode: z.enum(["replace", "append"]).optional(),
52
+ dryRun: z.boolean().optional(),
53
+ // Images already uploaded to the site, by asset key: the script's MEDIA arrives filled in.
54
+ media: z
55
+ .record(z.object({ id: z.number().int().positive().optional(), url: z.string().optional() }))
56
+ .optional(),
57
+ }, async ({ conceptId, projectId, mode, dryRun, media }) => {
58
+ try {
59
+ const data = await client.get(`/api/mcp/concepts/${conceptId}/etch`, {
60
+ projectId,
61
+ mode,
62
+ dryRun: dryRun ? "1" : undefined,
63
+ media: media && Object.keys(media).length ? JSON.stringify(media) : undefined,
64
+ });
65
+ return ok(data);
66
+ }
67
+ catch (e) {
68
+ return fail(e instanceof Error ? e.message : "Failed to prepare the Etch build.");
69
+ }
70
+ });
71
+ server.tool("get_design_tokens", toolDescription("get_design_tokens"), {
72
+ conceptId: z.string(),
73
+ projectId: z.string().optional(),
74
+ }, async ({ conceptId, projectId }) => {
75
+ try {
76
+ const data = await client.get(`/api/mcp/concepts/${conceptId}/tokens`, { projectId });
77
+ return ok(data);
78
+ }
79
+ catch (e) {
80
+ return fail(e instanceof Error ? e.message : "Failed to read the design's tokens.");
81
+ }
82
+ });
83
+ server.tool("get_font_faces", toolDescription("get_font_faces"), {
84
+ families: z.array(z.string().max(80)).min(1).max(3),
85
+ }, async ({ families }) => {
86
+ try {
87
+ const data = await client.post(`/api/mcp/fonts`, { families });
88
+ return ok(data);
89
+ }
90
+ catch (e) {
91
+ return fail(e instanceof Error ? e.message : "Failed to embed the typefaces.");
92
+ }
93
+ });
94
+ server.tool("get_premium_exemplar", toolDescription("get_premium_exemplar"), {
95
+ part: z.enum(["all", "breakdown", "html"]).optional(),
96
+ }, async ({ part }) => {
97
+ try {
98
+ const data = await client.get(`/api/mcp/exemplar`, { part });
99
+ return ok(data);
100
+ }
101
+ catch (e) {
102
+ return fail(e instanceof Error ? e.message : "Failed to fetch the premium exemplar.");
103
+ }
104
+ });
105
+ server.tool("update_concept_status", toolDescription("update_concept_status"), {
48
106
  conceptId: z.string(),
49
107
  status: z.enum(["sent", "built"]),
50
108
  buildNote: z.string().optional(),
@@ -57,7 +115,7 @@ export function registerConceptTools(server, client) {
57
115
  return fail(e instanceof Error ? e.message : "Failed to update status.");
58
116
  }
59
117
  });
60
- server.tool("add_build_note", "Add a note to a concept — use this to log build progress, issues, or completion details.", { conceptId: z.string(), note: z.string() }, async ({ conceptId, note }) => {
118
+ server.tool("add_build_note", toolDescription("add_build_note"), { conceptId: z.string(), note: z.string() }, async ({ conceptId, note }) => {
61
119
  try {
62
120
  const data = await client.patch(`/api/mcp/concepts/${conceptId}/notes`, { note });
63
121
  return ok(data);
@@ -0,0 +1,30 @@
1
+ import { z } from "zod";
2
+ import { toolDescription } from "../tool-descriptions.js";
3
+ function ok(data) {
4
+ return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
5
+ }
6
+ function fail(message) {
7
+ return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
8
+ }
9
+ /**
10
+ * The Etch site audit for agents (docs/ETCH-TOOLKIT-LESSONS.md, item 3), over the REST route
11
+ * /api/mcp/etch/audit. The hosted endpoint registers the same tool from
12
+ * apps/web/src/lib/mcp/tools-etch-audit.ts, and the description comes from the generated
13
+ * tool-descriptions.ts, so the two transports cannot drift.
14
+ */
15
+ export function registerEtchAuditTools(server, client) {
16
+ server.tool("get_etch_audit", toolDescription("get_etch_audit"), {
17
+ remove: z.array(z.string().regex(/^(style|stylesheet|component):[A-Za-z0-9_-]{1,64}$/)).max(500).optional(),
18
+ scanPages: z.boolean().optional(),
19
+ }, async ({ remove, scanPages }) => {
20
+ try {
21
+ return ok(await client.get("/api/mcp/etch/audit", {
22
+ remove: remove && remove.length ? remove.join(",") : undefined,
23
+ scanPages: scanPages === false ? "0" : undefined,
24
+ }));
25
+ }
26
+ catch (e) {
27
+ return fail(e instanceof Error ? e.message : "Failed to prepare the Etch site audit.");
28
+ }
29
+ });
30
+ }
@@ -0,0 +1,67 @@
1
+ import { z } from "zod";
2
+ import { toolDescription } from "../tool-descriptions.js";
3
+ function ok(data) {
4
+ return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
5
+ }
6
+ function fail(message) {
7
+ return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
8
+ }
9
+ const ASPECTS = ["1:1", "4:3", "3:2", "16:9", "9:16"];
10
+ const STYLES = ["photo", "illustration", "3d", "abstract", "texture"];
11
+ /**
12
+ * Project images over the REST routes under /api/mcp/images. The hosted endpoint registers the
13
+ * same four tools from apps/web/src/lib/mcp/images.ts; the descriptions come from the generated
14
+ * tool-descriptions.ts, so the two transports can never drift.
15
+ */
16
+ export function registerImageTools(server, client) {
17
+ server.tool("generate_image", toolDescription("generate_image"), {
18
+ projectId: z.string(),
19
+ prompt: z.string().max(1000).optional(),
20
+ aspect: z.enum(ASPECTS).optional(),
21
+ style: z.enum(STYLES).optional(),
22
+ useBrand: z.boolean().optional(),
23
+ pageId: z.string().optional(),
24
+ designId: z.string().optional(),
25
+ parentId: z.string().optional(),
26
+ title: z.string().max(120).optional(),
27
+ }, async (args) => {
28
+ try {
29
+ return ok(await client.post("/api/mcp/images", args));
30
+ }
31
+ catch (e) {
32
+ return fail(e instanceof Error ? e.message : "Failed to generate the image.");
33
+ }
34
+ });
35
+ server.tool("get_image", toolDescription("get_image"), { imageId: z.string() }, async ({ imageId }) => {
36
+ try {
37
+ return ok(await client.get(`/api/mcp/images/${encodeURIComponent(imageId)}`));
38
+ }
39
+ catch (e) {
40
+ return fail(e instanceof Error ? e.message : "Failed to read the image.");
41
+ }
42
+ });
43
+ server.tool("list_images", toolDescription("list_images"), { projectId: z.string(), since: z.string().optional(), limit: z.number().int().min(1).max(60).optional() }, async ({ projectId, since, limit }) => {
44
+ try {
45
+ return ok(await client.get("/api/mcp/images", { projectId, since, limit: limit === undefined ? undefined : String(limit) }));
46
+ }
47
+ catch (e) {
48
+ return fail(e instanceof Error ? e.message : "Failed to list images.");
49
+ }
50
+ });
51
+ server.tool("add_image", toolDescription("add_image"), {
52
+ projectId: z.string(),
53
+ data: z.string(),
54
+ title: z.string().max(120).optional(),
55
+ alt: z.string().max(300).optional(),
56
+ prompt: z.string().max(1000).optional(),
57
+ pageId: z.string().optional(),
58
+ designId: z.string().optional(),
59
+ }, async (args) => {
60
+ try {
61
+ return ok(await client.post("/api/mcp/images/upload", args));
62
+ }
63
+ catch (e) {
64
+ return fail(e instanceof Error ? e.message : "Failed to add the image.");
65
+ }
66
+ });
67
+ }
@@ -1,4 +1,5 @@
1
1
  import { z } from "zod";
2
+ import { toolDescription } from "../tool-descriptions.js";
2
3
  function ok(data) {
3
4
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
4
5
  }
@@ -6,7 +7,7 @@ function fail(message) {
6
7
  return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
7
8
  }
8
9
  export function registerInspirationTools(server, client) {
9
- server.tool("list_inspiration", "List inspiration screenshots saved to a project's folders. These are the reference images the user collected before generating a concept.", { projectId: z.string(), folderId: z.string().optional() }, async ({ projectId, folderId }) => {
10
+ server.tool("list_inspiration", toolDescription("list_inspiration"), { projectId: z.string(), folderId: z.string().optional() }, async ({ projectId, folderId }) => {
10
11
  try {
11
12
  const data = await client.get("/api/mcp/inspiration", { projectId, folderId });
12
13
  return ok(data);
@@ -1,4 +1,5 @@
1
1
  import { z } from "zod";
2
+ import { toolDescription } from "../tool-descriptions.js";
2
3
  function ok(data) {
3
4
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
4
5
  }
@@ -12,7 +13,7 @@ function fail(message) {
12
13
  * replies with post_message. This is the back-and-forth loop.
13
14
  */
14
15
  export function registerMessageTools(server, client) {
15
- server.tool("get_messages", "Read the conversation thread on a concept, including any feedback the human left in the SpecShot portal. Poll this to see new human feedback before revising.", { conceptId: z.string() }, async ({ conceptId }) => {
16
+ server.tool("get_messages", toolDescription("get_messages"), { conceptId: z.string() }, async ({ conceptId }) => {
16
17
  try {
17
18
  return ok(await client.get(`/api/mcp/concepts/${conceptId}/messages`));
18
19
  }
@@ -20,7 +21,7 @@ export function registerMessageTools(server, client) {
20
21
  return fail(e instanceof Error ? e.message : "Failed to read messages.");
21
22
  }
22
23
  });
23
- server.tool("post_message", "Reply in a concept's conversation thread. Use this to answer the human's feedback, explain what you changed, or ask a question. The human sees it in the SpecShot portal. Requires a read/write token.", { conceptId: z.string(), body: z.string() }, async ({ conceptId, body }) => {
24
+ server.tool("post_message", toolDescription("post_message"), { conceptId: z.string(), body: z.string() }, async ({ conceptId, body }) => {
24
25
  try {
25
26
  return ok(await client.post(`/api/mcp/concepts/${conceptId}/messages`, { body }));
26
27
  }
@@ -28,7 +29,7 @@ export function registerMessageTools(server, client) {
28
29
  return fail(e instanceof Error ? e.message : "Failed to post message.");
29
30
  }
30
31
  });
31
- server.tool("revise_wireframe", "Revise a saved design's html/css in response to feedback, at full fidelity. Read the feedback first (get_messages), change what was asked, keep everything else. ALWAYS pass baseVersion: it is the only thing standing between you and silently discarding another agent's work on the same design. Pass sections too — the revised page's section names in document order — or the owner's selectable sections stay as the first build left them and any section you added never becomes clickable. Each revision is saved as a NEW design version and the previous one is KEPT, so the owner can put them side by side on the canvas; read them back with get_design_versions. Pass overwrite: true ONLY if the owner asked you to replace the design without keeping a version. Requires a read/write token.", {
32
+ server.tool("revise_wireframe", toolDescription("revise_wireframe"), {
32
33
  conceptId: z.string(),
33
34
  html: z.string(),
34
35
  css: z.string().optional(),
@@ -36,12 +37,17 @@ export function registerMessageTools(server, client) {
36
37
  // conflict guard the description calls the only thing standing between you and
37
38
  // discarding another agent's work was simply unreachable over this transport.
38
39
  baseVersion: z.number().optional(),
39
- sections: z.array(z.string()).optional(),
40
+ sections: z
41
+ .array(z.union([z.string().max(120), z.object({ name: z.string().min(1).max(120), html: z.string().optional(), css: z.string().optional() })]))
42
+ .optional(),
40
43
  /** Replace in place, keeping NO version. Only when the owner asked. */
41
44
  overwrite: z.boolean().optional(),
42
- }, async ({ conceptId, html, css, baseVersion, sections, overwrite }) => {
45
+ // The owner asked for a SHORTER page. The shared description names it and the
46
+ // hosted tool always had it; without it a stdio agent could not pass it at all.
47
+ allowShrink: z.boolean().optional(),
48
+ }, async ({ conceptId, html, css, baseVersion, sections, overwrite, allowShrink }) => {
43
49
  try {
44
- return ok(await client.patch(`/api/mcp/concepts/${conceptId}/wireframe`, { html, css, baseVersion, sections, overwrite }));
50
+ return ok(await client.patch(`/api/mcp/concepts/${conceptId}/wireframe`, { html, css, baseVersion, sections, overwrite, allowShrink }));
45
51
  }
46
52
  catch (e) {
47
53
  return fail(e instanceof Error ? e.message : "Failed to revise wireframe.");