mysql-client-mcp-py 0.2.0__tar.gz

mysql_client_mcp_py-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dong_tech
+
+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.

mysql_client_mcp_py-0.2.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: mysql-client-mcp-py
+Version: 0.2.0
+Summary: MCP Server for MySQL-protocol databases - schema discovery, SQL analysis, safe execution
+Project-URL: Homepage, https://github.com/dong-tech/mysql-client-mcp-py
+Project-URL: Repository, https://github.com/dong-tech/mysql-client-mcp-py
+Author: dong_tech
+License: MIT
+License-File: LICENSE
+Keywords: ai,database,llm,mcp,model-context-protocol,mysql
+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: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pymysql>=1.1.0
+Requires-Dist: sqlparse>=0.5.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MySQL Client MCP Server (mysql-client-mcp-py)
+
+支持 MySQL 协议的 MCP Server：连接与元数据发现、SQL 分析、安全执行（单条，DDL 不执行，写操作需确认）。
+
+## 环境变量
+
+### 必填（单连接）
+
+| 变量 | 说明 |
+|------|------|
+| `DB_HOST` | 主机 |
+| `DB_USER` | 用户名 |
+| `DB_PASSWORD` | 密码 |
+| `DB_PORT` | 端口，默认 3306 |
+| `DB_DATABASE` | 默认库，可选 |
+
+### 多环境（仅方式二：TEST_DB_PROFILES / UAT_DB_PROFILES / PROD_DB_PROFILES）
+
+- **多环境只配三个变量**：`TEST_DB_PROFILES`、`UAT_DB_PROFILES`、`PROD_DB_PROFILES`，每个为 **JSON 数组** `[{},{}]`，表示该环境下的一条或多条连接。**不需**再配 `DB_HOST`/`DB_USER`/`DB_PASSWORD`。
+- 每个数组项需含 `host`、`port`、`user`、`password`；可选 `database`、`description`、`databases`、`name`（子名）。
+- Profile 名：`test_0`、`test_1`、`test_finance`（若该项含 `"name":"finance"`）、`uat_0`、`prod_0` 等。默认连接取 prod 下第一个（如 `prod_0`）。
+- **单环境**：不设任一 `*_DB_PROFILES` 时，只配 `DB_HOST`、`DB_USER`、`DB_PASSWORD`（及可选 `DB_PORT`、`DB_DATABASE`）。
+
+**示例（test / uat / prod 三环境）**：
+
+```bash
+TEST_DB_PROFILES='[{"host":"test-db.example.com","port":3306,"user":"t1","password":"xxx","database":"app_test","description":"测试环境","databases":["app_test"]}]'
+UAT_DB_PROFILES='[{"host":"uat-db.example.com","port":3306,"user":"u1","password":"yyy","database":"app_uat","description":"UAT环境","databases":["app_uat"]}]'
+PROD_DB_PROFILES='[{"host":"db.example.com","port":3306,"user":"ro","password":"zzz","database":"app","description":"生产环境","databases":["app","report"]}]'
+```
+
+测试环境多条连接时，数组里放多项即可，例如：
+
+```bash
+TEST_DB_PROFILES='[{"host":"t1","port":3306,"user":"u","password":"p","database":"app"},{"host":"t2","port":3306,"user":"u","password":"p","database":"order","name":"order"}]'
+# → profile 为 test_0、test_order
+```
+
+调用时传 `connection="test_0"` 或 `connection="prod_0"` 等指定用哪条。
+
+**让智能体根据自然语言选连接**：每项可配 `description`，`list_connections` / `db://config` 会展示，便于将用户说的「测试」「生产」映射到 profile 名。
+
+**每个连接聚焦若干数据库**：每项可配 `databases`：**不配置** → 默认所有库；**空数组 `[]`** → 不允许任何库；**非空数组** → 仅允许这些库。
+
+### 安全与行为
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `DB_READ_ONLY` | false | 为 true 时仅允许 SELECT |
+| `DB_MAX_SELECT_ROWS` | 10000 | SELECT 单次最大行数 |
+| `DB_QUERY_TIMEOUT_SECONDS` | 30 | 执行超时(秒) |
+| `DB_SLOW_QUERY_SECONDS` | 10 | 超过此秒数提示慢查询 |
+
+## 安装与运行
+
+```bash
+# 开发
+cd mysql-client-mcp-py
+uv sync
+uv run python -m mysql_client_mcp
+
+# 或安装后
+pip install -e .
+DB_HOST=localhost DB_USER=root DB_PASSWORD=xxx mysql-client-mcp-py
+```
+
+### Cursor / Claude 配置示例
+
+**发布到 PyPI 后**（用户已 `pip install mysql-client-mcp-py` 或使用 `uvx`）：
+
+**Cursor** 编辑 `~/.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "uvx",
+      "args": ["mysql-client-mcp-py"],
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_PORT": "3306",
+        "DB_USER": "root",
+        "DB_PASSWORD": "your-password",
+        "DB_DATABASE": "your_db"
+      }
+    }
+  }
+}
+```
+
+多环境示例（**只配 TEST_DB_PROFILES / UAT_DB_PROFILES / PROD_DB_PROFILES**，每项需含 `host`、`port`、`user`、`password`）：
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "uvx",
+      "args": ["mysql-client-mcp-py"],
+      "env": {
+        "TEST_DB_PROFILES": "[{\"host\":\"test-db.example.com\",\"port\":3306,\"user\":\"u\",\"password\":\"p\",\"database\":\"app\"}]",
+        "UAT_DB_PROFILES": "[{\"host\":\"uat-db.example.com\",\"port\":3306,\"user\":\"u\",\"password\":\"p\",\"database\":\"app\"}]",
+        "PROD_DB_PROFILES": "[{\"host\":\"db.example.com\",\"port\":3306,\"user\":\"ro\",\"password\":\"xxx\",\"database\":\"app\"}]"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "uvx",
+      "args": ["mysql-client-mcp-py"],
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_USER": "root",
+        "DB_PASSWORD": "your-password",
+        "DB_DATABASE": "your_db"
+      }
+    }
+  }
+}
+```
+
+若已用 pip 安装到当前环境，也可直接指定命令（无需 uvx）：
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "mysql-client-mcp-py",
+      "args": [],
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_USER": "root",
+        "DB_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+**本地开发**（未发布、从源码运行）：
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "uv",
+      "args": ["run", "python", "-m", "mysql_client_mcp"],
+      "cwd": "/path/to/mysql-client-mcp-py",
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_USER": "root",
+        "DB_PASSWORD": "your-password",
+        "DB_DATABASE": "your_db"
+      }
+    }
+  }
+}
+```
+
+## 工具
+
+| 工具 | 说明 |
+|------|------|
+| `list_connections` | 列出可用连接（profile + 可选说明），便于按用户自然语言选 connection |
+| `list_databases` | 列出数据库 |
+| `list_tables` | 列出指定库的表 |
+| `describe_table` | 表结构（列、行数、大小） |
+| `analyze_sql` | 分析 SQL（支持多条），不执行 |
+| `execute_sql` | 执行单条 SQL（DDL 不执行，写操作需 confirm=true） |
+
+## 资源
+
+- `db://config` - 配置与安全策略摘要
+- `db://databases` - 数据库列表
+- `db://tables/{database}` - 表列表
+- `db://table/{database}/{table}` - 单表结构
+
+## 提示词
+
+- **`ask_user_which_connection_prompt`** - **连接选择规则**：一开始无已选配置，必须先 list_connections 并让用户选择；用户选择后记住该 connection，后续默认使用且不再提示；仅当用户明确要切换环境时，再次列出并让用户选择
+- `query_safely_prompt` - 安全查询习惯
+- `explore_schema_prompt` - 先看 Schema 再写 SQL
+- `switch_connection_prompt` - 切换环境时带 connection 参数
+- `use_connection_from_natural_language_prompt` - 列出配置让用户选择，并根据用户说法映射到 connection
+
+## 设计文档
+
+参见项目内 `docs/plans/2025-03-14-database-mcp-design.md`。
+
+## License
+
+MIT

mysql_client_mcp_py-0.2.0/README.md

@@ -0,0 +1,198 @@
+# MySQL Client MCP Server (mysql-client-mcp-py)
+
+支持 MySQL 协议的 MCP Server：连接与元数据发现、SQL 分析、安全执行（单条，DDL 不执行，写操作需确认）。
+
+## 环境变量
+
+### 必填（单连接）
+
+| 变量 | 说明 |
+|------|------|
+| `DB_HOST` | 主机 |
+| `DB_USER` | 用户名 |
+| `DB_PASSWORD` | 密码 |
+| `DB_PORT` | 端口，默认 3306 |
+| `DB_DATABASE` | 默认库，可选 |
+
+### 多环境（仅方式二：TEST_DB_PROFILES / UAT_DB_PROFILES / PROD_DB_PROFILES）
+
+- **多环境只配三个变量**：`TEST_DB_PROFILES`、`UAT_DB_PROFILES`、`PROD_DB_PROFILES`，每个为 **JSON 数组** `[{},{}]`，表示该环境下的一条或多条连接。**不需**再配 `DB_HOST`/`DB_USER`/`DB_PASSWORD`。
+- 每个数组项需含 `host`、`port`、`user`、`password`；可选 `database`、`description`、`databases`、`name`（子名）。
+- Profile 名：`test_0`、`test_1`、`test_finance`（若该项含 `"name":"finance"`）、`uat_0`、`prod_0` 等。默认连接取 prod 下第一个（如 `prod_0`）。
+- **单环境**：不设任一 `*_DB_PROFILES` 时，只配 `DB_HOST`、`DB_USER`、`DB_PASSWORD`（及可选 `DB_PORT`、`DB_DATABASE`）。
+
+**示例（test / uat / prod 三环境）**：
+
+```bash
+TEST_DB_PROFILES='[{"host":"test-db.example.com","port":3306,"user":"t1","password":"xxx","database":"app_test","description":"测试环境","databases":["app_test"]}]'
+UAT_DB_PROFILES='[{"host":"uat-db.example.com","port":3306,"user":"u1","password":"yyy","database":"app_uat","description":"UAT环境","databases":["app_uat"]}]'
+PROD_DB_PROFILES='[{"host":"db.example.com","port":3306,"user":"ro","password":"zzz","database":"app","description":"生产环境","databases":["app","report"]}]'
+```
+
+测试环境多条连接时，数组里放多项即可，例如：
+
+```bash
+TEST_DB_PROFILES='[{"host":"t1","port":3306,"user":"u","password":"p","database":"app"},{"host":"t2","port":3306,"user":"u","password":"p","database":"order","name":"order"}]'
+# → profile 为 test_0、test_order
+```
+
+调用时传 `connection="test_0"` 或 `connection="prod_0"` 等指定用哪条。
+
+**让智能体根据自然语言选连接**：每项可配 `description`，`list_connections` / `db://config` 会展示，便于将用户说的「测试」「生产」映射到 profile 名。
+
+**每个连接聚焦若干数据库**：每项可配 `databases`：**不配置** → 默认所有库；**空数组 `[]`** → 不允许任何库；**非空数组** → 仅允许这些库。
+
+### 安全与行为
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `DB_READ_ONLY` | false | 为 true 时仅允许 SELECT |
+| `DB_MAX_SELECT_ROWS` | 10000 | SELECT 单次最大行数 |
+| `DB_QUERY_TIMEOUT_SECONDS` | 30 | 执行超时(秒) |
+| `DB_SLOW_QUERY_SECONDS` | 10 | 超过此秒数提示慢查询 |
+
+## 安装与运行
+
+```bash
+# 开发
+cd mysql-client-mcp-py
+uv sync
+uv run python -m mysql_client_mcp
+
+# 或安装后
+pip install -e .
+DB_HOST=localhost DB_USER=root DB_PASSWORD=xxx mysql-client-mcp-py
+```
+
+### Cursor / Claude 配置示例
+
+**发布到 PyPI 后**（用户已 `pip install mysql-client-mcp-py` 或使用 `uvx`）：
+
+**Cursor** 编辑 `~/.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "uvx",
+      "args": ["mysql-client-mcp-py"],
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_PORT": "3306",
+        "DB_USER": "root",
+        "DB_PASSWORD": "your-password",
+        "DB_DATABASE": "your_db"
+      }
+    }
+  }
+}
+```
+
+多环境示例（**只配 TEST_DB_PROFILES / UAT_DB_PROFILES / PROD_DB_PROFILES**，每项需含 `host`、`port`、`user`、`password`）：
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "uvx",
+      "args": ["mysql-client-mcp-py"],
+      "env": {
+        "TEST_DB_PROFILES": "[{\"host\":\"test-db.example.com\",\"port\":3306,\"user\":\"u\",\"password\":\"p\",\"database\":\"app\"}]",
+        "UAT_DB_PROFILES": "[{\"host\":\"uat-db.example.com\",\"port\":3306,\"user\":\"u\",\"password\":\"p\",\"database\":\"app\"}]",
+        "PROD_DB_PROFILES": "[{\"host\":\"db.example.com\",\"port\":3306,\"user\":\"ro\",\"password\":\"xxx\",\"database\":\"app\"}]"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "uvx",
+      "args": ["mysql-client-mcp-py"],
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_USER": "root",
+        "DB_PASSWORD": "your-password",
+        "DB_DATABASE": "your_db"
+      }
+    }
+  }
+}
+```
+
+若已用 pip 安装到当前环境，也可直接指定命令（无需 uvx）：
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "mysql-client-mcp-py",
+      "args": [],
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_USER": "root",
+        "DB_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+**本地开发**（未发布、从源码运行）：
+
+```json
+{
+  "mcpServers": {
+    "database": {
+      "command": "uv",
+      "args": ["run", "python", "-m", "mysql_client_mcp"],
+      "cwd": "/path/to/mysql-client-mcp-py",
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_USER": "root",
+        "DB_PASSWORD": "your-password",
+        "DB_DATABASE": "your_db"
+      }
+    }
+  }
+}
+```
+
+## 工具
+
+| 工具 | 说明 |
+|------|------|
+| `list_connections` | 列出可用连接（profile + 可选说明），便于按用户自然语言选 connection |
+| `list_databases` | 列出数据库 |
+| `list_tables` | 列出指定库的表 |
+| `describe_table` | 表结构（列、行数、大小） |
+| `analyze_sql` | 分析 SQL（支持多条），不执行 |
+| `execute_sql` | 执行单条 SQL（DDL 不执行，写操作需 confirm=true） |
+
+## 资源
+
+- `db://config` - 配置与安全策略摘要
+- `db://databases` - 数据库列表
+- `db://tables/{database}` - 表列表
+- `db://table/{database}/{table}` - 单表结构
+
+## 提示词
+
+- **`ask_user_which_connection_prompt`** - **连接选择规则**：一开始无已选配置，必须先 list_connections 并让用户选择；用户选择后记住该 connection，后续默认使用且不再提示；仅当用户明确要切换环境时，再次列出并让用户选择
+- `query_safely_prompt` - 安全查询习惯
+- `explore_schema_prompt` - 先看 Schema 再写 SQL
+- `switch_connection_prompt` - 切换环境时带 connection 参数
+- `use_connection_from_natural_language_prompt` - 列出配置让用户选择，并根据用户说法映射到 connection
+
+## 设计文档
+
+参见项目内 `docs/plans/2025-03-14-database-mcp-design.md`。
+
+## License
+
+MIT

mysql_client_mcp_py-0.2.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "mysql-client-mcp-py"
+version = "0.2.0"
+description = "MCP Server for MySQL-protocol databases - schema discovery, SQL analysis, safe execution"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "dong_tech" }]
+keywords = ["mcp", "mysql", "database", "model-context-protocol", "ai", "llm"]
+classifiers = [
+    "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",
+    "pymysql>=1.1.0",
+    "pydantic>=2.0.0",
+    "sqlparse>=0.5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/dong-tech/mysql-client-mcp-py"
+Repository = "https://github.com/dong-tech/mysql-client-mcp-py"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[project.scripts]
+mysql-client-mcp-py = "mysql_client_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mysql_client_mcp"]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

mysql_client_mcp_py-0.2.0/scripts/test_live.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""用当前环境变量连接数据库，依次调用 list_connections、list_databases、list_tables、analyze_sql、execute_sql(SELECT 1)。"""
+import os
+import sys
+
+# 确保能 import 到 mysql_client_mcp
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from mysql_client_mcp.config import load_connection_map, load_safety_config
+from mysql_client_mcp.client import connect, list_databases, list_tables, get_connection_config, execute_select
+from mysql_client_mcp.sql_analysis import analyze_one
+
+
+def main():
+    default_conn, conn_map, default_name = load_connection_map()
+    safety = load_safety_config()
+
+    print("=== list_connections 等效 ===")
+    print(f"默认 profile: {default_name}")
+    for k, c in sorted(conn_map.items()):
+        print(f"  {k}: {c.host}:{c.port} user={c.user} database={c.database or '(未指定)'}")
+
+    config = get_connection_config(None, default_conn, conn_map)
+    print(f"\n使用连接: {config.host}:{config.port} database={config.database}")
+
+    with connect(config, safety) as conn:
+        dbs = list_databases(conn, getattr(config, "databases", None))
+        print(f"\n=== list_databases === 共 {len(dbs)} 个库")
+        for db in (dbs or [])[:20]:
+            print(f"  {db}")
+        if len(dbs or []) > 20:
+            print(f"  ... 等共 {len(dbs)} 个")
+
+        db_name = config.database or (dbs[0] if dbs else None)
+        if not db_name:
+            print("\n跳过 list_tables（无默认库且未指定）")
+        else:
+            tables = list_tables(conn, db_name)
+            print(f"\n=== list_tables({db_name!r}) === 共 {len(tables)} 张表")
+            for t in (tables or [])[:10]:
+                print(f"  {t.get('name', t)}")
+            if len(tables or []) > 10:
+                print(f"  ... 等共 {len(tables)} 张")
+
+    a = analyze_one("SELECT 1")
+    print(f"\n=== analyze_sql('SELECT 1') === type={a.stype} need_confirm={a.need_confirm} message={a.message}")
+
+    with connect(config, safety) as conn:
+        rows, truncated = execute_select(conn, "SELECT 1 AS n", max_rows=safety.max_select_rows)
+        print(f"\n=== execute_sql('SELECT 1') === rows={len(rows)} truncated={truncated}")
+        if rows:
+            print(f"  结果: {rows[0]}")
+
+    print("\n测试通过。")
+
+
+if __name__ == "__main__":
+    main()

mysql_client_mcp_py-0.2.0/src/mysql_client_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MySQL-protocol database MCP Server."""
+
+__version__ = "0.2.0"

mysql_client_mcp_py-0.2.0/src/mysql_client_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Run the MCP server with: python -m mysql_client_mcp"""
+from .server import main
+
+if __name__ == "__main__":
+    main()