@scayver/specshot-mcp-server 0.11.0 → 0.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +118 -4
- package/dist/build-standard.js +5284 -17
- package/dist/index.js +45 -13
- package/dist/skills.js +502 -0
- package/dist/tool-descriptions.js +99 -0
- package/dist/tools/agent-loop.js +81 -0
- package/dist/tools/brand.js +2 -1
- package/dist/tools/canvas.js +5 -4
- package/dist/tools/concepts.js +63 -5
- package/dist/tools/etch-audit.js +30 -0
- package/dist/tools/images.js +67 -0
- package/dist/tools/inspiration.js +2 -1
- package/dist/tools/messages.js +12 -6
- package/dist/tools/prototype.js +27 -0
- package/dist/tools/render.js +53 -0
- package/dist/tools/review.js +27 -0
- package/dist/tools/seo.js +56 -0
- package/dist/tools/site.js +78 -0
- package/dist/tools/skills.js +20 -0
- package/dist/tools/state.js +33 -0
- package/dist/tools/tasks.js +60 -0
- package/dist/tools/wireframe.js +41 -21
- package/dist/tools/wordpress.js +24 -0
- package/dist/tools/workspace.js +26 -22
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -56,7 +56,7 @@ The server speaks stdio MCP, so it works in every major MCP client. Use a read/w
|
|
|
56
56
|
|
|
57
57
|
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"]`.
|
|
58
58
|
|
|
59
|
-
Claude Code (
|
|
59
|
+
Claude Code (`.mcp.json` in the project folder, or `claude mcp add`; it does not read MCP servers from `settings.json`), Claude Desktop (`claude_desktop_config.json`), Cursor (`.cursor/mcp.json` or Cursor Settings, MCP), and Cline all use the same JSON:
|
|
60
60
|
|
|
61
61
|
```json
|
|
62
62
|
{
|
|
@@ -82,8 +82,45 @@ args = ["-y", "@scayver/specshot-mcp-server"]
|
|
|
82
82
|
env = { SPECSHOT_API_TOKEN = "spec_your_token_here", SPECSHOT_APP_URL = "https://specshot.cc" }
|
|
83
83
|
```
|
|
84
84
|
|
|
85
|
+
## The design law and the prompts
|
|
86
|
+
|
|
87
|
+
Every design built through SpecShot is held to one law: the build standard, the premium bar, the
|
|
88
|
+
fluid token contract (the token names to use, every type and space step a `clamp()`), the rules
|
|
89
|
+
that make a design build into Etch, and the anti-slop list. The server hands over its one-screen
|
|
90
|
+
form when you connect and serves the whole law as prompts, the same ones the hosted endpoint
|
|
91
|
+
serves: `design_law`, `etch_ready`, `build_a_page`, `build_a_site`, `premium_craft`,
|
|
92
|
+
`design_principles`, `design_protocol`, `design_direction`, `reference_build` and `design_review`.
|
|
93
|
+
`build_a_site` is the loop for a whole site under one system (see "Build a whole site" below).
|
|
94
|
+
|
|
95
|
+
An agency that runs its work by plain phrases gets one prompt per phrase, each a short checklist
|
|
96
|
+
with the real tools and the agency skill for that phase: `new_client`, `start_discovery`,
|
|
97
|
+
`start_copywriting`, `start_design`, `start_development` and `remember_that`. The agency setup file
|
|
98
|
+
(Settings, MCP in SpecShot) maps every phrase to them.
|
|
99
|
+
|
|
100
|
+
Every save (`save_wireframe`, `publish_page_version`, `revise_wireframe`, `create_design_version`)
|
|
101
|
+
returns `designLaw`: a score from 0 to 100 and findings, each with a code, a severity and a fix.
|
|
102
|
+
Fix every `block` finding before calling a design ready. A save is never refused for a finding.
|
|
103
|
+
|
|
104
|
+
The same law installs as a skill for any agent that reads skills: copy
|
|
105
|
+
`docs/skills/specshot-design/SKILL.md` from the SpecShot repository into your skills folder.
|
|
106
|
+
|
|
107
|
+
The law, the prompts, the tool descriptions and the design skills in `src/build-standard.ts`,
|
|
108
|
+
`src/tool-descriptions.ts` and `src/skills.ts` are generated from the shared source; do not edit
|
|
109
|
+
them by hand.
|
|
110
|
+
|
|
85
111
|
## Tools
|
|
86
112
|
|
|
113
|
+
Where the project stands (call this first):
|
|
114
|
+
|
|
115
|
+
- `get_project_state({ projectId })`: the project as the team sees it: its stage, every page's state and detail, whose turn it is, and `next`, the one thing to do now with the tool call and its arguments filled in. When `next.actor` is not `agent`, it is someone else's turn.
|
|
116
|
+
- `get_next_action({ projectId })`: only the next action and whose turn it is. The cheap way to check back.
|
|
117
|
+
|
|
118
|
+
Design skills and the workflow (served from this package, no network call):
|
|
119
|
+
|
|
120
|
+
- `list_skills({})`: SpecShot's design skills (page composition, the hero, pricing, navigation, footers, forms, cards, buttons, typography, color and contrast, motion, accessibility, responsive behavior, the Etch and ACSS build and more), each with when to load it, plus the short page workflow. The agency process skills follow them: the phases and their gates, the discovery interview, copy and wireframe, design for ACSS, and the development rules for Etch.
|
|
121
|
+
- `get_skill({ id })`: one skill in full. Load the skill for each section kind before you build it; `get_wireframe_context` names the skills that fit each page.
|
|
122
|
+
- The `build_a_page` prompt leads with the page workflow and its tools, and the `revise_a_page` prompt carries the workflow for a revision.
|
|
123
|
+
|
|
87
124
|
Wireframe building (build a full site yourself, no AI key):
|
|
88
125
|
|
|
89
126
|
- `list_projects({})` — list the projects in your workspace.
|
|
@@ -95,6 +132,15 @@ Wireframe building (build a full site yourself, no AI key):
|
|
|
95
132
|
- `create_page({ projectId, name, slug?, position?, kind? })` — add a page the brief implies. `kind` is `screens` (default), `foundations`, or `components`.
|
|
96
133
|
- `list_components({ projectId })` — the project's shared component library, and what has drifted between pages.
|
|
97
134
|
|
|
135
|
+
Whole-site generation (every page of a site under one system; the `build_a_site` prompt gives the loop):
|
|
136
|
+
|
|
137
|
+
- `get_site_plan({ projectId })`: the site map (each page with its family and whether it is approved), the page families with their plans, pilots and findings, the site system's approved version and newest draft, the open site run and what it waits on, which reference goes to the whole site, a family or a page, and `next`, the one thing to do now. Read-only.
|
|
138
|
+
- `get_site_kit({ projectId, detail? })`: the approved site system (tokens, `:root`, kit CSS, header, footer, components) or the newest draft with its findings, sized for your context. `detail: "full"` returns the long parts whole. Read-only.
|
|
139
|
+
- `save_site_kit({ projectId, html, css?, direction?, itemId?, allowShrink? })`: save the style guide every page is built from. SpecShot embeds its faces, saves it as "Site system vN" under the Foundations page, reads the kit off it into a draft, and returns the extraction, the kit findings, the law and the layout check. A person approves the kit in SpecShot. Read/write token, and an owner, admin or editor seat.
|
|
140
|
+
- `set_page_families({ projectId, groupByCode?, families?, order? })`: group pages by their addresses, make or edit families (job, hero archetype, signature interaction, section plan, kit components, pages, pilot) and order them. The whole change is checked first, the way the Families sheet checks a save, and refused with its findings when it would add an error. Read/write token.
|
|
141
|
+
- `next_site_page({ projectId, start?, pageIds?, concurrency?, another?, known? })`: start an agent-driven run (`start: true`), then take each item with everything it needs in one call: the instructions, the site brief with the client's rules first, the kit, the family template with the pilot's `<main>`, the skills, the TYPE FACTS, the page's own facts and copy, the references with links to open, and the exact call to make. Pass `known` with the fingerprints of blocks you already hold to get `same: true` instead of their text. When the run waits on a person (the kit's approval or a family's pilot), `waitingOn` says so: you cannot pass a gate. Read/write token, and an owner, admin or editor seat.
|
|
142
|
+
- `publish_page_version({ projectId, itemId, mainHtml, pageCss?, sections?, finish? })`: site mode. Send only the page's `<main>` and its own CSS; SpecShot composes the page from the kit, checks it against the law, the layout and the kit, saves it under its page and records it in the run. A first publish with a block finding stays yours for one fix; the next one finishes the page, flagged if a block finding is left.
|
|
143
|
+
|
|
98
144
|
Conversation (iterate with the human, both ways):
|
|
99
145
|
|
|
100
146
|
- `get_messages({ conceptId })` — read the concept's thread, including feedback the human left in the portal.
|
|
@@ -133,15 +179,30 @@ Approved concepts (build a design SpecShot generated):
|
|
|
133
179
|
- `update_concept_status({ conceptId, status: "sent" | "built", buildNote? })` — mark a build started or complete.
|
|
134
180
|
- `add_build_note({ conceptId, note })` — log build progress on a concept.
|
|
135
181
|
|
|
182
|
+
Project tasks (tasks for people, the team's and the client's; your own queue stays `get_agent_tasks`):
|
|
183
|
+
|
|
184
|
+
- `list_project_tasks({ projectId, filter?, pageId?, limit?, offset? })`: the project's tasks with their status, assignee, due date and page. `filter` is `open` (the default), `mine`, `done` or `all`. Also the teammates a task can go to (never a viewer), the client's contacts, each page's due date and owner, the review rounds and the target launch. Read only.
|
|
185
|
+
- `create_project_task({ projectId, title, notes?, pageId?, assignee?, contactId?, dueOn?, status? })`: add a task. `assignee` is a teammate's userId or `client` (with `contactId` for a person at the client). Set a date or an assignee only when a person gave it to you. Read/write token.
|
|
186
|
+
- `update_project_task({ projectId, taskId, title?, notes?, status?, assignee?, contactId?, dueOn?, pageId? })`: change only the fields sent; `none` clears an assignee, a date or a page. Read/write token.
|
|
187
|
+
- `complete_project_task({ projectId, taskId })`: mark a task done. Read/write token.
|
|
188
|
+
- `set_page_schedule({ projectId, pageId, dueOn?, ownerUserId? })`, `set_round_due_date({ projectId, roundId?, dueOn })` and `set_target_launch({ projectId, targetLaunchOn })`: the dates beside the tasks; `none` clears one. The client sees the open round's date and the target launch. Read/write token.
|
|
189
|
+
|
|
190
|
+
Every change shows in the project's activity as your agent's. A task never moves a page or decides on one: approving and asking for changes stay with people.
|
|
191
|
+
|
|
192
|
+
The Etch site audit (run through the Etch Connector, like a build):
|
|
193
|
+
|
|
194
|
+
- `get_etch_audit({ remove?, scanPages? })`: a script that reads every page, template and component of the open Etch site and reports classes with no style record, SpecShot's own unused styles, stylesheets and components, where each SpecShot component is used, and assets outside a collection. It changes nothing unless `remove` names keys from a report's `removable` list that the person confirmed, and it never offers the site's own items.
|
|
195
|
+
|
|
136
196
|
## Build a full website wireframe (no AI key)
|
|
137
197
|
|
|
138
198
|
Any connected LLM can build the whole site itself and save it back. Nothing calls an AI provider on the SpecShot side.
|
|
139
199
|
|
|
140
200
|
1. `list_projects({})` and pick a project.
|
|
141
201
|
2. `get_wireframe_context({ projectId })`. You get the brief, every page, the brand tokens, the captured section references, and a build instruction.
|
|
142
|
-
3.
|
|
143
|
-
4.
|
|
144
|
-
5.
|
|
202
|
+
3. Load the skills it names for each page with `get_skill`, and follow the workflow in the `build_a_page` prompt.
|
|
203
|
+
4. Build one FULL-FIDELITY design per page as a self-contained HTML document, following the instruction: real brand tokens, real SVG icons, real copy, fluid responsive, light and dark. Never a gray skeleton.
|
|
204
|
+
5. `publish_page_version({ projectId, name: "Home", html, sections, pageSlug, ... })` for each page. SpecShot stores your HTML exactly as given, versions it, files it under the page, syncs its sections, and puts it on the owner's canvas.
|
|
205
|
+
6. Open the project in SpecShot to review the wireframes, iterate, or promote them.
|
|
145
206
|
|
|
146
207
|
### Iterate back and forth
|
|
147
208
|
|
|
@@ -153,6 +214,59 @@ The human and the agent share a conversation on each concept, so the two can go
|
|
|
153
214
|
4. The agent calls `post_message({ conceptId, body })` to say what changed. The human gets a notification.
|
|
154
215
|
5. Repeat until the human is happy, then they promote the concept.
|
|
155
216
|
|
|
217
|
+
## Build a whole site (an example session)
|
|
218
|
+
|
|
219
|
+
For a site of many pages, SpecShot keeps one system: a site kit made and approved once, page families
|
|
220
|
+
each made from an approved pilot page, and a queue for every other page. You write the parts that
|
|
221
|
+
need judgment; SpecShot puts the kit's shared parts on every page itself, checks each page and keeps
|
|
222
|
+
the queue. Every page is held to the design law, and the gates are a person's: you never approve.
|
|
223
|
+
|
|
224
|
+
```
|
|
225
|
+
> get_site_plan({ projectId: "p1" })
|
|
226
|
+
{ siteMap: [55 pages], families: [], kit: { approved: null, draft: null }, run: null,
|
|
227
|
+
next: "The project has no site system yet. Call next_site_page with start: true ..." }
|
|
228
|
+
|
|
229
|
+
> set_page_families({ projectId: "p1", groupByCode: true })
|
|
230
|
+
{ grouped: { created: 12, placed: 55 }, families: [...], readiness: { families: 12, incomplete: 12, ... } }
|
|
231
|
+
|
|
232
|
+
> set_page_families({ projectId: "p1", families: [
|
|
233
|
+
{ id: "f-services", job: "Explain one service and invite a call.", heroArchetype: "split-media",
|
|
234
|
+
signatureInteraction: "A process timeline that fills as you read.", pilot: "services-web-design",
|
|
235
|
+
sectionPlan: [{ key: "hero", name: "Hero", layout: "split" }, { key: "outcomes", name: "Outcomes", layout: "card-grid" }],
|
|
236
|
+
kitComponents: ["Button", "ServiceCard"] }, ... ] })
|
|
237
|
+
{ applied: [...], refused: [], readiness: { errors: 0, incomplete: 0, ... } }
|
|
238
|
+
|
|
239
|
+
> next_site_page({ projectId: "p1", start: true })
|
|
240
|
+
{ state: "claimed", started: true, item: { id: "i-kit", kind: "kit" },
|
|
241
|
+
instructions: "YOU MAKE THE SITE SYSTEM ...", parts: [13 parts], save: { tool: "save_site_kit", ... } }
|
|
242
|
+
|
|
243
|
+
> save_site_kit({ projectId: "p1", itemId: "i-kit", html: "<!doctype html>...", direction: { ... } })
|
|
244
|
+
{ kit: { version: 1, status: "draft" }, kitFindings: [], findings: { block: 0, ... }, item: { status: "done" } }
|
|
245
|
+
|
|
246
|
+
> next_site_page({ projectId: "p1" })
|
|
247
|
+
{ state: "waiting", waitingOn: "Waiting for the site system to be approved. Approve it, or continue
|
|
248
|
+
without the client's approval.", next: "A person approves it in SpecShot ..." }
|
|
249
|
+
|
|
250
|
+
(a person approves the site system in SpecShot)
|
|
251
|
+
|
|
252
|
+
> next_site_page({ projectId: "p1" })
|
|
253
|
+
{ state: "claimed", item: { id: "i-7", kind: "pilot", page: { name: "Web Design", path: "/services-web-design" } },
|
|
254
|
+
blocks: { siteBrief: {...}, kit: {...}, family: {...}, familySkills: {...}, page: {...} },
|
|
255
|
+
references: { page: [...], family: [...], site: [...] },
|
|
256
|
+
publish: { tool: "publish_page_version", arguments: { itemId: "i-7", sections: ["Header", "Hero", "Outcomes", "Footer"] } } }
|
|
257
|
+
|
|
258
|
+
> publish_page_version({ projectId: "p1", itemId: "i-7", mainHtml: "<section data-section=\"hero\">...</section>...",
|
|
259
|
+
pageCss: ".service-hero { ... }", sections: ["Header", "Hero", "Outcomes", "Footer"] })
|
|
260
|
+
{ concept: {...}, designLaw: {...}, layoutCheck: {...},
|
|
261
|
+
site: { status: "done", findings: { block: 0, ... }, consistency: { score: 100 }, next: "The pilot is done. ..." } }
|
|
262
|
+
|
|
263
|
+
... each family's pilot, a person approves them, then every other page, each call passing
|
|
264
|
+
known: [the fingerprints of the blocks already held], so a family's later pages send only their own words ...
|
|
265
|
+
|
|
266
|
+
> next_site_page({ projectId: "p1" })
|
|
267
|
+
{ state: "finished", next: "The run is finished: 56 done, 0 flagged, 0 failed, 0 skipped. ..." }
|
|
268
|
+
```
|
|
269
|
+
|
|
156
270
|
## Build an approved concept
|
|
157
271
|
|
|
158
272
|
1. Capture inspiration and sections in SpecShot, define your brand system, generate a design concept, and approve it.
|