cubrid-mcp-server 0.4.0__tar.gz

cubrid_mcp_server-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Yeongseon Choe, Gyeongjun Paik
+
+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.

cubrid_mcp_server-0.4.0/NOTICE

@@ -0,0 +1,8 @@
+cubrid-mcp-server
+Copyright (c) 2025-2026 Yeongseon Choe, Gyeongjun Paik
+
+This product is licensed under the MIT License (see LICENSE).
+
+This package is an original implementation. It contains no third-party
+source code and embeds no third-party assets. Runtime dependencies and
+their licenses are enumerated in THIRD_PARTY_LICENSES.md.

cubrid_mcp_server-0.4.0/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: cubrid-mcp-server
+Version: 0.4.0
+Summary: Model Context Protocol server for CUBRID database
+Author-email: Yeongseon Choe <yeongseon.choe@gmail.com>, Gyeongjun Paik <paikend@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cubrid-lab/cubrid-mcp-server
+Project-URL: Repository, https://github.com/cubrid-lab/cubrid-mcp-server
+Project-URL: Issues, https://github.com/cubrid-lab/cubrid-mcp-server/issues
+Project-URL: Documentation, https://cubrid-lab.github.io/cubrid-mcp-server/
+Project-URL: Changelog, https://github.com/cubrid-lab/cubrid-mcp-server/blob/main/CHANGELOG.md
+Keywords: CUBRID,database,MCP,Model Context Protocol,LLM
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python
+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
+Classifier: Topic :: Database :: Front-Ends
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: fastmcp<4,>=3.0
+Requires-Dist: pycubrid<2,>=1.4
+Requires-Dist: sqlparse<1,>=0.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff==0.16.6; extra == "dev"
+Requires-Dist: mypy==2.3.1; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+Dynamic: license-file
+
+# cubrid-mcp-server
+
+[![coverage](https://codecov.io/gh/cubrid-lab/cubrid-mcp-server/branch/main/graph/badge.svg)](https://codecov.io/gh/cubrid-lab/cubrid-mcp-server)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for [CUBRID](https://www.cubrid.org/), enabling LLMs to safely inspect schemas and execute read-only queries via [pycubrid](https://pypi.org/project/pycubrid/).
+
+<!-- mcp-name: io.github.cubrid-lab/cubrid-mcp-server -->
+
+## Features
+
+| Tool | Description |
+|------|-------------|
+| `all_table_names` | List every user table in the database |
+| `filter_table_names` | Substring search over table names |
+| `schema_definitions` | Column types, nullability, defaults, and primary key info |
+| `describe_table` | Full metadata: columns, primary key, and indexes in one call |
+| `list_indexes` | Indexes for a table with key columns and flags |
+| `explain_query` | Execution plan/trace for a `SELECT`/`WITH` (via CUBRID `SHOW TRACE`) |
+| `table_row_counts` | `COUNT(*)` for one or many tables |
+| `list_serials` | CUBRID `SERIAL` sequences with current value and bounds |
+| `list_class_hierarchy` | CUBRID `CLASS` inheritance relationships |
+| `execute_query` | Run read-only SQL with automatic output truncation |
+| `health_check` | Verify database connectivity on demand |
+| `execute_write` | Run a single `INSERT`/`UPDATE`/`DELETE` in an atomic transaction (**only registered when opt-in write mode is enabled**) |
+
+### Resources
+
+Schema metadata is also exposed as read-only [MCP Resources](https://modelcontextprotocol.io/docs/concepts/resources), so clients can discover and read schema context without a tool call. Resources reuse the same read-only catalog queries as the tools — no additional data access or write surface.
+
+| Resource URI | Description |
+|--------------|-------------|
+| `cubrid://schema` | Whole-schema index: every user table with its per-table resource URI |
+| `cubrid://schema/{table}` | Per-table metadata (columns, primary key, indexes) — mirrors `describe_table` |
+
+Both return `application/json`. Table names in `{table}` are percent-decoded by URI-template matching; an unknown or system table produces a resource-read error, matching the `describe_table` tool.
+
+## Prompts
+
+The server also exposes a small set of **MCP Prompt templates** — reusable, guided
+starting points for common inspection tasks. Prompts are **guidance-only**: each one
+returns text that tells the client which of the existing read-only tools to call and
+in what order. They never touch the database, execute SQL, or add any new data-access
+surface, and any argument you pass is fenced and treated strictly as untrusted data.
+The prompts are advisory templates only — the actual read-only enforcement remains in
+the underlying tools (`execute_query`/`explain_query` via `safety.py`).
+
+| Prompt | Arguments | Description |
+|--------|-----------|-------------|
+| `summarize_table` | `table` | Describe a table, then sample it with a bounded read-only query |
+| `explain_query` | `sql` | Obtain and interpret a `SELECT`/`WITH` execution plan via `explain_query` |
+| `inspect_schema` | _(none)_ | Build a high-level overview of the whole schema from the read-only tools |
+| `find_index_candidates` | `table` | Review a table's index coverage for potential review areas |
+
+## Quick Start
+
+### Configure
+
+Set the required environment variables:
+
+```bash
+export CUBRID_HOST=localhost
+export CUBRID_PORT=33000        # optional, default: 33000
+export CUBRID_USER=readonly_user   # a CUBRID user with SELECT-only grants (see Security)
+export CUBRID_PASSWORD=secret
+export CUBRID_DATABASE=mydb
+```
+
+Optional settings:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CUBRID_MCP_READONLY` | `1` | Enforce read-only SQL whitelist |
+| `CUBRID_MCP_MAX_CHARS` | `4000` | Max characters in query output |
+| `CUBRID_MCP_MAX_ROWS` | `1000` | Max rows returned by `execute_query` before truncation |
+| `CUBRID_MCP_MAX_SQL_LENGTH` | `65536` | Max length (characters) of a submitted SQL statement |
+| `CUBRID_MCP_QUERY_TIMEOUT` | `30` | Per-statement socket read timeout in seconds. If the server sends no data within this window the query is aborted and the connection is reset. This is a socket read timeout, not a true server-side statement timeout. |
+| `CUBRID_MCP_AUDIT_LOG` | `0` | Opt-in audit logging. When enabled, emits one redaction-safe JSON record per executed statement (`execute_query`/`explain_query`/`execute_write`) to **stderr** — see [Logging](#logging). Honoured per connection (`CUBRID_<NAME>_MCP_AUDIT_LOG`). |
+| `CUBRID_MCP_WRITE` | `0` | Opt-in write mode. When enabled (`1`), registers the `execute_write` tool for single-statement DML. Honoured per connection (`CUBRID_<NAME>_MCP_WRITE`); the tool is registered when any connection enables it. Off by default. |
+
+### Multiple connections
+
+By default the bare `CUBRID_*` variables define a single connection named `default`.
+You can serve additional CUBRID databases from the same process by listing extra
+connection names in `CUBRID_CONNECTIONS` (comma-separated) and providing
+`CUBRID_<NAME>_*` variables for each. Every tool accepts an optional `connection`
+argument selecting which connection to target; omitting it (or passing `default`)
+uses the bare-variable connection, so existing single-database setups are unchanged.
+
+```bash
+# Default connection (unchanged)
+export CUBRID_HOST=localhost
+export CUBRID_USER=readonly_user
+export CUBRID_PASSWORD=secret
+export CUBRID_DATABASE=mydb
+
+# Additional named connections
+export CUBRID_CONNECTIONS=reporting,analytics
+
+export CUBRID_REPORTING_HOST=reporting-db
+export CUBRID_REPORTING_USER=readonly_user
+export CUBRID_REPORTING_PASSWORD=secret
+export CUBRID_REPORTING_DATABASE=reports
+export CUBRID_REPORTING_MCP_MAX_ROWS=500   # optional per-connection tuning
+
+export CUBRID_ANALYTICS_HOST=analytics-db
+export CUBRID_ANALYTICS_USER=readonly_user
+export CUBRID_ANALYTICS_PASSWORD=secret
+export CUBRID_ANALYTICS_DATABASE=analytics
+```
+
+Notes:
+
+- Connection names must match `[A-Za-z0-9_]+` and are matched case-insensitively.
+- `default` is reserved (it always comes from the bare `CUBRID_*` variables) and
+  cannot appear in `CUBRID_CONNECTIONS`.
+- For a named connection `<NAME>`, connection fields live at `CUBRID_<NAME>_HOST`
+  etc. and the optional MCP tuning knobs at `CUBRID_<NAME>_MCP_*` (same suffixes as
+  the global ones). Named connections do **not** inherit values from the bare vars.
+- Selecting an unknown connection returns a clear error listing the available names.
+- Each connection has its own read-only enforcement, so a named connection can set
+  `CUBRID_<NAME>_MCP_READONLY` independently of the default.
+
+### Run
+
+### Run from PyPI
+
+Use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to run directly from PyPI:
+
+```bash
+uvx cubrid-mcp-server
+```
+
+Or with `pipx`:
+
+```bash
+pipx run cubrid-mcp-server
+```
+
+### Run from source
+
+```bash
+git clone https://github.com/cubrid-lab/cubrid-mcp-server.git
+cd cubrid-mcp-server
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+cubrid-mcp-server
+```
+
+## MCP Client Integration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cubrid": {
+      "command": "uvx",
+      "args": ["cubrid-mcp-server"],
+      "env": {
+        "CUBRID_HOST": "localhost",
+        "CUBRID_USER": "readonly_user",
+        "CUBRID_PASSWORD": "secret",
+        "CUBRID_DATABASE": "mydb"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "cubrid": {
+      "command": "uvx",
+      "args": ["cubrid-mcp-server"],
+      "env": {
+        "CUBRID_HOST": "localhost",
+        "CUBRID_USER": "readonly_user",
+        "CUBRID_PASSWORD": "secret",
+        "CUBRID_DATABASE": "mydb"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cubrid": {
+      "command": "uvx",
+      "args": ["cubrid-mcp-server"],
+      "env": {
+        "CUBRID_HOST": "localhost",
+        "CUBRID_USER": "readonly_user",
+        "CUBRID_PASSWORD": "secret",
+        "CUBRID_DATABASE": "mydb"
+      }
+    }
+  }
+}
+```
+
+## Security
+
+The server is **read-only by default**. A code-level SQL whitelist allows only `SELECT`, `SHOW`, `DESC`, `DESCRIBE`, `EXPLAIN`, and `WITH` statements. Multi-statement queries are rejected.
+
+> **The SQL whitelist is defense-in-depth, not a security boundary.** It is a non-validating parser-based guardrail against obvious mistakes. The real enforcement layer is the database itself: **always run the server as a CUBRID user that has only `SELECT` grants** on the tables the model may read. See [`SECURITY.md`](./SECURITY.md).
+
+For production use, also configure a read-only database user. See [`SECURITY.md`](./SECURITY.md) for the recommended setup.
+
+### Write mode (opt-in)
+
+Write access is **disabled by default**. Setting `CUBRID_MCP_WRITE=1` registers an additional `execute_write` tool that accepts a **single** `INSERT`, `UPDATE`, or `DELETE` statement and runs it in an explicit transaction (commit on success, rollback on any error). When write mode is off the tool is not registered at all, so no write path is exposed in MCP capability discovery. With multiple connections configured, the tool is registered when **any** connection enables writes (via `CUBRID_MCP_WRITE` or `CUBRID_<NAME>_MCP_WRITE`).
+
+Constraints and rationale:
+
+- **Single-statement DML only.** Standalone reads, DDL (`CREATE`/`ALTER`/`DROP`/`TRUNCATE`), transaction-control, and multi-statement input are rejected. (A single DML statement may still legally contain subqueries, e.g. `INSERT ... SELECT`.)
+- **DDL is intentionally unsupported.** CUBRID auto-commits DDL, which defeats the rollback guarantee, so it is excluded from write mode.
+- **Write mode is per-connection.** `execute_write` accepts the same optional `connection` argument as the read tools and runs against that connection; a connection whose `CUBRID_<NAME>_MCP_WRITE` is off refuses the write even when another connection enables it.
+- `execute_query` remains **read-only regardless** of the write-mode flag.
+- Enforcement is defense-in-depth; still run the server as a CUBRID user granted only the privileges it needs. See [`SECURITY.md`](./SECURITY.md).
+
+## Logging
+
+The server speaks the MCP **stdio transport**, where `stdout` carries the JSON-RPC protocol stream. Anything written to `stdout` by the server or its dependencies will corrupt that stream and break the client connection. For this reason **all logging is routed to `stderr`**, and you should keep it that way: when adding custom logging or diagnostics, never `print()` to `stdout` — use the standard `logging` module (which is configured to emit on `stderr`) or write to `stderr` explicitly. The log level defaults to `INFO`.
+
+Errors surfaced back to the LLM client are **sanitized**: only the exception category (e.g. `query failed: OperationalError`) is returned, while the full exception detail is logged to `stderr` for operators. This keeps schema details, hostnames, SQL fragments, and configuration values out of client-visible messages.
+
+### Audit logging (opt-in)
+
+Set `CUBRID_MCP_AUDIT_LOG=1` to record every executed statement (`execute_query`, `explain_query`, and `execute_write`) as a single structured JSON line on **stderr**. It is **off by default** and honoured **per connection** — a named connection sets `CUBRID_<NAME>_MCP_AUDIT_LOG` independently of the default. Each record is redaction-safe and contains only:
+
+| Field | Description |
+|-------|-------------|
+| `tool` | The MCP tool that ran the statement (`execute_query` / `explain_query` / `execute_write`). |
+| `status` | `ok` or `error`. |
+| `category` | The leading SQL keyword only (e.g. `SELECT`, `WITH`) — never the full statement. |
+| `identifiers` | Table names extracted after `FROM`/`JOIN` via a strict identifier regex; anything that is not a bare identifier (values, literals, expressions) is dropped. |
+| `sql_length` | Length of the submitted SQL, in characters. |
+| `row_count`, `truncated` | Result size and whether output was truncated (success only). |
+| `duration_ms` | Wall-clock duration of the call, in integer milliseconds. |
+| `error_type` | On failure, the exception **class name only** (via the same sanitization as client-facing errors). |
+
+The **raw SQL text, bound parameters, and literal values are never logged**, so secrets embedded in a query (e.g. `WHERE token = '...'`) do not reach the audit stream. Records go to `stderr` only and never to `stdout`.
+
+
+## Development
+
+```bash
+git clone https://github.com/cubrid-lab/cubrid-mcp-server.git
+cd cubrid-mcp-server
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Lint & type check
+ruff check .
+mypy cubrid_mcp_server
+
+# Unit tests
+pytest -m "not integration"
+
+# Integration tests (requires running CUBRID)
+export CUBRID_HOST=localhost CUBRID_USER=dba CUBRID_PASSWORD="" CUBRID_DATABASE=demodb
+pytest -m integration
+```
+
+## Disclaimer
+
+> This project is part of [CUBRID Lab](https://github.com/cubrid-lab), an independent open-source initiative for CUBRID developer tooling, and is not affiliated with, sponsored by, or endorsed by CUBRID Corporation or the official CUBRID project.
+
+
+## License
+
+MIT (see [`LICENSE`](./LICENSE)).

cubrid_mcp_server-0.4.0/README.md

@@ -0,0 +1,285 @@
+# cubrid-mcp-server
+
+[![coverage](https://codecov.io/gh/cubrid-lab/cubrid-mcp-server/branch/main/graph/badge.svg)](https://codecov.io/gh/cubrid-lab/cubrid-mcp-server)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for [CUBRID](https://www.cubrid.org/), enabling LLMs to safely inspect schemas and execute read-only queries via [pycubrid](https://pypi.org/project/pycubrid/).
+
+<!-- mcp-name: io.github.cubrid-lab/cubrid-mcp-server -->
+
+## Features
+
+| Tool | Description |
+|------|-------------|
+| `all_table_names` | List every user table in the database |
+| `filter_table_names` | Substring search over table names |
+| `schema_definitions` | Column types, nullability, defaults, and primary key info |
+| `describe_table` | Full metadata: columns, primary key, and indexes in one call |
+| `list_indexes` | Indexes for a table with key columns and flags |
+| `explain_query` | Execution plan/trace for a `SELECT`/`WITH` (via CUBRID `SHOW TRACE`) |
+| `table_row_counts` | `COUNT(*)` for one or many tables |
+| `list_serials` | CUBRID `SERIAL` sequences with current value and bounds |
+| `list_class_hierarchy` | CUBRID `CLASS` inheritance relationships |
+| `execute_query` | Run read-only SQL with automatic output truncation |
+| `health_check` | Verify database connectivity on demand |
+| `execute_write` | Run a single `INSERT`/`UPDATE`/`DELETE` in an atomic transaction (**only registered when opt-in write mode is enabled**) |
+
+### Resources
+
+Schema metadata is also exposed as read-only [MCP Resources](https://modelcontextprotocol.io/docs/concepts/resources), so clients can discover and read schema context without a tool call. Resources reuse the same read-only catalog queries as the tools — no additional data access or write surface.
+
+| Resource URI | Description |
+|--------------|-------------|
+| `cubrid://schema` | Whole-schema index: every user table with its per-table resource URI |
+| `cubrid://schema/{table}` | Per-table metadata (columns, primary key, indexes) — mirrors `describe_table` |
+
+Both return `application/json`. Table names in `{table}` are percent-decoded by URI-template matching; an unknown or system table produces a resource-read error, matching the `describe_table` tool.
+
+## Prompts
+
+The server also exposes a small set of **MCP Prompt templates** — reusable, guided
+starting points for common inspection tasks. Prompts are **guidance-only**: each one
+returns text that tells the client which of the existing read-only tools to call and
+in what order. They never touch the database, execute SQL, or add any new data-access
+surface, and any argument you pass is fenced and treated strictly as untrusted data.
+The prompts are advisory templates only — the actual read-only enforcement remains in
+the underlying tools (`execute_query`/`explain_query` via `safety.py`).
+
+| Prompt | Arguments | Description |
+|--------|-----------|-------------|
+| `summarize_table` | `table` | Describe a table, then sample it with a bounded read-only query |
+| `explain_query` | `sql` | Obtain and interpret a `SELECT`/`WITH` execution plan via `explain_query` |
+| `inspect_schema` | _(none)_ | Build a high-level overview of the whole schema from the read-only tools |
+| `find_index_candidates` | `table` | Review a table's index coverage for potential review areas |
+
+## Quick Start
+
+### Configure
+
+Set the required environment variables:
+
+```bash
+export CUBRID_HOST=localhost
+export CUBRID_PORT=33000        # optional, default: 33000
+export CUBRID_USER=readonly_user   # a CUBRID user with SELECT-only grants (see Security)
+export CUBRID_PASSWORD=secret
+export CUBRID_DATABASE=mydb
+```
+
+Optional settings:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CUBRID_MCP_READONLY` | `1` | Enforce read-only SQL whitelist |
+| `CUBRID_MCP_MAX_CHARS` | `4000` | Max characters in query output |
+| `CUBRID_MCP_MAX_ROWS` | `1000` | Max rows returned by `execute_query` before truncation |
+| `CUBRID_MCP_MAX_SQL_LENGTH` | `65536` | Max length (characters) of a submitted SQL statement |
+| `CUBRID_MCP_QUERY_TIMEOUT` | `30` | Per-statement socket read timeout in seconds. If the server sends no data within this window the query is aborted and the connection is reset. This is a socket read timeout, not a true server-side statement timeout. |
+| `CUBRID_MCP_AUDIT_LOG` | `0` | Opt-in audit logging. When enabled, emits one redaction-safe JSON record per executed statement (`execute_query`/`explain_query`/`execute_write`) to **stderr** — see [Logging](#logging). Honoured per connection (`CUBRID_<NAME>_MCP_AUDIT_LOG`). |
+| `CUBRID_MCP_WRITE` | `0` | Opt-in write mode. When enabled (`1`), registers the `execute_write` tool for single-statement DML. Honoured per connection (`CUBRID_<NAME>_MCP_WRITE`); the tool is registered when any connection enables it. Off by default. |
+
+### Multiple connections
+
+By default the bare `CUBRID_*` variables define a single connection named `default`.
+You can serve additional CUBRID databases from the same process by listing extra
+connection names in `CUBRID_CONNECTIONS` (comma-separated) and providing
+`CUBRID_<NAME>_*` variables for each. Every tool accepts an optional `connection`
+argument selecting which connection to target; omitting it (or passing `default`)
+uses the bare-variable connection, so existing single-database setups are unchanged.
+
+```bash
+# Default connection (unchanged)
+export CUBRID_HOST=localhost
+export CUBRID_USER=readonly_user
+export CUBRID_PASSWORD=secret
+export CUBRID_DATABASE=mydb
+
+# Additional named connections
+export CUBRID_CONNECTIONS=reporting,analytics
+
+export CUBRID_REPORTING_HOST=reporting-db
+export CUBRID_REPORTING_USER=readonly_user
+export CUBRID_REPORTING_PASSWORD=secret
+export CUBRID_REPORTING_DATABASE=reports
+export CUBRID_REPORTING_MCP_MAX_ROWS=500   # optional per-connection tuning
+
+export CUBRID_ANALYTICS_HOST=analytics-db
+export CUBRID_ANALYTICS_USER=readonly_user
+export CUBRID_ANALYTICS_PASSWORD=secret
+export CUBRID_ANALYTICS_DATABASE=analytics
+```
+
+Notes:
+
+- Connection names must match `[A-Za-z0-9_]+` and are matched case-insensitively.
+- `default` is reserved (it always comes from the bare `CUBRID_*` variables) and
+  cannot appear in `CUBRID_CONNECTIONS`.
+- For a named connection `<NAME>`, connection fields live at `CUBRID_<NAME>_HOST`
+  etc. and the optional MCP tuning knobs at `CUBRID_<NAME>_MCP_*` (same suffixes as
+  the global ones). Named connections do **not** inherit values from the bare vars.
+- Selecting an unknown connection returns a clear error listing the available names.
+- Each connection has its own read-only enforcement, so a named connection can set
+  `CUBRID_<NAME>_MCP_READONLY` independently of the default.
+
+### Run
+
+### Run from PyPI
+
+Use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to run directly from PyPI:
+
+```bash
+uvx cubrid-mcp-server
+```
+
+Or with `pipx`:
+
+```bash
+pipx run cubrid-mcp-server
+```
+
+### Run from source
+
+```bash
+git clone https://github.com/cubrid-lab/cubrid-mcp-server.git
+cd cubrid-mcp-server
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+cubrid-mcp-server
+```
+
+## MCP Client Integration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cubrid": {
+      "command": "uvx",
+      "args": ["cubrid-mcp-server"],
+      "env": {
+        "CUBRID_HOST": "localhost",
+        "CUBRID_USER": "readonly_user",
+        "CUBRID_PASSWORD": "secret",
+        "CUBRID_DATABASE": "mydb"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "cubrid": {
+      "command": "uvx",
+      "args": ["cubrid-mcp-server"],
+      "env": {
+        "CUBRID_HOST": "localhost",
+        "CUBRID_USER": "readonly_user",
+        "CUBRID_PASSWORD": "secret",
+        "CUBRID_DATABASE": "mydb"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cubrid": {
+      "command": "uvx",
+      "args": ["cubrid-mcp-server"],
+      "env": {
+        "CUBRID_HOST": "localhost",
+        "CUBRID_USER": "readonly_user",
+        "CUBRID_PASSWORD": "secret",
+        "CUBRID_DATABASE": "mydb"
+      }
+    }
+  }
+}
+```
+
+## Security
+
+The server is **read-only by default**. A code-level SQL whitelist allows only `SELECT`, `SHOW`, `DESC`, `DESCRIBE`, `EXPLAIN`, and `WITH` statements. Multi-statement queries are rejected.
+
+> **The SQL whitelist is defense-in-depth, not a security boundary.** It is a non-validating parser-based guardrail against obvious mistakes. The real enforcement layer is the database itself: **always run the server as a CUBRID user that has only `SELECT` grants** on the tables the model may read. See [`SECURITY.md`](./SECURITY.md).
+
+For production use, also configure a read-only database user. See [`SECURITY.md`](./SECURITY.md) for the recommended setup.
+
+### Write mode (opt-in)
+
+Write access is **disabled by default**. Setting `CUBRID_MCP_WRITE=1` registers an additional `execute_write` tool that accepts a **single** `INSERT`, `UPDATE`, or `DELETE` statement and runs it in an explicit transaction (commit on success, rollback on any error). When write mode is off the tool is not registered at all, so no write path is exposed in MCP capability discovery. With multiple connections configured, the tool is registered when **any** connection enables writes (via `CUBRID_MCP_WRITE` or `CUBRID_<NAME>_MCP_WRITE`).
+
+Constraints and rationale:
+
+- **Single-statement DML only.** Standalone reads, DDL (`CREATE`/`ALTER`/`DROP`/`TRUNCATE`), transaction-control, and multi-statement input are rejected. (A single DML statement may still legally contain subqueries, e.g. `INSERT ... SELECT`.)
+- **DDL is intentionally unsupported.** CUBRID auto-commits DDL, which defeats the rollback guarantee, so it is excluded from write mode.
+- **Write mode is per-connection.** `execute_write` accepts the same optional `connection` argument as the read tools and runs against that connection; a connection whose `CUBRID_<NAME>_MCP_WRITE` is off refuses the write even when another connection enables it.
+- `execute_query` remains **read-only regardless** of the write-mode flag.
+- Enforcement is defense-in-depth; still run the server as a CUBRID user granted only the privileges it needs. See [`SECURITY.md`](./SECURITY.md).
+
+## Logging
+
+The server speaks the MCP **stdio transport**, where `stdout` carries the JSON-RPC protocol stream. Anything written to `stdout` by the server or its dependencies will corrupt that stream and break the client connection. For this reason **all logging is routed to `stderr`**, and you should keep it that way: when adding custom logging or diagnostics, never `print()` to `stdout` — use the standard `logging` module (which is configured to emit on `stderr`) or write to `stderr` explicitly. The log level defaults to `INFO`.
+
+Errors surfaced back to the LLM client are **sanitized**: only the exception category (e.g. `query failed: OperationalError`) is returned, while the full exception detail is logged to `stderr` for operators. This keeps schema details, hostnames, SQL fragments, and configuration values out of client-visible messages.
+
+### Audit logging (opt-in)
+
+Set `CUBRID_MCP_AUDIT_LOG=1` to record every executed statement (`execute_query`, `explain_query`, and `execute_write`) as a single structured JSON line on **stderr**. It is **off by default** and honoured **per connection** — a named connection sets `CUBRID_<NAME>_MCP_AUDIT_LOG` independently of the default. Each record is redaction-safe and contains only:
+
+| Field | Description |
+|-------|-------------|
+| `tool` | The MCP tool that ran the statement (`execute_query` / `explain_query` / `execute_write`). |
+| `status` | `ok` or `error`. |
+| `category` | The leading SQL keyword only (e.g. `SELECT`, `WITH`) — never the full statement. |
+| `identifiers` | Table names extracted after `FROM`/`JOIN` via a strict identifier regex; anything that is not a bare identifier (values, literals, expressions) is dropped. |
+| `sql_length` | Length of the submitted SQL, in characters. |
+| `row_count`, `truncated` | Result size and whether output was truncated (success only). |
+| `duration_ms` | Wall-clock duration of the call, in integer milliseconds. |
+| `error_type` | On failure, the exception **class name only** (via the same sanitization as client-facing errors). |
+
+The **raw SQL text, bound parameters, and literal values are never logged**, so secrets embedded in a query (e.g. `WHERE token = '...'`) do not reach the audit stream. Records go to `stderr` only and never to `stdout`.
+
+
+## Development
+
+```bash
+git clone https://github.com/cubrid-lab/cubrid-mcp-server.git
+cd cubrid-mcp-server
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Lint & type check
+ruff check .
+mypy cubrid_mcp_server
+
+# Unit tests
+pytest -m "not integration"
+
+# Integration tests (requires running CUBRID)
+export CUBRID_HOST=localhost CUBRID_USER=dba CUBRID_PASSWORD="" CUBRID_DATABASE=demodb
+pytest -m integration
+```
+
+## Disclaimer
+
+> This project is part of [CUBRID Lab](https://github.com/cubrid-lab), an independent open-source initiative for CUBRID developer tooling, and is not affiliated with, sponsored by, or endorsed by CUBRID Corporation or the official CUBRID project.
+
+
+## License
+
+MIT (see [`LICENSE`](./LICENSE)).

cubrid_mcp_server-0.4.0/cubrid_mcp_server/__init__.py

@@ -0,0 +1,3 @@
+"""Model Context Protocol server for CUBRID database."""
+
+__version__ = "0.4.0"

cubrid_mcp_server-0.4.0/cubrid_mcp_server/__main__.py

@@ -0,0 +1,4 @@
+from cubrid_mcp_server.server import main
+
+if __name__ == "__main__":
+    main()