Duckpond MCP Server

DuckPond MCP服务器

](https://github.com/jordanburke/duckpond-mcp-server/actions/workflows/node.js.yml) 

用于R2/S3云存储的多租户DuckDB管理的模型上下文协议（MCP）服务器。

建在 鸭池 库，此MCP服务器使AI代理能够通过自动云持久性管理每个用户的DuckDB数据库。

特性

• 🦆 多租户DuckDB -每个用户使用LRU缓存隔离数据库
• ☁️ 云存储 -无缝的R2/S3集成，实现持久性
• 🔌 双重运输 -stdio（克劳德桌面）和HTTP（服务器部署）
• 🔐 认证 -OAuth 2.0和HTTP的基本身份验证支持
• 🎯 MCP工具 -查询、执行、统计、缓存管理
• 🖥️ DuckDB用户界面 -内置web UI，用于数据库检查和调试
• 📊 类型安全 -带有functype错误处理的完整TypeScript

快速开始

安装

# Global installation
npm install -g duckpond-mcp-server

# Or use directly with npx
npx duckpond-mcp-server

克劳德桌面设置（stdio）

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "duckpond": {
      "command": "npx",
      "args": ["-y", "duckpond-mcp-server"],
      "env": {
        "DUCKPOND_R2_ACCOUNT_ID": "your-account-id",
        "DUCKPOND_R2_ACCESS_KEY_ID": "your-access-key",
        "DUCKPOND_R2_SECRET_ACCESS_KEY": "your-secret-key",
        "DUCKPOND_R2_BUCKET": "your-bucket"
      }
    }
  }
}

HTTP服务器

# Start HTTP server on port 3000
npx duckpond-mcp-server --transport http

# With custom port
npx duckpond-mcp-server --transport http --port 8080

可用的MCP工具

query

为特定用户执行SQL查询并返回结果。

输入：

{
  userId: string // User identifier
  sql: string // SQL query to execute
}

输出：

{
  rows: T[]              // Query results
  rowCount: number       // Number of rows
  executionTime: number  // Execution time in ms
}

execute

执行DDL/DML语句（CREATE、INSERT、UPDATE、DELETE）而不返回结果。

输入：

{
  userId: string // User identifier
  sql: string // SQL statement to execute
}

输出：

{
  success: boolean
  message: string
  executionTime: number
}

getUserStats

获取用户数据库的统计信息。

输入：

{
  userId: string // User identifier
}

输出：

{
  userId: string
  attached: boolean // Is user currently cached?
  lastAccess: string // ISO 8601 timestamp
  memoryUsage: number // Bytes
  storageUsage: number // Bytes
  queryCount: number
}

isAttached

检查用户的数据库当前是否缓存在内存中。

输入：

{
  userId: string // User identifier
}

输出：

{
  attached: boolean
  userId: string
}

detachUser

手动从缓存中分离用户的数据库以释放资源。

输入：

{
  userId: string // User identifier
}

输出：

{
  success: boolean
  message: string
}

配置

环境变量

DuckDB设置

• DUCKPOND_MEMORY_LIMIT -内存限制（默认值： 4GB)
• DUCKPOND_THREADS -线程数（默认值： 4)
• DUCKPOND_CACHE_TYPE -缓存类型： disk, memory, noop （默认值： disk)

存储配置

默认情况下，DuckPond在本地存储数据库。对于云部署，请配置R2或S3。

本地存储（默认）

# Databases stored in ~/.duckpond/data by default
# Customize with:
export DUCKPOND_DATA_DIR=/path/to/data

npx duckpond-mcp-server

Cloudflare R2 的

export DUCKPOND_R2_ACCOUNT_ID=your-account-id
export DUCKPOND_R2_ACCESS_KEY_ID=your-access-key
export DUCKPOND_R2_SECRET_ACCESS_KEY=your-secret-key
export DUCKPOND_R2_BUCKET=your-bucket

npx duckpond-mcp-server

AWS S3

export DUCKPOND_S3_REGION=us-east-1
export DUCKPOND_S3_ACCESS_KEY_ID=your-access-key
export DUCKPOND_S3_SECRET_ACCESS_KEY=your-secret-key
export DUCKPOND_S3_BUCKET=your-bucket

npx duckpond-mcp-server

S3兼容（MinIO等）

export DUCKPOND_S3_REGION=us-east-1
export DUCKPOND_S3_ACCESS_KEY_ID=minioadmin
export DUCKPOND_S3_SECRET_ACCESS_KEY=minioadmin
export DUCKPOND_S3_BUCKET=duckpond
export DUCKPOND_S3_ENDPOINT=http://localhost:9000

npx duckpond-mcp-server

多租户设置

• DUCKPOND_MAX_ACTIVE_USERS -LRU缓存大小（默认值： 10)
• DUCKPOND_EVICTION_TIMEOUT -空闲超时（毫秒）（默认值： 300000)
• DUCKPOND_STRATEGY -存储策略： parquet, duckdb, hybrid （默认值： duckdb)
• DUCKPOND_DATA_DIR -本地数据目录（默认： ~/.duckpond/data)

Cloudflare R2配置

• DUCKPOND_R2_ACCOUNT_ID -R2帐户ID
• DUCKPOND_R2_ACCESS_KEY_ID -R2访问密钥
• DUCKPOND_R2_SECRET_ACCESS_KEY -R2密钥
• DUCKPOND_R2_BUCKET -R2存储桶名称

AWS S3配置

• DUCKPOND_S3_REGION -S3区域（例如。， us-east-1)
• DUCKPOND_S3_ACCESS_KEY_ID -S3访问密钥
• DUCKPOND_S3_SECRET_ACCESS_KEY -S3密钥
• DUCKPOND_S3_BUCKET -S3存储桶名称
• DUCKPOND_S3_ENDPOINT -自定义S3端点（用于MinIO等）

HTTP传输身份验证

OAuth 2.0

export DUCKPOND_OAUTH_ENABLED=true
export DUCKPOND_OAUTH_USERNAME=admin
export DUCKPOND_OAUTH_PASSWORD=secret123
export DUCKPOND_OAUTH_USER_ID=admin-user
export DUCKPOND_OAUTH_EMAIL=admin@example.com

npx duckpond-mcp-server --transport http

OAuth端点：

• /oauth/authorize -授权端点（登录表单）
• /oauth/token -令牌端点（授权码和刷新令牌）
• /oauth/jwks -JSON Web密钥集
• /oauth/register -动态客户端注册

特征：

• 使用PKCE的授权码流（S256&plain）
• 刷新令牌轮换
• JWT访问令牌（可配置过期时间）

基本身份验证

export DUCKPOND_BASIC_AUTH_USERNAME=admin
export DUCKPOND_BASIC_AUTH_PASSWORD=secret123
export DUCKPOND_BASIC_AUTH_USER_ID=admin-user
export DUCKPOND_BASIC_AUTH_EMAIL=admin@example.com

npx duckpond-mcp-server --transport http

JWT配置

• DUCKPOND_JWT_SECRET -签名JWT的密码（如果未设置，则自动生成）
• DUCKPOND_JWT_EXPIRES_IN -令牌过期时间（秒）（默认值： 31536000 =1年）

HTTP端点

MCP协议

• POST /mcp -MCP协议端点（服务器发送事件）

- 要求： Accept: application/json, text/event-stream - 初始化会话，然后调用工具

服务器信息

• GET / -服务器信息和功能
• GET /health -健康检查

OAuth（启用时）

• GET /oauth/authorize -授权端点
• POST /oauth/token -令牌端点
• GET /oauth/jwks -JSON Web密钥集
• POST /oauth/register -客户注册

DuckDB用户界面

• GET /ui -UI状态和可用用户
• GET /ui/:userId -为特定用户启动UI（返回直接访问的URL）

DuckDB用户界面

MCP服务器内置了对 DuckDB用户界面，允许您通过web浏览器直观地检查和调试数据库。

运作原理

随着 DUCKPOND_DEFAULT_USER 设置UI 自动启动 当服务器启动时。只需打开 http://localhost:4213 在您的浏览器中。

UI在端口4213上运行，因为DuckDB UI需要特定的浏览器功能（SharedArrayBuffer），这些功能最适合直接访问。

Claude桌面配置（推荐）

{
  "mcpServers": {
    "duckpond": {
      "command": "npx",
      "args": ["-y", "duckpond-mcp-server", "--ui"],
      "env": {
        "DUCKPOND_DEFAULT_USER": "claude",
        "DUCKPOND_DATA_DIR": "${HOME}/.duckpond/data"
      }
    }
  }
}

默认用户的UI会自动启动。打开 http://localhost:4213 在您的浏览器中。

HTTP模式

# Start server
npx duckpond-mcp-server --transport http --port 3000

# Start UI for user "claude"
curl http://localhost:3000/ui/claude

# Access UI directly
# Browser: http://localhost:4213

无默认用户的stdio模式

如果没有 DUCKPOND_DEFAULT_USER 设置后，管理服务器启动，供用户手动选择：

# Start with UI management server
npx duckpond-mcp-server --ui --ui-port 4000

# Start UI for a user
curl http://localhost:4000/ui/claude

# Access UI directly
# Browser: http://localhost:4213

码头工人

# Using docker-compose (recommended)
docker compose up -d

# Start UI for a user
curl http://localhost:3000/ui/claude

# Access UI directly
# Browser: http://localhost:4213

# Simple docker run
docker run -p 3000:3000 -p 4213:4213 duckpond-mcp-server

# Start UI for a user, then access directly
curl http://localhost:3000/ui/claude
# Browser: http://localhost:4213

为什么要直接进入港口？ DuckDB UI使用SharedArrayBuffer，它需要特定的CORS标头。直接访问端口4213可确保与UI的WebAssembly要求完全兼容。

UI功能

• 数据库浏览器 -浏览架构、表和列
• SQL笔记本 -使用语法高亮显示执行查询
• 表摘要 -行数、数据配置文件、预览
• 列资源管理器 -详细的专栏统计数据和见解

切换用户（HTTP模式）

在HTTP模式下，导航到 /ui/:differentUserId 在用户之间切换。一次只有一个用户的UI处于活动状态——切换会自动停止上一个UI，并为新用户启动。

环境变量

• DUCKPOND_DEFAULT_USER -默认用户ID；设置后，此用户的UI将自动启动
• DUCKPOND_UI_ENABLED -启用UI（默认值： false，或使用 --ui 旗帜）

CLI标志

• --ui -启用DuckDB UI（自动启动 DUCKPOND_DEFAULT_USER)
• `--ui-port

-管理服务器端口，仅在没有默认用户时使用（默认值： 4000`)

• `--ui-internal-port

-DuckDB UI端口（默认： 4213`)

发展

本地开发

# Clone repository
git clone https://github.com/jordanburke/duckpond-mcp-server.git
cd duckpond-mcp-server

# Install dependencies
pnpm install

# Development mode (watch)
pnpm dev

# Run tests
pnpm test

# Format and lint
pnpm validate

测试服务器

# Test stdio transport
pnpm serve:test

# Test HTTP transport
pnpm serve:test:http

# Test with OAuth
DUCKPOND_OAUTH_ENABLED=true \
DUCKPOND_OAUTH_USERNAME=admin \
DUCKPOND_OAUTH_PASSWORD=secret \
pnpm serve:test:http

# Test with Basic Auth
DUCKPOND_BASIC_AUTH_USERNAME=admin \
DUCKPOND_BASIC_AUTH_PASSWORD=secret \
pnpm serve:test:http

开发命令

# Pre-checkin validation
pnpm validate      # format + lint + test + build

# Individual commands
pnpm format        # Format with Prettier
pnpm lint          # Fix ESLint issues
pnpm test          # Run tests
pnpm test:watch    # Run tests in watch mode
pnpm test:coverage # Run tests with coverage
pnpm build         # Production build
pnpm ts-types      # Check TypeScript types

建筑

图书馆优先设计

MCP服务器是 薄传输层 在...之上 鸭池 图书馆：

┌─────────────┐     ┌──────────────┐
│ stdio Mode  │     │  HTTP Mode   │
│ (index.ts)  │     │(FastMCP/3000)│
└──────┬──────┘     └──────┬───────┘
       │                   │
       └───────┬───────────┘
               │
       ┌───────▼────────┐
       │ MCP Tool Layer │  (server-core.ts)
       │ - Error mapping│
       │ - Result format│
       └───────┬────────┘
               │
       ┌───────▼────────┐
       │    DuckPond    │  npm: duckpond@^0.1.0
       │ - Multi-tenant │
       │ - LRU Cache    │
       │ - R2/S3        │
       │ - Either  │
       └───────┬────────┘
               │
       ┌───────▼────────┐
       │ DuckDB + Cloud │
       └────────────────┘

关键组件

• src/index.ts -CLI入口点、传输选择
• src/server-core.ts -带有MCP结果类型的DuckPond包装
• src/server-stdio.ts -Claude Desktop的stdio传输
• src/server-fastmcp.ts -使用FastMCP的HTTP传输
• src/tools/index.ts -MCP工具模式和实现

错误处理

用途 函数类型 对于功能错误处理：

// DuckPond returns Either
const result = await pond.query(userId, sql)

// MCP server converts to MCPResult
result.fold(
  (error) => ({ success: false, error: formatError(error) }),
  (data) => ({ success: true, data }),
)

用例

个人分析

使用自动云备份存储每个用户的分析数据：

// User creates their own tables
await execute({
  userId: "user123",
  sql: "CREATE TABLE orders (id INT, total DECIMAL, date DATE)",
})

// Query their data
const result = await query({
  userId: "user123",
  sql: "SELECT SUM(total) FROM orders WHERE date > '2024-01-01'",
})

多用户应用程序

• 每个用户都会获得隔离的DuckDB实例
• 自动LRU驱逐管理内存
• 云存储保存用户数据
• 使用DuckDB的列式引擎进行快速查询

数据科学工作流程

• 拼花文件管理
• 云数据湖集成
• 复杂的分析查询
• 每用户沙盒环境

故障排除

服务器无法启动

检查DuckDB安装：

npm list duckdb

验证环境变量：

printenv | grep DUCKPOND

身份验证问题

OAuth不工作：

• 验证 DUCKPOND_OAUTH_USERNAME 和 DUCKPOND_OAUTH_PASSWORD 已设置
• 检查浏览器控制台是否有错误
• 确保重定向URI匹配

基本身份验证失败：

• 验证凭据是否设置正确
• 检查 Authorization: Basic 头部格式
• 确保用户名/密码与环境变量匹配

内存问题

调整内存限制：

export DUCKPOND_MEMORY_LIMIT=8GB
export DUCKPOND_MAX_ACTIVE_USERS=5

监控缓存使用情况：

const stats = await getUserStats({ userId: "user123" })
console.log(`Memory: ${stats.memoryUsage} bytes`)

存储问题

R2/S3连接错误：

• 验证凭据是否正确
• 检查铲斗是否存在且可接近
• 使用AWS CLI进行测试： aws s3 ls s3://your-bucket

拼花文件问题：

• 确保DuckDB拼花地板扩展件已装载
• 检查存储桶中的文件权限

贡献

欢迎投稿！请看 贡献.md 作为指导方针。

许可证

麻省理工学院

相关项目

• 鸭池 -核心多租户DuckDB库
• 函数类型 -TypeScript的函数式编程工具
• 模型上下文协议 -MCP规范

支持

• 问题:
• 讨论:
• 文档: docs/