stackbilt-mcp-gateway

# Stackbilt MCP Gateway

<p align="center">
  <img src="docs/banner.png" alt="Stackbilt MCP Gateway — img-forge + Stackbilder" width="480" />
</p>

<p align="center">
  <em>Two products. One MCP connection. Image generated by img-forge (ultra tier).</em>
</p>

[![Stackbilt MCP server](https://glama.ai/mcp/servers/Stackbilt-dev/stackbilt-mcp-gateway/badges/card.svg)](https://glama.ai/mcp/servers/Stackbilt-dev/stackbilt-mcp-gateway)

> **MCP Registry**: [`dev.stackbilt.mcp/gateway`](https://registry.modelcontextprotocol.io/v0.1/servers?search=stackbilt) — published on the [Official MCP Registry](https://modelcontextprotocol.io/registry/quickstart)

OAuth-authenticated [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) gateway for Stackbilt platform services. Built as a Cloudflare Worker using `@cloudflare/workers-oauth-provider`.

## What It Does

A single MCP endpoint (`mcp.stackbilt.dev/mcp`) that routes tool calls to multiple backend product workers:

| Backend | Tools | Description |
|---------|-------|-------------|
| **TarotScript** | `scaffold_create`, `scaffold_classify`, `scaffold_publish`, `scaffold_deploy`, `scaffold_import`, `scaffold_status` | Deterministic project scaffolding, n8n workflow import, GitHub publishing, CF deployment |
| **img-forge** | `image_generate`, `image_list_models`, `image_check_job` | AI image generation (5 quality tiers) |
| **Stackbilder** (TarotScript backend) | `flow_create`, `flow_status`, `flow_summary`, `flow_quality`, `flow_governance`, `flow_advance`, `flow_recover` | **DEPRECATED** — Architecture flow orchestration (migrating to `scaffold_*`) |

### The Scaffold Pipeline (E2E)

```
You: "Build a restaurant menu API with D1 storage"
  ↓
scaffold_create → structured facts + 9 deployable project files
  ↓
scaffold_publish → GitHub repo with atomic initial commit
  ↓
git clone → npm install → npx wrangler deploy → live Worker
```

Zero LLM calls for file generation. ~20ms for structure, ~2s with oracle prose. 21x faster than flow_create.

## Key Features

- **OAuth 2.1 with PKCE** — GitHub SSO, Google SSO, and email/password authentication
- **Backend adapter pattern** — tool catalogs aggregated from multiple service bindings, namespaced to avoid collisions
- **Per-tier rate limiting** — fixed-window per-tenant limits via `RATELIMIT_KV` (free=20/min, hobby=60, pro=300, enterprise=1000); 429 with `Retry-After` and `X-RateLimit-*` headers
- **Cost attribution & quota** — every tool call carries a credit cost; quota is reserved via `edge-auth` before dispatch and committed/refunded on outcome; `image_generate` cost scales with the effective quality tier (1×/1×/3×/5×/8× for draft/standard/premium/ultra/ultra_plus); when `model` is set it takes billing precedence over `quality_tier`
- **Scope + tier enforcement** — `tools/list` is filtered by token scopes; `tools/call` requires the `generate` scope for mutating tools; expensive `image_generate` quality tiers (`premium` and above) are gated to Pro+ plans; specifying `model` directly enforces the same gate via model→tier mapping
- **Security Constitution compliance** — every tool declares a risk level (`READ_ONLY`, `LOCAL_MUTATION`, `EXTERNAL_MUTATION`); structured audit logging with secret redaction; HMAC-signed identity tokens
- **Coming-soon gate** — `PUBLIC_SIGNUPS_ENABLED` flag to control public access
- **MCP JSON-RPC over HTTP** — supports both streaming (SSE) and request/response transport

## Quick Start

### Prerequisites

- Node.js 18+
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) (`npm i -g wrangler`)
- Cloudflare account with the required service bindings configured

### Install & Run

```bash
npm install
npm run dev
```

### Run Tests

```bash
npm test
```

### Deploy

```bash
npm run deploy
```

Deploys to the `mcp.stackbilt.dev` custom domain via Cloudflare Workers.

## Environment Variables & Secrets

| Name | Type | Description |
|------|------|-------------|
| `SERVICE_BINDING_SECRET` | Secret | HMAC-SHA256 key for signing identity tokens |
| `API_BASE_URL` | Variable | Base URL for OAuth redirects (e.g. `https://mcp.stackbilt.dev`) |
| `AUTH_SERVICE` | Service Binding | RPC to `edge-auth` worker (`AuthEntrypoint`) |
| `TAROTSCRIPT` | Service Binding | Route to scaffold + classify backend |
| `IMG_FORGE` | Service Binding | Route to image generation backend |
| `OAUTH_KV` | KV Namespace | Stores social OAuth state (5-min TTL entries) and MCP sessions |
| `RATELIMIT_KV` | KV Namespace | Per-tenant fixed-window rate-limit counters (60s TTL) |
| `PLATFORM_EVENTS_QUEUE` | Queue | Audit event pipeline (`stackbilt-user-events`) |
| `MCP_REGISTRY_AUTH` | Variable | MCP Registry domain verification string (served at `/.well-known/mcp-registry-auth`) |

Set secrets with:
```bash
wrangler secret put SERVICE_BINDING_SECRET
```

## Project Structure

```
src/
  index.ts           # Entry point — OAuthProvider setup, CORS, health check, MCP Registry well-known
  gateway.ts         # MCP JSON-RPC transport, session management, tool dispatch
  oauth-handler.ts   # OAuth 2.1 flows: login, signup, social SSO, consent
  tool-registry.ts   # Tool catalog aggregation, namespacing, schema validation
  audit.ts           # Structured audit logging, secret redaction, trace IDs
  auth.ts            # Bearer token extraction & validation
  route-table.ts     # Static routing table, tool-to-backend mapping, risk levels
  types.ts           # Type definitions, RiskLevel enum, interfaces

test/
  audit.test.ts
  auth.test.ts
  gateway.test.ts
  oauth-handler.test.ts
  route-table.test.ts
  tool-registry.test.ts

docs/
  user-guide.md      # End-user guide: account creation, client setup, tool usage
  api-reference.md   # MCP tool surface, authentication flow, tool routing
  architecture.md    # System design, security model, request flow
```

## Test Suite

122 tests across 6 test files covering:

- **OAuth handler** — identity token signing/verification, login, signup, social OAuth flows, consent, HTML escaping
- **Gateway** — session lifecycle, `initialize`, `tools/list`, `tools/call`, SSE streaming, error handling
- **Audit** — secret redaction patterns (API keys, bearer tokens, hex hashes, password fields), trace IDs, queue emission
- **Auth** — bearer token extraction, API key vs JWT validation, error mapping
- **Tool registry** — catalog building, name mapping, schema validation, risk level enforcement
- **Route table** — route resolution, risk level lookup

```bash
npm test          # single run
npm run test:watch # watch mode
```

## Documentation

- [User Guide](docs/user-guide.md) — account creation, client setup, tool usage
- [API Reference](docs/api-reference.md) — MCP tools, authentication, tool routing
- [Architecture](docs/architecture.md) — system design, security model, data flow

## License

MIT — see [LICENSE](LICENSE)