Lukynnnn
/

mcp-database-universal

@@ -1,176 +1,81 @@
-# MCP Database Server
-A reasoning interface for databases for MCP-capable AI agents — not a thin SQL wrapper.
-`mcp-database-universal` gives AI agents a set of **7 reasoning tools** to explore and query a database safely, understand its schema and data shape, run natural-language questions, and visualize relationships — all without exposing raw connection internals.
-## Features
-- **7 reasoning tools** designed for AI agents: test connection, list tables, inspect a table, run parameterized SQL, ask questions in plain language, profile data, and render an ER diagram.
-- **Multi-engine**: SQLite (built-in) plus optional PostgreSQL, MySQL, and MSSQL.
-- **Safety first**: read-only by default, parameterized queries, statement validation, row/time/output limits.
-- **LLM-friendly output**: types translated, `NULL`s handled, results formatted in Markdown tables with context.
-- **Schema introspection**: auto-discover tables, columns, indexes, foreign keys, and relationships.
-- **Natural language queries**: translate plain-text questions into SQL and return results.
-## Supported engines
-| Engine      | Requirement    | Install extra                    |
-|-------------|----------------|----------------------------------|
-| SQLite      | built-in       | —                                |
-| PostgreSQL  | psycopg        | `pip install "mcp-database-universal[postgres]"` |
-| MySQL       | PyMySQL        | `pip install "mcp-database-universal[mysql]"`     |
-| MSSQL       | pyodbc + ODBC driver | `pip install "mcp-database-universal[mssql]"`     |
-| all         | —              | `pip install "mcp-database-universal[all]"`       |
-## Install
 ```bash
 pip install mcp-database-universal
-# With optional engines:
-pip install "mcp-database-universal[postgres]"
-pip install "mcp-database-universal[mysql]"
-pip install "mcp-database-universal[mssql]"
-# or everything:
-pip install "mcp-database-universal[all]"
 ```
-## Quick start
-Run the server over STDIO (the default transport for MCP clients):
 ```bash
 DATABASE_URL=sqlite:///app.db python -m mcp_database_universal
 ```
-Connection URLs:
-```
-sqlite:///path/to/db.db              SQLite (file)
-sqlite:///:memory:                   SQLite (in-memory)
-postgresql://user:pass@host:5432/db  PostgreSQL
-mysql://user:pass@host:3306/db       MySQL
-mssql://user:pass@host:1433/db       MSSQL (uses ODBC Driver 18)
-```
-## Docker
 ```bash
-docker build -t mcp-db .
-# Mount a SQLite database read-only:
-docker run --rm -i \
-  -v /host/path/app.db:/data/app.db:ro \
-  -e DATABASE_URL=sqlite:////data/app.db \
-  mcp-db
-# Or in-memory:
-docker run --rm -i -e DATABASE_URL=sqlite:///:memory: mcp-db
 ```
-## Configuration
-All configuration is done through environment variables.
-| Variable                    | Default   | Description                                            |
-|-----------------------------|-----------|--------------------------------------------------------|
-| `DATABASE_URL`              | *(required)* | Database connection URL.                            |
-| `DATABASE_READ_ONLY`        | `true`    | Enforce read-only mode (blocks writes even if `DATABASE_WRITE_ENABLED`). |
-| `DATABASE_WRITE_ENABLED`    | `false`   | Allow write statements when `DATABASE_READ_ONLY=false`. |
-| `DATABASE_MAX_ROWS`         | `1000`    | Maximum rows returned per query.                       |
-| `DATABASE_MAX_QUERY_TIME`   | `30`      | Query timeout in seconds.                              |
-| `DATABASE_MAX_OUTPUT_BYTES` | `50000`   | Cap on result payload size.                            |
-| `DATABASE_SAMPLE_SIZE`      | `5`       | Number of sample rows shown in table/column stats.     |
-| `DATABASE_PROFILE_TOP_N`    | `10`      | Top-N value distribution entries in profiling.         |
-| `OPENAI_API_KEY`            | —         | API key for the LLM-backed `natural_query` mode.       |
-| `ANTHROPIC_API_KEY`         | —         | API key for the LLM-backed `natural_query` mode.       |
 ## Tools
-| Tool               | Description                                                        |
-|--------------------|--------------------------------------------------------------------|
-| `test_connection`  | Test DB connectivity; report engine, version, name, size, table count. |
-| `list_tables`      | Overview of all tables with row counts, column counts, FK relationships. |
-| `inspect_table`    | Full structure of one table: columns, types, indexes, FKs, sample data. |
-| `query`            | Run a safe, parameterized SQL query and get Markdown results.      |
-| `natural_query`    | Ask a question in plain text; get generated SQL + results.         |
-| `profile_database` | Data profile: distributions, NULL rates, relationships, sizes.     |
-| `schema_graph`     | Mermaid ER diagram of table relationships.                         |
-### Example: `query` with parameters
-```json
-{
-  "sql": "SELECT * FROM users WHERE id = :id AND active = :active",
-  "params": "{\"id\": 42, \"active\": true}"
-}
-```
-Parameters use `:name` placeholders; pass the values as a JSON string in `params`.
-### Example: `natural_query`
-```text
-question: "How many users are there?"
--> SELECT COUNT(*) FROM users
-question: "Show me all orders"
--> SELECT * FROM orders LIMIT 100
-```
-A working example against a small sample database is in [`examples/`](examples/) together with ready-to-use configuration snippets for common MCP clients.
-## MCP client configuration
-### Claude Desktop (`claude_desktop_config.json`)
-```json
-{
-  "mcpServers": {
-    "database": {
-      "command": "python",
-      "args": ["-m", "mcp_database_universal"],
-      "env": {"DATABASE_URL": "sqlite:///C:/data/app.db"}
-    }
-  }
-}
-```
-### Cursor / other CLI-based clients
-```json
-{
-  "mcpServers": {
-    "database": {
-      "command": "uvx",
-      "args": ["mcp-database-universal"],
-      "env": {"DATABASE_URL": "sqlite:///C:/data/app.db"}
-    }
-  }
-}
-```
-> **Windows note**: the async Postgres driver requires the Windows selector event loop. The package sets this policy automatically on `win32`, so no extra configuration is needed.
-## Development
-```bash
-pip install -e ".[dev]"
-pytest
-```
-Integration tests for PostgreSQL/MySQL use Docker Compose and are skipped automatically if the servers are unreachable:
-```bash
-docker compose -f tests/integration/docker-compose.yml up -d
-pytest
-```
-## Safety model
-- The server is **read-only by default**; `INSERT`/`UPDATE`/`DELETE`/`DROP`/`ALTER` and other write statements are blocked.
-- Writes are only possible when the operator explicitly sets `DATABASE_READ_ONLY=false` **and** `DATABASE_WRITE_ENABLED=true`.
-- Query results are capped by row count, timeout, and output size — runaway queries are prevented.
 ## License

+---
+language:
+  - en
+tags:
+  - mcp
+  - model-context-protocol
+  - ai-tools
+  - database
+  - sqlite
+  - postgresql
+  - mysql
+  - mssql
+library_name: mcp-database-universal
+license: mit
+---
+# MCP Database Universal
+A reasoning interface for databases — not a thin execution wrapper. Designed so LLM agents understand *what* the data means, not just how to fetch it.
+## What it does
+- **7 tools** designed for agent thinking: `test_connection`, `list_tables`, `inspect_table`, `query`, `natural_query`, `profile_database`, `schema_graph`
+- **4 database engines**: SQLite (built-in), PostgreSQL, MySQL, MSSQL (optional extras)
+- **Read-only by default** — write operations only with `DATABASE_WRITE_ENABLED=true`
+- **Safety layer** — SQL injection detection, read-only classification, LIMIT enforcement, query timeout, row limits
+- **LLM formatter** — type translation (e.g. `VARCHAR(255)` → "text, max 255 chars"), NULL → `(empty)`, output size cap
+- **Schema inspector** — relationship discovery + Mermaid ER diagram generation
+- **Zero-config SQLite** via `DATABASE_URL=sqlite:///path/to.db`
+## Installation
 ```bash
 pip install mcp-database-universal
+pip install "mcp-database-universal[postgres]"   # PostgreSQL support
+pip install "mcp-database-universal[mysql]"      # MySQL support
+pip install "mcp-database-universal[mssql]"      # MSSQL support
 ```
+## Quick Start
+### Run locally
 ```bash
 DATABASE_URL=sqlite:///app.db python -m mcp_database_universal
 ```
+### Run with Docker
 ```bash
+docker run -i -e DATABASE_URL=sqlite:////data/app.db \
+  -v ./data:/data mcp-database-universal:latest
 ```
+## Configuration (env vars)
+| Variable                  | Description                                             | Default    |
+|---------------------------|---------------------------------------------------------|------------|
+| `DATABASE_URL`            | `sqlite:///path.db`, `postgresql://...`, `mysql://...`, `mssql://...` | required |
+| `DATABASE_READ_ONLY`      | Enforce read-only mode                                  | `true`     |
+| `DATABASE_WRITE_ENABLED`  | Allow write operations (INSERT/UPDATE/DELETE)           | `false`    |
+| `DATABASE_MAX_ROWS`       | Max rows returned per query                             | `1000`     |
+| `DATABASE_MAX_QUERY_TIME` | Query timeout in seconds                                | `30`       |
+| `DATABASE_MAX_OUTPUT_BYTES` | Cap on result payload size                            | `50000`    |
+| `OPENAI_API_KEY`          | API key for the LLM-backed `natural_query` mode         | —          |
+| `ANTHROPIC_API_KEY`       | API key for the LLM-backed `natural_query` mode         | —          |
 ## Tools
+| Tool               | Description                                              |
+|--------------------|----------------------------------------------------------|
+| `test_connection`  | Verify connection, get engine type, version, size         |
+| `list_tables`      | Overview of tables with row counts and relationships      |
+| `inspect_table`    | Full table structure: columns, types, keys, sample data   |
+| `query`            | Execute parametrized, safety-checked SQL                  |
+| `natural_query`    | Ask in plain language, get SQL + results + explanation    |
+| `profile_database` | Value distributions, NULL rates, relationships, sizes     |
+| `schema_graph`     | Mermaid ER diagram of relationships                       |
 ## License