# MCP Cloud Deploy

> Model Context Protocol server for deploying projects to multiple cloud platforms via CLI.

Deploy your projects to **Vercel**, **Railway**, **Neon** (PostgreSQL), **MongoDB Atlas**, **Docker** (local), or run them as **local dev servers** — all through natural language commands from any MCP-compatible client (Kiro, Claude Desktop, etc.).

---

## Features

| Tool | Description |
|------|-------------|
| `deploy_to_vercel` | Deploy frontend/fullstack apps to Vercel |
| `deploy_to_railway` | Deploy apps to Railway with database plugins |
| `provision_neon_database` | Create serverless PostgreSQL on Neon |
| `provision_mongodb` | Create MongoDB Atlas clusters |
| `deploy_docker_local` | Run with Docker Compose (auto-generates configs) |
| `deploy_local` | Start native local dev server |
| `orchestrate_deploy` | Full-stack deploy combining multiple services |
| `check_deploy_prerequisites` | Verify which CLIs are installed |

---

## Quick Start

### 1. Install

```bash
# Clone or download this project
cd mcp-cloud-deploy

# Install dependencies
npm install

# Build
npm run build
```

### 2. Configure in your MCP client

**For Kiro / Claude Desktop** — add to your MCP config:

```json
{
  "mcpServers": {
    "cloud-deploy": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-cloud-deploy/dist/index.js"]
    }
  }
}
```

**For development (with auto-reload):**

```json
{
  "mcpServers": {
    "cloud-deploy": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/mcp-cloud-deploy/src/index.ts"]
    }
  }
}
```

### 3. Get your API tokens

| Service | Where to get token |
|---------|-------------------|
| Vercel | https://vercel.com/account/tokens |
| Railway | https://railway.app/account/tokens |
| Neon | https://console.neon.tech/app/settings/api-keys |
| MongoDB Atlas | Organization > Access Manager > API Keys |

### 4. Install CLIs (only the ones you need)

```bash
# Vercel
npm install -g vercel

# Railway
npm install -g @railway/cli

# Neon
npm install -g neonctl

# MongoDB Atlas
brew install mongodb-atlas-cli   # macOS
# Or: https://www.mongodb.com/docs/atlas/cli/stable/install-atlas-cli/

# Docker (for local deployments)
# https://docs.docker.com/get-docker/
```

---

## Usage Examples

### Deploy a Next.js app to Vercel

```
"Deploy my project at /home/user/my-app to Vercel. Here's my token: vercel_xxxxx"
```

The MCP will call `deploy_to_vercel` with:
- Auto-detect framework (Next.js)
- Deploy as preview (or production if specified)
- Return the deployment URL

### Full-stack: Vercel + Neon PostgreSQL

```
"Deploy my app to Vercel with a PostgreSQL database on Neon.
Vercel token: vercel_xxx
Neon API key: neon_xxx
Project name: my-saas-app"
```

The `orchestrate_deploy` tool will:
1. Create a Neon project + database
2. Get the connection string
3. Deploy to Vercel with `DATABASE_URL` injected

### Deploy everything on Railway

```
"Put my project on Railway with a PostgreSQL database.
Token: railway_xxx
Path: /home/user/my-api"
```

Railway handles app + database in one platform.

### Local development with Docker

```
"Start my project locally with Docker, include PostgreSQL and Redis"
```

This will:
1. Auto-generate a Dockerfile (based on project type)
2. Generate docker-compose.yml with app + PostgreSQL + Redis
3. Build and start all containers
4. Return URLs for each service

### Quick local dev server

```
"Run my project locally at /home/user/my-app on port 4000"
```

Auto-detects Node.js/Python/Go/Rust and runs the appropriate dev command.

---

## Tools Reference

### `deploy_to_vercel`

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectPath` | Yes | Absolute path to project |
| `token` | Yes | Vercel API token |
| `production` | No | Deploy to production (default: false) |
| `teamId` | No | Vercel Team ID |
| `projectName` | No | Custom project name |
| `envVars` | No | Environment variables object |
| `buildCommand` | No | Custom build command |
| `framework` | No | Framework preset |

### `deploy_to_railway`

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectPath` | Yes | Absolute path to project |
| `token` | Yes | Railway API token |
| `projectName` | No | Railway project name |
| `serviceName` | No | Service name |
| `withPostgres` | No | Add PostgreSQL (default: false) |
| `withRedis` | No | Add Redis (default: false) |
| `withMongoDB` | No | Add MongoDB (default: false) |
| `envVars` | No | Environment variables |
| `region` | No | Deploy region |

### `provision_neon_database`

| Parameter | Required | Description |
|-----------|----------|-------------|
| `apiKey` | Yes | Neon API key |
| `projectName` | Yes | Neon project name |
| `databaseName` | No | Database name (default: main) |
| `roleName` | No | Role name (default: app_user) |
| `region` | No | Region (default: aws-us-east-1) |
| `schemaFile` | No | Path to .sql schema file |
| `runMigrations` | No | Migration command to execute |
| `migrationsCwd` | No | Working directory for migrations |

### `provision_mongodb`

| Parameter | Required | Description |
|-----------|----------|-------------|
| `publicKey` | Yes | Atlas public API key |
| `privateKey` | Yes | Atlas private API key |
| `orgId` | Yes | Atlas Organization ID |
| `projectName` | Yes | Atlas project name |
| `clusterName` | Yes | Cluster name |
| `tier` | No | Tier: M0 (free), M2, M5, M10... |
| `provider` | No | AWS, GCP, AZURE (default: AWS) |
| `region` | No | Region (default: US_EAST_1) |
| `dbName` | No | Database name (default: main) |
| `dbUser` | No | Username (default: app_user) |
| `dbPassword` | No | Password (auto-generated) |
| `ipAllowAll` | No | Allow all IPs (default: false) |
| `ipWhitelist` | No | List of IPs to whitelist |

### `deploy_docker_local`

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectPath` | Yes | Absolute path to project |
| `serviceName` | No | Docker service name (default: app) |
| `port` | No | Port to expose (default: 3000) |
| `withPostgres` | No | Include PostgreSQL container |
| `withMongoDB` | No | Include MongoDB container |
| `withRedis` | No | Include Redis container |
| `envVars` | No | Additional env vars |
| `dockerfilePath` | No | Custom Dockerfile path |
| `generateDockerfile` | No | Auto-generate Dockerfile (default: true) |
| `generateCompose` | No | Generate docker-compose.yml (default: true) |
| `build` | No | Build before start (default: true) |
| `detach` | No | Run in background (default: true) |

### `deploy_local`

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectPath` | Yes | Absolute path to project |
| `port` | No | Port (default: 3000) |
| `installDeps` | No | Install dependencies (default: true) |
| `runMigrations` | No | Migration command |
| `seedCommand` | No | Seed command |
| `envVars` | No | Environment variables |
| `envFile` | No | Path to .env file |
| `startCommand` | No | Custom start command (auto-detected) |
| `background` | No | Run in background (default: true) |

### `orchestrate_deploy`

| Parameter | Required | Description |
|-----------|----------|-------------|
| `projectPath` | Yes | Absolute path to project |
| `target` | Yes | One of: `vercel+neon`, `vercel+mongodb`, `railway-fullstack`, `docker-local`, `local` |
| `tokens` | Yes | Object with tokens for each service |
| `projectName` | Yes | Project name |
| `production` | No | Production mode (default: false) |
| `envVars` | No | Additional env vars |
| `dbSchema` | No | Path to DB schema file |
| `port` | No | Port for local targets (default: 3000) |

### `check_deploy_prerequisites`

No parameters. Returns a table showing which CLIs are installed.

---

## Architecture

```
mcp-cloud-deploy/
├── src/
│   ├── index.ts              # Entry point - stdio transport
│   ├── server.ts             # MCP server with all tools registered
│   ├── tools/
│   │   ├── vercel.ts         # Vercel deployment logic
│   │   ├── railway.ts        # Railway deployment logic
│   │   ├── neon.ts           # Neon PostgreSQL provisioning
│   │   ├── mongodb.ts        # MongoDB Atlas provisioning
│   │   ├── docker-local.ts   # Docker Compose local deployment
│   │   ├── local.ts          # Native local dev server
│   │   └── orchestrator.ts   # Multi-service orchestration
│   ├── auth/
│   │   └── token-manager.ts  # In-memory token handling
│   └── utils/
│       ├── cli-runner.ts     # Safe CLI execution wrapper
│       └── logger.ts         # Stderr logger (MCP-safe)
├── dist/                     # Compiled JavaScript
├── package.json
└── tsconfig.json
```

---

## Security

- **Tokens are NEVER persisted to disk** — they exist only in memory during the session
- **Tokens are passed per-call** — each tool invocation includes the token it needs
- **stderr for logging** — all logs go to stderr to not interfere with MCP stdio
- **CLI execution is sandboxed** — commands run with timeouts and buffer limits

---

## Supported Project Types (Auto-detection)

The Docker and local tools automatically detect your project type:

| Type | Detection | Dev Command | Docker Base |
|------|-----------|-------------|-------------|
| Next.js | `next` in dependencies | `npx next dev` | Multi-stage Node 20 |
| Nuxt | `nuxt` in dependencies | `npx nuxt dev` | Node 20 |
| SvelteKit | `@sveltejs/kit` in deps | `npx vite dev` | Node 20 |
| Vite | `vite` in deps | `npx vite` | Node 20 |
| Express/Fastify | `express`/`fastify` in deps | `npm run dev` | Node 20 |
| Python/FastAPI | `requirements.txt` | `uvicorn main:app` | Python 3.12 |
| Django | `manage.py` exists | `python manage.py runserver` | Python 3.12 |
| Go | `go.mod` exists | `go run .` | Go 1.22 multi-stage |
| Rust | `Cargo.toml` exists | `cargo run` | Rust multi-stage |

---

## Development

```bash
# Run in development mode (with tsx)
npm run dev

# Build for production
npm run build

# Run built version
npm start

# Clean build output
npm run clean
```

---

## License

MIT