@scayver/specshot-mcp-server 0.9.1 → 0.10.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 CHANGED
@@ -89,13 +89,17 @@ Wireframe building (build a full site yourself, no AI key):
89
89
  - `list_projects({})` — list the projects in your workspace.
90
90
  - `get_project_intelligence({ projectId })` — the full Project Intelligence Pack: brief, discovery, goals, audience, brand, captures, inspiration, pages, concepts (approved one flagged), constraints, agent instructions, acceptance criteria. Read this first.
91
91
  - `get_wireframe_context({ projectId })` — the brief, the pages, the brand tokens, the captured references, and a build instruction for a full multi-page wireframe.
92
- - `save_wireframe({ projectId, name, html, css?, pageType?, sections? })` — save a wireframe you built back into SpecShot as a concept. Needs a read/write token.
92
+ - `publish_page_version({ projectId, name, html, css?, sections?, pageSlug?, viewport? })` — save a design AND place it on the owner's canvas, in one call. The path to use for a new page: saving alone leaves the design invisible on the canvas. Retrying the same publish inside ten minutes returns the same design, not a duplicate. Needs a read/write token.
93
+ - `save_wireframe({ projectId, name, html, css?, pageType?, sections?, components? })` — save a design back into SpecShot as a concept, WITHOUT placing it on the canvas. Needs a read/write token.
94
+ - `link_concept_page({ conceptId, pageSlug? | pageId? })` — file an existing concept under a project page, or move it. Needs a read/write token.
95
+ - `create_page({ projectId, name, slug?, position?, kind? })` — add a page the brief implies. `kind` is `screens` (default), `foundations`, or `components`.
96
+ - `list_components({ projectId })` — the project's shared component library, and what has drifted between pages.
93
97
 
94
98
  Conversation (iterate with the human, both ways):
95
99
 
96
100
  - `get_messages({ conceptId })` — read the concept's thread, including feedback the human left in the portal.
97
101
  - `post_message({ conceptId, body })` — reply to the human. Needs a read/write token.
98
- - `revise_wireframe({ conceptId, html, css? })` — replace a saved wireframe's markup in response to feedback. Keeps every revision in the version history. Needs a read/write token.
102
+ - `revise_wireframe({ conceptId, html, css?, baseVersion?, sections? })` — replace a saved design's markup in response to feedback. Send `baseVersion` (the version you read) and a stale write is refused with a conflict instead of silently discarding someone else's work. Send `sections` (the revised page's section names in document order) or the owner's selectable sections stay as the first build left them. Each revision is stored as a new design version, readable with `get_design_versions`. Needs a read/write token.
99
103
 
100
104
  Agent Workspace (read the whole project, act on exact sections and layers):
101
105
 
@@ -135,8 +139,8 @@ Any connected LLM can build the whole site itself and save it back. Nothing call
135
139
 
136
140
  1. `list_projects({})` and pick a project.
137
141
  2. `get_wireframe_context({ projectId })`. You get the brief, every page, the brand tokens, the captured section references, and a build instruction.
138
- 3. Build one structural wireframe per page as a self-contained HTML document, following the instruction (low fidelity, brand-aware, responsive).
139
- 4. `save_wireframe({ projectId, name: "Home (wireframe)", html, ... })` for each page. SpecShot stores your HTML exactly as given.
142
+ 3. Build one FULL-FIDELITY design per page as a self-contained HTML document, following the instruction: real brand tokens, real SVG icons, real copy, fluid responsive, light and dark. Never a grey skeleton.
143
+ 4. `publish_page_version({ projectId, name: "Home", html, sections, pageSlug, ... })` for each page. SpecShot stores your HTML exactly as given, versions it, files it under the page, syncs its sections, and puts it on the owner's canvas.
140
144
  5. Open the project in SpecShot to review the wireframes, iterate, or promote them.
141
145
 
142
146
  ### Iterate back and forth
@@ -30,9 +30,25 @@ model on the server, so the quality is entirely yours.
30
30
  renders in the preview. One with an external url is dropped whole. Do not strip
31
31
  embedded fonts to work around the preview, and do not depend on locally installed
32
32
  fonts (a client reviewing in the portal does not have them).
33
- - Save each page with save_wireframe and ALWAYS pass its pageSlug, so it files under
34
- the page and its sections become selectable for client feedback. Revise in place
35
- with revise_wireframe when feedback arrives; keep version history.
33
+ - Publish each new page with publish_page_version, which saves AND places it on the
34
+ owner's canvas. ALWAYS pass its pageSlug, so it files under the page, and pass
35
+ sections (names in document order) so they become selectable for client feedback.
36
+ save_wireframe saves the same way but places nothing, so an agent that only saves
37
+ reports success on work nobody can see. Revise in place with revise_wireframe when
38
+ feedback arrives: send baseVersion and the revised sections. Every revision is
39
+ stored as a design version you can read back with get_design_versions.
40
+
41
+ ANTI-SLOP DESIGN LAW (craft floor, non-negotiable). Slop is the model's default, so these are
42
+ hard constraints. No Inter/Roboto/Geist/Fraunces by default, pair a display and body face,
43
+ headline at most 3 lines, body 14px or larger, measure 65-75ch, no kicker above a heading. One
44
+ accent under 80 percent saturation, no purple-to-cyan AI gradient, never pure black or white,
45
+ never gray text on color, no gradient text. A border or a shadow, never both, no nested cards,
46
+ no side-tab accent border. Break the center, no three equal cards. Exponential ease-out or
47
+ spring only, never bounce, animate transform and opacity only. Every value is a token, shared
48
+ UI is a component, repeated content is a loop, fluid with clamp and dvh from 360px to ultrawide.
49
+ Ship hover, focus, loading, empty, and error states. Organic content, no John Doe or Lorem. The
50
+ committed brand tokens win over any generic instinct.
51
+ Full law: "AIOS/00 Core/Core - Anti-Slop Design Law.md".
36
52
 
37
53
  get_wireframe_context returns the full, current, per-project build instruction. Read
38
54
  it before you build, and follow it as the authoritative standard.`;
@@ -22,7 +22,7 @@ export function registerCanvasTools(server, client) {
22
22
  return fail(e instanceof Error ? e.message : "Failed to list frames.");
23
23
  }
24
24
  });
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. 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.", {
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
26
  projectId: z.string(),
27
27
  boardConceptId: z.string().optional(),
28
28
  sourceConceptId: z.string().optional(),
@@ -44,7 +44,7 @@ export function registerConceptTools(server, client) {
44
44
  return fail(e instanceof Error ? e.message : "Failed to get the approved concept.");
45
45
  }
46
46
  });
47
- server.tool("update_concept_status", "Update the status of a concept. Use 'sent' when you start building, 'built' when the build is complete.", {
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
48
  conceptId: z.string(),
49
49
  status: z.enum(["sent", "built"]),
50
50
  buildNote: z.string().optional(),
@@ -28,9 +28,20 @@ export function registerMessageTools(server, client) {
28
28
  return fail(e instanceof Error ? e.message : "Failed to post message.");
29
29
  }
30
30
  });
31
- server.tool("revise_wireframe", "Revise a wireframe you already saved, in response to the human's feedback. Replaces its html/css and keeps every revision in the concept's version history. After revising, post_message to tell the human what you changed. Requires a read/write token.", { conceptId: z.string(), html: z.string(), css: z.string().optional() }, async ({ conceptId, html, css }) => {
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
+ conceptId: z.string(),
33
+ html: z.string(),
34
+ css: z.string().optional(),
35
+ // Was MISSING on stdio. The route forwards the body straight through, so the
36
+ // conflict guard the description calls the only thing standing between you and
37
+ // discarding another agent's work was simply unreachable over this transport.
38
+ baseVersion: z.number().optional(),
39
+ sections: z.array(z.string()).optional(),
40
+ /** Replace in place, keeping NO version. Only when the owner asked. */
41
+ overwrite: z.boolean().optional(),
42
+ }, async ({ conceptId, html, css, baseVersion, sections, overwrite }) => {
32
43
  try {
33
- return ok(await client.patch(`/api/mcp/concepts/${conceptId}/wireframe`, { html, css }));
44
+ return ok(await client.patch(`/api/mcp/concepts/${conceptId}/wireframe`, { html, css, baseVersion, sections, overwrite }));
34
45
  }
35
46
  catch (e) {
36
47
  return fail(e instanceof Error ? e.message : "Failed to revise wireframe.");
@@ -56,15 +56,18 @@ export function registerWireframeTools(server, client) {
56
56
  name: z.string(),
57
57
  slug: z.string().optional(),
58
58
  position: z.number().optional(),
59
- }, async ({ projectId, name, slug, position }) => {
59
+ // Was MISSING on stdio while lib/mcp/pages.ts already accepted it, so a
60
+ // foundations or components page could not be created over this transport.
61
+ kind: z.enum(["screens", "foundations", "components"]).optional(),
62
+ }, async ({ projectId, name, slug, position, kind }) => {
60
63
  try {
61
- return ok(await client.post(`/api/mcp/projects/${projectId}/pages`, { name, slug, position }));
64
+ return ok(await client.post(`/api/mcp/projects/${projectId}/pages`, { name, slug, position, kind }));
62
65
  }
63
66
  catch (e) {
64
67
  return fail(e instanceof Error ? e.message : "Failed to create the page.");
65
68
  }
66
69
  });
67
- server.tool("get_wireframe_context", "START HERE. Get everything needed to build a FULL multi-page website design for a project: the brief, the list of pages, the real brand tokens, the captured section references with their real copy, the inspiration, and the full build instruction that defines what done looks like (full fidelity, real tokens, real SVG icons, never grey placeholders). Build one full-fidelity page per page from this, then save each with save_wireframe. No AI runs on the SpecShot server, you do the building.", { projectId: z.string() }, async ({ projectId }) => {
70
+ server.tool("get_wireframe_context", "START HERE. Get everything needed to build a FULL multi-page website design for a project: the brief, the list of pages, the real brand tokens, the captured section references with their real copy, the inspiration, and the full build instruction that defines what done looks like (full fidelity, real tokens, real SVG icons, never grey placeholders). Build one full-fidelity page per page from this, then publish each with publish_page_version (which saves AND puts it on the owner's canvas). No AI runs on the SpecShot server, you do the building.", { projectId: z.string() }, async ({ projectId }) => {
68
71
  try {
69
72
  return ok(await client.get(`/api/mcp/projects/${projectId}/wireframe-context`));
70
73
  }
@@ -72,7 +75,7 @@ export function registerWireframeTools(server, client) {
72
75
  return fail(e instanceof Error ? e.message : "Failed to get wireframe context.");
73
76
  }
74
77
  });
75
- server.tool("save_wireframe", "Save a full design you built back into SpecShot as a design concept. Call this once per page after building that page from get_wireframe_context at FULL FIDELITY (real brand tokens, real SVG icons, real content, never grey placeholder boxes). Pass the project id, a name (for example \"Home\"), and the self-contained html (put css inline in a <style> block, or pass css separately). File it under the page it realizes by passing pageSlug (from get_wireframe_context), so the owner sees every version side by side and the design's sections become selectable for client feedback. STUDY the inspiration images first, and use your frontend-design skill if you have one. The response may include qualityWarnings (placeholder copy, grey-only palette, missing SVG): fix them with revise_wireframe before telling the user the design is done. SpecShot stores your html exactly as given and does not modify or regenerate it. Requires a read/write API token.", {
78
+ server.tool("save_wireframe", "Save a full design you built back into SpecShot as a design concept. PREFER publish_page_version, which does this AND places the design on the owner's canvas: saving alone leaves it invisible there. Call this once per page after building that page from get_wireframe_context at FULL FIDELITY (real brand tokens, real SVG icons, real content, never grey placeholder boxes). Pass the project id, a name (for example \"Home\"), and the self-contained html (put css inline in a <style> block, or pass css separately). File it under the page it realizes by passing pageSlug (from get_wireframe_context), so the owner sees every version side by side and the design's sections become selectable for client feedback. STUDY the inspiration images first, and use your frontend-design skill if you have one. The response may include qualityWarnings (placeholder copy, grey-only palette, missing SVG): fix them with revise_wireframe before telling the user the design is done. SpecShot stores your html exactly as given and does not modify or regenerate it. Requires a read/write API token.", {
76
79
  projectId: z.string(),
77
80
  name: z.string(),
78
81
  html: z.string(),
@@ -81,9 +84,11 @@ export function registerWireframeTools(server, client) {
81
84
  goal: z.string().optional(),
82
85
  sections: z.array(z.string()).optional(),
83
86
  builderTarget: z.string().optional(),
87
+ // Was MISSING on stdio, so component-drift tracking was hosted-only.
88
+ components: z.array(z.record(z.unknown())).optional(),
84
89
  pageSlug: z.string().optional(),
85
90
  pageId: z.string().optional(),
86
- }, async ({ projectId, name, html, css, pageType, goal, sections, builderTarget, pageSlug, pageId }) => {
91
+ }, async ({ projectId, name, html, css, pageType, goal, sections, builderTarget, components, pageSlug, pageId }) => {
87
92
  try {
88
93
  const data = await client.post("/api/mcp/concepts", {
89
94
  projectId,
@@ -94,6 +99,7 @@ export function registerWireframeTools(server, client) {
94
99
  goal,
95
100
  sections,
96
101
  builderTarget,
102
+ components,
97
103
  pageSlug,
98
104
  pageId,
99
105
  });
@@ -103,6 +109,41 @@ export function registerWireframeTools(server, client) {
103
109
  return fail(e instanceof Error ? e.message : "Failed to save wireframe.");
104
110
  }
105
111
  });
112
+ // Description COPY-IDENTICAL to the hosted registry (apps/web/src/lib/mcp-http-tools.ts
113
+ // publish_page_version). The description is the only thing an agent reads to decide
114
+ // whether to call a tool, so drift here makes the same agent behave differently on
115
+ // stdio than over the hosted endpoint — and this tool existed on hosted ONLY for its
116
+ // whole life, so a stdio agent was never told the save-and-place path exists.
117
+ server.tool("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. 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. Requires a read/write token.", {
118
+ projectId: z.string(),
119
+ name: z.string(),
120
+ html: z.string(),
121
+ css: z.string().optional(),
122
+ pageType: z.string().optional(),
123
+ goal: z.string().optional(),
124
+ sections: z.array(z.string()).optional(),
125
+ builderTarget: z.string().optional(),
126
+ components: z.array(z.record(z.unknown())).optional(),
127
+ pageSlug: z.string().optional(),
128
+ pageId: z.string().optional(),
129
+ viewport: z.enum(["mobile", "tablet", "desktop"]).optional(),
130
+ }, async (args) => {
131
+ try {
132
+ return ok(await client.post("/api/mcp/concepts/publish", args));
133
+ }
134
+ catch (e) {
135
+ return fail(e instanceof Error ? e.message : "Failed to publish the page version.");
136
+ }
137
+ });
138
+ // Description COPY-IDENTICAL to the hosted registry (list_components).
139
+ server.tool("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.", { projectId: z.string() }, async ({ projectId }) => {
140
+ try {
141
+ return ok(await client.get(`/api/mcp/projects/${projectId}/components`));
142
+ }
143
+ catch (e) {
144
+ return fail(e instanceof Error ? e.message : "Failed to list components.");
145
+ }
146
+ });
106
147
  server.tool("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 as 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 API token.", {
107
148
  conceptId: z.string(),
108
149
  pageSlug: z.string().optional(),
@@ -75,7 +75,7 @@ export function registerWorkspaceTools(server, client) {
75
75
  layerUid: z.string().optional(),
76
76
  priority: z.enum(["low", "medium", "high", "blocker"]).optional(),
77
77
  }, async (args) => call("add_comment", args, "Failed to add comment."));
78
- server.tool("resolve_design_comment", "Resolve or update a comment pin's status (resolved, accepted, rejected, in_review, needs_clarification). Requires a read/write API token.", { commentId: z.string(), status: z.string().optional() }, async ({ commentId, status }) => call("resolve_comment", { commentId, status }, "Failed to resolve comment."));
78
+ server.tool("resolve_design_comment", "Move a feedback pin through its workflow (resolved, accepted, rejected, in_review, needs_clarification). IMPORTANT: on feedback left by a CLIENT you may only set \"in_review\", to show you have picked it up. Deciding whether a client got what they asked for is a person's call, so resolved/accepted/rejected on a client comment is refused. Requires a read/write API token.", { commentId: z.string(), status: z.string().optional() }, async ({ commentId, status }) => call("resolve_comment", { commentId, status }, "Failed to resolve comment."));
79
79
  server.tool("get_handoff_package", "Get 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.", { projectId: z.string(), conceptId: z.string().optional() }, async ({ projectId, conceptId }) => call("get_handoff", { projectId, conceptId }, "Failed to get handoff package."));
80
80
  server.tool("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 API token.", {
81
81
  sectionId: z.string(),
@@ -90,5 +90,5 @@ export function registerWorkspaceTools(server, client) {
90
90
  locked: z.boolean().optional(),
91
91
  sortOrder: z.number().int().optional(),
92
92
  }, async (args) => call("update_layer", args, "Failed to update layer."));
93
- server.tool("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. Do this once so you and the user can reference exact sections. Requires a read/write API token.", { projectId: z.string(), conceptId: z.string() }, async ({ projectId, conceptId }) => call("extract_sections", { projectId, conceptId }, "Failed to extract sections."));
93
+ server.tool("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.", { projectId: z.string(), conceptId: z.string() }, async ({ projectId, conceptId }) => call("extract_sections", { projectId, conceptId }, "Failed to extract sections."));
94
94
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scayver/specshot-mcp-server",
3
- "version": "0.9.1",
3
+ "version": "0.10.0",
4
4
  "description": "MCP server for SpecShot — 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",