@scayver/specshot-mcp-server 0.7.0 → 0.9.1
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 +16 -5
- package/dist/build-standard.js +38 -0
- package/dist/index.js +62 -2
- package/dist/tools/wireframe.js +54 -3
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -22,11 +22,22 @@ node dist/index.js
|
|
|
22
22
|
`npm install` alone does NOT reliably produce `dist/`: it only builds via the
|
|
23
23
|
`prepare` hook, which `npm ci` skips and which behaves differently across npm
|
|
24
24
|
versions and workspaces. Always run `npm run build`. Rebuild after any src
|
|
25
|
-
change. The server prints a startup
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
25
|
+
change. The server prints a startup banner to stderr with its version and target
|
|
26
|
+
URL, so a stale dist is visible at a glance: `[specshot-mcp] v<version> ->
|
|
27
|
+
https://specshot.cc`. That version is read from package.json at runtime, so it
|
|
28
|
+
is always the truth about the build you are running.
|
|
29
|
+
|
|
30
|
+
**Do not diagnose your build from a version number written in a doc.** An
|
|
31
|
+
earlier revision of this paragraph named specific versions and tool counts, and
|
|
32
|
+
those numbers rotted: a doc claiming "the current server is 0.6.0" teaches you
|
|
33
|
+
to conclude you are on an old build when you are not. On 2026-07-21 an agent
|
|
34
|
+
reasoning from stale published guidance re-reported a bug that had been fixed
|
|
35
|
+
days earlier and built workarounds that degraded its designs. Compare against
|
|
36
|
+
the LIVE server instead: call the `whoami` tool. Over stdio it returns the
|
|
37
|
+
running `serverVersion` (read from package.json in that very process), the
|
|
38
|
+
transport, and the SpecShot URL it targets. Over the hosted HTTP endpoint it
|
|
39
|
+
also returns the workspace, the token scope, and the real `toolCount`. If
|
|
40
|
+
`whoami` disagrees with anything you read here, `whoami` is right.
|
|
30
41
|
|
|
31
42
|
After publishing, npx works with no install:
|
|
32
43
|
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
// The SpecShot build standard, concise form, for the stdio MCP package.
|
|
2
|
+
//
|
|
3
|
+
// This package publishes standalone to npm, so it cannot import the canonical
|
|
4
|
+
// text from @specshot/shared. It carries a SHORT standard: enough to reverse the
|
|
5
|
+
// grey-placeholder failure at connection time, and a pointer to the authoritative,
|
|
6
|
+
// always-current, per-project instruction that get_wireframe_context returns
|
|
7
|
+
// (that text is assembled from the shared BUILD_STANDARD on the server, so it is
|
|
8
|
+
// the copy that never drifts). Delivered as the server's `instructions` and as
|
|
9
|
+
// the body of the build_a_page prompt.
|
|
10
|
+
export const BUILD_STANDARD_SHORT = `# SpecShot build standard
|
|
11
|
+
|
|
12
|
+
You are connected to build real, approvable website designs. SpecShot never calls a
|
|
13
|
+
model on the server, so the quality is entirely yours.
|
|
14
|
+
|
|
15
|
+
- Build FULL FIDELITY, never grey placeholder boxes, dashed "image here" holes, or a
|
|
16
|
+
bare skeleton. If a human cannot approve or reject it as a real website, it is not done.
|
|
17
|
+
- Read the project FIRST with get_wireframe_context and use every input: the real
|
|
18
|
+
brand tokens, the approved copy (verbatim), the captured references, and the pages.
|
|
19
|
+
If an input is missing, say so and ask. Do not ship generic filler.
|
|
20
|
+
- STUDY the inspiration before you build. Open every inspiration and capture image
|
|
21
|
+
(each has a signed imageUrl; use visualSummary if you cannot see images) and design
|
|
22
|
+
at that level. If your environment has a frontend-design or web-design skill,
|
|
23
|
+
invoke it and build with it. Skipping the references is the core failure mode.
|
|
24
|
+
- Real SVG icons (never emoji). Every color and size from the project's tokens.
|
|
25
|
+
Light and dark. Responsive at 390, 768, and 1440. WCAG AA contrast, labels, focus.
|
|
26
|
+
- One self-contained HTML per page, CSS inline in a <style> block. No external
|
|
27
|
+
scripts, fonts, or images: the preview strips script/iframe/object/embed/link/meta/
|
|
28
|
+
base and drops @import, so inline everything (SVG, gradients, data: URIs).
|
|
29
|
+
- Embedded fonts load: an @font-face with a data: URI src (or local()) registers and
|
|
30
|
+
renders in the preview. One with an external url is dropped whole. Do not strip
|
|
31
|
+
embedded fonts to work around the preview, and do not depend on locally installed
|
|
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.
|
|
36
|
+
|
|
37
|
+
get_wireframe_context returns the full, current, per-project build instruction. Read
|
|
38
|
+
it before you build, and follow it as the authoritative standard.`;
|
package/dist/index.js
CHANGED
|
@@ -9,7 +9,31 @@ import { registerWireframeTools } from "./tools/wireframe.js";
|
|
|
9
9
|
import { registerMessageTools } from "./tools/messages.js";
|
|
10
10
|
import { registerWorkspaceTools } from "./tools/workspace.js";
|
|
11
11
|
import { registerCanvasTools } from "./tools/canvas.js";
|
|
12
|
-
|
|
12
|
+
import { BUILD_STANDARD_SHORT } from "./build-standard.js";
|
|
13
|
+
import { createRequire } from "node:module";
|
|
14
|
+
/**
|
|
15
|
+
* Read the version from package.json instead of restating it. A hardcoded copy
|
|
16
|
+
* sat at 0.7.0 while the package shipped 0.9.0, so this server introduced itself
|
|
17
|
+
* to every agent as two versions older than it was — including in the 0.9.0
|
|
18
|
+
* tarball published on 2026-07-21. That is the same lie the hosted endpoint told
|
|
19
|
+
* (see apps/web/src/lib/mcp-version.ts), and it matters because an agent that
|
|
20
|
+
* believes it is on an old build will "confirm" bugs that were already fixed and
|
|
21
|
+
* build workarounds for them, which is exactly what happened that day.
|
|
22
|
+
*
|
|
23
|
+
* dist/index.js resolves "../package.json" to the package root, and npm always
|
|
24
|
+
* includes package.json in the tarball, so this holds for a published install
|
|
25
|
+
* and a local build alike. Falling back to "unknown" is deliberate: a version we
|
|
26
|
+
* cannot read must never masquerade as a specific one.
|
|
27
|
+
*/
|
|
28
|
+
const VERSION = (() => {
|
|
29
|
+
try {
|
|
30
|
+
const require = createRequire(import.meta.url);
|
|
31
|
+
return require("../package.json").version ?? "unknown";
|
|
32
|
+
}
|
|
33
|
+
catch {
|
|
34
|
+
return "unknown";
|
|
35
|
+
}
|
|
36
|
+
})();
|
|
13
37
|
const token = process.env.SPECSHOT_API_TOKEN;
|
|
14
38
|
const baseUrl = process.env.SPECSHOT_APP_URL ?? "https://specshot.cc";
|
|
15
39
|
if (!token) {
|
|
@@ -20,7 +44,43 @@ if (!token) {
|
|
|
20
44
|
// dist or a silently-defaulted URL visible at a glance in the client's logs.
|
|
21
45
|
console.error(`[specshot-mcp] v${VERSION} -> ${baseUrl}${process.env.SPECSHOT_APP_URL ? "" : " (default; set SPECSHOT_APP_URL to override)"}`);
|
|
22
46
|
const client = new SpecShotClient(baseUrl, token);
|
|
23
|
-
|
|
47
|
+
// instructions travel with the connection: a client surfaces them to the model
|
|
48
|
+
// as system context, so the agent knows to build full fidelity before it reads a
|
|
49
|
+
// single tool description. Without this the build standard lived only inside one
|
|
50
|
+
// tool's payload and grey-placeholder output was the result.
|
|
51
|
+
const server = new McpServer({ name: "specshot", version: VERSION }, { instructions: BUILD_STANDARD_SHORT });
|
|
52
|
+
// A callable prompt whose body IS the standard, for clients that surface prompts
|
|
53
|
+
// in a picker. Registered before the tools so it lists first.
|
|
54
|
+
server.registerPrompt("build_a_page", {
|
|
55
|
+
title: "SpecShot: build a page",
|
|
56
|
+
description: "The SpecShot build standard: how to build a full-fidelity, approvable website design. Read this before you build.",
|
|
57
|
+
}, () => ({
|
|
58
|
+
messages: [{ role: "user", content: { type: "text", text: BUILD_STANDARD_SHORT } }],
|
|
59
|
+
}));
|
|
60
|
+
/**
|
|
61
|
+
* whoami: ground truth about THIS process, so an agent never has to infer what
|
|
62
|
+
* it is running from a version written in a doc or remembered from a past
|
|
63
|
+
* session. The hosted endpoint has always had this; stdio did not, which left
|
|
64
|
+
* an npx agent with no way to ask. On 2026-07-21 one reasoned from stale
|
|
65
|
+
* published guidance, "confirmed" an already-fixed bug, and built workarounds
|
|
66
|
+
* for it. Everything here is read live: the version from package.json, the
|
|
67
|
+
* target from the resolved base URL. No secrets, and the token is never echoed.
|
|
68
|
+
*/
|
|
69
|
+
server.tool("whoami", "Confirm what you are actually connected to: the running server version, the transport (stdio), the SpecShot URL it targets, and whether an API token is configured. Call this FIRST when anything seems inconsistent with what you expect, and trust it over any version number written in a doc, a README, or your own memory of a past session. Returns no secrets.", {}, async () => ({
|
|
70
|
+
content: [
|
|
71
|
+
{
|
|
72
|
+
type: "text",
|
|
73
|
+
text: JSON.stringify({
|
|
74
|
+
serverVersion: VERSION,
|
|
75
|
+
transport: "stdio",
|
|
76
|
+
packageName: "@scayver/specshot-mcp-server",
|
|
77
|
+
targetUrl: baseUrl,
|
|
78
|
+
tokenConfigured: Boolean(token),
|
|
79
|
+
note: "Read live from this process. If a doc or a remembered version disagrees with this, this is right.",
|
|
80
|
+
}, null, 2),
|
|
81
|
+
},
|
|
82
|
+
],
|
|
83
|
+
}));
|
|
24
84
|
registerConceptTools(server, client);
|
|
25
85
|
registerBrandTools(server, client);
|
|
26
86
|
registerInspirationTools(server, client);
|
package/dist/tools/wireframe.js
CHANGED
|
@@ -29,7 +29,42 @@ export function registerWireframeTools(server, client) {
|
|
|
29
29
|
return fail(e instanceof Error ? e.message : "Failed to get project intelligence.");
|
|
30
30
|
}
|
|
31
31
|
});
|
|
32
|
-
server.tool("
|
|
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
|
+
projectId: z.string(),
|
|
34
|
+
businessGoals: z.string().optional(),
|
|
35
|
+
pageGoals: z.string().optional(),
|
|
36
|
+
targetAudience: z.string().optional(),
|
|
37
|
+
sectionRequirements: z.string().optional(),
|
|
38
|
+
decisions: z.string().optional(),
|
|
39
|
+
constraints: z.string().optional(),
|
|
40
|
+
platformPreferences: z.string().optional(),
|
|
41
|
+
openQuestions: z.string().optional(),
|
|
42
|
+
agentInstructions: z.string().optional(),
|
|
43
|
+
acceptanceCriteria: z.string().optional(),
|
|
44
|
+
discovery: z.array(z.object({ question: z.string(), answer: z.string() })).optional(),
|
|
45
|
+
discoveryMode: z.enum(["append", "replace"]).optional(),
|
|
46
|
+
}, async ({ projectId, ...fields }) => {
|
|
47
|
+
try {
|
|
48
|
+
return ok(await client.patch(`/api/mcp/projects/${projectId}/intelligence`, fields));
|
|
49
|
+
}
|
|
50
|
+
catch (e) {
|
|
51
|
+
return fail(e instanceof Error ? e.message : "Failed to update the brief.");
|
|
52
|
+
}
|
|
53
|
+
});
|
|
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
|
+
projectId: z.string(),
|
|
56
|
+
name: z.string(),
|
|
57
|
+
slug: z.string().optional(),
|
|
58
|
+
position: z.number().optional(),
|
|
59
|
+
}, async ({ projectId, name, slug, position }) => {
|
|
60
|
+
try {
|
|
61
|
+
return ok(await client.post(`/api/mcp/projects/${projectId}/pages`, { name, slug, position }));
|
|
62
|
+
}
|
|
63
|
+
catch (e) {
|
|
64
|
+
return fail(e instanceof Error ? e.message : "Failed to create the page.");
|
|
65
|
+
}
|
|
66
|
+
});
|
|
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 }) => {
|
|
33
68
|
try {
|
|
34
69
|
return ok(await client.get(`/api/mcp/projects/${projectId}/wireframe-context`));
|
|
35
70
|
}
|
|
@@ -37,7 +72,7 @@ export function registerWireframeTools(server, client) {
|
|
|
37
72
|
return fail(e instanceof Error ? e.message : "Failed to get wireframe context.");
|
|
38
73
|
}
|
|
39
74
|
});
|
|
40
|
-
server.tool("save_wireframe", "Save a
|
|
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.", {
|
|
41
76
|
projectId: z.string(),
|
|
42
77
|
name: z.string(),
|
|
43
78
|
html: z.string(),
|
|
@@ -46,7 +81,9 @@ export function registerWireframeTools(server, client) {
|
|
|
46
81
|
goal: z.string().optional(),
|
|
47
82
|
sections: z.array(z.string()).optional(),
|
|
48
83
|
builderTarget: z.string().optional(),
|
|
49
|
-
|
|
84
|
+
pageSlug: z.string().optional(),
|
|
85
|
+
pageId: z.string().optional(),
|
|
86
|
+
}, async ({ projectId, name, html, css, pageType, goal, sections, builderTarget, pageSlug, pageId }) => {
|
|
50
87
|
try {
|
|
51
88
|
const data = await client.post("/api/mcp/concepts", {
|
|
52
89
|
projectId,
|
|
@@ -57,6 +94,8 @@ export function registerWireframeTools(server, client) {
|
|
|
57
94
|
goal,
|
|
58
95
|
sections,
|
|
59
96
|
builderTarget,
|
|
97
|
+
pageSlug,
|
|
98
|
+
pageId,
|
|
60
99
|
});
|
|
61
100
|
return ok(data);
|
|
62
101
|
}
|
|
@@ -64,4 +103,16 @@ export function registerWireframeTools(server, client) {
|
|
|
64
103
|
return fail(e instanceof Error ? e.message : "Failed to save wireframe.");
|
|
65
104
|
}
|
|
66
105
|
});
|
|
106
|
+
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
|
+
conceptId: z.string(),
|
|
108
|
+
pageSlug: z.string().optional(),
|
|
109
|
+
pageId: z.string().nullable().optional(),
|
|
110
|
+
}, async ({ conceptId, pageSlug, pageId }) => {
|
|
111
|
+
try {
|
|
112
|
+
return ok(await client.post(`/api/mcp/concepts/${conceptId}/page`, { pageSlug, pageId }));
|
|
113
|
+
}
|
|
114
|
+
catch (e) {
|
|
115
|
+
return fail(e instanceof Error ? e.message : "Failed to file the concept under a page.");
|
|
116
|
+
}
|
|
117
|
+
});
|
|
67
118
|
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@scayver/specshot-mcp-server",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "MCP server for SpecShot
|
|
3
|
+
"version": "0.9.1",
|
|
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",
|
|
7
7
|
"model-context-protocol",
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
"license": "MIT",
|
|
23
23
|
"type": "module",
|
|
24
24
|
"bin": {
|
|
25
|
-
"specshot-mcp": "
|
|
25
|
+
"specshot-mcp": "dist/index.js"
|
|
26
26
|
},
|
|
27
27
|
"files": [
|
|
28
28
|
"dist",
|