@scayver/specshot-mcp-server 0.10.0 → 0.13.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,87 @@
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
+ "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.",
18
+ "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.",
19
+ "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.",
20
+ "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.",
21
+ "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.",
22
+ "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.",
23
+ "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.",
24
+ "get_approved_concept": "The most recently approved concept for a project, as a full build package. Start here to build the approved design.",
25
+ "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.",
26
+ "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.",
27
+ "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).",
28
+ "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).",
29
+ "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.",
30
+ "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.",
31
+ "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`.",
32
+ "get_design_versions": "A project's design versions, newest first, each with its version number, parent, change summary, and status. Optionally filter by conceptId.",
33
+ "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.",
34
+ "get_etch_build": "Build a SpecShot design into a live Etch builder tab (Etch for WordPress or Etch Studio) through the Etch Connector. Returns `script`: save it to a file and run `npx @digital-gravy/etch-connector eval -f <file>` (add `-t <tab>` when several tabs are connected). 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` confirms the tab is connected. 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), put the ids in MEDIA at the top of the script, and run it again. Read `warnings` and pass them on to the user.",
35
+ "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.",
36
+ "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.",
37
+ "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.",
38
+ "get_layer_by_uid": "Get one layer by its layer id (for example SS-LYR-HEADLINE-001), with its style, layout, and animation data.",
39
+ "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.",
40
+ "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.",
41
+ "get_premium_exemplar": "Call this once before you design your first page, to see the premium bar met rather than described. Returns a complete one-page site for a fictional brand that clears all twelve points of the production gate in the premium_craft prompt: `html` (one document, one style block, one authored motion moment, a hero visual that is a real diagram of the product, written to survive SpecShot's preview), `sections` (each section's skeleton, ground and how it clears the gate), `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.",
42
+ "get_project_copy": "Read the project's per-section copywriting (headlines, body, CTAs, labels), with each block's status and version.",
43
+ "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.",
44
+ "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.",
45
+ "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.",
46
+ "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.",
47
+ "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.",
48
+ "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.",
49
+ "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.",
50
+ "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.",
51
+ "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.",
52
+ "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.",
53
+ "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.",
54
+ "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.",
55
+ "get_wireframes": "List the project's saved wireframes with type, status, and version.",
56
+ "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.",
57
+ "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.",
58
+ "list_concepts": "List design concepts and saved wireframes in your workspace, newest first. Filter by projectId or status.",
59
+ "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.",
60
+ "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.",
61
+ "list_inspiration": "List inspiration screenshots saved to a project, optionally filtered by folder.",
62
+ "list_projects": "List the projects in your SpecShot workspace, newest first.",
63
+ "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.",
64
+ "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.",
65
+ "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.",
66
+ "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.",
67
+ "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.",
68
+ "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.",
69
+ "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.",
70
+ "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.",
71
+ "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.",
72
+ "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.",
73
+ "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.",
74
+ "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.",
75
+ "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.",
76
+ "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.",
77
+ "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.",
78
+ "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.",
79
+ "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.",
80
+ "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.",
81
+ "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.",
82
+ "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.",
83
+ "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.",
84
+ };
85
+ export function toolDescription(name) {
86
+ return TOOL_DESCRIPTIONS[name] ?? `SpecShot tool ${name}.`;
87
+ }
@@ -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,59 @@ 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
+ }, async ({ conceptId, projectId, mode, dryRun }) => {
54
+ try {
55
+ const data = await client.get(`/api/mcp/concepts/${conceptId}/etch`, {
56
+ projectId,
57
+ mode,
58
+ dryRun: dryRun ? "1" : undefined,
59
+ });
60
+ return ok(data);
61
+ }
62
+ catch (e) {
63
+ return fail(e instanceof Error ? e.message : "Failed to prepare the Etch build.");
64
+ }
65
+ });
66
+ server.tool("get_design_tokens", toolDescription("get_design_tokens"), {
67
+ conceptId: z.string(),
68
+ projectId: z.string().optional(),
69
+ }, async ({ conceptId, projectId }) => {
70
+ try {
71
+ const data = await client.get(`/api/mcp/concepts/${conceptId}/tokens`, { projectId });
72
+ return ok(data);
73
+ }
74
+ catch (e) {
75
+ return fail(e instanceof Error ? e.message : "Failed to read the design's tokens.");
76
+ }
77
+ });
78
+ server.tool("get_font_faces", toolDescription("get_font_faces"), {
79
+ families: z.array(z.string().max(80)).min(1).max(3),
80
+ }, async ({ families }) => {
81
+ try {
82
+ const data = await client.post(`/api/mcp/fonts`, { families });
83
+ return ok(data);
84
+ }
85
+ catch (e) {
86
+ return fail(e instanceof Error ? e.message : "Failed to embed the typefaces.");
87
+ }
88
+ });
89
+ server.tool("get_premium_exemplar", toolDescription("get_premium_exemplar"), {
90
+ part: z.enum(["all", "breakdown", "html"]).optional(),
91
+ }, async ({ part }) => {
92
+ try {
93
+ const data = await client.get(`/api/mcp/exemplar`, { part });
94
+ return ok(data);
95
+ }
96
+ catch (e) {
97
+ return fail(e instanceof Error ? e.message : "Failed to fetch the premium exemplar.");
98
+ }
99
+ });
100
+ server.tool("update_concept_status", toolDescription("update_concept_status"), {
48
101
  conceptId: z.string(),
49
102
  status: z.enum(["sent", "built"]),
50
103
  buildNote: z.string().optional(),
@@ -57,7 +110,7 @@ export function registerConceptTools(server, client) {
57
110
  return fail(e instanceof Error ? e.message : "Failed to update status.");
58
111
  }
59
112
  });
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 }) => {
113
+ server.tool("add_build_note", toolDescription("add_build_note"), { conceptId: z.string(), note: z.string() }, async ({ conceptId, note }) => {
61
114
  try {
62
115
  const data = await client.patch(`/api/mcp/concepts/${conceptId}/notes`, { note });
63
116
  return ok(data);
@@ -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.");
@@ -0,0 +1,27 @@
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
+ * Owned by slice 3, click through the site (docs/CANVAS-DOOP-PLAN.md, section 4.4). index.ts calls
11
+ * this once. get_prototype reads the project as a click-through prototype over the REST route
12
+ * /api/mcp/projects/[id]/prototype. The hosted twin is apps/web/src/lib/mcp/tools-prototype.ts,
13
+ * the parity test holds the two to the same tool names, and the description comes from the
14
+ * generated tool-descriptions.ts, so the two transports cannot drift.
15
+ */
16
+ export function registerPrototypeTools(server, client) {
17
+ server.tool("get_prototype", toolDescription("get_prototype"), { projectId: z.string(), approved: z.boolean().optional() }, async ({ projectId, approved }) => {
18
+ try {
19
+ return ok(await client.get(`/api/mcp/projects/${encodeURIComponent(projectId)}/prototype`, {
20
+ approved: approved ? "1" : undefined,
21
+ }));
22
+ }
23
+ catch (e) {
24
+ return fail(e instanceof Error ? e.message : "Failed to read the project's prototype.");
25
+ }
26
+ });
27
+ }
@@ -0,0 +1,53 @@
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
+ * Owned by slice 4, export and render (docs/CANVAS-DOOP-PLAN.md, section 4.5). index.ts calls this
11
+ * once. The hosted twin is apps/web/src/lib/mcp/tools-render.ts, and the parity test holds the two
12
+ * to the same tool names. Each tool calls a REST route under /api/mcp through `client` and takes its
13
+ * description from toolDescription(name).
14
+ *
15
+ * get_design_screenshot renders a design in SpecShot's server browser and returns a signed link to
16
+ * the PNG, valid for an hour, over the REST route /api/mcp/render/screenshot.
17
+ *
18
+ * check_built_page compares the page built on the client's WordPress site with the approved design,
19
+ * over the REST route /api/mcp/render/built-check. It opens only the address a connected site
20
+ * reported, so it takes a design id and never an address.
21
+ */
22
+ export function registerRenderTools(server, client) {
23
+ server.tool("get_design_screenshot", toolDescription("get_design_screenshot"), {
24
+ designId: z.string(),
25
+ width: z.number().optional(),
26
+ section: z.string().optional(),
27
+ }, async ({ designId, width, section }) => {
28
+ try {
29
+ return ok(await client.get("/api/mcp/render/screenshot", {
30
+ designId,
31
+ width: width === undefined ? undefined : String(width),
32
+ section,
33
+ }));
34
+ }
35
+ catch (e) {
36
+ return fail(e instanceof Error ? e.message : "Failed to render the design.");
37
+ }
38
+ });
39
+ server.tool("check_built_page", toolDescription("check_built_page"), {
40
+ designId: z.string(),
41
+ refresh: z.boolean().optional(),
42
+ }, async ({ designId, refresh }) => {
43
+ try {
44
+ return ok(await client.get("/api/mcp/render/built-check", {
45
+ designId,
46
+ refresh: refresh === undefined ? undefined : String(refresh),
47
+ }));
48
+ }
49
+ catch (e) {
50
+ return fail(e instanceof Error ? e.message : "Failed to check the built page.");
51
+ }
52
+ });
53
+ }