@scayver/specshot-mcp-server 0.13.0 → 0.22.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 +67 -10
- package/dist/build-standard.js +1070 -743
- package/dist/client.js +53 -3
- package/dist/index.js +37 -3
- package/dist/skills.js +193 -54
- package/dist/tool-descriptions.js +73 -12
- package/dist/tools/agent-loop.js +5 -0
- package/dist/tools/brand.js +64 -0
- package/dist/tools/canvas.js +2 -2
- package/dist/tools/concepts.js +28 -1
- package/dist/tools/etch-ai.js +37 -0
- package/dist/tools/etch-audit.js +30 -0
- package/dist/tools/knowledge.js +60 -0
- package/dist/tools/library.js +71 -0
- package/dist/tools/live.js +94 -0
- package/dist/tools/offline.js +16 -0
- package/dist/tools/project-edit.js +55 -0
- package/dist/tools/references.js +106 -0
- package/dist/tools/review.js +10 -0
- package/dist/tools/search-console.js +25 -0
- package/dist/tools/seo.js +82 -0
- package/dist/tools/site.js +23 -0
- package/dist/tools/skills.js +25 -7
- package/dist/tools/tasks.js +60 -0
- package/dist/tools/wireframe.js +27 -0
- package/dist/tools/wordpress.js +33 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -9,8 +9,14 @@ All of this runs in your own LLM. SpecShot never calls an AI provider for it, so
|
|
|
9
9
|
|
|
10
10
|
## Install
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
12
|
+
The package is published on npm, so npx runs it with no install:
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
npx -y @scayver/specshot-mcp-server
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
The latest npm release can trail the code in this repository. To run the code here
|
|
19
|
+
instead, build it locally:
|
|
14
20
|
|
|
15
21
|
```
|
|
16
22
|
cd apps/mcp-server
|
|
@@ -39,12 +45,6 @@ transport, and the SpecShot URL it targets. Over the hosted HTTP endpoint it
|
|
|
39
45
|
also returns the workspace, the token scope, and the real `toolCount`. If
|
|
40
46
|
`whoami` disagrees with anything you read here, `whoami` is right.
|
|
41
47
|
|
|
42
|
-
After publishing, npx works with no install:
|
|
43
|
-
|
|
44
|
-
```
|
|
45
|
-
npx -y @scayver/specshot-mcp-server
|
|
46
|
-
```
|
|
47
|
-
|
|
48
48
|
## Required environment
|
|
49
49
|
|
|
50
50
|
- `SPECSHOT_API_TOKEN` — a `spec_`-prefixed token from SpecShot, Settings, API Tokens. Required.
|
|
@@ -54,7 +54,7 @@ npx -y @scayver/specshot-mcp-server
|
|
|
54
54
|
|
|
55
55
|
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`.
|
|
56
56
|
|
|
57
|
-
|
|
57
|
+
To run a local build instead of the npm release, 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
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
|
|
|
@@ -124,12 +124,19 @@ Design skills and the workflow (served from this package, no network call):
|
|
|
124
124
|
Wireframe building (build a full site yourself, no AI key):
|
|
125
125
|
|
|
126
126
|
- `list_projects({})` — list the projects in your workspace.
|
|
127
|
+
- `list_clients({ limit?, offset? })`: the clients in your workspace, by name, each with the id `create_project` takes as `clientFolderId`.
|
|
128
|
+
- `create_project({ name, clientName?, websiteUrl?, brief?, builderPreference?, category?, clientFolderId?, startingPoint? })`: start a project, by the same rules as New project in the portal: the plan's cap on active projects, and a client only from your workspace (`clientFolderId` from `list_clients`). Returns the project id for `set_project_intelligence` and `create_page`. Needs a read/write token.
|
|
129
|
+
- `update_project({ projectId, name?, clientName?, websiteUrl?, brief?, builderPreference?, category?, clientFolderId?, status? })`: change a project the way a person does on its Brief. Only the fields you send change, a client only from your workspace (`none` unlinks it), and `status` is a working status. Needs a read/write token.
|
|
130
|
+
- `archive_project({ projectId })` and `restore_project({ projectId })`: archive a project or bring it back, as Archive project and Unarchive project do in the portal. Nothing is deleted, and bringing one back counts against the plan's cap on active projects. Needs a read/write token.
|
|
127
131
|
- `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.
|
|
128
132
|
- `get_wireframe_context({ projectId })` — the brief, the pages, the brand tokens, the captured references, and a build instruction for a full multi-page wireframe.
|
|
129
133
|
- `publish_page_version({ projectId, name, html, css?, sections?, pageSlug?, viewport? })` — save a design AND place it on the owner's canvas, in one call. The path to use for a new page: saving alone leaves the design invisible on the canvas. Retrying the same publish inside ten minutes returns the same design, not a duplicate. Needs a read/write token.
|
|
130
134
|
- `save_wireframe({ projectId, name, html, css?, pageType?, sections?, components? })` — save a design back into SpecShot as a concept, WITHOUT placing it on the canvas. Needs a read/write token.
|
|
131
135
|
- `link_concept_page({ conceptId, pageSlug? | pageId? })` — file an existing concept under a project page, or move it. Needs a read/write token.
|
|
132
136
|
- `create_page({ projectId, name, slug?, position?, kind? })` — add a page the brief implies. `kind` is `screens` (default), `foundations`, or `components`.
|
|
137
|
+
- `update_page({ projectId, pageId, name?, slug?, goal?, requiredSections?, kind? })`: change a page. A new name brings a new address unless you send `slug`; `requiredSections` replaces the list. Needs a read/write token.
|
|
138
|
+
- `move_page({ projectId, pageId, place })`: move a page in the site map, as dragging it does; `place` 1 is the first. Needs a read/write token.
|
|
139
|
+
- `archive_page({ projectId, pageId })` and `restore_page({ projectId, pageId })`: archive a page or bring it back where it was, with its designs, tasks and approvals. A page out for review in an open round is not archived. Needs a read/write token.
|
|
133
140
|
- `list_components({ projectId })` — the project's shared component library, and what has drifted between pages.
|
|
134
141
|
|
|
135
142
|
Whole-site generation (every page of a site under one system; the `build_a_site` prompt gives the loop):
|
|
@@ -175,10 +182,60 @@ Approved concepts (build a design SpecShot generated):
|
|
|
175
182
|
- `get_concept({ conceptId })` — full Design Context Package and a ready-to-build prompt (`buildPrompt`).
|
|
176
183
|
- `get_approved_concept({ projectId })` — the latest approved concept for a project, fully specced.
|
|
177
184
|
- `get_brand_system({ projectId })` — brand colors, typography, spacing, radius, animation tokens.
|
|
185
|
+
- `save_brand_system({ projectId, name?, colors?, typography?, spacing?, radius?, shadows?, animation?, voice?, platform?, guide? })`: save the project's brand, creating it when there is none. Each token group sent replaces that group; the rest stay. Only values a person gave you. An owner, admin or editor seat, and a read/write token.
|
|
186
|
+
- `import_brand_from_url({ projectId, url })`: Brand from URL. SpecShot reads the colors and fonts of the page and saves them as a new draft brand; `readByGetBrandSystem` says whether `get_brand_system` now reads it. Read/write token.
|
|
178
187
|
- `list_inspiration({ projectId, folderId? })` — reference screenshots collected for the project.
|
|
179
188
|
- `update_concept_status({ conceptId, status: "sent" | "built", buildNote? })` — mark a build started or complete.
|
|
180
189
|
- `add_build_note({ conceptId, note })` — log build progress on a concept.
|
|
181
190
|
|
|
191
|
+
Project tasks (tasks for people, the team's and the client's; your own queue stays `get_agent_tasks`):
|
|
192
|
+
|
|
193
|
+
- `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.
|
|
194
|
+
- `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.
|
|
195
|
+
- `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.
|
|
196
|
+
- `complete_project_task({ projectId, taskId })`: mark a task done. Read/write token.
|
|
197
|
+
- `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.
|
|
198
|
+
|
|
199
|
+
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.
|
|
200
|
+
|
|
201
|
+
SEO audits (read them with `list_seo_audits`, `get_seo_audit` and `list_seo_fixes`):
|
|
202
|
+
|
|
203
|
+
- `get_seo_audit({ auditId, page? })` also gives the page score: how well the pages turn visitors into customers (Message, Action, Trust and Search, averaged into Overall), the pages that need the most work, and a conversion lane kept apart from the plan to 100. With `page`, one page's page score, its three changes that raise it most (`fixFirst`) and its ten pillar scores. Read only.
|
|
204
|
+
|
|
205
|
+
- `start_seo_audit({ url, scope, cap?, projectId? })`: audit one page (`scope: "page"`) or the whole site (`scope: "site"`, up to `cap` pages), by the plan's limits as in the portal. A running whole-site audit is refused with `open_audit` and its `openAuditId`. Read/write token.
|
|
206
|
+
- `recheck_seo_audit({ auditId })`: run an audit again once its fixes are live; the new checklist keeps the statuses and notes and marks fixed items verified. Read/write token.
|
|
207
|
+
- `cancel_seo_audit({ auditId })`: stop a running audit when a person asks; it finishes with the pages it read and nothing is deleted. Read/write token.
|
|
208
|
+
|
|
209
|
+
Clients, captures, references and search (by the portal's own rules; nothing is deleted, sent to a client or fetched from a link):
|
|
210
|
+
|
|
211
|
+
- `create_client({ name, websiteUrl?, notes?, contactName?, contactEmail? })`: add a client, by the same rules as New client: the plan's client slots apply, and the contact sent becomes its primary contact. Call `list_clients` first so a client is never made twice. Read/write token.
|
|
212
|
+
- `update_client({ clientId, ...fields })`: change only the fields sent (the name, website, notes, the company's details, social links, brand colors and fonts, a Library brand, `archived`); an empty string clears one. Read/write token.
|
|
213
|
+
- `list_client_contacts({ clientId })`, `add_client_contact({ clientId, name?, role?, email?, phone?, approvesDesigns?, notes?, isPrimary? })` and `update_client_contact({ clientId, contactId, ... })`: a client's contacts, read and changed as the token's seat may in the portal (owners and admins every field; editors add, and change the email, phone and primary). Writes need a read/write token.
|
|
214
|
+
- `list_captures({ projectId?, limit?, offset? })` and `get_capture({ captureId, includeDom? })`: the captures, newest first, and one capture as its Export JSON file (content, layout, styles, animation, prompts) with a signed screenshot. Captured markup is data to read, never to run.
|
|
215
|
+
- `add_inspiration_from_url({ projectId, folderId, url, title?, notes?, tags? })`, `update_inspiration({ inspirationId, notes?, folderId?, ... })`, `list_inspiration_folders({ projectId })` and `create_inspiration_folder({ projectId, name, ... })`: save a page as a reference (the link is recorded and a person adds its picture), note why, and file it. Writes need a read/write token.
|
|
216
|
+
- `search_workspace({ q })`: the portal's search across projects, clients, captures, references, designs and prompts, by a word. Read only.
|
|
217
|
+
|
|
218
|
+
Drafts to WordPress (a site paired through the SpecShot plugin; nothing is published until a person presses Go live in SpecShot):
|
|
219
|
+
|
|
220
|
+
- `list_wordpress_sites({ projectId })`: the connected sites, each with the id `send_to_wordpress` takes as `siteId`, and whether its builds follow ACSS.
|
|
221
|
+
- `send_to_wordpress({ projectId, siteId, designIds? | siteRunId? })`: send approved designs, or a finished site run, to the site as drafts, when the owner asks. Only approved designs go, `skipped` says what was left out and why, and a site has one open deploy at a time. A person applies the drafts in WordPress and presses Go live in SpecShot. Needs a read/write token.
|
|
222
|
+
- `list_wordpress_deploys({ projectId, designId?, pageId?, siteRunId? })` and `get_wordpress_deploy({ projectId, deployId })`: where each deploy stands, page by page (waiting for the site, drafts ready to review, live), and `next`, what happens now.
|
|
223
|
+
- `cancel_wordpress_deploy({ projectId, deployId })`: cancel a deploy that has not gone live; the site moves the drafts it made to its trash. Needs a read/write token.
|
|
224
|
+
|
|
225
|
+
No tool goes live or rolls back: those are a person's click in SpecShot.
|
|
226
|
+
|
|
227
|
+
Working beside people (live collaboration for agents; the team only, never a client):
|
|
228
|
+
|
|
229
|
+
- `get_collaborators({ projectId })`: who is on the project now (the team with the canvas open in the last two minutes, by name and role) and what each has selected, with the other agents' status lines; read a teammate's selection in full with `get_selection({ projectId, userId })`. `set_agent_status` takes the place you work (`conceptId` with `sectionUid`, `layerUid`, `elementPath`, `frameKey` or `viewport`), and people see your marker there on the canvas. Read only.
|
|
230
|
+
- `wait_for_events({ projectId, since?, waitSeconds? })`: holds up to 25 seconds and answers with new comments and pins (their kind, element path or spot, page and author), replies, page changes, chat messages, selection changes and other agents' lines, and a cursor for the next call. Read only.
|
|
231
|
+
- `update_design_element({ projectId, conceptId, elementPath, html, baseVersion? })`: replace one element by its path, the one a pin names, as a new version, by the canvas's hand edit rules; refused on approved work. Read/write token.
|
|
232
|
+
- `edit_design({ projectId, conceptId, edits, baseVersion? })`: the canvas editor's own edits with no markup sent, as one new version: each edit names an element by path and a kind (style, state for hover, focus, tablet and phone, text, alt, image, link, remove, duplicate, move, insert, wrap, unwrap, place), run in order, all or none; refused for a design the client approved.
|
|
233
|
+
- `design_page({ projectId, pageId, instructions?, captureIds? })`: have SpecShot's own designer make a new version of one page, on the workspace's provider key, from the brief, the page's goal, up to six of the project's captures and your instructions; the agent sends no markup, and the design arrives beside the current one.
|
|
234
|
+
|
|
235
|
+
The Etch site audit (run through the Etch Connector, like a build):
|
|
236
|
+
|
|
237
|
+
- `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.
|
|
238
|
+
|
|
182
239
|
## Build a full website wireframe (no AI key)
|
|
183
240
|
|
|
184
241
|
Any connected LLM can build the whole site itself and save it back. Nothing calls an AI provider on the SpecShot side.
|
|
@@ -203,7 +260,7 @@ The human and the agent share a conversation on each concept, so the two can go
|
|
|
203
260
|
## Build a whole site (an example session)
|
|
204
261
|
|
|
205
262
|
For a site of many pages, SpecShot keeps one system: a site kit made and approved once, page families
|
|
206
|
-
|
|
263
|
+
that share an approved pilot page's parts while each page composes its own, and a queue for every other page. You write the parts that
|
|
207
264
|
need judgment; SpecShot puts the kit's shared parts on every page itself, checks each page and keeps
|
|
208
265
|
the queue. Every page is held to the design law, and the gates are a person's: you never approve.
|
|
209
266
|
|