@zaai-dev/mcp 0.2.0 → 0.3.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.
Files changed (7) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +53 -14
  3. package/dist/bin/http.js +1097 -0
  4. package/dist/bin/http.js.map +1 -0
  5. package/dist/bin/stdio.js +38 -15
  6. package/dist/bin/stdio.js.map +1 -1
  7. package/package.json +4 -2
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Zaai Studio
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Zaai Studio
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -34,7 +34,7 @@ Add to `claude_desktop_config.json` — merge into the existing `mcpServers` blo
34
34
  }
35
35
  ```
36
36
 
37
- Restart Claude Desktop. The 9 tools below appear in the slash-command picker.
37
+ Restart Claude Desktop. The 17 tools below appear in the slash-command picker.
38
38
 
39
39
  ### Cursor
40
40
 
@@ -64,21 +64,51 @@ One-liner — updates `~/.claude/mcp_servers.json` automatically:
64
64
  claude mcp add zaai-dev -e ZAAI_API_TOKEN=zaai_mcp_YOUR_SECRET_HERE -- npx -y @zaai-dev/mcp
65
65
  ```
66
66
 
67
+ ### Streamable HTTP (v0.3.0+, hosted-agent use cases)
68
+
69
+ If you want to run Zaai Dev MCP as a network service — e.g. behind a reverse proxy on Fly / Cloudflare / Render so hosted agents (Claude.ai web, OpenAI Assistants, custom frameworks) can reach it — use the `zaai-dev-mcp-http` binary instead of the stdio one:
70
+
71
+ ```sh
72
+ ZAAI_API_TOKEN=zaai_mcp_... \
73
+ ZAAI_HTTP_PORT=3001 \
74
+ npx -y --package=@zaai-dev/mcp zaai-dev-mcp-http
75
+ # POST /mcp for MCP traffic, GET /healthz for liveness
76
+ ```
77
+
78
+ **Single-tenant in v1.5** — one process serves one workspace token. Run one process per token if you need multi-tenant, or wait for v2 which adds per-request token binding. Most "I want HTTP" use cases are single-tenant anyway.
79
+
67
80
  ## Tools
68
81
 
69
- All tools except `health` need a valid token. All tools except `health` and `whoami` charge **1 credit** per successful call (your workspace plan determines the monthly credit grant — see [pricing](https://www.zaaistudio.com/dev/pricing)).
82
+ All tools except `health` need a valid token. All tools except `health` and `whoami` charge credits per successful call (your workspace plan determines the monthly grant — see [pricing](https://www.zaaistudio.com/dev/pricing)).
70
83
 
71
- | Tool | What it does |
72
- |---|---|
73
- | `health` | Server status + version + uptime. No auth, no charge. |
74
- | `whoami` | Returns your userId, orgId, project scope, and credit balance. No charge. |
75
- | `list_captures` | Paginated list of your captures (newest first). Args: `q`, `cursor`, `limit`. |
76
- | `search_captures` | Same as list but with `q` required. Tuned description for targeted retrieval. |
77
- | `get_capture` | Full payload + signed screenshot URLs for one capture id. |
78
- | `get_palette` | Just the palette slice (page) or eyedropper picks (element/composite). |
79
- | `get_html` | Just the HTML. Page → full HTML; element → outerHTML; composite → concat with markers. |
80
- | `get_animation` | Just the animation data — CSS transitions, keyframes, library hints. |
81
- | `get_media` | Just the media inventory — videos, images, backgrounds, carousels. |
84
+ ### Captures (org-wide)
85
+
86
+ | Tool | What it does | Cost |
87
+ |---|---|---|
88
+ | `health` | Server status + version + uptime. No auth. | 0 |
89
+ | `whoami` | Your userId, orgId, project scope, credit balance. | 0 |
90
+ | `list_captures` | Paginated list of your captures (newest first). Args: `q`, `cursor`, `limit`. | 1 |
91
+ | `search_captures` | Same as list but with `q` required. Tuned description for targeted retrieval. | 1 |
92
+ | `get_capture` | Full payload + signed screenshot URLs for one capture id. | 1 |
93
+ | `get_palette` | Just the palette slice (page) or eyedropper picks (element/composite). | 1 |
94
+ | `get_html` | Just the HTML. Page → full HTML; element → outerHTML; composite → concat with markers. | 1 |
95
+ | `get_animation` | Just the animation data — CSS transitions, keyframes, library hints. | 1 |
96
+ | `get_media` | Just the media inventory — videos, images, backgrounds, carousels. | 1 |
97
+
98
+ ### Brand brief + references (project-scoped, v0.2.0+)
99
+
100
+ These tools each take a `project_id` arg (find via the workspace at `zaaistudio.com/dev/projects/<id>` — the UUID is in the URL).
101
+
102
+ | Tool | What it does | Cost |
103
+ |---|---|---|
104
+ | `get_brand_brief` | Full published brief: positioning, values, voice, audience, design intent, decisions. | 1 |
105
+ | `get_voice` | Voice slice only — one-liner, tone descriptors, do/don't say, example phrases. | 1 |
106
+ | `get_audience` | Primary + secondary segments, needs, channels. | 1 |
107
+ | `get_design_intent` | Descriptors + anti-descriptors + inspiration summary. | 1 |
108
+ | `get_brand_tokens` | Colors, fonts, radius, shadow scales. | 1 |
109
+ | `get_decisions` | Paginated decisions log with attribution + brief_field links. | 1 |
110
+ | `get_references` | Paginated project-scoped reference list. | 1 |
111
+ | `search_references` | Keyword search within a project's references. | 1 |
82
112
 
83
113
  Plus the `zaai-capture://{id}` resource template — attach individual captures to a conversation via the resource picker.
84
114
 
@@ -89,11 +119,20 @@ Plus the `zaai-capture://{id}` resource template — attach individual captures
89
119
  | `Unauthorized` | Token invalid, revoked, or wrong kind | Mint a fresh `mcp` token, update your config, restart |
90
120
  | `InsufficientCredits` | Out of credits for the month | [Top up](https://www.zaaistudio.com/dev/settings/billing) or wait for the monthly grant |
91
121
  | `CaptureNotFound` | id doesn't exist OR is in a project the token can't see | `list_captures` to find valid ids |
92
- | `InvalidCaptureId` | id isn't a UUID | Pass an id from `list_captures` or the workspace URL |
122
+ | `InvalidCaptureId` / `InvalidProjectId` | id isn't a UUID | Pass a UUID from `list_captures` / the workspace URL |
123
+ | `ProjectNotFound` | project_id isn't in your org | Check the id, or that the token's project scope allows this project |
124
+ | `ProjectArchived` | Project exists but is archived | Unarchive in the workspace or use a different project |
125
+ | `OutOfScope` | Token is scoped to specific projects + this isn't one of them | Mint a token without project scope, or add this project to the existing token |
93
126
  | `UnknownCaptureField` | Hit a focused-getter route with an unknown field | Use one of: `palette`, `html`, `animation`, `media` |
94
127
 
95
128
  Errors return as `isError: true` in the tool result so the LLM can read and act on them.
96
129
 
130
+ Transient failures (network errors, 502/503/504, 429 rate-limits) retry automatically with exponential backoff (250ms → 500ms → 1000ms, 3 attempts). Retries are transparent — you only see the final outcome — and don't double-charge because the workspace only bills on requests that actually executed.
131
+
132
+ ## Troubleshooting
133
+
134
+ See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for a checklist of common first-install issues and their fixes.
135
+
97
136
  ## Privacy + scoping
98
137
 
99
138
  The server holds **only your MCP token** — it never sees your password, your Supabase service-role key, or other users' data. The workspace's `verifyToken` derives `userId` + `orgId` from your token on every request; queries are scoped to that user + the token's project allowlist (which you set at mint time). A revoked token causes the next tool call to fail with `Unauthorized`.