# @brainerce/mcp-server

Framework-agnostic domain knowledge for building on [Brainerce](https://brainerce.com), a headless commerce platform. This MCP server answers questions an AI coding assistant needs while building or extending a Brainerce-powered storefront — SDK reference, type definitions, business-flow sequencing, critical rules, and a given store's live capabilities.

It does **not** generate framework boilerplate. Use Next.js, Remix, Vite + React, Vue, Svelte, Astro, SolidStart, or whatever the surrounding project already uses — this server tells the agent what to build correctly, not how to lay out files. For opinionated scaffolding, see the companion [`create-brainerce-store`](https://www.npmjs.com/package/create-brainerce-store) CLI.

## Install

**Claude Code (plugin):**

```bash
claude plugin install brainerce-mcp@claude-plugins-community
```

**Any MCP client (stdio, manual config):**

```json
{
  "mcpServers": {
    "brainerce": {
      "command": "npx",
      "args": ["-y", "@brainerce/mcp-server"]
    }
  }
}
```

## Tools

| Tool | Purpose |
| --- | --- |
| `get-store-capabilities` | Live features configured for a specific store (payment providers, OAuth, discounts, shipping, i18n). Call first — it tells the agent which conditional features to build. |
| `get-required-features` | Functional coverage checklist — what users must be able to do, not which files to create. Mandatory features must exist even when currently disabled in the store (they auto-hide; owners enable them later). |
| `get-critical-rules` | Do's and don'ts that cause production incidents if violated — SDK usage, auth token handling, checkout invariants, i18n, type safety. |
| `get-business-flows` | Non-negotiable ordered SDK call sequences: checkout, auth, password reset, OAuth, order confirmation, cart persistence, inventory reservation. |
| `get-sdk-docs` | SDK documentation by topic — setup, API usage, best practices. |
| `get-type-definitions` | TypeScript types for Product, Cart, Checkout, Order, etc. |
| `get-code-example` | Short, focused snippets for tricky SDK calls (payment confirmation, reservation countdown, OAuth redirect, variant selection). |
| `get-store-info` | Live store metadata (display name, currency, language) for a sales channel. |
| `get-integration-guide` | Step-by-step integration walkthrough — `core` (products/cart/checkout/payment/orders), `optional` (accounts/OAuth/promotions), or `rules` (validation/error codes/edge cases). |

## Resources

- `sdk-types` — the full Brainerce SDK type surface as a text resource.

## Prompts

- `create-store` — framework-agnostic brief for building a new Brainerce-powered store; instructs the agent to call the knowledge tools above before writing code.
- `add-feature` — focused prompt for adding one feature to an existing Brainerce store.

## Self-hosting

```bash
pnpm build
pnpm start:stdio   # stdio transport, for local MCP clients
pnpm start:http    # Streamable HTTP + legacy SSE, for remote clients (default port 3100)
```

The HTTP server is a public, unauthenticated documentation oracle by design — everything behind it is public SDK/docs data. It applies allow-listed CORS, per-IP rate limiting, request size caps, and SSE session limits; see `src/bin/http.ts` for details.

## Privacy

This server serves static SDK documentation and, for the store-scoped tools (`get-store-info`, `get-store-capabilities`, `get-required-features`), reads public store configuration via Brainerce's public API. It does not collect or store conversation data. See [brainerce.com/privacy](https://brainerce.com/privacy) for the full policy.

## License

MIT — see [LICENSE](./LICENSE).