Weaverse MCP Server

@weaverse/mcp is the official Model Context Protocol server for Weaverse. It gives an AI coding agent two things:

1. Docs — search the Weaverse documentation/knowledge base (public, no key).
2. Your account — read your own Weaverse projects, pages, theme settings, and locales over the Content API (authenticated, read-only, scoped to your shop).

It runs locally over stdio and is distributed via npx, so the same binary works in Cursor, Claude, Codex, and any other MCP client.

Quick start

Docs-only (no account, no key required):

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

With your account (adds the authenticated tools):

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

Tools

Docs (public — no API key)

| Tool | Description | | ---- | ----------- | | search_weaverse_docs | Search the Weaverse docs/knowledge base. Returns titles, links, and content. | | search_docs | Alias of search_weaverse_docs. |

Docs search proxies to the official Weaverse documentation MCP (hosted by Mintlify). Knowledge, ranking, and freshness all live upstream — this server never caches or reimplements docs search.

Account (authenticated, read-only)

All require WEAVERSE_API_KEY. Each call is scoped to the shop the key belongs to; cross-shop access returns an error.

| Tool | Description | | ---- | ----------- | | whoami | Identify the token: shop id + scopes (when available) and the projects it can access. Call this first. | | list_projects | List the projects in your shop (cursor-paginated). | | list_pages | List pages in a project (filter by type / locale). | | get_page | Get a page's content. Defaults to Portable Text (LLM-friendly); pass format: "weaverse" for the raw item tree. | | get_theme_settings | Get a project's theme settings (design tokens + config). | | list_languages | List a project's locales. |

Writes — not yet

The Content API is read-only today, so no write tools are exposed. When the write endpoints land, the planned tools (update_page_content, update_theme_settings, …) will ship behind a dry-run → confirm: true flow that returns a diff first and writes an audit-log entry on apply.

Destructive / account-level operations are intentionally never exposed via MCP — deleting projects, billing, team/members, plan changes, and production publishes stay human-only in Weaverse Builder. An agent may propose; a human confirms.

Authentication

The server reads WEAVERSE_API_KEY from its environment and forwards it to the Content API as Authorization: Bearer <key>. It never inspects or stores the token — the Content API is the single source of truth for shop scoping and per-scope access. Account tools return a clear auth error (never data) when the key is missing, invalid, or lacks the required scope.

Getting a key

• Today: a Content API key from Weaverse Dashboard → Settings → API Keys.
• Coming: a scoped, expiring agent_cli token from the agent device handshake — your agent runs the handshake once, you approve it in Builder, and the agent stores the key. Tokens are revocable any time from Settings → Connected agents.

Scopes

Account tools map to Content API scopes (content:read for the read tools). Scope and shop enforcement happen server-side; the MCP surfaces a 403-style error when a token is missing a scope or reaches across shops.

Configuration

| Env var | Default | Purpose | | ------- | ------- | ------- | | WEAVERSE_API_KEY | — | Bearer token for account tools. Unset = docs-only. | | WEAVERSE_CONTENT_API_URL | https://studio.weaverse.io/api/v1/content | Content API base URL. | | WEAVERSE_DOCS_MCP_URL | https://weaverse.io/docs/mcp | Upstream Mintlify docs MCP. | | WEAVERSE_DOCS_SEARCH_TOOL | search_weaverse | Tool name to call on the docs MCP. |

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

https://docs.weaverse.io/mcp is the Mintlify-hosted, docs-only MCP (great if all you want is documentation search over HTTP, no install). @weaverse/mcp is the canonical server: it proxies that same docs search and adds the authenticated account tools. Use @weaverse/mcp when you want your agent to work with your projects, not just read docs.

Development

npm install
npm run build     # tsc -> build/
npm test          # offline, deterministic unit tests (node:test)
node test.js      # live stdio smoke (hits the docs MCP; set WEAVERSE_API_KEY for account tools)

Source layout:

src/
  index.ts            # stdio entry
  config.ts           # env -> config
  content-api.ts      # typed Content API client (forwards the bearer token)
  result.ts           # MCP result + error-mapping helpers
  tools/
    docs.ts           # docs search (proxies the Mintlify docs MCP)
    account.ts        # read-only account tools
    index.ts          # registers all tools

License

ISC