Metadata-Version: 2.4
Name: db-semantic-mcp
Version: 0.1.0
Summary: A multi-backend MCP server (PostgreSQL + SQL Server) for AI coding agents — schema metadata + semantic search
Project-URL: Homepage, https://github.com/chncaesar/db-semantic-mcp
Project-URL: Repository, https://github.com/chncaesar/db-semantic-mcp
Project-URL: Issues, https://github.com/chncaesar/db-semantic-mcp/issues
License: MIT
Keywords: ai,llm,mcp,mssql,postgresql,schema,sqlserver
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: asyncpg>=0.30.0
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: all
Requires-Dist: pymssql>=2.3.0; extra == 'all'
Provides-Extra: sqlserver
Requires-Dist: pymssql>=2.3.0; extra == 'sqlserver'
Description-Content-Type: text/markdown

# db-semantic-mcp

A multi-backend MCP server for AI coding agents — supports both PostgreSQL and
SQL Server.

Exposes your database schema — table names, column types, comments, and sample
data — as MCP tools. Includes semantic search powered by any OpenAI-compatible
LLM, enriched by a user-authored semantic layer document.

No SQL execution. Read-only. No vector database required.

## Backends

| Backend | Scheme | Driver | Required Extras |
|---|---|---|---|
| PostgreSQL | `postgresql://...` | asyncpg | (built-in) |
| SQL Server | `sqlserver://...` | pymssql | `[sqlserver]` |

The backend is auto-detected from `DATABASE_URL`. Everything else works the same.

## Features

- **list_tables** — discover all tables with comments
- **describe_table** — inspect column names, types, nullability, and comments
- **sample_data** — fetch example rows from any table
- **search_schema** — semantic keyword search across tables and columns using LLM

## Install

```bash
# PostgreSQL only
pip install db-semantic-mcp

# With SQL Server support
pip install "db-semantic-mcp[sqlserver]"
```

Requires Python 3.11+.

## Quick Start

```bash
# PostgreSQL
export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"

# SQL Server (Kingdee ERP or any MSSQL instance)
export DATABASE_URL="sqlserver://user:pass@host:1433?database=mydb&encrypt=disable"

export LLM_API_KEY="sk-..."          # required only for search_schema
pg-semantic-mcp
```

## Configuration

| Variable | Required | Default | Description |
|---|---|---|---|
| `DATABASE_URL` | yes | — | PostgreSQL or SQL Server connection string |
| `SEMANTIC_FILE` | no | — | Path to your semantic layer markdown |
| `LLM_BASE_URL` | no | `https://api.openai.com/v1` | OpenAI-compatible endpoint |
| `LLM_API_KEY` | no | — | Required for `search_schema` |
| `LLM_MODEL` | no | `gpt-4o-mini` | LLM model name |
| `CACHE_REFRESH_MINUTES` | no | `30` | Background cache refresh interval |
| `CACHE_SCHEMAS` | no | all | Comma-separated schema names to cache |
| `CACHE_TABLE_PREFIX` | no | — | Comma-separated table name prefixes to cache |
| `SAMPLE_DATA_LIMIT` | no | `5` | Default row count for `sample_data` |

You can also use a `.env` file in the working directory.

## Register with OpenCode

Add to your `opencode.jsonc`:

```jsonc
{
  "mcp": {
    "pg-data": {
      "type": "local",
      "command": "pg-semantic-mcp",
      "environment": {
        "DATABASE_URL": "postgresql://user:pass@host:5432/dbname",
        "SEMANTIC_FILE": "/path/to/SCHEMA.md",
        "LLM_API_KEY": "sk-..."
      }
    }
  }
}
```

Same config format works for Claude Code, Cursor, and any MCP-compatible agent.

## Semantic Layer

Create a `SCHEMA.md` file describing your database — naming conventions,
business term mappings, design decisions. See
[SCHEMA.md.example](SCHEMA.md.example) for a template.

This document is loaded at startup and included in the `search_schema` LLM
prompt. It is the main way to teach the agent about your specific domain.

## Compatible LLMs

`search_schema` calls any OpenAI-compatible endpoint:

- OpenAI (`gpt-4o-mini`, `gpt-4o`, …)
- DeepSeek (`deepseek-v4`, set `LLM_BASE_URL=https://api.deepseek.com/v1`)
- Anthropic via proxy
- Local models via Ollama or LM Studio

## License

MIT
