@wafle/mcp — Model Context Protocol server for wafle

The first MCP server for the wafle commerce platform. Lets Claude Desktop, Claude Code, agents, and any MCP-compatible client drive a wafle tenant — stores, products, orders, pricing, gateways, audiences, system — by talking to it.

What this is

Wafle is the LLM-first multi-tenant commerce platform. Its REST API at https://wafle.click/wp-json/waffle/v1/ does the work; this MCP server exposes that work as 68 tools, 14 resources, and 5 server-defined prompts an LLM can pick from. Every wafle feature should land here as a tool first, UI second.

This is a thin, well-typed wrapper. No business logic lives in this package — bugs in pricing or order flow belong to the wafle backend.

Install

git clone <repo>
cd wafle-mcp
npm install
npm run build

Configure

Set environment variables (or copy .env.example to .env):

WAFLE_API_URL=https://wafle.click/wp-json/waffle/v1   # default
WAFLE_API_KEY=<your wafle admin key>                   # required (upstream)
WAFLE_TIMEOUT_MS=30000                                 # optional

# Only used by --transport=http:
WAFLE_MCP_HTTP_HOST=0.0.0.0
WAFLE_MCP_HTTP_PORT=7100

# Tenant-scoped JWT auth (recommended). Same value as WAFFLE_MCP_JWT_SECRET
# in the backend mu-plugin. Generate: openssl rand -hex 64
WAFLE_MCP_JWT_SECRET=<shared HS256 secret>
WAFLE_MCP_REQUIRE_JWT=1                                 # refuses legacy bearers in prod

# Legacy admin-tier bearers (cross-tenant). Used as fallback when REQUIRE_JWT is unset.
WAFLE_MCP_TOKENS=<comma-separated bearer tokens>

LOG_LEVEL=info

WAFLE_API_KEY is the upstream wafle key the MCP server uses to talk to the backend (master, scoped at the backend layer). Tenant isolation for the MCP itself is enforced by WAFLE_MCP_JWT_SECRET — the backend mints HS256 JWTs carrying tenant_id + tenant_slug + scope, and this server filters tools/list and rewrites every per-store call to the JWT's tenant. See src/auth/jwt.ts, src/auth/tenant.ts.

Tenant tokens

Clients obtain a tenant-scoped JWT from the wafle backend:

POST /wp-json/waffle/v1/admin/account/mcp/issue-token
X-Wafle-Admin-Key: <store key for that tenant>
{ "ttl_days": 30 }

Response includes { token, jti, tenant_slug, expires_at, mcp_url }. The client then sends Authorization: Bearer <token> to mcp.wafle.click/mcp. With this token:

• tools/list only shows the tenant's tools — admin-only tools (wafle_system_*, wafle_gateways_*, wafle_stores_list/create, wafle_auth_keys_*) are filtered out server-side.

• Every per-tenant tool ignores the slug argument and uses the JWT's tenant_slug instead. A token for tenant A cannot read or mutate tenant B regardless of arguments passed.

• Tokens can be revoked via POST /admin/account/mcp/revoke-token ({ jti }) and listed via GET /admin/account/mcp/tokens.

Run

stdio (Claude Desktop, Claude Code local)

node dist/index.js --transport=stdio

Logs go to stderr. Stdout is reserved for the JSON-RPC framing — never console.log from a tool handler.

HTTP / Streamable HTTP (remote agents, web)

node dist/index.js --transport=http

Listens on WAFLE_MCP_HTTP_PORT (default 7100). Single endpoint at POST /mcp per the MCP Streamable HTTP spec (2025-03-26). GET /healthz for liveness.

Bearer auth on every request: Authorization: Bearer <token> where <token> is one of the values in WAFLE_MCP_TOKENS. The MCP server refuses all traffic if no tokens are configured.

Connect Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "wafle": {
      "command": "node",
      "args": ["/absolute/path/to/wafle-mcp/dist/index.js", "--transport=stdio"],
      "env": {
        "WAFLE_API_KEY": "your-wafle-admin-key",
        "WAFLE_API_URL": "https://wafle.click/wp-json/waffle/v1",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Restart Claude Desktop. You should see "wafle" with 63 tools in the /mcp panel.

There is also an example at examples/claude-desktop-config.json.

Connect Claude Code

Project-scoped: drop a file at <repo>/.mcp.json:

{
  "mcpServers": {
    "wafle": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/wafle-mcp/dist/index.js", "--transport=stdio"],
      "env": { "WAFLE_API_KEY": "your-key" }
    }
  }
}

User-scoped: append to ~/.claude/.mcp.json (same shape).

For the deployed HTTP transport at mcp.wafle.click:

{
  "mcpServers": {
    "wafle": {
      "type": "http",
      "url": "https://mcp.wafle.click/mcp",
      "headers": { "Authorization": "Bearer <bearer token>" }
    }
  }
}

Tool catalogue (68)

Every tool has a markdown description with usage guidance, a Zod schema with .describe()-annotated fields, scope requirements, and readOnlyHint/destructiveHint/idempotentHint annotations to help the LLM pick wisely.

The long-running tools (_sync_trigger_and_wait, _csv_import, _ads_sync_full) emit notifications/progress while polling — clients that support progress (Claude Desktop) show a live progress bar.

Resources (14)

MCP Resources expose read-only context the LLM can pull in without spending a tool call. Reference them with @<uri> in Claude Desktop or by URI in any client.

Cache is in-memory per session, with TTL per resource. Manual invalidation: wafle_resources_invalidate { uri_pattern }. Long-running tools auto-invalidate the affected store.

See docs/RESOURCES.md for full details and examples.

Prompts (5)

Server-defined parametric workflows for the most common BATTO operations. The client surfaces a picker; pick → fill args → conversation starts with a fully-rendered plan.

See docs/PROMPTS.md for argument schemas and example invocations.

Conversational examples

See examples/prompts/:

• 01-onboarding-tienda-nueva.md — onboarding a new client end to end.

• 02-pedido-enviar.md — single-shot logistics action.

• 03-segmentar-y-campania.md — segment + campaign.

• 04-conectar-meta-y-sync.md — connect Meta + catalog sync.

• 05-debug-orden-fallida.md — payment failure diagnosis.

The 5 prompts above are converted to server-defined MCP prompts in src/prompts/.

Scopes

Each tool declares a scope (e.g. orders:write, gateways:admin). At startup the server calls wafle_auth_me to retrieve the granted scopes; if wafle's /auth/me returns type=master we grant ALL_SCOPES. If it returns neither scopes nor a known type, the server runs in warn-mode — scope checks are skipped and a startup warning is logged.

The full matrix lives in src/auth/scopes.ts.

Architecture

See ARCHITECTURE.md. TL;DR: thin TypeScript wrapper over wafle REST, Fastify for HTTP, the official @modelcontextprotocol/sdk, Zod for validation, pino for logs (stderr only — required for stdio).

Deploy

docker compose up -d

or with the systemd unit at deploy/systemd/wafle-mcp.service. The repo includes Dockerfile (multistage, alpine runtime) and a sample nginx config for mcp.wafle.click.

Troubleshooting

• 401 waffle_unauthorized: WAFLE_API_KEY is missing or wrong. Get the master key from the waffle container at /root/.waffle-creds.txt.

• Claude Desktop says no tools: confirm the path in claude_desktop_config.json is absolute and dist/index.js exists. Run node dist/index.js --transport=stdio in a terminal — if it doesn't start, fix the env first.

• Stdout corruption: don't console.log anywhere. All logs must go via getLogger() (which writes to stderr).

• HTTP transport refuses traffic: set WAFLE_MCP_TOKENS and pass Authorization: Bearer <token>.

• Wafle says forbidden, invalid master key: some endpoints (e.g. /system/versions) check a different key. Verify with curl -H "X-Wafle-Admin-Key: $KEY" https://wafle.click/wp-json/waffle/v1/auth/me first.

Development

npm run dev          # tsx-watch, stdio
npm run dev:http     # tsx-watch, http
npm test             # vitest
npm run test:coverage
npm run lint
npm run typecheck

License

MIT — see LICENSE.