============================================================

DataBridge AI — README

============================================================

🎯 What is this?

DataBridge AI transforms unsafe, complex database connections into a secure, auditable, plug-and-play AI plugin — so any AI assistant (Cursor, Claude Desktop, etc.) can query your business data safely through the MCP (Model Context Protocol) standard.

⚡ Quick Start

Prerequisites

• Node.js 20+
• Docker & Docker Compose
• PostgreSQL 16+ (for metadata storage)

1. Clone & Install

cd databridge-ai
npm install

2. Configure Environment

cp .env.example .env
# Edit .env with your DB_PASSWORD and JWT_SECRET

3. Start Infrastructure

npm run docker:up

4. Start API Gateway

npm run dev
# → http://localhost:3001

5. Connect a Database (via API)

curl -X POST http://localhost:3001/api/connections \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "label": "Production PostgreSQL",
    "dbType": "postgres",
    "host": "db.example.com",
    "port": 5432,
    "database": "mystore",
    "username": "readonly_user",
    "password": "secret"
  }'

6. Query with AI

curl -X POST http://localhost:3001/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "<conn-id>",
    "sql": "SELECT date, SUM(amount) FROM orders GROUP BY date",
    "aiModel": "claude-3-5-sonnet"
  }'

🏗️ Architecture

User Browser / AI Client
        ↓
  Next.js Dashboard (Frontend)
        ↓
  Express API Gateway (:3001)
        ↓
  ┌─────────────────────────────────────┐
  │        SQL-Guard (Interceptor)        │
  │  1. AST Parse & Op-Type Check        │
  │  2. Table Whitelist Validation       │
  │  3. JOIN Depth Limit                 │
  │  4. Cost Estimation + LIMIT Append  │
  └─────────────────────────────────────┘
        ↓
  MCP-Proxy (per-connection lifecycle)
        ↓
  ┌─────────────────────────────────────┐
  │  Docker Container (MCP Server)       │
  │  postgres:// / mysql:// / sqlite:// │
  └─────────────────────────────────────┘
        ↓
  Target Business Database

🔒 Security Model

Layer	Protection
Operation Filter	Blocks INSERT/UPDATE/DELETE/DROP/TRUNCATE
Table Whitelist	Only pre-approved tables are accessible
Blocked Tables	Hard-block on salary/passwords tables
JOIN Limit	Max 3 JOINs per query
Cost Guard	Heavy queries (>5000 cost units) rejected
Result Cap	Auto-appends LIMIT 100
Audit Log	Every query logged with user, SQL, status

📁 Project Structure

databridge-ai/
├── src/
│   ├── api/
│   │   └── server.ts          # Express API gateway
│   ├── core/
│   │   ├── sql-guard.ts       # AST SQL interceptor
│   │   └── mcp-proxy.ts       # MCP server lifecycle manager
│   └── db/
│       └── schema.sql         # PostgreSQL metadata schema
├── scripts/
│   └── init-db.sql           # DB initialization
├── docker/
│   ├── docker-compose.yml     # Full stack orchestration
│   └── Dockerfile.gateway    # API gateway image
└── package.json

📋 Roadmap

• v0.1.0-alpha — Core SQL guard + Postgres MCP server
• v0.2.0 — MySQL + SQLite MCP support
• v0.3.0 — Web Dashboard (Next.js)
• v0.4.0 — Rate limiting + per-plan quotas
• v0.5.0 — Multi-tenant SaaS billing
• v1.0.0 — Public beta release

💰 Pricing

Plan	Price	Connections	Queries/day
Free	$0	1	50
Pro	$49/mo	10	Unlimited
Enterprise	Custom	Unlimited	Unlimited + SOC2

📄 License

MIT License — see LICENSE file.