Development Setup¶

Prerequisites¶

Tool	Minimum Version	Check Command
Node.js	20.0.0	`node --version`
pnpm	9.0.0	`pnpm --version`
Docker	24.0.0	`docker --version`
Docker Compose	2.20.0	`docker compose version`

First-Time Setup¶

# Clone the repo
git clone https://github.com/chitrank2050/mcp-devkit.git
cd mcp-devkit

# Install dependencies
pnpm install

# Copy environment template
cp .env.example .env

# Start infrastructure (Postgres, Redis)
pnpm docker:up

# Wait for containers to be healthy (~15 seconds)
docker compose ps

# Run database migrations and seed (inside apps/api)
cd apps/api
npx prisma generate
npx prisma migrate dev --name init
npx prisma db seed
cd ../..

# Start the monorepo apps
pnpm dev

Verify Everything Works¶

# Health check (should return status: ok)
curl http://localhost:3000/health | jq

# Swagger docs (open in browser)
open http://localhost:3000/api/docs

Daily Workflow¶

# Start your day
pnpm docker:up          # Start containers (if stopped)
pnpm dev                # Start apps with hot reload

# After changing schema.prisma (in apps/api)
cd apps/api
npx prisma migrate dev --name describe-your-change
npx prisma generate     # Regenerate typed client

Nuclear Reset¶

If you want to drop all data and start fresh:

pnpm docker:down        # Removes containers AND volumes
pnpm docker:up
cd apps/api
npx prisma migrate dev
npx prisma db seed

Common Issues¶

Port 5432 already in use¶

You have a local Postgres installation competing with Docker. Stop it:

# Homebrew
brew services stop postgresql@17

# Postgres.app
# Quit from menu bar

Port 6379 already in use¶

You have a local Redis installation competing with Docker. Stop it:

# Homebrew
brew services stop redis

Environment Variables¶

All environment variables are documented in .env.example.

Conventions¶

Monorepo Structure¶

We use pnpm workspaces.

apps/api: NestJS backend
apps/web: React Vite frontend (coming soon)
apps/worker: BullMQ worker (coming soon)
packages/shared: Shared types, constants, and utilities

Import Aliases (in backend)¶

Alias	Resolves To
`@common/*`	`apps/api/src/common/*`
`@config/*`	`apps/api/src/config/*`
`@modules/*`	`apps/api/src/modules/*`