npm package: @legacy-lens/mcp-server
Description: MCP server for legacy SQL database introspection (Cursor and other MCP hosts)
Latest version: 0.1.1

# @legacy-lens/mcp-server

**Legacy Lens** is an MCP (Model Context Protocol) server that lets AI assistants in Cursor and other hosts **inspect legacy SQL databases safely**. It answers questions about structure and sample data: schemas, tables, columns, foreign keys, and a small number of sample rows per request (default **5**, maximum **10**). It is meant for understanding old systems before you change them—not for arbitrary read/write SQL from the model.

**Supported databases:** PostgreSQL, MySQL / MariaDB, SQLite, Microsoft SQL Server. Oracle is not supported.

---

## Install

You need **Node.js 20+**.

```bash
npm install -g @legacy-lens/mcp-server
```

The **`legacy-lens-mcp`** command is available. The MCP host must run it **with no arguments** (stdio mode). Subcommands are only for setup from a normal terminal:

```bash
legacy-lens-mcp help
legacy-lens-mcp version
legacy-lens-mcp setup
legacy-lens-mcp init --url 'postgresql://user:pass@localhost:5432/db?sslmode=disable' --check
```

`setup` (aliases: `init`, `configure`) can print Cursor-style JSON, env lines, or JSON; use `--check` to verify the connection. Passwords are redacted in output unless you pass `--print-secrets`.

**SQLite:** the driver uses native code (`better-sqlite3`). If install fails, install a [node-gyp](https://github.com/nodejs/node-gyp) toolchain (Python, C++ build tools) and retry.

---

## Use with Cursor (MCP config)

Point **`command`** at the installed binary or use **`npx`**. Set **`DATABASE_URL`** (or discrete variables—see below) in **`env`**.

Example with a global install:

```json
{
  "mcpServers": {
    "legacy-lens": {
      "command": "legacy-lens-mcp",
      "args": [],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb?sslmode=disable"
      }
    }
  }
}
```

Example using `npx`:

```json
{
  "mcpServers": {
    "legacy-lens": {
      "command": "npx",
      "args": ["-y", "@legacy-lens/mcp-server"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb?sslmode=disable"
      }
    }
  }
}
```

### `DATABASE_URL` schemes

| Scheme | Database |
|--------|----------|
| `postgresql://` / `postgres://` | PostgreSQL |
| `mysql://` / `mysql2://` | MySQL / MariaDB |
| `mssql://` / `sqlserver://` | SQL Server |
| `file:` | SQLite (path in URL) |

More examples:

```json
"env": { "DATABASE_URL": "mysql://user:pass@localhost:3306/mydb" }
```

```json
"env": { "DATABASE_URL": "file:/absolute/path/to/app.db" }
```

```json
"env": { "DATABASE_URL": "mssql://user:pass@localhost:1433/mydb?encrypt=true&trustServerCertificate=true" }
```

### Without `DATABASE_URL`

Set **`DIALECT`** to `postgres`, `mysql`, `sqlite`, or `sqlserver`, then use the usual discrete variables:

- **PostgreSQL:** `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`, `PGSSLMODE` (`disable`, `prefer`, `require`).
- **MySQL:** `MYSQL_*` or `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`. Optional: `MYSQL_SSL=true` or `MYSQL_SSL_MODE=required`.
- **SQLite:** `SQLITE_PATH`; optional `SQLITE_READONLY=true`.
- **SQL Server:** `MSSQL_*` or `DB_*` aliases. Optional: `MSSQL_ENCRYPT`, `MSSQL_TRUST_SERVER_CERTIFICATE` (avoid lax TLS in production).

---

## MCP tools

- **`list_schemas`** — Schemas / catalogs (non-system where applicable)
- **`list_tables`** — Base tables (`schema` + `table`; SQLite often `main`)
- **`describe_table`** — Columns, types, nullability, primary keys
- **`list_foreign_keys`** — Foreign keys (optionally scoped to a table). SQLite without a filter walks tables and uses `PRAGMA foreign_key_list`
- **`sample_rows`** — `schema`, `table`, optional `limit` (capped at **10**)

---

## Database permissions (recommended)

Use a **read-only** database user with **SELECT** only on the schemas you care about.

**PostgreSQL** — role with `CONNECT`, `USAGE` on schema, `SELECT` on tables; new sessions use `default_transaction_read_only=on`.

**MySQL** — `SELECT` on relevant schemas; the pool attempts a read-only session where supported.

**SQLite** — prefer `SQLITE_READONLY=true` or read-only file access.

**SQL Server** — `db_datareader` or narrower `SELECT` grants; avoid `trustServerCertificate` in production.

---

## Security

- Treat `DATABASE_URL` and passwords as **secrets**. Do not commit them; lock down env files and screen shares.
- Legacy Lens does not target Oracle (client and packaging complexity).

---

## Related package

Database access is implemented by [`@legacy-lens/db-introspect`](https://www.npmjs.com/package/@legacy-lens/db-introspect), which you can also use directly in Node.js applications.