# mcp_db_tool

**Repository Path**: jf_g/mcp_db_tool

## Basic Information

- **Project Name**: mcp_db_tool
- **Description**: No description available
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-09
- **Last Updated**: 2025-12-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP 数据库工具服务器（Node/TS + 官方 MCP SDK）

本项目旨在实现一个符合 MCP（Model Context Protocol）的工具服务器，用于安全、可审计地操作数据库并向通用 MCP 客户端（如 Claude Desktop、VS Code MCP 插件）提供上下文与工具能力。

## 特性概览
- 只读默认与白名单控制写操作
- 参数化查询、行数与时间上限、超时与取消
- 多数据库支持：PostgreSQL、MySQL、SQLite（可扩展）
- 资源与提示：暴露 Schema、提供安全 SQL Few-shot
- 审计与指标：结构化日志、调用轨迹、性能监控

## 快速开始
- 环境要求：Node.js ≥ 18，npm/pnpm，数据库连接可用
- 安装依赖与运行（示例）：
  - `pnpm install`
  - `pnpm dev`
- 基本目录建议：
  - `src/index.ts`：服务器入口与工具注册
  - `src/tools/*`：数据库相关工具实现
  - `src/resources/*`：Schema/样例资源提供器
  - `src/prompts/*`：安全与示例提示提供器

## 最小服务器示例
```ts
import { createServer, Tool } from "@modelcontextprotocol/sdk"
const server = createServer({ name: "mcp-db-tool" })
const queryTool: Tool = {
  name: "db.query",
  description: "参数化查询",
  inputSchema: { type: "object", properties: {
    connectionId: { type: "string" }, sql: { type: "string" }, params: { type: "array" }
  }, required: ["connectionId", "sql"] },
  handler: async (input) => ({ rows: [] })
}
server.tools.register(queryTool)
server.start()
```

## 配置示例
```json
{
  "connections": {
    "primary": {
      "driver": "postgres",
      "url": "env:DB_URL",
      "readOnly": true,
      "rowLimit": 1000,
      "timeoutMs": 10000
    }
  },
  "security": { "allowWrite": false, "blockedVerbs": ["DROP","TRUNCATE","ALTER"] },
  "rbac": { "tokens": { "reader-token": ["db.query","db.listTables"] } }
}
```

## 工具列表（摘要）
- `db.connect`：建立命名连接，返回 `connectionId`
- `db.listSchemas`：列出模式/数据库/命名空间
- `db.listTables`：分页与过滤列出表
- `db.describeTable`：字段、索引、约束、示例行
- `db.query`：只读参数化查询，支持上限与超时
- `db.run`：受控写操作，需要显式允许与 RBAC 放行
- `db.transaction.start|commit|rollback`：事务工具
- `db.health`：健康检查

## 资源与提示
- 资源：`resource:db_schema:<connection>`、`resource:samples:<table>`（脱敏）
- 提示：`prompt:safe_sql`（安全实践 Few-shot）、`prompt:examples`（常用查询示例）

## 安全实践
- 只读默认，阻断危险 DDL/DML（如 `DROP/TRUNCATE/ALTER`）
- 强制参数化与预编译，拒绝字符串拼接 SQL
- 数据脱敏、行列级过滤、返回上限与超时
- RBAC 按工具与连接授权；审计调用与去敏 SQL
- 连接池上限、背压与隔离；事务会话关联

## 客户端集成
- 启动服务：
  - `pnpm install`
  - 可选设置端口：`export MCP_PORT=38080`
  - 启动：`pnpm dev`
- VS Code MCP Inspector：
  - 安装扩展并在面板中添加服务器：`ws://localhost:38080`
  - 在 Tools 列表中选择 `db.connect` 进行连接；随后调用 `db.query`
  - 示例参数：
    - `db.connect`：`{"id":"primary","driver":"postgres","url":"postgres://user:pass@localhost:5432/db"}`
    - `db.query`：`{"connectionId":"primary","sql":"SELECT 1 as x","params":[]}`
- Claude Desktop：
  - 设置 -> MCP Servers -> 添加 `ws://localhost:38080`
  - 通过工具面板选择 `db.connect` 与 `db.query`，或在对话中提示调用
- 直接调用（WebSocket JSON-RPC，示意）：
  - 连接 `ws://localhost:38080`，发送 `tools/list`/`tools/call` 请求
  - `tools/call` 示例：
    - 连接：`{"id":1,"method":"tools/call","params":{"name":"db.connect","arguments":{"id":"primary","driver":"postgres","url":"postgres://user:pass@localhost:5432/db"}}}`
    - 查询：`{"id":2,"method":"tools/call","params":{"name":"db.query","arguments":{"connectionId":"primary","sql":"SELECT 1 as x"}}}`
  - Schema 工具调用示例：
    - 列模式：`{"id":3,"method":"tools/call","params":{"name":"db.listSchemas","arguments":{"connectionId":"primary"}}}`
    - 列表：`{"id":4,"method":"tools/call","params":{"name":"db.listTables","arguments":{"connectionId":"primary","schema":"public"}}}`
    - 表描述：`{"id":5,"method":"tools/call","params":{"name":"db.describeTable","arguments":{"connectionId":"primary","schema":"public","table":"users"}}}`
  - 资源获取示例：
    - `{"id":6,"method":"resources/get","params":{"name":"db_schema","arguments":"primary"}}`

## 参考
- MCP 架构与原语：https://modelcontextprotocol.io/docs/learn/architecture
- 官方示例服务器汇总：https://modelcontextprotocol.io/examples
- MCP servers 开源清单：https://github.com/modelcontextprotocol/servers
- Azure PostgreSQL MCP 服务器（工具设计参考）：https://techcommunity.microsoft.com/blog/adforpostgresql/introducing-model-context-protocol-mcp-server-for-azure-database-for-postgresql-/4404360