@scayver/specshot-mcp-server 0.5.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 +150 -0
- package/dist/client.js +56 -0
- package/dist/index.js +30 -0
- package/dist/tools/brand.js +18 -0
- package/dist/tools/concepts.js +69 -0
- package/dist/tools/inspiration.js +18 -0
- package/dist/tools/messages.js +39 -0
- package/dist/tools/wireframe.js +67 -0
- package/dist/tools/workspace.js +94 -0
- package/package.json +44 -0
package/README.md
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# @scayver/specshot-mcp-server
|
|
2
|
+
|
|
3
|
+
A Model Context Protocol (MCP) server for [SpecShot](https://specshot.cc). It lets Claude Code, Claude Desktop, Cursor, Codex, and any other MCP client work directly against your SpecShot workspace. Any of these LLMs can:
|
|
4
|
+
|
|
5
|
+
- Pull an approved design concept with its full brand tokens, references, and a ready-to-build prompt, then build it.
|
|
6
|
+
- Build a complete multi-page website wireframe from a project's context and save it straight back into SpecShot.
|
|
7
|
+
|
|
8
|
+
All of this runs in your own LLM. SpecShot never calls an AI provider for it, so you do not need an AI key, and it works the same in Claude Code, Cursor, Codex, or any MCP client. The server is a thin stdio adapter over SpecShot's token-authenticated `/api/mcp/*` API.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
NOT YET ON NPM: `npx -y @scayver/specshot-mcp-server` fails with a 404 until the package
|
|
13
|
+
is published. Until then, run the local build:
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
cd apps/mcp-server
|
|
17
|
+
npm install
|
|
18
|
+
npm run build # compiles TypeScript into dist/. Always run it explicitly.
|
|
19
|
+
node dist/index.js
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
`npm install` alone does NOT reliably produce `dist/`: it only builds via the
|
|
23
|
+
`prepare` hook, which `npm ci` skips and which behaves differently across npm
|
|
24
|
+
versions and workspaces. Always run `npm run build`. Rebuild after any src
|
|
25
|
+
change. The server prints a startup
|
|
26
|
+
banner to stderr with its version and target URL, so a stale dist is visible at
|
|
27
|
+
a glance: `[specshot-mcp] v0.5.0 -> https://specshot.cc`. If the banner shows an
|
|
28
|
+
old version, rebuild. The 0.5.0 server exposes the full workspace toolset
|
|
29
|
+
(roughly 37 tools); seeing only 13 tools means you are running a 0.3.0 dist.
|
|
30
|
+
|
|
31
|
+
After publishing, npx works with no install:
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
npx -y @scayver/specshot-mcp-server
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Required environment
|
|
38
|
+
|
|
39
|
+
- `SPECSHOT_API_TOKEN` — a `spec_`-prefixed token from SpecShot, Settings, API Tokens. Required.
|
|
40
|
+
- `SPECSHOT_APP_URL` — your SpecShot URL. Defaults to `https://specshot.cc`.
|
|
41
|
+
|
|
42
|
+
## Client setup
|
|
43
|
+
|
|
44
|
+
The server speaks stdio MCP, so it works in every major MCP client. Use a read/write token to save wireframes back (a read-only token can still read concepts and context). Replace `spec_your_token_here` with a real token from SpecShot, Settings, API Tokens: the placeholder authenticates against nothing. Set `SPECSHOT_APP_URL` explicitly when pointing at a local dev instance; unset, it defaults to `https://specshot.cc`.
|
|
45
|
+
|
|
46
|
+
Until the npm publish, swap `"command": "npx", "args": ["-y", "@scayver/specshot-mcp-server"]` for the local build: `"command": "node", "args": ["/absolute/path/to/specshot/apps/mcp-server/dist/index.js"]`.
|
|
47
|
+
|
|
48
|
+
Claude Code (`~/.claude/settings.json`), Claude Desktop (`claude_desktop_config.json`), Cursor (`.cursor/mcp.json` or Cursor Settings, MCP), and Cline all use the same JSON:
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"mcpServers": {
|
|
53
|
+
"specshot": {
|
|
54
|
+
"command": "npx",
|
|
55
|
+
"args": ["-y", "@scayver/specshot-mcp-server"],
|
|
56
|
+
"env": {
|
|
57
|
+
"SPECSHOT_API_TOKEN": "spec_your_token_here",
|
|
58
|
+
"SPECSHOT_APP_URL": "https://specshot.cc"
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Codex CLI uses TOML at `~/.codex/config.toml`:
|
|
66
|
+
|
|
67
|
+
```toml
|
|
68
|
+
[mcp_servers.specshot]
|
|
69
|
+
command = "npx"
|
|
70
|
+
args = ["-y", "@scayver/specshot-mcp-server"]
|
|
71
|
+
env = { SPECSHOT_API_TOKEN = "spec_your_token_here", SPECSHOT_APP_URL = "https://specshot.cc" }
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Tools
|
|
75
|
+
|
|
76
|
+
Wireframe building (build a full site yourself, no AI key):
|
|
77
|
+
|
|
78
|
+
- `list_projects({})` — list the projects in your workspace.
|
|
79
|
+
- `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.
|
|
80
|
+
- `get_wireframe_context({ projectId })` — the brief, the pages, the brand tokens, the captured references, and a build instruction for a full multi-page wireframe.
|
|
81
|
+
- `save_wireframe({ projectId, name, html, css?, pageType?, sections? })` — save a wireframe you built back into SpecShot as a concept. Needs a read/write token.
|
|
82
|
+
|
|
83
|
+
Conversation (iterate with the human, both ways):
|
|
84
|
+
|
|
85
|
+
- `get_messages({ conceptId })` — read the concept's thread, including feedback the human left in the portal.
|
|
86
|
+
- `post_message({ conceptId, body })` — reply to the human. Needs a read/write token.
|
|
87
|
+
- `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.
|
|
88
|
+
|
|
89
|
+
Agent Workspace (read the whole project, act on exact sections and layers):
|
|
90
|
+
|
|
91
|
+
- `get_discovery_answers({ projectId })` — the discovery Q&A that drives the design.
|
|
92
|
+
- `get_project_copy({ projectId })` — per-section copywriting.
|
|
93
|
+
- `get_wireframes({ projectId })` — saved wireframes.
|
|
94
|
+
- `get_design_sections({ projectId, conceptId? })` — sections with their copyable ids (SS-SEC-HERO-001).
|
|
95
|
+
- `get_section_by_uid({ projectId, sectionUid })` — one section plus its layers.
|
|
96
|
+
- `get_design_layers({ projectId, conceptId?, sectionId? })` — the Photoshop-style layer tree.
|
|
97
|
+
- `get_layer_by_uid({ projectId, layerUid })` — one layer (SS-LYR-HEADLINE-001) with style/layout/animation.
|
|
98
|
+
- `get_design_versions({ projectId, conceptId? })` / `get_selected_design_version({ projectId, conceptId? })`.
|
|
99
|
+
- `get_comments_for_section({ projectId, sectionUid?, status? })` — comment pins / feedback.
|
|
100
|
+
- `get_agent_tasks({ projectId, status? })` — what work is queued, running, or waiting.
|
|
101
|
+
- `get_project_memory({ projectId })` — durable decisions and rules to honor in every revision.
|
|
102
|
+
- `reserve_section_uid({ projectId, kind, type })` — the next stable id (SEC/LYR/CMP).
|
|
103
|
+
- `update_design_section({ sectionId, name?, sectionOrder?, status? })` — quick-edit a section: rename, reorder, hide (status "hidden") or show ("draft"). Read/write token.
|
|
104
|
+
- `update_design_layer({ layerId, name?, hidden?, locked?, sortOrder? })` — the layer panel: rename, hide, lock, reorder. A locked layer only accepts an unlock. Read/write token.
|
|
105
|
+
- `extract_concept_sections({ projectId, conceptId })` — turn a concept into selectable sections and layers with copyable ids. Idempotent. Read/write token.
|
|
106
|
+
- `get_handoff_package({ projectId, conceptId? })` — the complete brief to BUILD the approved concept: brief, goals, brand, sections with ids, copy, open feedback, decisions, acceptance criteria, and a ready-to-paste buildInstruction.
|
|
107
|
+
- `create_agent_task`, `update_agent_task` — make your work visible as tasks. Read/write token.
|
|
108
|
+
- `create_design_version({ projectId, html, changeSummary?, parentVersionId? })` — add a NEW version, never overwriting approved work. Read/write token.
|
|
109
|
+
- `add_design_comment`, `resolve_design_comment` — comment pins tied to a section or layer. Read/write token.
|
|
110
|
+
|
|
111
|
+
Approved concepts (build a design SpecShot generated):
|
|
112
|
+
|
|
113
|
+
- `list_concepts({ projectId?, status? })` — list concepts, filter by status to find approved ones.
|
|
114
|
+
- `get_concept({ conceptId })` — full Design Context Package and a ready-to-build prompt (`buildPrompt`).
|
|
115
|
+
- `get_approved_concept({ projectId })` — the latest approved concept for a project, fully specced.
|
|
116
|
+
- `get_brand_system({ projectId })` — brand colors, typography, spacing, radius, animation tokens.
|
|
117
|
+
- `list_inspiration({ projectId, folderId? })` — reference screenshots collected for the project.
|
|
118
|
+
- `update_concept_status({ conceptId, status: "sent" | "built", buildNote? })` — mark a build started or complete.
|
|
119
|
+
- `add_build_note({ conceptId, note })` — log build progress on a concept.
|
|
120
|
+
|
|
121
|
+
## Build a full website wireframe (no AI key)
|
|
122
|
+
|
|
123
|
+
Any connected LLM can build the whole site itself and save it back. Nothing calls an AI provider on the SpecShot side.
|
|
124
|
+
|
|
125
|
+
1. `list_projects({})` and pick a project.
|
|
126
|
+
2. `get_wireframe_context({ projectId })`. You get the brief, every page, the brand tokens, the captured section references, and a build instruction.
|
|
127
|
+
3. Build one structural wireframe per page as a self-contained HTML document, following the instruction (low fidelity, brand-aware, responsive).
|
|
128
|
+
4. `save_wireframe({ projectId, name: "Home (wireframe)", html, ... })` for each page. SpecShot stores your HTML exactly as given.
|
|
129
|
+
5. Open the project in SpecShot to review the wireframes, iterate, or promote them.
|
|
130
|
+
|
|
131
|
+
### Iterate back and forth
|
|
132
|
+
|
|
133
|
+
The human and the agent share a conversation on each concept, so the two can go back and forth.
|
|
134
|
+
|
|
135
|
+
1. The human reviews a wireframe in SpecShot and posts feedback in its Conversation panel.
|
|
136
|
+
2. The agent calls `get_messages({ conceptId })` to read the feedback.
|
|
137
|
+
3. The agent rebuilds the page and calls `revise_wireframe({ conceptId, html })`. Every revision is kept in the version history.
|
|
138
|
+
4. The agent calls `post_message({ conceptId, body })` to say what changed. The human gets a notification.
|
|
139
|
+
5. Repeat until the human is happy, then they promote the concept.
|
|
140
|
+
|
|
141
|
+
## Build an approved concept
|
|
142
|
+
|
|
143
|
+
1. Capture inspiration and sections in SpecShot, define your brand system, generate a design concept, and approve it.
|
|
144
|
+
2. `get_approved_concept({ projectId: "..." })`.
|
|
145
|
+
3. Build the design from the spec, brand tokens, and references.
|
|
146
|
+
4. `update_concept_status({ conceptId, status: "built" })` when done.
|
|
147
|
+
|
|
148
|
+
## Security
|
|
149
|
+
|
|
150
|
+
The token is the credential. It scopes every call to one workspace. Never commit it. Revoke it anytime from Settings, API Tokens.
|
package/dist/client.js
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/** Thin HTTP client for the SpecShot /api/mcp/* routes, authed by an API token. */
|
|
2
|
+
export class SpecShotClient {
|
|
3
|
+
baseUrl;
|
|
4
|
+
token;
|
|
5
|
+
constructor(baseUrl, token) {
|
|
6
|
+
this.baseUrl = baseUrl.replace(/\/$/, "");
|
|
7
|
+
this.token = token;
|
|
8
|
+
}
|
|
9
|
+
async get(path, params) {
|
|
10
|
+
const url = new URL(`${this.baseUrl}${path}`);
|
|
11
|
+
if (params) {
|
|
12
|
+
for (const [k, v] of Object.entries(params)) {
|
|
13
|
+
if (v !== undefined && v !== "")
|
|
14
|
+
url.searchParams.set(k, v);
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
const res = await fetch(url.toString(), {
|
|
18
|
+
headers: { Authorization: `Bearer ${this.token}` },
|
|
19
|
+
});
|
|
20
|
+
if (!res.ok) {
|
|
21
|
+
const body = (await res.json().catch(() => ({})));
|
|
22
|
+
throw new Error(body.error ?? `HTTP ${res.status}`);
|
|
23
|
+
}
|
|
24
|
+
return res.json();
|
|
25
|
+
}
|
|
26
|
+
async patch(path, body) {
|
|
27
|
+
const res = await fetch(`${this.baseUrl}${path}`, {
|
|
28
|
+
method: "PATCH",
|
|
29
|
+
headers: {
|
|
30
|
+
Authorization: `Bearer ${this.token}`,
|
|
31
|
+
"Content-Type": "application/json",
|
|
32
|
+
},
|
|
33
|
+
body: JSON.stringify(body),
|
|
34
|
+
});
|
|
35
|
+
if (!res.ok) {
|
|
36
|
+
const b = (await res.json().catch(() => ({})));
|
|
37
|
+
throw new Error(b.error ?? `HTTP ${res.status}`);
|
|
38
|
+
}
|
|
39
|
+
return res.json();
|
|
40
|
+
}
|
|
41
|
+
async post(path, body) {
|
|
42
|
+
const res = await fetch(`${this.baseUrl}${path}`, {
|
|
43
|
+
method: "POST",
|
|
44
|
+
headers: {
|
|
45
|
+
Authorization: `Bearer ${this.token}`,
|
|
46
|
+
"Content-Type": "application/json",
|
|
47
|
+
},
|
|
48
|
+
body: JSON.stringify(body),
|
|
49
|
+
});
|
|
50
|
+
if (!res.ok) {
|
|
51
|
+
const b = (await res.json().catch(() => ({})));
|
|
52
|
+
throw new Error(b.error ?? `HTTP ${res.status}`);
|
|
53
|
+
}
|
|
54
|
+
return res.json();
|
|
55
|
+
}
|
|
56
|
+
}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
3
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
4
|
+
import { SpecShotClient } from "./client.js";
|
|
5
|
+
import { registerConceptTools } from "./tools/concepts.js";
|
|
6
|
+
import { registerBrandTools } from "./tools/brand.js";
|
|
7
|
+
import { registerInspirationTools } from "./tools/inspiration.js";
|
|
8
|
+
import { registerWireframeTools } from "./tools/wireframe.js";
|
|
9
|
+
import { registerMessageTools } from "./tools/messages.js";
|
|
10
|
+
import { registerWorkspaceTools } from "./tools/workspace.js";
|
|
11
|
+
const VERSION = "0.5.0";
|
|
12
|
+
const token = process.env.SPECSHOT_API_TOKEN;
|
|
13
|
+
const baseUrl = process.env.SPECSHOT_APP_URL ?? "https://specshot.cc";
|
|
14
|
+
if (!token) {
|
|
15
|
+
console.error("SPECSHOT_API_TOKEN is required. Generate one at SpecShot, Settings, API Tokens.");
|
|
16
|
+
process.exit(1);
|
|
17
|
+
}
|
|
18
|
+
// Startup banner on stderr (stdout is the MCP protocol channel). Makes a stale
|
|
19
|
+
// dist or a silently-defaulted URL visible at a glance in the client's logs.
|
|
20
|
+
console.error(`[specshot-mcp] v${VERSION} -> ${baseUrl}${process.env.SPECSHOT_APP_URL ? "" : " (default; set SPECSHOT_APP_URL to override)"}`);
|
|
21
|
+
const client = new SpecShotClient(baseUrl, token);
|
|
22
|
+
const server = new McpServer({ name: "specshot", version: VERSION });
|
|
23
|
+
registerConceptTools(server, client);
|
|
24
|
+
registerBrandTools(server, client);
|
|
25
|
+
registerInspirationTools(server, client);
|
|
26
|
+
registerWireframeTools(server, client);
|
|
27
|
+
registerMessageTools(server, client);
|
|
28
|
+
registerWorkspaceTools(server, client);
|
|
29
|
+
const transport = new StdioServerTransport();
|
|
30
|
+
await server.connect(transport);
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
function ok(data) {
|
|
3
|
+
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
4
|
+
}
|
|
5
|
+
function fail(message) {
|
|
6
|
+
return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
|
|
7
|
+
}
|
|
8
|
+
export function registerBrandTools(server, client) {
|
|
9
|
+
server.tool("get_brand_system", "Get the brand system (colors, typography, spacing, radius, animation tokens) for a project.", { projectId: z.string() }, async ({ projectId }) => {
|
|
10
|
+
try {
|
|
11
|
+
const data = await client.get("/api/mcp/brand-systems", { projectId });
|
|
12
|
+
return ok(data);
|
|
13
|
+
}
|
|
14
|
+
catch (e) {
|
|
15
|
+
return fail(e instanceof Error ? e.message : "Failed to get the brand system.");
|
|
16
|
+
}
|
|
17
|
+
});
|
|
18
|
+
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
function ok(data) {
|
|
3
|
+
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
4
|
+
}
|
|
5
|
+
function fail(message) {
|
|
6
|
+
return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
|
|
7
|
+
}
|
|
8
|
+
export function registerConceptTools(server, client) {
|
|
9
|
+
server.tool("list_concepts", "List design concepts in this SpecShot workspace. Filter by status to find approved concepts ready to build.", {
|
|
10
|
+
projectId: z.string().optional(),
|
|
11
|
+
status: z.enum(["draft", "reviewing", "approved", "sent", "built", "archived"]).optional(),
|
|
12
|
+
}, async ({ projectId, status }) => {
|
|
13
|
+
try {
|
|
14
|
+
const data = await client.get("/api/mcp/concepts", { projectId, status });
|
|
15
|
+
return ok(data);
|
|
16
|
+
}
|
|
17
|
+
catch (e) {
|
|
18
|
+
return fail(e instanceof Error ? e.message : "Failed to list concepts.");
|
|
19
|
+
}
|
|
20
|
+
});
|
|
21
|
+
server.tool("get_concept", "Get a single design concept with its full Design Context Package — brand tokens, inspiration sources, transformation spec, and a ready-to-paste build prompt.", { conceptId: z.string() }, async ({ conceptId }) => {
|
|
22
|
+
try {
|
|
23
|
+
const data = await client.get(`/api/mcp/concepts/${conceptId}`);
|
|
24
|
+
return ok(data);
|
|
25
|
+
}
|
|
26
|
+
catch (e) {
|
|
27
|
+
return fail(e instanceof Error ? e.message : "Failed to get concept.");
|
|
28
|
+
}
|
|
29
|
+
});
|
|
30
|
+
server.tool("get_approved_concept", "Get the most recently approved design concept for a project. Use this to start building immediately after the user approves a design in SpecShot.", { projectId: z.string() }, async ({ projectId }) => {
|
|
31
|
+
try {
|
|
32
|
+
const list = await client.get("/api/mcp/concepts", {
|
|
33
|
+
projectId,
|
|
34
|
+
status: "approved",
|
|
35
|
+
limit: "1",
|
|
36
|
+
});
|
|
37
|
+
const latest = list.concepts?.[0];
|
|
38
|
+
if (!latest)
|
|
39
|
+
return fail("No approved concept for this project yet.");
|
|
40
|
+
const data = await client.get(`/api/mcp/concepts/${latest.id}`);
|
|
41
|
+
return ok(data);
|
|
42
|
+
}
|
|
43
|
+
catch (e) {
|
|
44
|
+
return fail(e instanceof Error ? e.message : "Failed to get the approved concept.");
|
|
45
|
+
}
|
|
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.", {
|
|
48
|
+
conceptId: z.string(),
|
|
49
|
+
status: z.enum(["sent", "built"]),
|
|
50
|
+
buildNote: z.string().optional(),
|
|
51
|
+
}, async ({ conceptId, status, buildNote }) => {
|
|
52
|
+
try {
|
|
53
|
+
const data = await client.patch(`/api/mcp/concepts/${conceptId}/status`, { status, buildNote });
|
|
54
|
+
return ok(data);
|
|
55
|
+
}
|
|
56
|
+
catch (e) {
|
|
57
|
+
return fail(e instanceof Error ? e.message : "Failed to update status.");
|
|
58
|
+
}
|
|
59
|
+
});
|
|
60
|
+
server.tool("add_build_note", "Add a note to a concept — use this to log build progress, issues, or completion details.", { conceptId: z.string(), note: z.string() }, async ({ conceptId, note }) => {
|
|
61
|
+
try {
|
|
62
|
+
const data = await client.patch(`/api/mcp/concepts/${conceptId}/notes`, { note });
|
|
63
|
+
return ok(data);
|
|
64
|
+
}
|
|
65
|
+
catch (e) {
|
|
66
|
+
return fail(e instanceof Error ? e.message : "Failed to add note.");
|
|
67
|
+
}
|
|
68
|
+
});
|
|
69
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
function ok(data) {
|
|
3
|
+
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
4
|
+
}
|
|
5
|
+
function fail(message) {
|
|
6
|
+
return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
|
|
7
|
+
}
|
|
8
|
+
export function registerInspirationTools(server, client) {
|
|
9
|
+
server.tool("list_inspiration", "List inspiration screenshots saved to a project's folders. These are the reference images the user collected before generating a concept.", { projectId: z.string(), folderId: z.string().optional() }, async ({ projectId, folderId }) => {
|
|
10
|
+
try {
|
|
11
|
+
const data = await client.get("/api/mcp/inspiration", { projectId, folderId });
|
|
12
|
+
return ok(data);
|
|
13
|
+
}
|
|
14
|
+
catch (e) {
|
|
15
|
+
return fail(e instanceof Error ? e.message : "Failed to list inspiration.");
|
|
16
|
+
}
|
|
17
|
+
});
|
|
18
|
+
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
function ok(data) {
|
|
3
|
+
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
4
|
+
}
|
|
5
|
+
function fail(message) {
|
|
6
|
+
return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* Two-way conversation on a concept. The human reviews a wireframe or design in
|
|
10
|
+
* the SpecShot portal and leaves feedback in the thread; the agent reads that
|
|
11
|
+
* feedback with get_messages, revises the wireframe with revise_wireframe, and
|
|
12
|
+
* replies with post_message. This is the back-and-forth loop.
|
|
13
|
+
*/
|
|
14
|
+
export function registerMessageTools(server, client) {
|
|
15
|
+
server.tool("get_messages", "Read the conversation thread on a concept, including any feedback the human left in the SpecShot portal. Poll this to see new human feedback before revising.", { conceptId: z.string() }, async ({ conceptId }) => {
|
|
16
|
+
try {
|
|
17
|
+
return ok(await client.get(`/api/mcp/concepts/${conceptId}/messages`));
|
|
18
|
+
}
|
|
19
|
+
catch (e) {
|
|
20
|
+
return fail(e instanceof Error ? e.message : "Failed to read messages.");
|
|
21
|
+
}
|
|
22
|
+
});
|
|
23
|
+
server.tool("post_message", "Reply in a concept's conversation thread. Use this to answer the human's feedback, explain what you changed, or ask a question. The human sees it in the SpecShot portal. Requires a read/write token.", { conceptId: z.string(), body: z.string() }, async ({ conceptId, body }) => {
|
|
24
|
+
try {
|
|
25
|
+
return ok(await client.post(`/api/mcp/concepts/${conceptId}/messages`, { body }));
|
|
26
|
+
}
|
|
27
|
+
catch (e) {
|
|
28
|
+
return fail(e instanceof Error ? e.message : "Failed to post message.");
|
|
29
|
+
}
|
|
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 }) => {
|
|
32
|
+
try {
|
|
33
|
+
return ok(await client.patch(`/api/mcp/concepts/${conceptId}/wireframe`, { html, css }));
|
|
34
|
+
}
|
|
35
|
+
catch (e) {
|
|
36
|
+
return fail(e instanceof Error ? e.message : "Failed to revise wireframe.");
|
|
37
|
+
}
|
|
38
|
+
});
|
|
39
|
+
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
function ok(data) {
|
|
3
|
+
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
4
|
+
}
|
|
5
|
+
function fail(message) {
|
|
6
|
+
return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* Tools for building a full multi-page website wireframe from a SpecShot project,
|
|
10
|
+
* entirely inside the connected LLM (Claude Code, Cursor, Codex, or any MCP
|
|
11
|
+
* client). SpecShot never calls an AI provider for this: get_wireframe_context
|
|
12
|
+
* hands over the brief, pages, brand, and references, the LLM builds each page's
|
|
13
|
+
* structural wireframe itself, and save_wireframe stores the result back.
|
|
14
|
+
*/
|
|
15
|
+
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
|
+
try {
|
|
18
|
+
return ok(await client.get("/api/mcp/projects"));
|
|
19
|
+
}
|
|
20
|
+
catch (e) {
|
|
21
|
+
return fail(e instanceof Error ? e.message : "Failed to list projects.");
|
|
22
|
+
}
|
|
23
|
+
});
|
|
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
|
+
try {
|
|
26
|
+
return ok(await client.get(`/api/mcp/projects/${projectId}/intelligence`));
|
|
27
|
+
}
|
|
28
|
+
catch (e) {
|
|
29
|
+
return fail(e instanceof Error ? e.message : "Failed to get project intelligence.");
|
|
30
|
+
}
|
|
31
|
+
});
|
|
32
|
+
server.tool("get_wireframe_context", "Get everything needed to build a FULL multi-page website wireframe for a project: the brief, the list of pages, the brand tokens, the captured section references, the inspiration, and a build instruction. Build one structural wireframe 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 }) => {
|
|
33
|
+
try {
|
|
34
|
+
return ok(await client.get(`/api/mcp/projects/${projectId}/wireframe-context`));
|
|
35
|
+
}
|
|
36
|
+
catch (e) {
|
|
37
|
+
return fail(e instanceof Error ? e.message : "Failed to get wireframe context.");
|
|
38
|
+
}
|
|
39
|
+
});
|
|
40
|
+
server.tool("save_wireframe", "Save a wireframe you built back into SpecShot as a design concept. Call this once per page after building that page's wireframe from get_wireframe_context. Pass the project id, a name (for example \"Home (wireframe)\"), and the self-contained html (put css inline in a <style> block, or pass css separately). SpecShot stores your html exactly as given and does not modify or regenerate it. Requires a read/write API token.", {
|
|
41
|
+
projectId: z.string(),
|
|
42
|
+
name: z.string(),
|
|
43
|
+
html: z.string(),
|
|
44
|
+
css: z.string().optional(),
|
|
45
|
+
pageType: z.string().optional(),
|
|
46
|
+
goal: z.string().optional(),
|
|
47
|
+
sections: z.array(z.string()).optional(),
|
|
48
|
+
builderTarget: z.string().optional(),
|
|
49
|
+
}, async ({ projectId, name, html, css, pageType, goal, sections, builderTarget }) => {
|
|
50
|
+
try {
|
|
51
|
+
const data = await client.post("/api/mcp/concepts", {
|
|
52
|
+
projectId,
|
|
53
|
+
name,
|
|
54
|
+
html,
|
|
55
|
+
css,
|
|
56
|
+
pageType,
|
|
57
|
+
goal,
|
|
58
|
+
sections,
|
|
59
|
+
builderTarget,
|
|
60
|
+
});
|
|
61
|
+
return ok(data);
|
|
62
|
+
}
|
|
63
|
+
catch (e) {
|
|
64
|
+
return fail(e instanceof Error ? e.message : "Failed to save wireframe.");
|
|
65
|
+
}
|
|
66
|
+
});
|
|
67
|
+
}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
function ok(data) {
|
|
3
|
+
return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
|
|
4
|
+
}
|
|
5
|
+
function fail(message) {
|
|
6
|
+
return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
|
|
7
|
+
}
|
|
8
|
+
const WORKSPACE = "/api/mcp/workspace";
|
|
9
|
+
/**
|
|
10
|
+
* Agent Workspace tools (PRD section 27). They let a connected LLM read the whole
|
|
11
|
+
* project workspace — discovery, copy, wireframes, sections, layers, versions,
|
|
12
|
+
* comments, tasks, and project memory — and act on it by referencing a section
|
|
13
|
+
* or layer ID: create agent tasks, add comment pins, and create new design
|
|
14
|
+
* versions. Every mutating tool needs a read/write API token. Approved work is
|
|
15
|
+
* never overwritten: create_design_version always adds a new version.
|
|
16
|
+
*
|
|
17
|
+
* All of these dispatch to one token-authed route (/api/mcp/workspace) that
|
|
18
|
+
* scopes every call to the token's workspace.
|
|
19
|
+
*/
|
|
20
|
+
export function registerWorkspaceTools(server, client) {
|
|
21
|
+
const call = async (action, params, label) => {
|
|
22
|
+
try {
|
|
23
|
+
return ok(await client.post(WORKSPACE, { action, ...params }));
|
|
24
|
+
}
|
|
25
|
+
catch (e) {
|
|
26
|
+
return fail(e instanceof Error ? e.message : label);
|
|
27
|
+
}
|
|
28
|
+
};
|
|
29
|
+
// ----------------------------------------------------------------- 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."));
|
|
43
|
+
// ---------------------------------------------------------------- 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
|
+
projectId: z.string(),
|
|
46
|
+
title: z.string(),
|
|
47
|
+
description: z.string().optional(),
|
|
48
|
+
conceptId: z.string().optional(),
|
|
49
|
+
sectionUid: z.string().optional(),
|
|
50
|
+
layerUid: z.string().optional(),
|
|
51
|
+
priority: z.enum(["low", "medium", "high", "blocker"]).optional(),
|
|
52
|
+
assignedAgent: z.string().optional(),
|
|
53
|
+
}, 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
|
+
taskId: z.string(),
|
|
56
|
+
status: z.string().optional(),
|
|
57
|
+
outputSummary: z.string().optional(),
|
|
58
|
+
versionId: z.string().optional(),
|
|
59
|
+
}, 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
|
+
projectId: z.string(),
|
|
62
|
+
conceptId: z.string().optional(),
|
|
63
|
+
parentVersionId: z.string().optional(),
|
|
64
|
+
versionName: z.string().optional(),
|
|
65
|
+
versionNumber: z.string().optional(),
|
|
66
|
+
changeSummary: z.string().optional(),
|
|
67
|
+
html: z.string().optional(),
|
|
68
|
+
css: z.string().optional(),
|
|
69
|
+
}, 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
|
+
projectId: z.string(),
|
|
72
|
+
comment: z.string(),
|
|
73
|
+
conceptId: z.string().optional(),
|
|
74
|
+
sectionUid: z.string().optional(),
|
|
75
|
+
layerUid: z.string().optional(),
|
|
76
|
+
priority: z.enum(["low", "medium", "high", "blocker"]).optional(),
|
|
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."));
|
|
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.", {
|
|
81
|
+
sectionId: z.string(),
|
|
82
|
+
name: z.string().optional(),
|
|
83
|
+
sectionOrder: z.number().int().optional(),
|
|
84
|
+
status: z.string().optional(),
|
|
85
|
+
}, 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.", {
|
|
87
|
+
layerId: z.string(),
|
|
88
|
+
name: z.string().optional(),
|
|
89
|
+
hidden: z.boolean().optional(),
|
|
90
|
+
locked: z.boolean().optional(),
|
|
91
|
+
sortOrder: z.number().int().optional(),
|
|
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."));
|
|
94
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@scayver/specshot-mcp-server",
|
|
3
|
+
"version": "0.5.0",
|
|
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
|
+
"keywords": ["mcp", "model-context-protocol", "specshot", "claude", "design", "ai"],
|
|
6
|
+
"homepage": "https://specshot.cc",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/scayver/specshot.git",
|
|
10
|
+
"directory": "apps/mcp-server"
|
|
11
|
+
},
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/scayver/specshot/issues"
|
|
14
|
+
},
|
|
15
|
+
"license": "MIT",
|
|
16
|
+
"type": "module",
|
|
17
|
+
"bin": {
|
|
18
|
+
"specshot-mcp": "./dist/index.js"
|
|
19
|
+
},
|
|
20
|
+
"files": ["dist", "README.md"],
|
|
21
|
+
"engines": {
|
|
22
|
+
"node": ">=18"
|
|
23
|
+
},
|
|
24
|
+
"publishConfig": {
|
|
25
|
+
"access": "public"
|
|
26
|
+
},
|
|
27
|
+
"scripts": {
|
|
28
|
+
"build": "tsc",
|
|
29
|
+
"dev": "tsc --watch",
|
|
30
|
+
"start": "node dist/index.js",
|
|
31
|
+
"type-check": "tsc --noEmit",
|
|
32
|
+
"lint": "echo 'no lint for mcp-server'",
|
|
33
|
+
"test": "echo 'no tests yet'",
|
|
34
|
+
"prepare": "npm run build",
|
|
35
|
+
"prepublishOnly": "npm run build"
|
|
36
|
+
},
|
|
37
|
+
"dependencies": {
|
|
38
|
+
"@modelcontextprotocol/sdk": "^1.0.0",
|
|
39
|
+
"zod": "^3.23.8"
|
|
40
|
+
},
|
|
41
|
+
"devDependencies": {
|
|
42
|
+
"typescript": "^5.7.2"
|
|
43
|
+
}
|
|
44
|
+
}
|