@scayver/specshot-mcp-server 0.13.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.
- package/README.md +14 -0
- package/dist/build-standard.js +937 -687
- package/dist/index.js +9 -0
- package/dist/skills.js +46 -20
- package/dist/tool-descriptions.js +14 -2
- package/dist/tools/concepts.js +6 -1
- package/dist/tools/etch-audit.js +30 -0
- package/dist/tools/seo.js +56 -0
- package/dist/tools/tasks.js +60 -0
- package/package.json +1 -1
|
@@ -14,10 +14,12 @@ export const TOOL_DESCRIPTIONS = {
|
|
|
14
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
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
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.",
|
|
17
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.",
|
|
18
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.",
|
|
19
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.",
|
|
20
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.",
|
|
21
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.",
|
|
22
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.",
|
|
23
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.",
|
|
@@ -31,14 +33,15 @@ export const TOOL_DESCRIPTIONS = {
|
|
|
31
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`.",
|
|
32
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.",
|
|
33
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.",
|
|
34
|
-
"
|
|
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.",
|
|
35
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.",
|
|
36
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.",
|
|
37
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.",
|
|
38
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.",
|
|
39
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.",
|
|
40
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.",
|
|
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
|
|
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.",
|
|
42
45
|
"get_project_copy": "Read the project's per-section copywriting (headlines, body, CTAs, labels), with each block's status and version.",
|
|
43
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.",
|
|
44
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,6 +51,7 @@ export const TOOL_DESCRIPTIONS = {
|
|
|
48
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.",
|
|
49
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.",
|
|
50
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.",
|
|
51
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.",
|
|
52
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.",
|
|
53
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.",
|
|
@@ -59,7 +63,10 @@ export const TOOL_DESCRIPTIONS = {
|
|
|
59
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.",
|
|
60
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.",
|
|
61
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.",
|
|
62
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.",
|
|
63
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.",
|
|
64
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.",
|
|
65
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.",
|
|
@@ -75,12 +82,17 @@ export const TOOL_DESCRIPTIONS = {
|
|
|
75
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.",
|
|
76
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.",
|
|
77
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.",
|
|
78
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.",
|
|
79
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.",
|
|
80
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.",
|
|
81
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.",
|
|
82
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.",
|
|
83
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.",
|
|
84
96
|
};
|
|
85
97
|
export function toolDescription(name) {
|
|
86
98
|
return TOOL_DESCRIPTIONS[name] ?? `SpecShot tool ${name}.`;
|
package/dist/tools/concepts.js
CHANGED
|
@@ -50,12 +50,17 @@ export function registerConceptTools(server, client) {
|
|
|
50
50
|
projectId: z.string().optional(),
|
|
51
51
|
mode: z.enum(["replace", "append"]).optional(),
|
|
52
52
|
dryRun: z.boolean().optional(),
|
|
53
|
-
|
|
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 }) => {
|
|
54
58
|
try {
|
|
55
59
|
const data = await client.get(`/api/mcp/concepts/${conceptId}/etch`, {
|
|
56
60
|
projectId,
|
|
57
61
|
mode,
|
|
58
62
|
dryRun: dryRun ? "1" : undefined,
|
|
63
|
+
media: media && Object.keys(media).length ? JSON.stringify(media) : undefined,
|
|
59
64
|
});
|
|
60
65
|
return ok(data);
|
|
61
66
|
}
|
|
@@ -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,56 @@
|
|
|
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 num = (v) => (v === undefined ? undefined : String(v));
|
|
10
|
+
/**
|
|
11
|
+
* SEO fixes for agents (docs/SEO-PORTAL-PLAN.md, phase 5): the workspace's SEO audits, their plan to
|
|
12
|
+
* 100, the open checklist items with each one's exact instruction, and marking an item done, over
|
|
13
|
+
* the REST routes under /api/mcp/seo. The hosted endpoint registers the same tools from
|
|
14
|
+
* apps/web/src/lib/mcp/tools-seo.ts, and the descriptions come from the generated
|
|
15
|
+
* tool-descriptions.ts, so the two transports cannot drift.
|
|
16
|
+
*/
|
|
17
|
+
export function registerSeoTools(server, client) {
|
|
18
|
+
server.tool("list_seo_audits", toolDescription("list_seo_audits"), { projectId: z.string().optional(), limit: z.number().optional(), offset: z.number().optional() }, async ({ projectId, limit, offset }) => {
|
|
19
|
+
try {
|
|
20
|
+
return ok(await client.get("/api/mcp/seo/audits", { projectId, limit: num(limit), offset: num(offset) }));
|
|
21
|
+
}
|
|
22
|
+
catch (e) {
|
|
23
|
+
return fail(e instanceof Error ? e.message : "Failed to list the SEO audits.");
|
|
24
|
+
}
|
|
25
|
+
});
|
|
26
|
+
server.tool("get_seo_audit", toolDescription("get_seo_audit"), { auditId: z.string() }, async ({ auditId }) => {
|
|
27
|
+
try {
|
|
28
|
+
return ok(await client.get(`/api/mcp/seo/audits/${encodeURIComponent(auditId)}`));
|
|
29
|
+
}
|
|
30
|
+
catch (e) {
|
|
31
|
+
return fail(e instanceof Error ? e.message : "Failed to read the SEO audit.");
|
|
32
|
+
}
|
|
33
|
+
});
|
|
34
|
+
server.tool("list_seo_fixes", toolDescription("list_seo_fixes"), {
|
|
35
|
+
auditId: z.string(),
|
|
36
|
+
status: z.enum(["open", "fixed", "ignored", "verified", "all"]).optional(),
|
|
37
|
+
page: z.string().optional(),
|
|
38
|
+
limit: z.number().optional(),
|
|
39
|
+
offset: z.number().optional(),
|
|
40
|
+
}, async ({ auditId, status, page, limit, offset }) => {
|
|
41
|
+
try {
|
|
42
|
+
return ok(await client.get(`/api/mcp/seo/audits/${encodeURIComponent(auditId)}/fixes`, { status, page, limit: num(limit), offset: num(offset) }));
|
|
43
|
+
}
|
|
44
|
+
catch (e) {
|
|
45
|
+
return fail(e instanceof Error ? e.message : "Failed to read the SEO checklist.");
|
|
46
|
+
}
|
|
47
|
+
});
|
|
48
|
+
server.tool("update_seo_fix", toolDescription("update_seo_fix"), { auditId: z.string(), fixId: z.string(), status: z.enum(["fixed", "ignored", "open"]), note: z.string().optional() }, async ({ auditId, fixId, status, note }) => {
|
|
49
|
+
try {
|
|
50
|
+
return ok(await client.patch(`/api/mcp/seo/audits/${encodeURIComponent(auditId)}/fixes/${encodeURIComponent(fixId)}`, { status, ...(note !== undefined ? { note } : {}) }));
|
|
51
|
+
}
|
|
52
|
+
catch (e) {
|
|
53
|
+
return fail(e instanceof Error ? e.message : "Failed to update the SEO checklist item.");
|
|
54
|
+
}
|
|
55
|
+
});
|
|
56
|
+
}
|
|
@@ -0,0 +1,60 @@
|
|
|
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 num = (v) => (v === undefined ? undefined : String(v));
|
|
10
|
+
const path = (projectId, rest) => `/api/mcp/projects/${encodeURIComponent(projectId)}/${rest}`;
|
|
11
|
+
async function run(work, label) {
|
|
12
|
+
try {
|
|
13
|
+
return ok(await work());
|
|
14
|
+
}
|
|
15
|
+
catch (e) {
|
|
16
|
+
return fail(e instanceof Error ? e.message : label);
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Project tasks for agents (docs/PROJECT-FLOW-PLAN.md, Phase 4): read a project's tasks for people,
|
|
21
|
+
* add, change and close them, and set the dates beside them (a page's due date and owner, an open
|
|
22
|
+
* round's answer-by date, the target launch), over the REST routes under /api/mcp/projects/[id]/tasks
|
|
23
|
+
* and /schedule. The hosted endpoint registers the same tools from
|
|
24
|
+
* apps/web/src/lib/mcp/tools-tasks.ts, and the descriptions come from the generated
|
|
25
|
+
* tool-descriptions.ts, so the two transports cannot drift. The server checks every argument.
|
|
26
|
+
*/
|
|
27
|
+
export function registerTaskTools(server, client) {
|
|
28
|
+
server.tool("list_project_tasks", toolDescription("list_project_tasks"), {
|
|
29
|
+
projectId: z.string(),
|
|
30
|
+
filter: z.enum(["open", "mine", "done", "all"]).optional(),
|
|
31
|
+
pageId: z.string().optional(),
|
|
32
|
+
limit: z.number().optional(),
|
|
33
|
+
offset: z.number().optional(),
|
|
34
|
+
}, async ({ projectId, filter, pageId, limit, offset }) => run(() => client.get(path(projectId, "tasks"), { filter, pageId, limit: num(limit), offset: num(offset) }), "Failed to list the project's tasks."));
|
|
35
|
+
server.tool("create_project_task", toolDescription("create_project_task"), {
|
|
36
|
+
projectId: z.string(),
|
|
37
|
+
title: z.string(),
|
|
38
|
+
notes: z.string().optional(),
|
|
39
|
+
pageId: z.string().optional(),
|
|
40
|
+
assignee: z.string().optional(),
|
|
41
|
+
contactId: z.string().optional(),
|
|
42
|
+
dueOn: z.string().optional(),
|
|
43
|
+
status: z.enum(["todo", "doing"]).optional(),
|
|
44
|
+
}, async ({ projectId, ...rest }) => run(() => client.post(path(projectId, "tasks"), rest), "Failed to add the task."));
|
|
45
|
+
server.tool("update_project_task", toolDescription("update_project_task"), {
|
|
46
|
+
projectId: z.string(),
|
|
47
|
+
taskId: z.string(),
|
|
48
|
+
title: z.string().optional(),
|
|
49
|
+
notes: z.string().optional(),
|
|
50
|
+
status: z.enum(["todo", "doing", "done", "canceled"]).optional(),
|
|
51
|
+
assignee: z.string().optional(),
|
|
52
|
+
contactId: z.string().optional(),
|
|
53
|
+
dueOn: z.string().optional(),
|
|
54
|
+
pageId: z.string().optional(),
|
|
55
|
+
}, async ({ projectId, taskId, ...rest }) => run(() => client.patch(path(projectId, `tasks/${encodeURIComponent(taskId)}`), rest), "Failed to change the task."));
|
|
56
|
+
server.tool("complete_project_task", toolDescription("complete_project_task"), { projectId: z.string(), taskId: z.string() }, async ({ projectId, taskId }) => run(() => client.post(path(projectId, `tasks/${encodeURIComponent(taskId)}/complete`), {}), "Failed to mark the task done."));
|
|
57
|
+
server.tool("set_page_schedule", toolDescription("set_page_schedule"), { projectId: z.string(), pageId: z.string(), dueOn: z.string().optional(), ownerUserId: z.string().optional() }, async ({ projectId, ...rest }) => run(() => client.patch(path(projectId, "schedule/page"), rest), "Failed to set the page's date or owner."));
|
|
58
|
+
server.tool("set_round_due_date", toolDescription("set_round_due_date"), { projectId: z.string(), roundId: z.string().optional(), dueOn: z.string() }, async ({ projectId, ...rest }) => run(() => client.patch(path(projectId, "schedule/round"), rest), "Failed to set the round's date."));
|
|
59
|
+
server.tool("set_target_launch", toolDescription("set_target_launch"), { projectId: z.string(), targetLaunchOn: z.string() }, async ({ projectId, ...rest }) => run(() => client.patch(path(projectId, "schedule/launch"), rest), "Failed to set the target launch."));
|
|
60
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@scayver/specshot-mcp-server",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.0",
|
|
4
4
|
"description": "MCP server for SpecShot \u2014 lets Claude Code, Claude Desktop, and Cursor fetch approved design concepts with brand tokens and a ready-to-build prompt.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"mcp",
|