98 lines
4.0 KiB
Markdown
98 lines
4.0 KiB
Markdown
# BuildMyMCPServer
|
||
|
||
> Describe your tool. We host the server. AI uses it.
|
||
|
||
Prompt-to-production MCP servers with OAuth 2.1 and Streamable HTTP. Production-grade
|
||
infrastructure for hosting Model Context Protocol servers your AI clients (Claude
|
||
Desktop, Cursor, ChatGPT) can install with a copy-paste snippet.
|
||
|
||
## Quick start
|
||
|
||
```bash
|
||
# 1. Install
|
||
pnpm install
|
||
|
||
# 2. Copy env. Defaults work for local dev. Set ANTHROPIC_API_KEY if you want real generation.
|
||
cp .env.example .env
|
||
|
||
# 3. Boot everything
|
||
pnpm dev
|
||
```
|
||
|
||
`pnpm dev` will:
|
||
1. Load `.env`.
|
||
2. `docker compose up -d --wait` postgres + redis.
|
||
3. Push the Drizzle schema (`drizzle-kit push --force`).
|
||
4. Start the full stack in parallel: web (Next.js, :3000), api (Fastify, :4000),
|
||
generator (BullMQ worker).
|
||
|
||
Then open:
|
||
|
||
- Dashboard: <http://localhost:3000>
|
||
- API: <http://localhost:4000/health>
|
||
|
||
Click **Start building**, enter your email, copy the magic-link URL printed to the
|
||
**api** terminal output, paste it in your browser. You land on `/dashboard`. Click
|
||
**New server**, paste a prompt, and watch the build stream live over WebSocket.
|
||
|
||
If `ANTHROPIC_API_KEY` is unset, the generator returns a deterministic mock spec
|
||
(an `echo` and a `now` tool) so the full end-to-end flow stays demoable.
|
||
|
||
If Docker is unavailable, the build will fail at the deploy step with a clear error.
|
||
Otherwise: a fresh container is launched on a host port from
|
||
`RUNNER_PORT_RANGE_START…RUNNER_PORT_RANGE_END`, the server is marked `live`, and the
|
||
dashboard renders install snippets for Claude Desktop, Cursor and ChatGPT.
|
||
|
||
## Architecture
|
||
|
||
See `BuildMyMCPServer_MASTER_PROMPT.md` for the full specification and `CHOICES.md`
|
||
for decisions made during this Sprints 1–3 build.
|
||
|
||
```
|
||
apps/
|
||
web/ Next.js 15 dashboard + marketing landing
|
||
api/ Fastify control plane (auth, server CRUD, OAuth 2.1 AS, JWKS, WS stream)
|
||
generator/ BullMQ worker — Claude → spec → render → docker build → local deploy
|
||
runner-template/ Hosted MCP server template (Streamable HTTP + OAuth 2.1 RS)
|
||
packages/
|
||
db/ Drizzle schema + client
|
||
auth/ Magic-link + session
|
||
types/ Shared Zod contracts
|
||
```
|
||
|
||
## Scripts
|
||
|
||
| Command | Effect |
|
||
| ------------------ | ------------------------------------------------------------- |
|
||
| `pnpm dev` | Bootstrap + parallel dev for web, api, generator |
|
||
| `pnpm dev:no-docker` | Skip docker-compose (assumes postgres + redis already up) |
|
||
| `pnpm build` | Turbo build all apps |
|
||
| `pnpm typecheck` | Turbo typecheck all apps |
|
||
| `pnpm lint` | Biome check |
|
||
| `pnpm lint:fix` | Biome check --write |
|
||
| `pnpm db:push` | Push schema to postgres (drizzle-kit) |
|
||
| `pnpm db:generate` | Generate SQL migration files |
|
||
| `pnpm db:migrate` | Apply pending migrations |
|
||
| `pnpm stop` | docker compose down |
|
||
|
||
## Acceptance check
|
||
|
||
After `pnpm dev` is up:
|
||
|
||
- [x] `http://localhost:3000` renders the landing page.
|
||
- [x] `http://localhost:4000/health` returns `{ "ok": true }`.
|
||
- [x] Sign in via magic link (URL printed in the api terminal).
|
||
- [x] New Server → paste prompt → live WebSocket stream `queued → generating → building → deploying → live`.
|
||
- [x] If Docker is running, a container is launched and `http://localhost:<port>/mcp`
|
||
responds **401 + WWW-Authenticate** without a token, **200** with a valid token
|
||
issued by `/oauth/token`.
|
||
- [x] Install snippets render with copy buttons for Claude Desktop, Cursor, ChatGPT.
|
||
|
||
## Repo conventions
|
||
|
||
- TypeScript strict, zero `any` (Biome lints `noExplicitAny` as error).
|
||
- ESM-only, Node 20 LTS.
|
||
- Conventional commits.
|
||
- Tailwind v4 (`@import 'tailwindcss'`).
|
||
- Geist + Geist Mono.
|