db-adapter 1.0.0__tar.gz

db_adapter-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+*.egg-info/
+__pycache__/
+*.pyc
+.venv/
+.ruff_cache/

db_adapter-1.0.0/AGENTS.md

@@ -0,0 +1,44 @@
+# MCP Database Server
+
+MCP server that provides database access tools for AI agents.
+
+## Tools
+
+### `list_tables`
+List all tables in the database. Returns table names and row counts.
+
+### `describe_table`
+Get the schema of a specific table. Returns column names, types, nullable, default values, foreign keys, and indexes.
+
+Parameters:
+- `table_name` (string, required): The name of the table to describe.
+
+### `run_select_query`
+Execute a read-only SELECT query against the database. Only SELECT statements are allowed for safety.
+
+Parameters:
+- `query` (string, required): The SELECT SQL query to execute.
+
+## Usage Guidelines
+
+When working with the database:
+- Use `list_tables` first to discover available tables
+- Use `describe_table` to understand a table's schema before querying it
+- Use `run_select_query` to execute SELECT queries only (INSERT/UPDATE/DELETE are blocked for safety)
+- Limit results with `LIMIT` clause when exploring large tables
+- Query results are returned as markdown tables
+
+## Configuration
+
+The database connection is configured via these environment variables:
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `DATABASE_POSTGRESQL_HOST` | Yes | — | PostgreSQL host address |
+| `DATABASE_POSTGRESQL_PORT` | Yes | — | PostgreSQL port |
+| `DATABASE_POSTGRESQL_USERNAME` | Yes | — | Database user |
+| `DATABASE_POSTGRESQL_PASSWORD` | No | — | Database password |
+| `DATABASE_POSTGRESQL_NAME` | Yes | — | Database name |
+| `DATABASE_POSTGRESQL_SCHEMA` | No | `public` | Schema to use for table discovery |
+
+If any required variable is missing, all tool calls will return an error indicating the database is not available.

db_adapter-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Husni Robani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

db_adapter-1.0.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: db-adapter
+Version: 1.0.0
+Summary: MCP server that provides PostgreSQL database access tools for AI agents (read-only)
+Author-email: Husni Robani <v.husni.robani@banksinarmas.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# MCP Database Server
+
+MCP server that provides read-only PostgreSQL database access for AI agents.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_tables` | List all tables with row counts |
+| `describe_table` | Get schema: columns, types, foreign keys, indexes |
+| `run_select_query` | Execute read-only SELECT queries |
+
+INSERT/UPDATE/DELETE are blocked for safety.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `DATABASE_POSTGRESQL_HOST` | Yes | — | PostgreSQL host |
+| `DATABASE_POSTGRESQL_PORT` | Yes | — | PostgreSQL port |
+| `DATABASE_POSTGRESQL_USERNAME` | Yes | — | Database user |
+| `DATABASE_POSTGRESQL_PASSWORD` | No | — | Database password |
+| `DATABASE_POSTGRESQL_NAME` | Yes | — | Database name |
+| `DATABASE_POSTGRESQL_SCHEMA` | No | `public` | Schema for table discovery |
+
+## Usage
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "db": {
+      "command": "uvx",
+      "args": ["db-adapter"],
+      "env": {
+        "DATABASE_POSTGRESQL_HOST": "localhost",
+        "DATABASE_POSTGRESQL_PORT": "5432",
+        "DATABASE_POSTGRESQL_USERNAME": "postgres",
+        "DATABASE_POSTGRESQL_PASSWORD": "postgres",
+        "DATABASE_POSTGRESQL_NAME": "mydb"
+      }
+    }
+  }
+}
+```
+
+### opencode
+
+Add to `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "db": {
+      "type": "local",
+      "command": ["uvx", "db-adapter"],
+      "enabled": true,
+      "environment": {
+        "DATABASE_POSTGRESQL_HOST": "localhost",
+        "DATABASE_POSTGRESQL_PORT": "5432",
+        "DATABASE_POSTGRESQL_USERNAME": "postgres",
+        "DATABASE_POSTGRESQL_PASSWORD": "postgres",
+        "DATABASE_POSTGRESQL_NAME": "mydb"
+      }
+    }
+  }
+}
+```
+
+Environment variables can be omitted to inherit from your shell.
+
+## Requirements
+
+- Python >= 3.10
+- PostgreSQL database

db_adapter-1.0.0/README.md

@@ -0,0 +1,78 @@
+# MCP Database Server
+
+MCP server that provides read-only PostgreSQL database access for AI agents.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_tables` | List all tables with row counts |
+| `describe_table` | Get schema: columns, types, foreign keys, indexes |
+| `run_select_query` | Execute read-only SELECT queries |
+
+INSERT/UPDATE/DELETE are blocked for safety.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `DATABASE_POSTGRESQL_HOST` | Yes | — | PostgreSQL host |
+| `DATABASE_POSTGRESQL_PORT` | Yes | — | PostgreSQL port |
+| `DATABASE_POSTGRESQL_USERNAME` | Yes | — | Database user |
+| `DATABASE_POSTGRESQL_PASSWORD` | No | — | Database password |
+| `DATABASE_POSTGRESQL_NAME` | Yes | — | Database name |
+| `DATABASE_POSTGRESQL_SCHEMA` | No | `public` | Schema for table discovery |
+
+## Usage
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "db": {
+      "command": "uvx",
+      "args": ["db-adapter"],
+      "env": {
+        "DATABASE_POSTGRESQL_HOST": "localhost",
+        "DATABASE_POSTGRESQL_PORT": "5432",
+        "DATABASE_POSTGRESQL_USERNAME": "postgres",
+        "DATABASE_POSTGRESQL_PASSWORD": "postgres",
+        "DATABASE_POSTGRESQL_NAME": "mydb"
+      }
+    }
+  }
+}
+```
+
+### opencode
+
+Add to `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "db": {
+      "type": "local",
+      "command": ["uvx", "db-adapter"],
+      "enabled": true,
+      "environment": {
+        "DATABASE_POSTGRESQL_HOST": "localhost",
+        "DATABASE_POSTGRESQL_PORT": "5432",
+        "DATABASE_POSTGRESQL_USERNAME": "postgres",
+        "DATABASE_POSTGRESQL_PASSWORD": "postgres",
+        "DATABASE_POSTGRESQL_NAME": "mydb"
+      }
+    }
+  }
+}
+```
+
+Environment variables can be omitted to inherit from your shell.
+
+## Requirements
+
+- Python >= 3.10
+- PostgreSQL database

db_adapter-1.0.0/opencode.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "db": {
+      "type": "local",
+      "command": [
+        "uv",
+        "run",
+        "server.py"
+      ],
+      "enabled": true,
+      "environment": {
+        "DATABASE_POSTGRESQL_NAME": "LMS_CUSTODY_MODULE"
+      }
+    }
+  }
+}

db_adapter-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "db-adapter"
+version = "1.0.0"
+description = "MCP server that provides PostgreSQL database access tools for AI agents (read-only)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Husni Robani", email = "v.husni.robani@banksinarmas.com" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "asyncpg>=0.29.0",
+]
+
+[project.scripts]
+mcp-db-adapter = "db_adapter.server:cli"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

db_adapter-1.0.0/src/db_adapter/__init__.py

@@ -0,0 +1,5 @@
+"""MCP Database Server - PostgreSQL database tools for AI agents."""
+
+from db_adapter.server import main, cli, server
+
+__version__ = "1.0.0"

db_adapter-1.0.0/src/db_adapter/server.py

@@ -0,0 +1,319 @@
+"""
+MCP Database Server - Exposes database tools for AI agents via MCP protocol.
+Connects to a PostgreSQL database using individual env vars for host, port,
+user, password, name, and schema.
+Provides: list_tables, describe_table, run_select_query.
+"""
+
+import asyncpg
+import os
+import re
+import asyncio
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+DB_NAME = os.environ.get("DATABASE_POSTGRESQL_NAME", "")
+DB_HOST = os.environ.get("DATABASE_POSTGRESQL_HOST", "")
+DB_PORT = os.environ.get("DATABASE_POSTGRESQL_PORT", "")
+DB_USER = os.environ.get("DATABASE_POSTGRESQL_USERNAME", "")
+DB_PASS = os.environ.get("DATABASE_POSTGRESQL_PASSWORD", "")
+DB_SCHEMA = os.environ.get("DATABASE_POSTGRESQL_SCHEMA", "public")
+
+_IDENTIFIER_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+server = Server("mcp-db")
+
+_pool = None
+
+
+def _is_safe_identifier(name: str) -> bool:
+    return bool(_IDENTIFIER_RE.match(name))
+
+
+def _build_dsn() -> str:
+    if DB_PASS:
+        return f"postgresql://{DB_USER}:{DB_PASS}@{DB_HOST}:{DB_PORT}/{DB_NAME}"
+    return f"postgresql://{DB_USER}@{DB_HOST}:{DB_PORT}/{DB_NAME}"
+
+
+async def _ensure_pool() -> TextContent | None:
+    global _pool
+    missing = []
+    if not DB_NAME:
+        missing.append("DATABASE_POSTGRESQL_NAME")
+    if not DB_HOST:
+        missing.append("DATABASE_POSTGRESQL_HOST")
+    if not DB_PORT:
+        missing.append("DATABASE_POSTGRESQL_PORT")
+    if not DB_USER:
+        missing.append("DATABASE_POSTGRESQL_USERNAME")
+    if missing:
+        return TextContent(
+            type="text",
+            text=f"Error: Missing required environment variables: {', '.join(missing)}. "
+            f"The database is not available.",
+        )
+    if not _is_safe_identifier(DB_SCHEMA):
+        return TextContent(
+            type="text",
+            text=f"Error: Invalid schema name '{DB_SCHEMA}'. "
+            f"Schema name must contain only alphanumeric characters and underscores.",
+        )
+    if _pool is None:
+        try:
+            _pool = await asyncpg.create_pool(_build_dsn())
+        except Exception as e:
+            return TextContent(
+                type="text",
+                text=f"Error: Failed to connect to database: {str(e)}",
+            )
+    return None
+
+
+async def _release_pool():
+    global _pool
+    if _pool:
+        await _pool.close()
+        _pool = None
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="list_tables",
+            description="List all tables in the database. Returns table names and row counts.",
+            inputSchema={
+                "type": "object",
+                "properties": {},
+                "required": [],
+            },
+        ),
+        Tool(
+            name="describe_table",
+            description="Get the schema of a specific table. Returns column names, types, nullable, and default values.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "table_name": {
+                        "type": "string",
+                        "description": "The name of the table to describe.",
+                    },
+                },
+                "required": ["table_name"],
+            },
+        ),
+        Tool(
+            name="run_select_query",
+            description="Execute a read-only SELECT query against the database. Only SELECT statements are allowed for safety.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": "The SELECT SQL query to execute.",
+                    },
+                },
+                "required": ["query"],
+            },
+        ),
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    if name == "list_tables":
+        return await _list_tables()
+    elif name == "describe_table":
+        return await _describe_table(arguments["table_name"])
+    elif name == "run_select_query":
+        return await _run_select_query(arguments["query"])
+    else:
+        raise ValueError(f"Unknown tool: {name}")
+
+
+async def _list_tables() -> list[TextContent]:
+    error = await _ensure_pool()
+    if error:
+        return [error]
+
+    schema = DB_SCHEMA
+    async with _pool.acquire() as conn:
+        rows = await conn.fetch(
+            f"SELECT table_name FROM information_schema.tables "
+            f"WHERE table_schema = '{schema}' AND table_type = 'BASE TABLE' "
+            f"ORDER BY table_name"
+        )
+
+        if not rows:
+            return [TextContent(type="text", text="No tables found in the database.")]
+
+        lines = []
+        for row in rows:
+            table_name = row["table_name"]
+            count = await conn.fetchval(
+                f'SELECT COUNT(*) FROM "{schema}"."{table_name}"'
+            )
+            lines.append(f"{table_name} ({count} rows)")
+
+        return [TextContent(type="text", text="\n".join(lines))]
+
+
+async def _describe_table(table_name: str) -> list[TextContent]:
+    if not _is_safe_identifier(table_name):
+        return [
+            TextContent(
+                type="text",
+                text=f"Error: Invalid table name '{table_name}'. "
+                f"Table name must contain only alphanumeric characters and underscores.",
+            )
+        ]
+
+    error = await _ensure_pool()
+    if error:
+        return [error]
+
+    schema = DB_SCHEMA
+    async with _pool.acquire() as conn:
+        exists = await conn.fetchval(
+            f"SELECT COUNT(*) FROM information_schema.tables "
+            f"WHERE table_schema = '{schema}' AND table_name = $1",
+            table_name,
+        )
+
+        if not exists:
+            return [
+                TextContent(
+                    type="text",
+                    text=f"Table '{table_name}' does not exist.",
+                )
+            ]
+
+        columns = await conn.fetch(
+            f"""
+            SELECT
+                c.column_name,
+                c.data_type,
+                c.is_nullable,
+                c.column_default,
+                CASE WHEN pk.column_name IS NOT NULL THEN true ELSE false END AS is_pk
+            FROM information_schema.columns c
+            LEFT JOIN (
+                SELECT kcu.column_name
+                FROM information_schema.table_constraints tc
+                JOIN information_schema.key_column_usage kcu
+                    ON tc.constraint_name = kcu.constraint_name
+                    AND tc.table_schema = kcu.table_schema
+                WHERE tc.table_schema = '{schema}'
+                    AND tc.table_name = $1
+                    AND tc.constraint_type = 'PRIMARY KEY'
+            ) pk ON c.column_name = pk.column_name
+            WHERE c.table_schema = '{schema}'
+                AND c.table_name = $1
+            ORDER BY c.ordinal_position
+            """,
+            table_name,
+        )
+
+        fks = await conn.fetch(
+            f"""
+            SELECT
+                kcu.column_name,
+                ccu.table_name AS foreign_table_name,
+                ccu.column_name AS foreign_column_name
+            FROM information_schema.table_constraints tc
+            JOIN information_schema.key_column_usage kcu
+                ON tc.constraint_name = kcu.constraint_name
+                AND tc.table_schema = kcu.table_schema
+            JOIN information_schema.constraint_column_usage ccu
+                ON tc.constraint_name = ccu.constraint_name
+                AND tc.table_schema = ccu.table_schema
+            WHERE tc.table_schema = '{schema}'
+                AND tc.table_name = $1
+                AND tc.constraint_type = 'FOREIGN KEY'
+            """,
+            table_name,
+        )
+
+        indexes = await conn.fetch(
+            f"SELECT indexname, indexdef FROM pg_indexes "
+            f"WHERE schemaname = '{schema}' AND tablename = $1",
+            table_name,
+        )
+
+        lines = [f"Table: {table_name}", "", "Columns:"]
+        for col in columns:
+            pk = " PRIMARY KEY" if col["is_pk"] else ""
+            notnull = " NOT NULL" if col["is_nullable"] == "NO" else ""
+            default = (
+                f" DEFAULT {col['column_default']}" if col["column_default"] else ""
+            )
+            lines.append(
+                f"  {col['column_name']} {col['data_type']}{pk}{notnull}{default}"
+            )
+
+        if fks:
+            lines.append("")
+            lines.append("Foreign Keys:")
+            for fk in fks:
+                lines.append(
+                    f"  {fk['column_name']} -> {fk['foreign_table_name']}.{fk['foreign_column_name']}"
+                )
+
+        if indexes:
+            lines.append("")
+            lines.append("Indexes:")
+            for idx in indexes:
+                unique = "UNIQUE" in (idx["indexdef"] or "")
+                lines.append(f"  {idx['indexname']} (unique: {unique})")
+
+        return [TextContent(type="text", text="\n".join(lines))]
+
+
+async def _run_select_query(query: str) -> list[TextContent]:
+    stripped = query.strip().upper()
+    if not stripped.startswith("SELECT"):
+        return [
+            TextContent(
+                type="text",
+                text="Error: Only SELECT queries are allowed for safety.",
+            )
+        ]
+
+    error = await _ensure_pool()
+    if error:
+        return [error]
+
+    async with _pool.acquire() as conn:
+        try:
+            rows = await conn.fetch(query)
+        except Exception as e:
+            return [TextContent(type="text", text=f"Error executing query: {str(e)}")]
+
+        if not rows:
+            return [TextContent(type="text", text="Query returned no rows.")]
+
+        headers = list(rows[0].keys())
+        lines = ["| " + " | ".join(headers) + " |"]
+        lines.append("|" + "|".join(["---" for _ in headers]) + "|")
+        for row in rows:
+            values = [str(v) if v is not None else "NULL" for v in row.values()]
+            lines.append("| " + " | ".join(values) + " |")
+
+        output = "\n".join(lines)
+        if len(rows) > 100:
+            output += f"\n\n({len(rows)} rows returned, showing all)"
+
+        return [TextContent(type="text", text=output)]
+
+
+async def main():
+    async with stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())
+
+
+def cli():
+    """Entry point for the console script."""
+    asyncio.run(main())