mini-db-mcp/README.md

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. 服务校验参数并将请求路由到对应处理器，最终返回结构化结果。

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/tools.py。

环境要求

• Python 3.12+
• 可访问的 MySQL 数据库
• 推荐使用 uv 管理依赖

快速开始

1. 安装依赖

uv sync

2. 创建本地配置

启动前必须先将示例配置复制为 .env。

Windows PowerShell：

Copy-Item .env.example .env

macOS / Linux：

cp .env.example .env

随后编辑 .env，至少填写数据库连接信息：

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 客户端拉起：

uv run mcp

也可以通过模块入口启动：

uv run python -m mini_db_mcp

如需使用 Streamable HTTP，将 .env 中的传输方式改为：

MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8000

然后运行：

uv run mcp

MCP 端点为 http://127.0.0.1:8000/mcp。

MCP 客户端配置

使用 stdio 的客户端可参考以下配置。请将项目路径替换为本机的绝对路径：

{
  "mcpServers": {
    "mini-db-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\mini-db-mcp",
        "run",
        "mcp"
      ]
    }
  }
}

服务从项目工作目录读取 .env，因此客户端配置必须将工作目录指向仓库根目录。

CallTool 示例

第一次调用 metadata 时不传业务参数，用于获取当前可用的子工具定义：

{
  "name": "metadata",
  "arguments": {}
}

返回结果的 mode 为 manifest，其中 children 包含子工具名称、说明及 JSON Schema。选择子工具后进行第二次调用：

{
  "name": "metadata",
  "arguments": {
    "child_tool": "list_tables",
    "child_arguments": {
      "keyword": "user",
      "limit": 20
    }
  }
}

成功结果的 mode 为 result；参数错误、未知子工具或执行失败时，mode 为 error，同时 MCP 响应的 isError 会被设置为 true。

query 领域同样采用两阶段调用。先发现 SQL 执行子工具：

{
  "name": "query",
  "arguments": {}
}

然后选择 execute_query 并提供 SQL：

{
  "name": "query",
  "arguments": {
    "child_tool": "execute_query",
    "child_arguments": {
      "sql": "SELECT id, name FROM users"
    }
  }
}

配置

配置由 .env 加载，完整默认值见 .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	日志级别

开发与测试

安装开发依赖并运行测试：

uv sync --dev
uv run pytest

使用 MCP Inspector 调试 stdio 服务：

npx @modelcontextprotocol/inspector uv run mcp

项目结构

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 和网络访问控制；当前服务默认仅监听本机地址。