@scayver/specshot-mcp-server 0.11.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,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 2, review anywhere (docs/CANVAS-DOOP-PLAN.md, section 4.3). index.ts calls this
11
+ * once, so the slice registers its stdio tools here without editing index.ts. The hosted twin is
12
+ * apps/web/src/lib/mcp/tools-review.ts, and the parity test holds the two to the same tool names.
13
+ * Each tool calls a REST route under /api/mcp through `client` and takes its description from
14
+ * toolDescription(name), so the two transports say the same thing.
15
+ *
16
+ * reply_to_comment: POST /api/mcp/comments/[commentId]/replies. Requires a read/write token.
17
+ */
18
+ export function registerReviewTools(server, client) {
19
+ server.tool("reply_to_comment", toolDescription("reply_to_comment"), { commentId: z.string().uuid(), comment: z.string().min(1).max(8000) }, async ({ commentId, comment }) => {
20
+ try {
21
+ return ok(await client.post(`/api/mcp/comments/${encodeURIComponent(commentId)}/replies`, { comment }));
22
+ }
23
+ catch (e) {
24
+ return fail(e instanceof Error ? e.message : "Failed to reply to the comment.");
25
+ }
26
+ });
27
+ }
@@ -0,0 +1,78 @@
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)}/site/${rest}`;
10
+ /**
11
+ * Whole-site generation for agents (docs/WHOLE-SITE-GENERATION-PLAN.md, "Agents over MCP"), over the
12
+ * REST routes under /api/mcp/projects/[id]/site. The hosted twin is
13
+ * apps/web/src/lib/mcp/tools-site.ts; the parity test holds the two to the same names, and each
14
+ * description comes from the generated tool-descriptions.ts, so the two transports cannot drift.
15
+ * The server checks every argument. publish_page_version's site mode is registered with
16
+ * publish_page_version in wireframe.ts.
17
+ */
18
+ export function registerSiteTools(server, client) {
19
+ server.tool("get_site_plan", toolDescription("get_site_plan"), { projectId: z.string() }, async ({ projectId }) => {
20
+ try {
21
+ return ok(await client.get(path(projectId, "plan")));
22
+ }
23
+ catch (e) {
24
+ return fail(e instanceof Error ? e.message : "Failed to read the site plan.");
25
+ }
26
+ });
27
+ server.tool("get_site_kit", toolDescription("get_site_kit"), { projectId: z.string(), detail: z.enum(["summary", "full"]).optional() }, async ({ projectId, detail }) => {
28
+ try {
29
+ return ok(await client.get(path(projectId, "kit"), { detail }));
30
+ }
31
+ catch (e) {
32
+ return fail(e instanceof Error ? e.message : "Failed to read the site system.");
33
+ }
34
+ });
35
+ server.tool("save_site_kit", toolDescription("save_site_kit"), {
36
+ projectId: z.string(),
37
+ html: z.string(),
38
+ css: z.string().optional(),
39
+ direction: z.record(z.unknown()).optional(),
40
+ itemId: z.string().optional(),
41
+ allowShrink: z.boolean().optional(),
42
+ }, async ({ projectId, ...rest }) => {
43
+ try {
44
+ return ok(await client.post(path(projectId, "kit"), rest));
45
+ }
46
+ catch (e) {
47
+ return fail(e instanceof Error ? e.message : "Failed to save the site system.");
48
+ }
49
+ });
50
+ server.tool("set_page_families", toolDescription("set_page_families"), {
51
+ projectId: z.string(),
52
+ groupByCode: z.boolean().optional(),
53
+ families: z.array(z.record(z.unknown())).optional(),
54
+ order: z.array(z.string()).optional(),
55
+ }, async ({ projectId, ...rest }) => {
56
+ try {
57
+ return ok(await client.post(path(projectId, "families"), rest));
58
+ }
59
+ catch (e) {
60
+ return fail(e instanceof Error ? e.message : "Failed to change the page families.");
61
+ }
62
+ });
63
+ server.tool("next_site_page", toolDescription("next_site_page"), {
64
+ projectId: z.string(),
65
+ start: z.boolean().optional(),
66
+ pageIds: z.array(z.string()).optional(),
67
+ concurrency: z.number().optional(),
68
+ another: z.boolean().optional(),
69
+ known: z.array(z.string()).optional(),
70
+ }, async ({ projectId, ...rest }) => {
71
+ try {
72
+ return ok(await client.post(path(projectId, "next"), rest));
73
+ }
74
+ catch (e) {
75
+ return fail(e instanceof Error ? e.message : "Failed to take the next page of the site.");
76
+ }
77
+ });
78
+ }
@@ -0,0 +1,20 @@
1
+ import { z } from "zod";
2
+ import { toolDescription } from "../tool-descriptions.js";
3
+ import { SKILL_BODIES, SKILL_LIST } from "../skills.js";
4
+ function ok(data) {
5
+ return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
6
+ }
7
+ function fail(message) {
8
+ return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
9
+ }
10
+ export function registerSkillTools(server) {
11
+ server.tool("list_skills", toolDescription("list_skills"), {}, async () => ok(SKILL_LIST));
12
+ server.tool("get_skill", toolDescription("get_skill"), {
13
+ id: z.string().min(1).max(80),
14
+ }, async ({ id }) => {
15
+ const skill = SKILL_BODIES[id.trim().toLowerCase()];
16
+ if (!skill)
17
+ return fail(`No skill "${id}". Skills: ${Object.keys(SKILL_BODIES).join(", ")}.`);
18
+ return ok(skill);
19
+ });
20
+ }
@@ -0,0 +1,33 @@
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 project as people see it: stage, every page's state, whose turn it is, and the next call.
11
+ * Both tools read the same state the SpecShot project home and the client portal render, through
12
+ * the same server handler as the hosted endpoint, so the two transports cannot disagree.
13
+ */
14
+ export function registerStateTools(server, client) {
15
+ server.tool("get_project_state", toolDescription("get_project_state"), { projectId: z.string() }, async ({ projectId }) => {
16
+ try {
17
+ const data = await client.get(`/api/mcp/projects/${encodeURIComponent(projectId)}/state`);
18
+ return ok(data);
19
+ }
20
+ catch (e) {
21
+ return fail(e instanceof Error ? e.message : "Failed to read the project state.");
22
+ }
23
+ });
24
+ server.tool("get_next_action", toolDescription("get_next_action"), { projectId: z.string() }, async ({ projectId }) => {
25
+ try {
26
+ const data = await client.get(`/api/mcp/projects/${encodeURIComponent(projectId)}/next`);
27
+ return ok(data);
28
+ }
29
+ catch (e) {
30
+ return fail(e instanceof Error ? e.message : "Failed to read the next action.");
31
+ }
32
+ });
33
+ }
@@ -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
  }
@@ -13,7 +14,7 @@ function fail(message) {
13
14
  * structural wireframe itself, and save_wireframe stores the result back.
14
15
  */
15
16
  export function registerWireframeTools(server, client) {
16
- server.tool("list_projects", "List the projects in this SpecShot workspace. Use this to find the project to build a website wireframe for.", {}, async () => {
17
+ server.tool("list_projects", toolDescription("list_projects"), {}, async () => {
17
18
  try {
18
19
  return ok(await client.get("/api/mcp/projects"));
19
20
  }
@@ -21,7 +22,7 @@ export function registerWireframeTools(server, client) {
21
22
  return fail(e instanceof Error ? e.message : "Failed to list projects.");
22
23
  }
23
24
  });
24
- server.tool("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. Read this before making any change, so you work from the shared source of truth rather than a bare prompt.", { projectId: z.string() }, async ({ projectId }) => {
25
+ server.tool("get_project_intelligence", toolDescription("get_project_intelligence"), { projectId: z.string() }, async ({ projectId }) => {
25
26
  try {
26
27
  return ok(await client.get(`/api/mcp/projects/${projectId}/intelligence`));
27
28
  }
@@ -29,7 +30,7 @@ export function registerWireframeTools(server, client) {
29
30
  return fail(e instanceof Error ? e.message : "Failed to get project intelligence.");
30
31
  }
31
32
  });
32
- server.tool("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.", {
33
+ server.tool("set_project_intelligence", toolDescription("set_project_intelligence"), {
33
34
  projectId: z.string(),
34
35
  businessGoals: z.string().optional(),
35
36
  pageGoals: z.string().optional(),
@@ -51,7 +52,7 @@ export function registerWireframeTools(server, client) {
51
52
  return fail(e instanceof Error ? e.message : "Failed to update the brief.");
52
53
  }
53
54
  });
54
- server.tool("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. Requires a read/write token.", {
55
+ server.tool("create_page", toolDescription("create_page"), {
55
56
  projectId: z.string(),
56
57
  name: z.string(),
57
58
  slug: z.string().optional(),
@@ -59,15 +60,19 @@ export function registerWireframeTools(server, client) {
59
60
  // Was MISSING on stdio while lib/mcp/pages.ts already accepted it, so a
60
61
  // foundations or components page could not be created over this transport.
61
62
  kind: z.enum(["screens", "foundations", "components"]).optional(),
62
- }, async ({ projectId, name, slug, position, kind }) => {
63
+ // The page's intent: hosted had both and stdio had neither, while the shared
64
+ // description tells the agent to record them.
65
+ goal: z.string().max(2000).optional(),
66
+ requiredSections: z.array(z.string().max(200)).max(60).optional(),
67
+ }, async ({ projectId, name, slug, position, kind, goal, requiredSections }) => {
63
68
  try {
64
- return ok(await client.post(`/api/mcp/projects/${projectId}/pages`, { name, slug, position, kind }));
69
+ return ok(await client.post(`/api/mcp/projects/${projectId}/pages`, { name, slug, position, kind, goal, requiredSections }));
65
70
  }
66
71
  catch (e) {
67
72
  return fail(e instanceof Error ? e.message : "Failed to create the page.");
68
73
  }
69
74
  });
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 gray 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 }) => {
75
+ server.tool("get_wireframe_context", toolDescription("get_wireframe_context"), { projectId: z.string() }, async ({ projectId }) => {
71
76
  try {
72
77
  return ok(await client.get(`/api/mcp/projects/${projectId}/wireframe-context`));
73
78
  }
@@ -75,14 +80,17 @@ export function registerWireframeTools(server, client) {
75
80
  return fail(e instanceof Error ? e.message : "Failed to get wireframe context.");
76
81
  }
77
82
  });
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 gray 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, gray-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.", {
83
+ server.tool("save_wireframe", toolDescription("save_wireframe"), {
79
84
  projectId: z.string(),
80
85
  name: z.string(),
81
86
  html: z.string(),
82
87
  css: z.string().optional(),
83
88
  pageType: z.string().optional(),
84
89
  goal: z.string().optional(),
85
- sections: z.array(z.string()).optional(),
90
+ // A name, or {name, html, css}: the object form stores that section's own markup.
91
+ sections: z
92
+ .array(z.union([z.string().max(120), z.object({ name: z.string().min(1).max(120), html: z.string().optional(), css: z.string().optional() })]))
93
+ .optional(),
86
94
  builderTarget: z.string().optional(),
87
95
  // Was MISSING on stdio, so component-drift tracking was hosted-only.
88
96
  components: z.array(z.record(z.unknown())).optional(),
@@ -109,24 +117,36 @@ export function registerWireframeTools(server, client) {
109
117
  return fail(e instanceof Error ? e.message : "Failed to save wireframe.");
110
118
  }
111
119
  });
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.", {
120
+ // Description generated from the hosted registry (tool-descriptions.ts). The description
121
+ // is the only thing an agent reads to decide whether to call a tool, so drift here makes
122
+ // the same agent behave differently on stdio than over the hosted endpoint, and this tool
123
+ // existed on hosted ONLY for its whole life, so a stdio agent was never told the
124
+ // save-and-place path exists.
125
+ server.tool("publish_page_version", toolDescription("publish_page_version"), {
118
126
  projectId: z.string(),
119
- name: z.string(),
120
- html: z.string(),
127
+ // Required for a whole page; in site mode (itemId) the server builds the page and names it.
128
+ // The hosted handler says which is missing in a plain sentence.
129
+ name: z.string().optional(),
130
+ html: z.string().optional(),
121
131
  css: z.string().optional(),
122
132
  pageType: z.string().optional(),
123
133
  goal: z.string().optional(),
124
- sections: z.array(z.string()).optional(),
134
+ sections: z
135
+ .array(z.union([z.string().max(120), z.object({ name: z.string().min(1).max(120), html: z.string().optional(), css: z.string().optional() })]))
136
+ .optional(),
125
137
  builderTarget: z.string().optional(),
126
138
  components: z.array(z.record(z.unknown())).optional(),
127
139
  pageSlug: z.string().optional(),
128
140
  pageId: z.string().optional(),
129
141
  viewport: z.enum(["mobile", "tablet", "desktop"]).optional(),
142
+ // The owner asked for a shorter page; without it a publish over the draft that would
143
+ // replace the page with a fragment is refused by the hosted handler.
144
+ allowShrink: z.boolean().optional(),
145
+ // Site mode: a page of an agent-driven site run (next_site_page), composed from the site kit.
146
+ itemId: z.string().optional(),
147
+ mainHtml: z.string().optional(),
148
+ pageCss: z.string().optional(),
149
+ finish: z.boolean().optional(),
130
150
  }, async (args) => {
131
151
  try {
132
152
  return ok(await client.post("/api/mcp/concepts/publish", args));
@@ -135,8 +155,8 @@ export function registerWireframeTools(server, client) {
135
155
  return fail(e instanceof Error ? e.message : "Failed to publish the page version.");
136
156
  }
137
157
  });
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 }) => {
158
+ // Description generated from the hosted registry (list_components).
159
+ server.tool("list_components", toolDescription("list_components"), { projectId: z.string() }, async ({ projectId }) => {
140
160
  try {
141
161
  return ok(await client.get(`/api/mcp/projects/${projectId}/components`));
142
162
  }
@@ -144,7 +164,7 @@ export function registerWireframeTools(server, client) {
144
164
  return fail(e instanceof Error ? e.message : "Failed to list components.");
145
165
  }
146
166
  });
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.", {
167
+ server.tool("link_concept_page", toolDescription("link_concept_page"), {
148
168
  conceptId: z.string(),
149
169
  pageSlug: z.string().optional(),
150
170
  pageId: z.string().nullable().optional(),
@@ -0,0 +1,24 @@
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
+ * SpecShot for WordPress: the sites connected to a project through the SpecShot plugin, with
11
+ * whether each runs Automatic.css, over the REST route /api/mcp/projects/[id]/wordpress. The hosted
12
+ * endpoint registers the same tool from apps/web/src/lib/mcp/wordpress.ts, and the description
13
+ * comes from the generated tool-descriptions.ts, so the two transports cannot drift.
14
+ */
15
+ export function registerWordPressTools(server, client) {
16
+ server.tool("list_wordpress_sites", toolDescription("list_wordpress_sites"), { projectId: z.string() }, async ({ projectId }) => {
17
+ try {
18
+ return ok(await client.get(`/api/mcp/projects/${encodeURIComponent(projectId)}/wordpress`));
19
+ }
20
+ catch (e) {
21
+ return fail(e instanceof Error ? e.message : "Failed to list the project's WordPress sites.");
22
+ }
23
+ });
24
+ }
@@ -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
  }
@@ -27,21 +28,21 @@ export function registerWorkspaceTools(server, client) {
27
28
  }
28
29
  };
29
30
  // ----------------------------------------------------------------- reads
30
- server.tool("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.", { projectId: z.string() }, async ({ projectId }) => call("get_discovery", { projectId }, "Failed to get discovery answers."));
31
- server.tool("get_project_copy", "Read the project's per-section copywriting (headlines, body, CTAs, labels), with each block's status and version.", { projectId: z.string() }, async ({ projectId }) => call("get_copy", { projectId }, "Failed to get project copy."));
32
- server.tool("get_wireframes", "List the project's saved wireframes with type, status, and version.", { projectId: z.string() }, async ({ projectId }) => call("get_wireframes", { projectId }, "Failed to get wireframes."));
33
- server.tool("get_design_sections", "List 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.", { projectId: z.string(), conceptId: z.string().optional() }, async ({ projectId, conceptId }) => call("get_sections", { projectId, conceptId }, "Failed to get sections."));
34
- server.tool("get_section_by_uid", "Get 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.", { projectId: z.string(), sectionUid: z.string() }, async ({ projectId, sectionUid }) => call("get_section", { projectId, sectionUid }, "Failed to get section."));
35
- server.tool("get_design_layers", "List the Photoshop-style layers for a project. Optionally filter by conceptId or by sectionId (the section's uuid, from get_design_sections).", { projectId: z.string(), conceptId: z.string().optional(), sectionId: z.string().optional() }, async ({ projectId, conceptId, sectionId }) => call("get_layers", { projectId, conceptId, sectionId }, "Failed to get layers."));
36
- server.tool("get_layer_by_uid", "Get one layer by its layer id (for example SS-LYR-HEADLINE-001), with its style, layout, and animation data.", { projectId: z.string(), layerUid: z.string() }, async ({ projectId, layerUid }) => call("get_layer", { projectId, layerUid }, "Failed to get layer."));
37
- server.tool("get_design_versions", "List a project's design versions (newest first), each with its version number, parent, change summary, and status. Optionally filter by conceptId.", { projectId: z.string(), conceptId: z.string().optional() }, async ({ projectId, conceptId }) => call("get_design_versions", { projectId, conceptId }, "Failed to get design versions."));
38
- server.tool("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.", { projectId: z.string(), conceptId: z.string().optional() }, async ({ projectId, conceptId }) => call("get_selected_version", { projectId, conceptId }, "Failed to get selected version."));
39
- server.tool("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).", { projectId: z.string(), sectionUid: z.string().optional(), conceptId: z.string().optional(), status: z.string().optional() }, async ({ projectId, sectionUid, conceptId, status }) => call("get_comments", { projectId, sectionUid, conceptId, status }, "Failed to get comments."));
40
- server.tool("get_agent_tasks", "List the agent tasks for a project (newest first). Filter by status or conceptId. Use this to see what work is queued, running, or waiting for the user.", { projectId: z.string(), status: z.string().optional(), conceptId: z.string().optional() }, async ({ projectId, status, conceptId }) => call("get_agent_tasks", { projectId, status, conceptId }, "Failed to get agent tasks."));
41
- server.tool("get_project_memory", "Read the project's durable decisions and memory: approved decisions, rejected directions, and brand, copy, layout, and platform rules. Honor these in every revision.", { projectId: z.string() }, async ({ projectId }) => call("get_decisions", { projectId }, "Failed to get project memory."));
42
- server.tool("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.", { projectId: z.string(), kind: z.enum(["SEC", "LYR", "CMP"]), type: z.string() }, async ({ projectId, kind, type }) => call("reserve_uid", { projectId, kind, type }, "Failed to reserve a uid."));
31
+ server.tool("get_discovery_answers", toolDescription("get_discovery_answers"), { projectId: z.string() }, async ({ projectId }) => call("get_discovery", { projectId }, "Failed to get discovery answers."));
32
+ server.tool("get_project_copy", toolDescription("get_project_copy"), { projectId: z.string() }, async ({ projectId }) => call("get_copy", { projectId }, "Failed to get project copy."));
33
+ server.tool("get_wireframes", toolDescription("get_wireframes"), { projectId: z.string() }, async ({ projectId }) => call("get_wireframes", { projectId }, "Failed to get wireframes."));
34
+ server.tool("get_design_sections", toolDescription("get_design_sections"), { projectId: z.string(), conceptId: z.string().optional() }, async ({ projectId, conceptId }) => call("get_sections", { projectId, conceptId }, "Failed to get sections."));
35
+ server.tool("get_section_by_uid", toolDescription("get_section_by_uid"), { projectId: z.string(), sectionUid: z.string() }, async ({ projectId, sectionUid }) => call("get_section", { projectId, sectionUid }, "Failed to get section."));
36
+ server.tool("get_design_layers", toolDescription("get_design_layers"), { projectId: z.string(), conceptId: z.string().optional(), sectionId: z.string().optional() }, async ({ projectId, conceptId, sectionId }) => call("get_layers", { projectId, conceptId, sectionId }, "Failed to get layers."));
37
+ server.tool("get_layer_by_uid", toolDescription("get_layer_by_uid"), { projectId: z.string(), layerUid: z.string() }, async ({ projectId, layerUid }) => call("get_layer", { projectId, layerUid }, "Failed to get layer."));
38
+ server.tool("get_design_versions", toolDescription("get_design_versions"), { projectId: z.string(), conceptId: z.string().optional() }, async ({ projectId, conceptId }) => call("get_design_versions", { projectId, conceptId }, "Failed to get design versions."));
39
+ server.tool("get_selected_design_version", toolDescription("get_selected_design_version"), { projectId: z.string(), conceptId: z.string().optional() }, async ({ projectId, conceptId }) => call("get_selected_version", { projectId, conceptId }, "Failed to get selected version."));
40
+ server.tool("get_comments_for_section", toolDescription("get_comments_for_section"), { projectId: z.string(), sectionUid: z.string().optional(), conceptId: z.string().optional(), status: z.string().optional() }, async ({ projectId, sectionUid, conceptId, status }) => call("get_comments", { projectId, sectionUid, conceptId, status }, "Failed to get comments."));
41
+ server.tool("get_agent_tasks", toolDescription("get_agent_tasks"), { projectId: z.string(), status: z.string().optional(), conceptId: z.string().optional() }, async ({ projectId, status, conceptId }) => call("get_agent_tasks", { projectId, status, conceptId }, "Failed to get agent tasks."));
42
+ server.tool("get_project_memory", toolDescription("get_project_memory"), { projectId: z.string() }, async ({ projectId }) => call("get_decisions", { projectId }, "Failed to get project memory."));
43
+ server.tool("reserve_section_uid", toolDescription("reserve_section_uid"), { projectId: z.string(), kind: z.enum(["SEC", "LYR", "CMP"]), type: z.string() }, async ({ projectId, kind, type }) => call("reserve_uid", { projectId, kind, type }, "Failed to reserve a uid."));
43
44
  // ---------------------------------------------------------------- writes
44
- server.tool("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 API token.", {
45
+ server.tool("create_agent_task", toolDescription("create_agent_task"), {
45
46
  projectId: z.string(),
46
47
  title: z.string(),
47
48
  description: z.string().optional(),
@@ -51,13 +52,13 @@ export function registerWorkspaceTools(server, client) {
51
52
  priority: z.enum(["low", "medium", "high", "blocker"]).optional(),
52
53
  assignedAgent: z.string().optional(),
53
54
  }, async (args) => call("create_agent_task", args, "Failed to create agent task."));
54
- server.tool("update_agent_task", "Update an agent task: set its status (draft, queued, running, waiting_for_user, completed, failed, cancelled), record an output summary, or link the design version it produced. Requires a read/write API token.", {
55
+ server.tool("update_agent_task", toolDescription("update_agent_task"), {
55
56
  taskId: z.string(),
56
57
  status: z.string().optional(),
57
58
  outputSummary: z.string().optional(),
58
59
  versionId: z.string().optional(),
59
60
  }, async (args) => call("update_agent_task", args, "Failed to update agent task."));
60
- server.tool("create_design_version", "Create a NEW design version. This never overwrites existing or approved work: it always adds a new version, so the original is preserved. Pass the built html (and optional css), a change summary, and the parentVersionId it was revised from. Requires a read/write API token.", {
61
+ server.tool("create_design_version", toolDescription("create_design_version"), {
61
62
  projectId: z.string(),
62
63
  conceptId: z.string().optional(),
63
64
  parentVersionId: z.string().optional(),
@@ -67,28 +68,31 @@ export function registerWorkspaceTools(server, client) {
67
68
  html: z.string().optional(),
68
69
  css: z.string().optional(),
69
70
  }, async ({ html, css, ...rest }) => call("create_design_version", { ...rest, htmlPreview: html, cssPreview: css }, "Failed to create design version."));
70
- server.tool("add_design_comment", "Add a comment pin to the design, tied to a section and/or layer id. Use this to flag something or leave a note the user will see on the canvas. Requires a read/write API token.", {
71
+ server.tool("add_design_comment", toolDescription("add_design_comment"), {
71
72
  projectId: z.string(),
72
73
  comment: z.string(),
73
74
  conceptId: z.string().optional(),
74
75
  sectionUid: z.string().optional(),
75
76
  layerUid: z.string().optional(),
77
+ // The element pin (review anywhere): same-tag steps from the body, and the frame width meant.
78
+ elementPath: z.string().max(2000).optional(),
79
+ anchorWidth: z.number().int().min(200).max(4000).optional(),
76
80
  priority: z.enum(["low", "medium", "high", "blocker"]).optional(),
77
81
  }, async (args) => call("add_comment", args, "Failed to add 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
- 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
- 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.", {
82
+ server.tool("resolve_design_comment", toolDescription("resolve_design_comment"), { commentId: z.string(), status: z.string().optional() }, async ({ commentId, status }) => call("resolve_comment", { commentId, status }, "Failed to resolve comment."));
83
+ server.tool("get_handoff_package", toolDescription("get_handoff_package"), { projectId: z.string(), conceptId: z.string().optional() }, async ({ projectId, conceptId }) => call("get_handoff", { projectId, conceptId }, "Failed to get handoff package."));
84
+ server.tool("update_design_section", toolDescription("update_design_section"), {
81
85
  sectionId: z.string(),
82
86
  name: z.string().optional(),
83
87
  sectionOrder: z.number().int().optional(),
84
88
  status: z.string().optional(),
85
89
  }, async (args) => call("update_section", args, "Failed to update section."));
86
- server.tool("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 API token.", {
90
+ server.tool("update_design_layer", toolDescription("update_design_layer"), {
87
91
  layerId: z.string(),
88
92
  name: z.string().optional(),
89
93
  hidden: z.boolean().optional(),
90
94
  locked: z.boolean().optional(),
91
95
  sortOrder: z.number().int().optional(),
92
96
  }, 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. 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."));
97
+ server.tool("extract_concept_sections", toolDescription("extract_concept_sections"), { projectId: z.string(), conceptId: z.string() }, async ({ projectId, conceptId }) => call("extract_sections", { projectId, conceptId }, "Failed to extract sections."));
94
98
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scayver/specshot-mcp-server",
3
- "version": "0.11.0",
3
+ "version": "0.13.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",
@@ -46,7 +46,7 @@
46
46
  "prepublishOnly": "npm run build"
47
47
  },
48
48
  "dependencies": {
49
- "@modelcontextprotocol/sdk": "^1.0.0",
49
+ "@modelcontextprotocol/sdk": "^1.32.2",
50
50
  "zod": "^3.23.8"
51
51
  },
52
52
  "devDependencies": {