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