# SQL MCP Gateway (NestJS)

NestJS-based MCP server for MySQL with session-level database selection and SQL safety controls.

## Features

- MCP tools:
  - `list_databases`
  - `connect_mysql_user`
  - `select_database`
  - `execute_sql`
- Two transports:
  - HTTP (`/mcp`) via streamable HTTP sessions
  - stdio (`--stdio`) for command-based MCP auto-start
- SQL controls:
  - `SQL_MODE`: `SAFE` | `WRITE` | `FULL`
  - mode categories:
    - `SAFE` => `DQL`
    - `WRITE` => `DQL`, `DML`
    - `FULL` => `DQL`, `DML`, `DDL`, `TCL`, `DCL`
  - hard block on destructive statements like `DROP`, `TRUNCATE`, `ALTER DATABASE/SCHEMA`, `RENAME TABLE`

## Project Structure

```text
src/
  main.ts
  app.module.ts
  config/
  sql/
  mcp/
scripts/
  run-stdio.sh
```

## Setup

```bash
npm install
cp .env.example .env
```

`.env.example`:

```env
MCP_HOST=0.0.0.0
MCP_PORT=8787
MCP_PATH=/mcp
MCP_SERVER_NAME=sql-mcp
MCP_SERVER_VERSION=2.0.0
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
SQL_MODE=SAFE
```

## Run

### HTTP mode (manual)

```bash
npm start
```

Endpoint: `http://localhost:8787/mcp`

### stdio mode (auto-start via command MCP)

Build once:

```bash
npm run build
```

Then run:

```bash
scripts/run-stdio.sh
```

Or:

```bash
node build/main.js --stdio
```

`MCP_TRANSPORT=stdio` also enables stdio mode.

## Cursor Config (`~/.cursor/mcp.json`)

### Recommended: command mode (auto-start)

```json
{
  "mcpServers": {
    "sql-mcp": {
      "command": "/ABSOLUTE/PATH/TO/sql-mcp/scripts/run-stdio.sh",
      "env": {
        "MCP_SQL_USER": "your_mysql_user",
        "MCP_SQL_PASSWORD": "your_mysql_password"
      }
    }
  }
}
```

Notes:
- Replace `/ABSOLUTE/PATH/TO/sql-mcp` with your actual repo path.
- `MCP_SQL_USER` / `MCP_SQL_PASSWORD` are optional. If omitted, use `connect_mysql_user` from chat.

### Alternative: URL mode (manual server)

```json
{
  "mcpServers": {
    "sql-mcp": {
      "url": "http://localhost:8787/mcp",
      "headers": {
        "x-sql-user": "your_mysql_user",
        "x-sql-password": "your_mysql_password"
      }
    }
  }
}
```

Use this only when the HTTP server is running.

## Tool Workflow

### If credentials are preconfigured (command `env` or URL `headers`)

1. `list_databases`
2. `select_database`
3. `execute_sql`

### If credentials are not preconfigured

1. `connect_mysql_user`
2. `select_database`
3. `execute_sql`

## Security

- Keep credentials only in user-level `~/.cursor/mcp.json`.
- Do not commit project-level `.cursor/mcp.json`.