# Production MCP Starter

> Ship a paid MCP server in an afternoon.

A hexagonal TypeScript starter for production MCP servers: Hono + Drizzle + Postgres + Redis + Stripe + Notion. OAuth-secured sessions, AES-256-GCM token storage at rest, dual subscription + metered (MPP) billing on one port, per-tool rate limiting, idempotency cache, structured logging, and SSE streaming. Six documented deployment targets, v1.0.0.

## Quick start

```bash
cp .env.example .env                            # then open .env in your editor
openssl rand -base64 32                         # paste into ENCRYPTION_KEY in .env
docker compose up -d --wait                     # postgres + redis + migrate + app, healthcheck-gated
curl -sS http://localhost:3000/health | jq .
# expect: {"status":"ok","services":{"database":"ok","redis":"ok"}}
```

Boot fails fast if `ENCRYPTION_KEY` is unset (Zod min-length check). Stripe / Notion placeholders are accepted at boot and only fail when a billing-gated or OAuth-protected tool fires — see [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) for the full validation matrix. The six target runbooks (Docker Compose, Railway, Render, Fly.io, Cloudflare Workers + Neon, generic VPS) are in [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md).

## What's inside

`src/transport/` is the Hono HTTP layer (routes, middleware, SSE writer); `src/application/` is orchestration (tool dispatcher, OAuth flow, token refresh, billing orchestrator, the 8-stage tool dispatcher pipeline — 11 stages including Hono middleware; see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the diagram); `src/domain/` is types, branded value objects, ports, and error classes; `src/infrastructure/` is the adapters (Postgres + Redis driver factories, AES-256-GCM token cipher, Stripe gateways, Notion clients, pino logger); `src/tools/` is where you add MCP tool definitions; `src/schema/` is your Drizzle tables (`users`, `oauth_tokens`, `subscriptions`, `usage`, `jobs`).

## First custom tool in 5 minutes

```bash
npm run new-tool myorg.hello
# edit src/tools/myorg-hello/myorg-hello.tool.ts — fill in input/output Zod schemas + handler
# register one line in src/composition-root.ts:
#   toolRegistry.register(myorgHelloTool as AnyToolDefinition);
npm run dev
curl -sS -X POST http://localhost:3000/mcp \
  -H 'Authorization: Bearer <session-token>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"myorg.hello","arguments":{}}}'
```

The scaffold emits a typed `ToolDefinition` with `AuthNone` + `BillingNone` defaults — flip those to `AuthRequired` or `BillingSubscription` / `BillingMpp` and the dispatcher pipeline picks up the new requirements at call time, no framework edits. Full extension guide — sync tool, streaming tool, table, OAuth provider — in `docs/CUSTOMIZATION.md`.

## Architecture in 100 words

Hexagonal. The domain layer defines ports (interfaces) and error classes and knows about nothing else. The application layer is orchestration logic (tool dispatcher, OAuth flow, billing) that depends only on domain. The infrastructure layer holds adapters that implement the ports (Postgres, Redis, Stripe, Notion, pino). The transport layer is the Hono app that wires HTTP to the dispatcher. The composition root in `src/composition-root.ts` is the only place adapters meet ports. A single `BillingGateway` port dispatches to both Stripe Subscriptions and Stripe MPP based on each tool's `billing.kind`. Full picture in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).

## Production deploy

Six runbooks ship in [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md): Docker Compose self-host (default), Railway, Render, Fly.io, Cloudflare Workers + Neon (serverless edge), and generic VPS behind Caddy. Each runbook covers Postgres + Redis provisioning, Stripe webhook URL, OAuth callback URL, and a smoke-test curl. Env-var rules are documented once in [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) and referenced from every runbook.

## What's NOT in v1

Honest list of what was intentionally deferred:

- **No Stripe Meters / usage-based billing** — `BillingGateway` ships with Subscription and MPP (Metered-Pricing-Per-call) adapters only.
- **No nested-block Notion rendering** — `blocksToMarkdown` emits flat bullets; rich block trees are a v1.1 polish item.
- **No queue/worker for async-poll tools** — the pattern is documented in `docs/PATTERNS_ASYNC_JOBS.md`; the queue itself (BullMQ, SQS, etc.) is the buyer's choice.
- **`ENCRYPTION_KEY` rotation is operationally manual** — re-encrypt-everything script lives in `docs/MAINTENANCE.md` (ships with the rest of the doc suite). Two-key window support is in the v1.1 backlog.
- **No mass logout or timeout distinction** — `SessionRepository.revokeAllForUser` (security events) and a dedicated `TimeoutError` (504 vs 500 in dashboards) are both v1.1; today, individual tokens revoke fine and timeouts surface as `InternalError`.

Full v1.1 roadmap with implementation sketches and ship triggers: [`V1_1_BACKLOG.md`](V1_1_BACKLOG.md).

## Support

For v1.0.0 ship day: Gumroad seller messages on the kit's listing + the email address in `LICENSE`. See `docs/TROUBLESHOOTING.md` and `SECURITY.md` for detail. Pre-launch, the maintainer should replace the `support@production-mcp-starter.dev` placeholder in `LICENSE`, `SECURITY.md`, and `docs/TROUBLESHOOTING.md` with the real channel — see `LAUNCH_CHECKLIST.md`.

## License

Commercial — single-seat. LICENSE ships in Phase 14 of the build.