Weaverse MCP Server

@weaverse/mcp is the official Model Context Protocol server for Weaverse. It runs locally over stdio and exposes:

1. Public Weaverse documentation search.
2. Every operation currently mounted by the configured Weaverse Content API.

Discovery is mutation-free by default. All six Content API mutations are absent unless the operator sets the exact string WEAVERSE_ENABLE_LIVE_WRITES=true.

Quick start

Without a key:

{
  "mcpServers": {
    "weaverse": {
      "command": "npx",
      "args": ["-y", "@weaverse/mcp"]
    }
  }
}

Nine read-only tools are registered. Documentation search and get_openapi_spec work; the six authenticated Content API reads return an authentication error until a key is configured.

With Content API authentication:

{
  "mcpServers": {
    "weaverse": {
      "command": "npx",
      "args": ["-y", "@weaverse/mcp"],
      "env": {
        "WEAVERSE_API_KEY": "your-key"
      }
    }
  }
}

To expose every mounted mutation as well:

{
  "mcpServers": {
    "weaverse": {
      "command": "npx",
      "args": ["-y", "@weaverse/mcp"],
      "env": {
        "WEAVERSE_API_KEY": "your-key",
        "WEAVERSE_ENABLE_LIVE_WRITES": "true"
      }
    }
  }
}

Only exact lowercase true opts in. Unset, blank, 1, TRUE, yes, and whitespace-padded values leave mutations unregistered. The flag changes discovery only; it is not a credential and never replaces WEAVERSE_API_KEY.

Tools

Documentation (public)

| Tool | Description | | --- | --- | | search_weaverse_docs | Search the Weaverse docs/knowledge base. | | search_docs | Alias of search_weaverse_docs. |

These proxy the configured documentation MCP. The server does not cache or reimplement its search.

Content API reads

| Tool | Auth | Description | | --- | --- | --- | | list_projects | Key | List shop-owned projects; cursor-paginated, default 50, max 100. | | get_project | Key | Get one project. | | list_pages | Key | List page assignments; cursor-paginated, default 50, max 100. | | get_page | Key | Get one page in weaverse or portable-text format. | | get_theme_settings | Key | Get the project's own theme settings and optional static translations. | | list_languages | Key | List all project locales; unpaginated. | | get_openapi_spec | Public | Get the mounted API's committed OpenAPI document. |

Important read contracts:

• list_pages.data[].id is the assignment id. list_pages.data[].pageId is the content page id used by assign_template_resources.
• get_page defaults to format="weaverse", matching the API. Page handles are path splats, so multi-segment values such as pages/gift-shop round-trip.
• format="portable-text" is a lossy, read-only representation. No reverse converter exists. Fetch format="weaverse" before calling update_page.
• meta=true adds _weaverse ids to Portable Text blocks. includeDefaults=true fills schema-default gaps without replacing stored values.

Content API mutations (explicit opt-in)

All six require both WEAVERSE_ENABLE_LIVE_WRITES=true and an accepted WEAVERSE_API_KEY.

| Tool | MCP semantics | Description | | --- | --- | --- | | update_project | destructive, idempotent | Overwrite project name only, max 191 characters. | | create_page | additive, not idempotent | Create one page + assignment. Creatable types: ARTICLE, BLOG, COLLECTION, CUSTOM, PAGE, PRODUCT. Duplicate live assignment → 409. | | delete_pages | destructive, idempotent | Soft-delete by assignment ids, or handles + type; max 500. Handle locale defaults to en-us. No API restore operation exists. | | update_page | destructive, idempotent | Shallow-merge up to 100 item patches. Nested values replace wholesale; children:null clears children. | | assign_template_resources | additive, idempotent | Add up to 100 resource assignments to an existing shared template page. Conflicts reject the whole request. | | update_theme_settings | destructive, idempotent | Shallow-merge top-level own-theme keys; nested objects replace wholesale. |

Safety details:

• create_page and delete_pages are separate tools with disjoint, whitelisted bodies. The mounted POST /pages route dispatches any body containing pageIds or handles to deletion, so the create client never forwards unknown keys.
• delete_pages always sends DELETE; it never uses the overloaded POST alias.
• update_page can return HTTP 200 with per-item failed or notFound counters. Inspect the entire result.
• Assignment conflicts preserve the API's details.conflicts payload.
• A 500 from create_page, delete_pages, or assign_template_resources may occur after commit during post-write propagation. Re-read before retrying.
• The startup warning identifies all six enabled mutations. Five content mutations can affect storefront content through the configured API; update_project changes project metadata only.

Authentication and ownership

The server forwards WEAVERSE_API_KEY verbatim as Authorization: Bearer <key>. It never sends the API's query-string key fallback, inspects tokens, or implements a second auth system.

The mounted API accepts content_api and shopify token types. It does not accept agent_cli tokens, expose identity/whoami data, or implement OAuth scopes. A valid token has the mounted API's read/write capability for projects owned by its shop:

• missing/invalid token → 401
• project owned by another shop → 403
• missing/deleted project → 404

The MCP preserves the API error status, code, message, and optional details. Method-not-allowed is detected by HTTP status 405 because the API reuses code="INVALID_PARAMS" for that response.

Configuration

| Environment variable | Default | Purpose | | --- | --- | --- | | WEAVERSE_API_KEY | — | Bearer token for authenticated Content API tools. | | WEAVERSE_ENABLE_LIVE_WRITES | unset | Exact true registers all six mutations. | | WEAVERSE_CONTENT_API_URL | https://studio.weaverse.io/api/v1/content | Content API base URL. | | WEAVERSE_DOCS_MCP_URL | https://weaverse.io/docs/mcp | Documentation MCP endpoint. | | WEAVERSE_DOCS_SEARCH_TOOL | search_weaverse | Upstream docs-search tool name. |

@weaverse/mcp vs docs.weaverse.io/mcp

https://docs.weaverse.io/mcp is documentation-only. @weaverse/mcp proxies that search and adds the mounted Content API surface.

Development

npm ci
npm run build
npm test
node test.js

npm test is offline and deterministic. test.js is a manual real-stdio smoke that calls the configured documentation and Content APIs; it never invokes a mutation.

License

ISC