使用说明

项目简介

'mcp-db' 是一个基于 Model Context Protocol (MCP) 构建的数据库查询服务器。它作为 LLM 应用的后端，提供了一系列工具，用于安全、便捷地查询和操作多种数据源，包括 PostgreSQL 数据库、DuckDB 数据文件（Parquet 格式，可存储在本地或 Google Cloud Storage (GCS)）。通过标准化的 MCP 协议，LLM 可以调用这些工具，获取结构化数据，从而增强其数据分析和处理能力。

主要功能点

数据库查询工具: 提供执行 SQL 查询的工具，支持 'SELECT', 'CREATE', 'INSERT', 'UPDATE', 'DELETE' 等操作，目前支持 PostgreSQL 数据库。
数据文件查询工具: 提供查询 Parquet 文件的工具，支持本地文件和 GCS 上的 Parquet 文件，使用 DuckDB 作为查询引擎。
多数据源支持: 支持 PostgreSQL, DuckDB (Parquet), Google Cloud Storage (GCS) 等多种数据源。
可扩展的工具集: 易于扩展，可以根据需求添加新的数据源和查询工具。
基于 MCP 协议: 遵循 MCP 协议标准，易于与各种 LLM 客户端集成。
开发文档: 提供详细的开发文档，指导用户集成和扩展工具。

安装步骤

克隆仓库

git clone https://github.com/dwarvesf/mcp-db
cd mcp-db

安装依赖 确保已安装 Node.js 22 或更高版本和 npm。
```
npm install
```
构建项目
```
npm run build
```

服务器配置

MCP 客户端需要配置以下信息以连接到 'mcp-db' 服务器。

{
  "serverName": "Data-Query-Server",
  "command": "npm",
  "args": [
    "start",
    "--",
    "--database-url", "<PostgreSQL 连接字符串>"
  ],
  "説明": "请将 <PostgreSQL 连接字符串> 替换为您的 PostgreSQL 数据库连接字符串。",
  "示例": {
    "PostgreSQL 连接字符串示例": "postgresql://用户名:密码@服务器地址:端口/数据库名"
  }
}

配置参数说明:

'serverName': 服务器名称，默认为 "Data-Query-Server"。
'command': 启动服务器的命令，这里使用 'npm'。
'args': 传递给 'npm start' 命令的参数列表。
- '"start"': 运行 'package.json' 中定义的 'start' 脚本，启动服务器。
- '"--"': 分隔 npm 命令和传递给服务器应用程序的参数。
- '"--database-url"': PostgreSQL 数据库连接 URL 参数，必须配置，用于连接 PostgreSQL 数据库。请替换为实际的 PostgreSQL 连接字符串，例如 'postgresql://user:password@localhost:5432/mydb'。

可选配置 (通过环境变量或运行时参数):

GCS 认证: 如果需要查询 GCS 上的 Parquet 文件，需要配置 GCS 认证。
- 方法一：设置 'GCP_SERVICE_ACCOUNT' 环境变量: 将 Base64 编码的服务账户凭据设置为 'GCP_SERVICE_ACCOUNT' 环境变量。
- 方法二：使用默认凭据: 如果服务器运行在 GKE 或其他支持默认凭据的环境中，则可以自动使用默认凭据。

日志级别: 可以通过 '--log-level' 参数或环境变量设置日志级别，可选值包括 'debug', 'info', 'error'，默认为 'info'。例如：

npm start -- --database-url "<PostgreSQL 连接字符串>" --log-level debug

基本使用方法

启动服务器: 根据上述服务器配置，启动 'mcp-db' 服务器。
配置 MCP 客户端: 在您的 LLM 应用 (MCP 客户端) 中，配置连接到 'mcp-db' 服务器。需要提供服务器的启动命令和参数（如上述 "服务器配置" 部分所示）。
调用工具: 在 LLM 应用中，可以使用以下工具名称来调用 'mcp-db' 服务器提供的功能：
- 'sql_query_read': 执行 'SELECT' 查询。
- 'sql_query_create': 执行 'CREATE' 或 'INSERT' 语句。
- 'sql_query_update': 执行 'UPDATE' 语句。
- 'sql_query_delete': 执行 'DELETE' 语句。
- 'duckdb_read_parquet_files': 查询 Parquet 文件。
传递参数: 根据工具的 'inputSchema' 定义，向工具传递参数。例如，调用 'sql_query_read' 工具时，需要提供 'sql' 参数 (SQL 查询语句)。

示例：使用 'sql_query_read' 工具

假设 LLM 客户端需要查询 PostgreSQL 数据库中的 'users' 表，可以构造如下的 MCP 请求 (CallToolRequest):

{
  "jsonrpc": "2.0",
  "method": "call_tool",
  "params": {
    "name": "sql_query_read",
    "arguments": {
      "sql": "SELECT * FROM users WHERE age > 18"
    }
  },
  "id": "123"
}

'mcp-db' 服务器将执行该 SQL 查询，并将结果以 JSON 格式返回给 LLM 客户端。

关键词