add query domain handler

2026-10-09 11:03:25 +08:00
parent 3cd836c929
commit 354d4e3a8d
9 changed files with 476 additions and 15 deletions
@@ -0,0 +1,250 @@
+# mini-db-mcp
+
+一个面向关系型数据库的轻量级 MCP（Model Context Protocol）服务。项目基于 Python MCP SDK 和 SQLAlchemy，当前支持 MySQL，并通过**渐进式披露**减少一次性注入模型上下文的工具定义数量。
+
+## 特性
+
+- 支持 `stdio` 与无状态 Streamable HTTP 两种传输方式
+- 采用“领域工具 -> 子工具”的两阶段发现与执行流程
+- 提供数据库对象浏览、表结构查看和字段采样能力
+- 查询默认只读，并提供行数、响应大小、单元格长度和超时限制
+- 同时返回 `structuredContent` 与兼容旧客户端的 JSON 文本内容
+- 支持工具列表和元数据结果分页
+
+## 工作原理
+
+项目不会在初始化时把所有子工具定义一次性暴露给模型，而是按需加载：
+
+1. MCP 客户端通过 `tools/list` 获取顶层领域工具，例如 `metadata`。
+2. 第一次调用领域工具时传入空参数，服务返回该领域的子工具清单及其输入、输出 Schema。
+3. 模型选择子工具后，再通过 `child_tool` 和 `child_arguments` 发起第二次调用。
+4. 服务校验参数并将请求路由到对应处理器，最终返回结构化结果。
+
+```mermaid
+sequenceDiagram
+    participant Client as MCP Client
+    participant Server as mini-db-mcp
+    participant DB as MySQL
+    Client->>Server: tools/list
+    Server-->>Client: metadata
+    Client->>Server: tools/call metadata, arguments={}
+    Server-->>Client: child tool manifest
+    Client->>Server: tools/call metadata, child_tool + child_arguments
+    Server->>DB: execute metadata query
+    DB-->>Server: result
+    Server-->>Client: structuredContent + JSON text
+```
+
+当前提供以下领域和子工具：
+
+| 领域 | 子工具 | 用途 |
+| --- | --- | --- |
+| `metadata` | `list_tables` | 分页列出当前数据库中的表和视图 |
+| `metadata` | `describe_table` | 分页查看指定表或视图的字段结构 |
+| `metadata` | `sample_values` | 获取指定字段的去重样例值 |
+| `query` | `execute_query` | 执行单条 SQL；根据 `QUERY_ALLOW_WRITE` 校验读写权限，并受查询超时和结果大小限制 |
+
+主要入口位于 [`src/mini_db_mcp/server.py`](src/mini_db_mcp/server.py)，渐进式工具发现与调用逻辑位于 [`src/mini_db_mcp/tools.py`](src/mini_db_mcp/tools.py)。
+
+## 环境要求
+
+- Python 3.12+
+- 可访问的 MySQL 数据库
+- 推荐使用 [uv](https://docs.astral.sh/uv/) 管理依赖
+
+## 快速开始
+
+### 1. 安装依赖
+
+```powershell
+uv sync
+```
+
+### 2. 创建本地配置
+
+启动前必须先将示例配置复制为 `.env`。
+
+Windows PowerShell：
+
+```powershell
+Copy-Item .env.example .env
+```
+
+macOS / Linux：
+
+```bash
+cp .env.example .env
+```
+
+随后编辑 `.env`，至少填写数据库连接信息：
+
+```dotenv
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=your_password
+DB_SCHEMA=your_database
+```
+
+不要提交 `.env`。仓库仅跟踪不含真实凭据的 `.env.example`。
+
+### 3. 启动服务
+
+默认使用 `stdio`，适合由本地 MCP 客户端拉起：
+
+```powershell
+uv run mcp
+```
+
+也可以通过模块入口启动：
+
+```powershell
+uv run python -m mini_db_mcp
+```
+
+如需使用 Streamable HTTP，将 `.env` 中的传输方式改为：
+
+```dotenv
+MCP_TRANSPORT=http
+MCP_HOST=127.0.0.1
+MCP_PORT=8000
+```
+
+然后运行：
+
+```powershell
+uv run mcp
+```
+
+MCP 端点为 `http://127.0.0.1:8000/mcp`。
+
+## MCP 客户端配置
+
+使用 `stdio` 的客户端可参考以下配置。请将项目路径替换为本机的绝对路径：
+
+```json
+{
+  "mcpServers": {
+    "mini-db-mcp": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "C:\\path\\to\\mini-db-mcp",
+        "run",
+        "mcp"
+      ]
+    }
+  }
+}
+```
+
+服务从项目工作目录读取 `.env`，因此客户端配置必须将工作目录指向仓库根目录。
+
+## CallTool 示例
+
+第一次调用 `metadata` 时不传业务参数，用于获取当前可用的子工具定义：
+
+```json
+{
+  "name": "metadata",
+  "arguments": {}
+}
+```
+
+返回结果的 `mode` 为 `manifest`，其中 `children` 包含子工具名称、说明及 JSON Schema。选择子工具后进行第二次调用：
+
+```json
+{
+  "name": "metadata",
+  "arguments": {
+    "child_tool": "list_tables",
+    "child_arguments": {
+      "keyword": "user",
+      "limit": 20
+    }
+  }
+}
+```
+
+成功结果的 `mode` 为 `result`；参数错误、未知子工具或执行失败时，`mode` 为 `error`，同时 MCP 响应的 `isError` 会被设置为 `true`。
+
+`query` 领域同样采用两阶段调用。先发现 SQL 执行子工具：
+
+```json
+{
+  "name": "query",
+  "arguments": {}
+}
+```
+
+然后选择 `execute_query` 并提供 SQL：
+
+```json
+{
+  "name": "query",
+  "arguments": {
+    "child_tool": "execute_query",
+    "child_arguments": {
+      "sql": "SELECT id, name FROM users"
+    }
+  }
+}
+```
+
+## 配置
+
+配置由 `.env` 加载，完整默认值见 [`.env.example`](.env.example)。
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `DB_HOST` | `127.0.0.1` | 数据库主机 |
+| `DB_PORT` | `3306` | 数据库端口 |
+| `DB_USER` | `root` | 数据库用户 |
+| `DB_PASSWORD` | 空 | 数据库密码 |
+| `DB_SCHEMA` | 空 | 默认数据库 Schema |
+| `QUERY_MAX_ROWS` | `1000` | 单次查询最大返回行数 |
+| `QUERY_MAX_BYTES` | `262144` | 单次响应最大字节数 |
+| `QUERY_MAX_CELL_CHARS` | `4096` | 单个字段值最大字符数 |
+| `QUERY_TIMEOUT_SECONDS` | `30` | 查询超时时间（秒） |
+| `QUERY_ALLOW_WRITE` | `false` | 是否允许写操作，建议保持关闭 |
+| `MCP_TRANSPORT` | `stdio` | 传输方式：`stdio` 或 `http` |
+| `MCP_HOST` | `127.0.0.1` | HTTP 监听地址 |
+| `MCP_PORT` | `8000` | HTTP 监听端口 |
+| `LOG_LEVEL` | `INFO` | 日志级别 |
+
+## 开发与测试
+
+安装开发依赖并运行测试：
+
+```powershell
+uv sync --dev
+uv run pytest
+```
+
+使用 MCP Inspector 调试 `stdio` 服务：
+
+```powershell
+npx @modelcontextprotocol/inspector uv run mcp
+```
+
+## 项目结构
+
+```text
+src/mini_db_mcp/
+|-- main.py                 # 命令行入口与传输方式选择
+|-- server.py               # MCP Server 注册与 CallTool 入口
+|-- tools.py                # 渐进式工具发现、校验与调用
+|-- config.py               # 环境变量配置
+|-- db.py                   # 异步数据库访问
+`-- domain/
+    |-- domain_catalog.py   # 领域与子工具 Schema
+    |-- domain_handler.py   # 处理器注册表
+    `-- handler/            # 子工具具体实现
+```
+
+## 安全建议
+
+- 使用权限最小化的专用数据库账号。
+- 保持 `QUERY_ALLOW_WRITE=false`，除非明确需要写入能力并已完成额外审计。
+- 不要在 MCP 客户端配置或版本库中直接保存数据库密码。
+- 对 HTTP 部署增加反向代理、身份认证、TLS 和网络访问控制；当前服务默认仅监听本机地址。