@staffbase/spark-mcp

Model Context Protocol server for Spark. Exposes components, props, tokens, icons, and the published docs as tools your AI coding agent can call.

It's a thin wrapper around the same data shipped in @staffbase/spark and the Astro docs site — no remote calls, no telemetry. Snapshots are baked at publish time, so the server runs offline once installed.

Install

The package is published publicly to npm — no registry config or token required. Point your agent at it via npx.

Claude Code

// ~/.claude.json or .mcp.json
{
  "mcpServers": {
    "staffbase-spark": {
      "command": "npx",
      "args": ["-y", "@staffbase/spark-mcp@latest"],
    },
  },
}

GitHub Copilot

// ~/.copilot/mcp-config.json (user-global) or .copilot/mcp-config.json (repo-local)
{
  "mcpServers": {
    "staffbase-spark": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@staffbase/spark-mcp@latest"],
    },
  },
}

Or add it interactively from the Copilot CLI with /mcp add.

VS Code

// .vscode/mcp.json — note VS Code uses "servers", not "mcpServers"
{
  "servers": {
    "staffbase-spark": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@staffbase/spark-mcp@latest"],
    },
  },
}

OpenCode

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "staffbase-spark": {
      "type": "local",
      "command": ["npx", "-y", "@staffbase/spark-mcp@latest"],
      "enabled": true,
    },
  },
}

Internal Staffbase consumers

The same package is also mirrored to the private @staffbase GitHub Packages registry. If your environment resolves the @staffbase scope from there, no change is needed — the npx command above works unmodified once your .npmrc points the scope at https://npm.pkg.github.com/ with a GITHUB_TOKEN.

Tools

| Tool | Purpose | | ----------------------- | ------------------------------------------------------------------------------- | | list_components | Names, categories, deprecation flags, compound subcomponents | | get_component | Props interface, anatomy, available variants, deprecation map | | get_component_example | One example code block (default or named variant) | | list_tokens | Filtered by layer (primitive/semantic/component) and/or category | | get_token | One token plus its resolution chain | | list_icons | Filter by search term (matches name + tags) | | get_icon | One icon's React component name + tags | | get_doc_page | A rendered Astro docs page (components/button, foundation/tokens/colors, …) | | search_spark | Fuzzy search across components, tokens, icons, and doc body text |

Doc pages are also exposed as MCP resources (staffbase-spark://docs/{slug}) for clients that surface resources first-class.

Local development

pnpm --filter @staffbase/spark-mcp build:data   # regenerate JSON snapshots
pnpm --filter @staffbase/spark-mcp dev          # run the stdio server against the local repo

Point your agent at the local build by replacing the npx command with node /absolute/path/to/packages/spark-mcp/dist/server.js.

Versioning

@staffbase/spark-mcp shares a version line with @staffbase/spark (Changesets fixed). Every Spark release ships a matching MCP build with refreshed snapshots, so you can rely on the version of the MCP you have installed matching the version of Spark your codebase consumes.