Database Lookup Protocol (DLP)

npm version npm downloads License: MIT Website

DLP lets your AI coding assistant read your database — so it writes better code, faster.

Ever had your AI assistant guess what your database looks like, only to generate wrong column names or miss relationships? DLP solves that. It gives tools like Claude Code, Cursor, VS Code Copilot, and antigravity (Gemini) read-only access to your database schema and data — no debug code needed, no copy-pasting table structures into chat.

🌐 dlp-mcp.vercel.app — Give Your AI Database Eyes

---

What does DLP do?

Think of DLP as a bridge between your AI assistant and your database. Once set up:

• Your AI can see your tables, columns, and relationships automatically
• It can preview actual data to understand what's stored
• It can run safe read-only queries to answer questions about your data
• All of this happens without you writing any code or pasting schema dumps

Example: Instead of telling your AI "I have a users table with id, name, email columns...", it can just look at the database itself.

---

How it works

DLP uses the Model Context Protocol (MCP) — an open standard that lets AI assistants use external tools. When you set up DLP:

1. Your IDE spawns DLP as a background process
2. DLP connects to your database using the DATABASE_URL from your project
3. Your AI assistant gets four new tools to inspect the database
4. Everything runs locally on your machine — your data never leaves

Your AI Assistant  <-->  DLP (MCP Server)  <-->  Your Database
   (Claude, etc.)         (runs locally)        (Postgres, MySQL, etc.)

---

Installation

npm install database-lookup-protocol

Or use it directly without installing (via npx):

npx database-lookup-protocol set cursor

---

Quick Start

Setting up DLP takes two steps and under a minute.

Prerequisites

• Node.js v18 or higher installed
• A database you want to connect to (PostgreSQL, MySQL, MongoDB, SQL Server, or Prisma)
• An IDE that supports MCP (Claude Code, Cursor, VS Code, or antigravity)

Step 1: Add your database connection to .env

Make sure your project has a .env file with your database connection. If you already have one (most projects do), you're good — skip to Step 2.

Option A: Single connection string (most common)

DATABASE_URL=postgresql://user:password@localhost:5432/mydb

Option B: Individual variables (if your project uses separate host/user/password vars)

# PostgreSQL
PG_HOST=localhost
PG_PORT=5432
PG_DATABASE=mydb
PG_USER=admin
PG_PASSWORD=secret

# MySQL
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_DATABASE=mydb
MYSQL_USER=admin
MYSQL_PASSWORD=secret

# MongoDB
MONGODB_URI=mongodb://localhost:27017/mydb

# SQL Server
MSSQL_HOST=localhost
MSSQL_PORT=1433
MSSQL_DATABASE=mydb
MSSQL_USER=admin
MSSQL_PASSWORD=secret

DLP automatically detects whichever format you use — DATABASE_URL or individual variables.

Not sure what your DATABASE_URL looks like? See the Connection String Formats section below for examples for each database.

Step 2: Connect DLP to your IDE

Open a terminal inside your project folder (where your .env file is) and run:

# For antigravity (Gemini)
npx dlp set antigravity

# For Cursor
npx dlp set cursor

# For VS Code
npx dlp set vscode

# For Claude Code
npx dlp set claude

# For all IDEs at once
npx dlp set all

That's it! Restart your IDE and DLP is ready to use.

What just happened? The dlp set command read your database connection variables from your project's .env file (either DATABASE_URL or individual vars like PG_HOST, MYSQL_HOST, etc.) and wrote the MCP configuration to your IDE's global config directory. Your AI assistant will now see DLP as an available tool.

---

Using DLP in your AI assistant

Once set up, your AI assistant automatically has access to four database tools. You don't need to do anything special — just ask questions about your database naturally:

• "What tables are in my database?"
• "Show me some sample data from the users table"
• "What columns does the orders table have?"
• "Find all users who signed up in the last week"

Your AI will use DLP tools behind the scenes to answer these questions.

Available tools

Tool	What it does	Example use
dlp_get_schema	Shows all tables, columns, types, keys, and relationships	"What does my database look like?"
dlp_describe_table	Shows detailed info about one table — column types, indexes, defaults, constraints	"Tell me about the orders table"
dlp_preview_table	Shows sample rows from a table (up to 20 rows)	"Show me some data from the users table"
dlp_safe_query	Runs a read-only SQL SELECT query (must include LIMIT, max 20 rows)	"How many orders were placed today?"

Tip: You can tell your AI: "Use dlp_get_schema to understand the database before writing any queries" — this gives it the full picture upfront.

---

Supported databases

DLP works with five popular databases. You only need to install the driver for the database you're using:

Database	Install the driver	Status
PostgreSQL	npm install pg	Production-ready
MySQL / MariaDB	npm install mysql2	Production-ready
MongoDB	npm install mongodb	Production-ready
Microsoft SQL Server	npm install mssql	Production-ready
Prisma (any DB Prisma supports)	npm install @prisma/client	Production-ready

Note: If your project already uses one of these drivers (check your package.json), you don't need to install anything extra.

Connection string formats

Here's what DATABASE_URL looks like for each database:

# PostgreSQL
DATABASE_URL=postgresql://username:password@hostname:5432/database_name

# MySQL / MariaDB
DATABASE_URL=mysql://username:password@hostname:3306/database_name

# MongoDB
DATABASE_URL=mongodb://username:password@hostname:27017/database_name

# Microsoft SQL Server
DATABASE_URL=mssql://username:password@hostname:1433/database_name

# Prisma (uses whatever your Prisma schema defines)
DATABASE_URL=postgresql://username:password@hostname:5432/database_name

Common hosted database examples:

# Supabase (PostgreSQL)
DATABASE_URL=postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres

# PlanetScale (MySQL)
DATABASE_URL=mysql://[user]:[password]@[host]/[database]?ssl={"rejectUnauthorized":true}

# MongoDB Atlas
DATABASE_URL=mongodb+srv://[user]:[password]@[cluster].mongodb.net/[database]

# Neon (PostgreSQL)
DATABASE_URL=postgresql://[user]:[password]@[host].neon.tech/[database]?sslmode=require

# Railway (PostgreSQL)
DATABASE_URL=postgresql://postgres:[password]@[host].railway.app:5432/railway

---

Where does dlp set write configs?

When you run npx dlp set <ide>, it writes the MCP configuration to your IDE's global config directory in your home folder (~ = C:\Users\YourName on Windows, /Users/YourName on Mac, /home/YourName on Linux):

IDE	Config file location
antigravity (Gemini)	~/.gemini/antigravity/mcp_config.json
Cursor	~/.cursor/mcp_config.json
VS Code	~/.vscode/mcp_config.json
Claude Code	~/.mcp.json

Switching projects? Just cd into the new project, and run npx dlp set <ide> again. It will update the config with the new project's database connection.

---

Security

DLP is designed to be safe by default:

• Read-only access — DLP can only SELECT data. It cannot INSERT, UPDATE, DELETE, DROP, or modify your database in any way.
• SQL injection protection — 15+ dangerous SQL patterns are blocked before any query reaches your database.
• No network exposure — In MCP mode, DLP runs as a local process communicating via stdio. Your database credentials and data never leave your machine.
• Row limits enforced — All queries are capped at 20 rows. Long text fields are automatically truncated to 200 characters.
• No API key needed — MCP uses stdio (standard input/output), so there's no HTTP server or API key to worry about.

About the postbuild script

DLP includes a postbuild npm script that adds a shebang line (#!/usr/bin/env node) to the CLI entry point file. This is a standard practice for Node.js command-line tools to work correctly on Unix-like systems (Linux, macOS).

What it does:

// Checks if dist/cli/index.js exists
// Reads the compiled CLI file
// Adds #!/usr/bin/env node at the top if it's not already there
// Writes it back to disk

This script runs automatically after TypeScript compilation (npm run build) and is necessary for the dlp command to be executable. The script only reads and writes to the project's own build output — it doesn't access external files, network resources, or perform any malicious operations.

Why it's needed: TypeScript doesn't preserve shebang lines during compilation, so we add it back afterwards. Without this line, the dlp command wouldn't work when installed globally or used via npx.

---

Switching projects

When you switch to a different project with a different database:

1. Make sure the new project has a .env file with its database connection (DATABASE_URL or individual vars)
2. Open a terminal in that project folder
3. Run npx dlp set <ide> again
4. Restart your IDE

The config will be updated with the new database connection.

---

HTTP Server Mode (Advanced)

Most users don't need this. The MCP mode (set up above) is the recommended way to use DLP. HTTP mode is for custom integrations, scripts, or tools that can't use MCP.

If you want to run DLP as a standalone HTTP API:

# Add these to your .env
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
DLP_API_KEY=your-secret-key

# Start the server
npx dlp start

The server runs on http://localhost:3434. All requests go to POST /protocol with an Authorization: Bearer <your-api-key> header.

Example requests:

# Get database schema
curl -X POST http://localhost:3434/protocol \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"action": "get_schema", "schema": "public"}'

# Preview table data
curl -X POST http://localhost:3434/protocol \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"action": "preview_table", "table": "users", "limit": 5}'

# Describe a table
curl -X POST http://localhost:3434/protocol \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"action": "describe_table", "table": "users"}'

# Run a read-only query
curl -X POST http://localhost:3434/protocol \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"action": "safe_query", "query": "SELECT id, email FROM users LIMIT 5"}'

Rules: Only SELECT queries are allowed. Every query must include a LIMIT clause. Maximum 20 rows returned.

---

CLI Reference

npx dlp set <ide>         Read DB vars from .env and configure your IDE
npx dlp set all           Configure all supported IDEs at once
npx dlp start             Start HTTP API server on port 3434
npx dlp start --mcp       Start MCP stdio server
npx dlp mcp               Same as "start --mcp"

---

Troubleshooting

"DLP tools not showing up in my IDE"

• Make sure you ran npx dlp set <ide> from inside your project folder (where .env is)
• Restart your IDE completely after running the set command
• Check that your .env file contains a valid DATABASE_URL

"Cannot connect to database"

• Verify your DATABASE_URL is correct by testing the connection with your database client
• Make sure the database server is running and accessible
• Check that you've installed the correct driver (npm install pg for PostgreSQL, etc.)

"Permission denied" or "Config file error"

• Run npx dlp set <ide> again — it will overwrite any broken config files
• Make sure you have write access to your home directory

Switching to a different database?

• Update DATABASE_URL in your project's .env
• Run npx dlp set <ide> again
• Restart your IDE

---

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Clone your fork: git clone https://github.com/your-username/Database-Lookup-Protocol.git
3. Create a feature branch: git checkout -b feat/your-feature
4. Make your changes in the src/ directory
5. Build the project: npm run build
6. Test your changes locally
7. Open a Pull Request

Adding a new database adapter

To add support for a new database:

1. Create a new adapter file in src/adapters/ that implements the DLPAdapter interface
2. The adapter needs four methods: getSchema(), previewTable(), describeTable(), and safeQuery()
3. Register the adapter in src/cli/index.ts
4. Add the connection string format to this README

---

Supported Environment Variables

dlp set automatically reads all database-related variables from your project's .env — not just DATABASE_URL. Here's the full list of variables it detects and writes into your IDE config:

Variable	Database	Description
DATABASE_URL	Any	Full connection string (auto-detects DB type from scheme)
DB_TYPE	Any	Explicitly set DB type: postgres, mysql, mongodb, mssql, prisma
PostgreSQL
PG_HOST / PGHOST	PostgreSQL	Database host
PG_PORT / PGPORT	PostgreSQL	Database port (default: 5432)
PG_DATABASE / PGDATABASE	PostgreSQL	Database name
PG_USER / PGUSER	PostgreSQL	Username
PG_PASSWORD / PGPASSWORD	PostgreSQL	Password
PG_SSL	PostgreSQL	Set to true to enable SSL
MySQL / MariaDB
MYSQL_HOST	MySQL	Database host
MYSQL_PORT	MySQL	Database port (default: 3306)
MYSQL_DATABASE	MySQL	Database name
MYSQL_USER	MySQL	Username
MYSQL_PASSWORD	MySQL	Password
MongoDB
MONGODB_URI	MongoDB	Full MongoDB connection URI
MONGODB_DATABASE	MongoDB	Database name (default: parsed from URI or test)
SQL Server
MSSQL_HOST	MSSQL	Database host
MSSQL_PORT	MSSQL	Database port (default: 1433)
MSSQL_DATABASE	MSSQL	Database name
MSSQL_USER	MSSQL	Username
MSSQL_PASSWORD	MSSQL	Password
MSSQL_ENCRYPT	MSSQL	Set to false to disable encryption
MSSQL_TRUST_CERT	MSSQL	Set to true to trust self-signed certificates

How it works: When you run npx dlp set <ide>, it scans your .env for all of the above variables, and writes every one it finds into the IDE's MCP config env block. That way, when the IDE spawns the DLP MCP server, all your database credentials are available — regardless of whether you use a single DATABASE_URL or separate variables.

---

License

MIT - see LICENSE for details.

---

Built by Kalyan Gupta & Arghajit Saha | 🌐 Website | Report a bug | npm package