BackGen MCP Server

BackGen

🤖 AI-Ready

BackGen ships a built-in MCP (Model Context Protocol) server that AI assistants (Claude, Cursor, GitHub Copilot, VS Code) can use to scaffold projects on your behalf.

{
  "mcpServers": {
    "backgen": {
      "command": "npx",
      "args": ["-y", "@ibrahimkhaled19/backgen", "backgen-mcp"]
    }
  }
}

Available MCP tools:

Then just ask: "Scaffold a SaaS backend with Prisma, JWT auth, and Stripe payments"

---

BackGen is a CLI tool that generates complete Express.js backend projects on Prisma, Drizzle, or Mongoose — with authentication, multi-tenant infrastructure, production hardening, Docker, and testing — all working out of the box.

npx @ibrahimkhaled19/backgen init my-api --orm drizzle
cd my-api
npm run dev

Swagger docs at http://localhost:3000/docs in under 60 seconds. Pick your ORM, keep everything else.

---

Features

• Express + TypeScript — strict mode, ESLint 9 (flat config), Vitest
• Multi-ORM — Prisma, Drizzle, or Mongoose. Pick at init time, switch later via the manifest
• SaaS-ready — saas-core preset ships Organizations, Memberships, Invitations, RBAC, tenant-scoped queries
• Hardened by default — helmet, strict CORS, request ID, request timeout, xss + mongo-sanitize, graceful shutdown, /health + /ready, error envelope
• Plugin System — JWT, Clerk, Stripe, S3, ratelimit via backgen add
• Resource Generator — CRUD modules with relations, validation, Swagger
• Domain Presets — saas-core, healthcare, SaaS, ecommerce, CRM, LMS — full domain in one command
• Seed & Factory Generators — development data and test factories
• Docker — multi-stage Dockerfile + docker-compose
• Swagger/OpenAPI — auto-generated API documentation
• Manifest — .backgenrc.json tracks ORM, plugins, versions, and ownership for upgrade/rollback

---

Quick Start

# Install globally
npm install -g @ibrahimkhaled19/backgen

# Create a project (pick your ORM)
backgen init my-api --orm prisma
backgen init my-api --orm drizzle
backgen init my-api --orm mongoose

# Create a full multi-tenant domain
backgen init my-saas --preset saas-core --defaults

# Add authentication
backgen add jwt
backgen add clerk

# Add production hardening
backgen add ratelimit

# Generate a resource
backgen generate resource Product name:string price:number stock:number

# Start developing
cd my-api
npm run dev

---

Commands

backgen init [name]

Generate a new backend project.

backgen init my-api                              # interactive ORM picker
backgen init my-api --orm prisma                 # explicit ORM
backgen init my-api --orm drizzle --defaults     # Drizzle, non-interactive
backgen init my-api --orm mongoose --skip-install
backgen init my-api --preset saas-core --defaults   # full multi-tenant domain
backgen init my-api --preset healthcare            # healthcare domain

Output:

• Express app with TypeScript strict mode
• ORM-specific data layer (Prisma / Drizzle / Mongoose)
• Environment validation (Zod)
• Swagger/OpenAPI documentation
• Docker + docker-compose
• Hardened by default: helmet, CORS, request ID, timeout, xss + mongo-sanitize, graceful shutdown, health checks
• ESLint 9 + Vitest
• .backgenrc.json manifest (records project.orm + plugins)

No auth by default — choose your auth provider with backgen add.

---

backgen add [plugin]

Install a plugin. Interactive multi-select if no argument.

backgen add                 # interactive multi-select
backgen add jwt             # JWT authentication
backgen add clerk           # Clerk auth-as-a-service
backgen add stripe          # Stripe payments
backgen add s3              # AWS S3 storage
backgen add ratelimit       # Per-IP / per-user rate limiting
backgen add devops          # Install all devops plugins at once

Available Plugins:

Conflict detection: jwt and clerk cannot be installed together.

---

Domain Presets

Generate a complete domain in one command. Each preset creates multiple resources with relations, auto-installs JWT auth, and wires everything together.

backgen init my-api --preset healthcare
backgen init my-api --preset saas --defaults

healthcare

Patient, Doctor, Appointment, Prescription, MedicalRecord — appointments between patients and doctors, prescriptions linked to patients, medical records per patient.

saas

Organization, Team, Membership, Subscription, Invoice — organizations with teams and memberships, subscriptions with invoices.

ecommerce

Category, Product, Cart, Order, OrderItem, Payment — products in categories, carts with items, orders with line items and payments.

crm

Contact, Company, Deal, Activity — companies with contacts, deals tracked through pipeline, activity logging.

lms

Course, Lesson, Enrollment, Progress, Certificate — courses with lessons, student enrollments, progress tracking, certificates.

---

backgen remove [plugin]

Remove a plugin. Interactive multi-select if no argument. Supports devops shorthand to remove all devops plugins.

backgen remove              # interactive multi-select
backgen remove stripe       # remove specific plugin
backgen remove devops       # remove all devops plugins

---

backgen generate resource <name> [fields...]

Generate a CRUD resource module.

# Interactive
backgen generate resource Product

# Non-interactive
backgen generate resource Product name:string price:number stock:number

# With relations
backgen generate resource Appointment date:datetime status:string \
  --relations "doctor:Doctor,patient:Patient"

# With --fields flag
backgen generate resource Product --fields "name:string,price:number"

Generated files:

src/modules/product/
  product.controller.ts    # CRUD endpoints
  product.service.ts       # business logic
  product.repository.ts    # database operations
  product.validation.ts    # Zod schemas
  product.types.ts         # TypeScript interfaces
  product.routes.ts        # route definitions + Swagger
  product.test.ts          # test placeholder

Field types: string, number, boolean, date, datetime

Relations: doctor:Doctor (belongsTo), patients:Patient (hasMany)

---

backgen generate seed <resource>

Generate seed data for development.

backgen generate seed Product --count 10

Output: prisma/seeds/product.ts (Prisma), db/seeds/product.ts (Drizzle), or seeds/product.ts (Mongoose)

---

backgen generate factory <resource>

Generate a test factory.

backgen generate factory Product

Output: src/factories/product.factory.ts

Usage:

import { createProduct } from "./factories/product.factory.js";
const product = await createProduct({ name: "Widget" });

---

backgen generate migration [name]

Generate a database migration (ORM-aware).

backgen generate migration add-product-table   # runs prisma migrate dev / drizzle-kit generate / no-op for Mongoose

---

backgen sync

Reconcile .backgenrc.json with the project. Regenerates missing plugin files.

backgen sync

---

backgen health

Show system health information.

backgen health

Displays:

• Node.js version
• Platform and architecture
• BackGen version

---

backgen doctor

Check project health with ownership integrity diagnostics.

backgen doctor              # health check + ownership audit
backgen doctor --fix        # auto-fix missing manifest entries

Checks:

• Node.js version (>= 18)
• npm availability
• .env file
• DATABASE_URL
• Prisma schema / Drizzle config / Mongoose connection
• Dependencies
• Package manager version
• File integrity — all manifest-tracked files exist on disk
• Ownership integrity — framework vs user file classification

---

backgen upgrade

Upgrade a generated project to the latest template version. Creates a backup, then applies pending migrations sequentially.

backgen upgrade              # show pending migrations, prompt before applying
backgen upgrade --yes        # skip confirmation, apply all pending

What happens:

• Reads current generatedVersion from .backgenrc.json
• Loads pending core + plugin migrations
• Creates backup in .backgen/backups/pre-<version>/
• Applies migrations in order (semver-sorted)
• Updates ownership register + generatedVersion in manifest

---

backgen rollback

Restore a project to its pre-upgrade state from the most recent backup.

backgen rollback              # show latest backup, prompt before restoring
backgen rollback --yes        # skip confirmation

What happens:

• Lists available backups in .backgen/backups/
• Restores the most recent backup (all tracked files + manifest)
• Project returns to exact pre-upgrade state

---

Plugin System

Every plugin implements the BackGenPlugin interface:

interface BackGenPlugin {
  name: string;
  category: string;
  description: string;
  version: string;

  dependencies?: string[];
  devDependencies?: string[];
  requires?: string[];
  conflicts?: string[];

  env?: Record<string, string>;
  templates: string[];
  migrations?: PluginMigration[];   // versioned plugin migration scripts

  install(ctx: InstallContext): Promise<void>;
  uninstall?(ctx: InstallContext): Promise<void>;
}

Plugins can:

• Install npm dependencies
• Inject environment variables
• Register routes in app.ts
• Replace existing middleware
• Add database models (Prisma / Drizzle / Mongoose)
• Carry versioned migrations for own upgrades

---

Project Manifest

.backgenrc.json tracks plugins, versions, generated version, and file ownership:

{
  "version": "1.0.0",
  "generatedVersion": "1.9.0",
  "project": {
    "name": "my-api",
    "framework": "express",
    "database": "postgresql",
    "orm": "prisma",
    "preset": "saas-core"
  },
  "plugins": {
    "jwt": {
      "version": "1.0.0",
      "installedAt": "2026-06-01",
      "source": "core"
    }
  },
  "files": {
    "src/app.ts": { "owner": "shared", "version": "1.9.0" },
    "src/server.ts": { "owner": "framework", "version": "1.9.0" },
    "src/config/env.ts": { "owner": "framework-editable", "version": "1.9.0" },
    "prisma/schema.prisma": { "owner": "user" },
    "src/modules/user/user.service.ts": { "owner": "user" },
    "docker-compose.yml": { "owner": "shared", "version": "1.9.0" }
  }
}

Ownership levels:

---

Generated Project Structure

my-api/
├── prisma/                       # Prisma ORM only
│   ├── schema.prisma
│   └── seeds/
├── src/db/                       # Drizzle ORM only
│   ├── schema/
│   │   └── index.ts
│   └── seeds/
├── src/models/                   # Mongoose ORM only
│   └── seeds/
├── src/
│   ├── app.ts                    # Express app setup
│   ├── server.ts                 # Server entry point
│   ├── config/
│   │   ├── env.ts                # Zod env validation
│   │   ├── database.ts           # Prisma client / Drizzle db / Mongoose connection
│   │   └── swagger.ts            # Swagger config
│   ├── middleware/
│   │   ├── auth.ts               # JWT/Clerk auth
│   │   ├── validate.ts           # Zod validation
│   │   ├── error.ts              # Global error handler
│   │   └── logger.ts             # Request logging
│   ├── modules/
│   │   ├── auth/                 # Auth module (if jwt installed)
│   │   ├── stripe/               # Stripe module (if installed)
│   │   └── <resource>/           # Generated resources
│   ├── services/
│   │   └── logger.service.ts     # Winston logger
│   ├── utils/
│   │   ├── api-error.ts          # Error class
│   │   ├── async-handler.ts      # Async wrapper
│   │   └── response.ts           # Response formatters
│   └── factories/                # Test factories
├── .env.example
├── .backgenrc.json               # Manifest
├── Dockerfile
├── docker-compose.yml
├── package.json
└── tsconfig.json

---

Development

# Clone
git clone https://github.com/your-username/backgen.git
cd backgen

# Install
npm install

# Build
npm run build

# Test
npm run test

# Lint
npm run lint

Test Suite

277+ tests covering:

• CLI help and version
• Init: project structure, configs, manifest (all 3 ORMs)
• Init with domain presets: preset-specific resources and relations
• Init with saas-core preset: multi-tenant organizations, memberships, RBAC
• Add plugin: files, routes, env vars, manifest (V4.6 plugin suite)
• Generate resource: module files, ORM model, routes, validation
• Generate with relations: foreign keys, ORM includes
• Seed and factory generators (all 3 ORMs)
• Drizzle: schema generation, client setup, codegen
• Mongoose: model generation, schema definition, connection
• Remove plugin: file + dependency + manifest cleanup
• Sync: file restoration
• Doctor: health checks, ownership integrity
• Upgrade: migration engine, pending detection, backup creation
• Rollback: backup listing, file restoration, manifest recovery
• Error handling: unknown plugin, non-empty directory

---

Tech Stack

Generated Projects

---

BackGen vs Alternatives

Key differentiators:

• ◈ ORM-switchable — change Prisma ↔ Drizzle ↔ Mongoose via manifest, not rewrite
• ◈ Domain presets — healthcare, SaaS, ecommerce, CRM, LMS in one command
• ◈ Upgrade engine — versioned migrations + backup + rollback for generated projects
• ◈ Multi-ORM from day one — not locked into one data layer

---

Roadmap

See docs/ROADMAP.md for details.

---

License

MIT