@wireweave/mcp-server 1.8.2 → 1.9.0-beta.14

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 (2) hide show
  1. package/README.md +20 -81
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -1,102 +1,41 @@
1
1
  # @wireweave/mcp-server
2
2
 
3
- A Model Context Protocol (MCP) server that exposes the Wireweave wireframe DSL to MCP clients like Claude Desktop and Cursor.
3
+ An MCP transport adapter for Wireweave tools.
4
4
 
5
- ## What it does
5
+ The [public tool contract](https://github.com/wireweave/wireweave/blob/develop/docs/spec/TOOLING.md#5-mcp-and-agent-plugins) defines this package's APIs, behavior, configuration and compatibility. The [language contract](https://github.com/wireweave/wireweave/blob/develop/docs/spec/LANGUAGE.md) defines the DSL. Package metadata owns versions, exports, dependencies and scripts.
6
6
 
7
- This server is a thin wrapper over [`@wireweave/sdk`](https://github.com/wireweave/wireweave/tree/main/packages/sdk). Every tool call from the MCP client is forwarded to the SDK's single `dispatch()` entry point, which validates the public input schema and routes it to one of two places:
7
+ ## Installation
8
8
 
9
- - **Local tools** run in-process via `@wireweave/core` and `@wireweave/ux-rules`. No network, no credits — they work even without an API key.
10
- - **Server tools** are proxied to the Wireweave API server (`api-server`) over HTTP. These require an API key (cloud project/wireframe storage, account & billing, hosted reference content such as the grammar and LLM guide).
11
-
12
- It serves **32 tools** (9 local + 23 server) plus prompts and resources. Tool definitions, routing and all four behavioral annotations come from the SDK's public `src/tool-catalog.json`. The offline generator and regression tests keep both adapters consistent; private service access is not required to build the catalog.
13
-
14
- Local tools:
15
-
16
- `wireweave_parse` · `wireweave_validate` · `wireweave_render_html_code` · `wireweave_validate_ux` · `wireweave_diff` · `wireweave_analyze` · `wireweave_list_components` · `wireweave_export_json` · `wireweave_export_figma`
17
-
18
- ## Install
9
+ Use Node.js >=22.13.0. Replace `<pinned-version>` with the release selected for your toolchain.
19
10
 
20
11
  ```bash
21
- npm install -g '@wireweave/mcp-server@<pinned-version>'
12
+ npm install --global '@wireweave/mcp-server@<pinned-version>'
22
13
  ```
23
14
 
24
- Or run directly:
15
+ The installed executable is `wireweave-mcp`. Setup, transports and credentials are defined by the tool contract.
25
16
 
26
- ```bash
27
- npx '@wireweave/mcp-server@<pinned-version>'
28
- ```
17
+ Run `wireweave-mcp` for stdio. Local parsing, validation, rendering, analysis, diffing, component discovery and JSON/Figma export need no account or API key. stdout contains only MCP protocol messages; diagnostics use stderr.
29
18
 
30
- Requires Node.js >=22.13.0. Replace `<pinned-version>` with the stable release selected for your toolchain. Only remote tools require an API key from the [Wireweave dashboard](https://wireweave.org).
19
+ ## HTTP and credentials
31
20
 
32
- ## Usage
21
+ HTTP mode (`wireweave-mcp --http`) requires a host-provided `WIREWEAVE_MCP_TOKEN`. Clients send it as `Authorization: Bearer <token>` on every MCP operation. Use a randomly generated secret and keep it in the host's secret store. The server binds to loopback by default. `WIREWEAVE_MCP_ALLOWED_ORIGINS` is an exact, comma-separated Origin allowlist; an empty list rejects requests carrying an Origin header. An allowed browser's CORS preflight needs no bearer token and cannot create a session or execute a tool; its actual request still requires authentication. See the public tool contract for configuration bounds and session behavior.
33
22
 
34
- ### MCP client configuration
23
+ The HTTP transport token is separate from `WIREWEAVE_API_KEY`. The latter authenticates explicitly invoked remote tools at `WIREWEAVE_API_URL` (default `https://api.wireweave.org`), using the `x-api-key` header. Remote tools include cloud storage/sharing, account/billing, gallery and hosted language guides/examples. Saving or updating a cloud wireframe sends its source and supplied metadata to that service. Local failures never fall back to remote execution. Remote calls time out after 30 seconds and do not follow redirects.
35
24
 
36
- Register the installed executable in your MCP client's supported stdio configuration, for example:
25
+ ## Privacy and security
37
26
 
38
- ```json
39
- {
40
- "mcpServers": {
41
- "wireweave": {
42
- "command": "wireweave-mcp",
43
- "args": [],
44
- "env": {}
45
- }
46
- }
47
- }
48
- ```
49
-
50
- Use the installed executable's absolute path if your client does not inherit its PATH. Client configuration locations and envelopes depend on the installed client; consult that client's setup instructions.
27
+ Read the [Privacy Policy](https://www.wireweave.org/privacy) for hosted-service data handling, retention and deletion requests. Local deterministic calls do not upload source or credentials. Every tool declares its read-only, destructive, idempotent and external-interaction hints; these describe behavior and do not replace authentication or authorization.
51
28
 
52
- ### Transport
29
+ ## Development
53
30
 
54
- The server runs over **stdio** by default. A streamable-HTTP transport is available with `--http` (or `WIREWEAVE_TRANSPORT=http`), serving the MCP endpoint at `/mcp` and a health check at `/health`.
31
+ Run from the monorepo root after the [workspace setup](https://github.com/wireweave/wireweave#workspace-commands).
55
32
 
56
33
  ```bash
57
- wireweave-mcp # stdio (default)
58
- wireweave-mcp --http # requires WIREWEAVE_MCP_TOKEN; loopback port 3305
34
+ pnpm --filter @wireweave/mcp-server run build
35
+ pnpm --filter @wireweave/mcp-server run typecheck
36
+ pnpm --filter @wireweave/mcp-server run lint
37
+ pnpm --filter @wireweave/mcp-server run test
38
+ pnpm --filter @wireweave/mcp-server run format:check
59
39
  ```
60
40
 
61
- ## Environment
62
-
63
- | Variable | Default | Purpose |
64
- | ------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------- |
65
- | `WIREWEAVE_API_KEY` | — | Required only for remote tools. Local tools work without it. |
66
- | `WIREWEAVE_API_URL` | `https://api.wireweave.org` | Override the API base. |
67
- | `WIREWEAVE_TRANSPORT` | `stdio` | Set to `http` for streamable HTTP (same as `--http`). |
68
- | `WIREWEAVE_MCP_PORT` | `3305` | HTTP port; integer 1–65535. |
69
- | `WIREWEAVE_MCP_HOST` | `127.0.0.1` | Loopback host. Non-loopback binding fails startup without a supported deployment profile. |
70
- | `WIREWEAVE_MCP_MAX_SESSIONS` | `10` | Active plus initializing session limit; integer 1–1024. |
71
- | `WIREWEAVE_MCP_TOKEN` | — | Required host-provided bearer credential for HTTP; separate from the account API key. |
72
- | `WIREWEAVE_MCP_ALLOWED_ORIGINS` | Empty | Exact comma-separated HTTP(S) origins. Empty rejects every request carrying Origin. |
73
-
74
- ### HTTP and credentials
75
-
76
- Send `Authorization: Bearer <WIREWEAVE_MCP_TOKEN>` on every MCP operation. Use a randomly generated token from the host secret store. Host and Origin are validated before dispatch. An allowed browser's OPTIONS preflight needs no bearer token but cannot create a session or execute a tool; its actual request still requires authentication. Wildcard CORS is not supported.
77
-
78
- Unknown or expired sessions return 404. Exhausted capacity returns 503 with `Retry-After: 1`. Idle sessions expire after 30 minutes. Termination cancels their pending work and frees capacity. Invalid configuration fails startup; malformed requests cannot terminate the process. Stdout is reserved for MCP messages and diagnostics use stderr.
79
-
80
- Remote tools send `WIREWEAVE_API_KEY` only to `WIREWEAVE_API_URL` using `x-api-key`. Saving or updating cloud wireframes transmits the supplied source and metadata. Requests time out after 30 seconds, carry cancellation and reject redirects. A local failure never triggers remote execution.
81
-
82
- ### Privacy and security
83
-
84
- The [Privacy Policy](https://www.wireweave.org/privacy) describes hosted-service data handling, retention and deletion requests. Local deterministic calls do not upload source or credentials. Tool annotations describe read-only, destructive, idempotent and external-interaction behavior; they are hints, not authorization.
85
-
86
- ## Tools
87
-
88
- Once connected, ask your MCP client to work with wireframes, for example:
89
-
90
- > "Parse and validate this Wireweave DSL." (local)
91
- >
92
- > "Check this wireframe against UX best practices." (local)
93
- >
94
- > "Save this wireframe as 'Dashboard v2' in my project." (server — needs an API key)
95
-
96
- Server tools cover cloud project/wireframe CRUD and versioning, share links, the public gallery, account balance & subscription, pricing, and hosted reference content (grammar, guide, patterns, examples, UX rules). Calls that need a key fail with a clear message if one is not configured.
97
-
98
- Part of the [Wireweave monorepo](https://github.com/wireweave/wireweave).
99
-
100
- ## License
101
-
102
- MIT
41
+ License: MIT.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wireweave/mcp-server",
3
- "version": "1.8.2",
3
+ "version": "1.9.0-beta.14",
4
4
  "description": "MCP server for Wireweave DSL - Thin client for API Server",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -16,7 +16,7 @@
16
16
  },
17
17
  "dependencies": {
18
18
  "@modelcontextprotocol/sdk": "^1.30.0",
19
- "@wireweave/sdk": "0.1.1"
19
+ "@wireweave/sdk": "0.2.0-beta.14"
20
20
  },
21
21
  "devDependencies": {
22
22
  "@commitlint/cli": "^21.2.2",
@@ -38,6 +38,9 @@
38
38
  "files": [
39
39
  "dist"
40
40
  ],
41
+ "engines": {
42
+ "node": ">=22.13.0"
43
+ },
41
44
  "repository": {
42
45
  "type": "git",
43
46
  "url": "git+https://github.com/wireweave/wireweave.git",
@@ -61,11 +64,9 @@
61
64
  "prototyping"
62
65
  ],
63
66
  "license": "MIT",
64
- "engines": {
65
- "node": ">=22.13.0"
66
- },
67
67
  "scripts": {
68
68
  "build": "tsup",
69
+ "postbuild": "node ../../scripts/dist-freshness-gate.mjs --write .",
69
70
  "dev": "tsup --watch",
70
71
  "start": "node dist/index.js",
71
72
  "start:http": "node dist/index.js --http",
@@ -76,7 +77,6 @@
76
77
  "format": "prettier --write .",
77
78
  "format:check": "prettier --check .",
78
79
  "knip": "knip",
79
- "publint": "publint --strict",
80
- "postbuild": "node ../../scripts/dist-freshness-gate.mjs --write ."
80
+ "publint": "publint --strict"
81
81
  }
82
82
  }