Upload README.md with huggingface_hub

README.md

@@ -1,49 +1,76 @@
-# MCP Database Server
+---
+language:
+  - en
+tags:
+  - mcp
+  - model-context-protocol
+  - ai-tools
+  - database
+  - sqlite
+  - postgresql
+  - mysql
+  - mssql
+library_name: mcp-database-universal
+license: mit
+---
 
-Reasoning interface for databases — not a thin wrapper.
+# MCP Database Universal
 
-## Features
+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.
 
-- **7 reasoning tools** for AI agents to work with databases
-- **Multi-engine**: SQLite (built-in), PostgreSQL, MySQL, MSSQL (optional)
-- **Safety first**: read-only default, parameterized queries, injection prevention
-- **LLM-friendly output**: types translated, NULLs handled, results contextualized
-- **Schema introspection**: auto-discover tables, columns, relationships, indexes
-- **Natural language queries**: ask questions in plain text, get SQL + results
+## What it does
 
-## Install
+- **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, 30s timeout, 1000-row limit
+- **LLM formatter** — type translation (e.g. `VARCHAR(255)` → "text, max 255 chars"), NULL → `(empty)`, truncation to 50KB
+- **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
-
-# With optional engines:
-pip install "mcp-database-server[postgres]"
-pip install "mcp-database-server[mysql]"
-pip install "mcp-database-server[mssql]"
+pip install "mcp-database-universal[postgres]"   # PostgreSQL support
+pip install "mcp-database-universal[mysql]"      # MySQL support
+pip install "mcp-database-universal[mssql]"      # MSSQL support
 ```
 
-## Usage
+## Quick Start
 
+### Run locally
 ```bash
-DATABASE_URL=sqlite:///mydb.db python -m mcp_database_universal
+python -m mcp_database_universal
 ```
 
-## Docker
-
+### Run with Docker
 ```bash
-docker build -t mcp-db .
-docker run --rm -i -e DATABASE_URL=sqlite:///:memory: mcp-db
+docker run -i -e DATABASE_URL=sqlite:////data/app.db \
+  -v ./data:/data mcp-database-universal:latest
 ```
 
-## Configuration
+## Configuration (env vars)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DATABASE_URL` | `sqlite:///path.db`, `postgresql://...`, `mysql://...`, `mssql://...` | required |
+| `DATABASE_WRITE_ENABLED` | Allow write operations (INSERT/UPDATE/DELETE) | `false` |
+| `DATABASE_QUERY_LIMIT` | Max rows returned per query | `1000` |
+| `DATABASE_TIMEOUT` | Query timeout in seconds | `30` |
+
+## Tools
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `DATABASE_URL` | (required) | Connection URL |
-| `DATABASE_READ_ONLY` | `true` | Read-only mode |
-| `DATABASE_MAX_ROWS` | `1000` | Max rows per query |
-| `DATABASE_MAX_QUERY_TIME` | `30` | Query timeout (seconds) |
+| 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
 
-MIT
+MIT