MCP 服务器

MCP Database Server

一个模型上下文协议服务器，提供与数据库交互的工具，包括 PostgreSQL、DuckDB 和 Google Cloud Storage Parquet 文件。

README

MCP 数据库服务器

一个使用 mcp-framework 构建的模型上下文协议 (MCP) 服务器，提供与数据库（通过 DuckDB 连接 PostgreSQL）和 Google Cloud Storage (GCS) 交互的工具和资源。

前提条件

Node.js 22 或更高版本
TypeScript
PostgreSQL（数据库功能需要）
Google Cloud 凭据（可选，用于 GCS 功能）
Devbox（用于使用 make 命令进行本地开发）

项目结构

.
├── docs
│   ├── assets
│   │   └── etl.png
│   ├── etl-workflow.md
│   └── setup-with-claude-desktop.md
├── migrations
│   ├── 1743322886782_initial-schema.cjs
│   └── 1743323460433_continuous-aggregates.cjs
├── scripts
│   └── setup-continuous-aggregates.sql
├── src
│   ├── resources       # MCP 资源定义
│   │   ├── gcs_objects.ts
│   │   └── sql_tables.ts
│   ├── services        # 服务初始化器（数据库连接，GCS 客户端）
│   │   ├── duckdb.ts
│   │   ├── gcs.ts
│   │   └── postgres.ts
│   ├── tools           # MCP 工具定义
│   │   ├── duckdb_insert.ts
│   │   ├── duckdb_query.ts
│   │   ├── duckdb_read_parquet.ts
│   │   └── gcs_directory_tree.ts
│   ├── utils           # 实用函数（日志记录，格式化）
│   │   ├── index.ts
│   │   └── logger.ts
│   ├── config.ts       # 配置加载和验证
│   ├── index.ts        # 主服务器入口点
│   └── utils.ts        # 弃用的实用程序？（如果未使用，请考虑删除）
├── .env.example        # 示例环境变量
├── .gitignore
├── CLAUDE.md
├── Dockerfile
├── MIGRATION.md
├── Makefile            # 开发命令
├── README.md
├── database.json       # 迁移配置
├── devbox.json         # Devbox 配置
├── devbox.lock
├── docker-compose.yml  # 数据库的 Docker 设置
├── fly.toml            # Fly.io 部署配置
├── package-lock.json
├── package.json
└── tsconfig.json

安装

克隆存储库：
```
git clone <repository-url>
cd mcp-db
```

安装依赖项（建议使用 Devbox 以保持一致性）：

devbox install
# 或者，如果不使用 Devbox，则直接使用 npm
# npm install

将 .env.example 复制到 .env 并填写您的环境变量。

cp .env.example .env
# 使用您的详细信息编辑 .env

构建项目：

# 使用 make（需要 Devbox）
make build
# 或者直接使用 npm
# npm run build

配置

环境变量

使用以下环境变量（或命令行参数）配置服务器：

DATABASE_URL: PostgreSQL 连接字符串（除非使用 supergateway 运行，否则为必需）。
DATABASE_URLS: 以逗号分隔的 alias=url 对列表，用于多个数据库连接（DATABASE_URL 的替代方案）。
LOG_LEVEL: 日志记录级别（debug、info、error）。默认值：info。
GCS_BUCKET: 默认 Google Cloud Storage 存储桶名称（可选）。
GCP_SERVICE_ACCOUNT: Base64 编码的 Google Cloud 服务帐户密钥 JSON（可选，用于 GCS 身份验证）。
GCS_KEY_ID / GCS_SECRET: 专门用于 DuckDB 的 httpfs 扩展的替代 GCS 凭据（可选）。
TRANSPORT: 传输类型（stdio 或 sse）。默认值：stdio。
PORT: SSE 传输的端口号。默认值：3001。
HOST: SSE 传输的主机名。默认值：localhost。
API_KEY: 用于保护服务器的可选 API 密钥（如果设置，客户端必须在 Authorization: Bearer <key> 标头中提供它）。

命令行参数（例如，--port 8080，--gcs-bucket my-bucket）会覆盖环境变量。有关详细信息，请参见 src/config.ts。

数据库迁移

该项目使用 node-pg-migrate 来管理 PostgreSQL 模式更改。有关运行和创建迁移的详细信息，请参见上面原始 README 内容中的“数据库迁移”部分。

注意： 先前提到的 npm run setup:db 命令可能需要根据当前设置进行审查或更新。

运行服务器

使用 Makefile 进行方便的开发命令（需要 Devbox）：

# 在开发模式下运行（构建并使用 nodemon 启动以进行自动重启）
# 默认情况下在端口 3001 上使用 SSE 传输
make dev

# 运行测试（如果已配置）
# make test

# 构建以进行生产
# make build

要在没有 make 的情况下运行（在 npm run build 之后）：

# 使用 stdio 传输运行
node dist/index.js --transport stdio

# 在默认端口 3001 上使用 SSE 传输运行
node dist/index.js --transport sse

# 在不同的端口上使用 SSE 运行
node dist/index.js --transport sse --port 8080

客户端配置

要将您的 MCP 客户端（例如，mcp-cli，Claude Desktop）连接到本地服务器：

对于 SSE 传输（例如，在端口 3001 上）：

{
  "mcpServers": {
    "mcp-db-local": {
      "command": "node",
      "args": [
        "/path/to/mcp-db/dist/index.js", // 如果需要，调整路径
        "--transport", "sse",
        "--port", "3001" // 匹配服务器正在运行的端口
      ],
      // 如果设置了 API_KEY，则添加 "env"
      // "env": { "API_KEY": "your-secret-key" }
    }
  }
}

(注意：先前 README 中的 Docker/supergateway 示例可能已过时或特定于不同的部署设置。)

对于 Stdio 传输：

{
  "mcpServers": {
    "mcp-db-local": {
      "command": "node",
      "args": [
        "/path/to/mcp-db/dist/index.js", // 如果需要，调整路径
        "--transport", "stdio"
      ],
      // 如果设置了 API_KEY，则添加 "env"
      // "env": { "API_KEY": "your-secret-key" }
    }
  }
}

使用 npx 从 GitHub 运行

您可以直接使用 npx 运行服务器（需要在 package 中进行构建步骤）：

# 确保设置了必需的环境变量
export DATABASE_URL="postgresql://user:password@localhost:5432/db"
export GCS_BUCKET="my-bucket"

npx github:dwarvesf/mcp-db --transport sse --port 3001

可用工具

duckdb_insert: 通过 DuckDB 在附加的 PostgreSQL 数据库上执行 INSERT 语句。仅允许 INSERT 查询。
duckdb_query: 使用 DuckDB 的 postgres_query 函数直接在附加的 PostgreSQL 数据库 (postgres_db) 上执行只读 SQL 查询。自动为不合格的表名添加前缀（例如，my_table 变为 postgres_db.public.my_table）。
duckdb_read_parquet: 使用 DuckDB 查询 Parquet 文件（如果已配置，则可能来自 GCS）。
gcs_directory_tree: 从 GCS 存储桶中获取目录树结构，并支持分页。

可用资源

mcp://gcs/objects (gcs_objects): 列出已配置的 GCS 存储桶中的对象。
mcp://db/tables (sql_tables): 列出已配置的 PostgreSQL 数据库中的所有表及其列。

开发：集成新工具/资源

该项目使用 mcp-framework。要添加新工具或资源：

创建类：

在 src/tools/ 或 src/resources/ 中创建一个新的 .ts 文件。
定义一个扩展 MCPTool 或 MCPResource 的类。
实现所需的属性（工具的 name、description、schema）和方法（工具的 execute，资源的 read）。
在 schema 属性中使用 Zod 进行输入验证（工具）。
在类中初始化任何依赖项（例如数据库连接或 GCS 客户端），通常在构造函数中，可能使用来自 src/services/ 的服务或来自 src/config.ts 的配置。

示例工具 (src/tools/my_tool.ts):

import { MCPTool } from "mcp-framework";
import { z } from "zod";
import { formatSuccessResponse } from "../utils.js";
import { getDuckDBConnection } from "../services/duckdb.js"; // 示例依赖项

const MyToolInputSchema = z.object({
  param1: z.string().describe("Description for parameter 1"),
});
type MyToolInput = z.infer<typeof MyToolInputSchema>;

export class MyTool extends MCPTool<MyToolInput> {
  name = "my_tool";
  description = "Description of what my tool does.";
  schema = { // 匹配 Zod 模式结构
    param1: { type: z.string(), description: "Description for parameter 1" },
  };

  async execute(args: MyToolInput): Promise<any> {
    console.error(`Handling tool request: ${this.name}`);
    const duckDBConn = getDuckDBConnection(); // 获取依赖项
    // ... 使用 args 和 duckDBConn 实现逻辑 ...
    const result = { message: `Processed ${args.param1}` };
    return formatSuccessResponse(result);
  }
}
export default MyTool; // 确保默认导出

自动发现：
- mcp-framework 自动发现并注册从 src/tools 和 src/resources 目录中的文件默认导出的工具/资源类。
- 确保您的新类是其文件中的 default export。
测试：
- 运行服务器 (make dev)。
- 检查启动日志以确保列出了您的新工具/资源。
- 使用 MCP 客户端（例如 mcp-cli 或 MCP Inspector）调用该工具或读取该资源，并验证其功能。

最佳实践

使用 Zod 为工具定义清晰的输入模式。
在 execute/read 中优雅地处理错误，并使用 formatErrorResponse 返回格式化的错误响应（或抛出错误）。
在需要时通过 getConfig() 使用集中式配置 (src/config.ts)。
利用 src/services/ 中的服务初始化器来处理数据库连接等依赖项。
添加日志记录 (console.error) 以提高可见性。