高级 PocketBase MCP 服务器

这是一个全面的 MCP 服务器，提供了与 PocketBase 数据库交互的高级工具。该服务器通过模型上下文协议 (MCP) 启用高级数据库操作、模式管理和数据操作。

更新日志

v2.1.0 (2025年4月3日)

新增

• 添加了 batch_update_records 工具，用于一次更新多个记录。
• 添加了 batch_delete_records 工具，用于一次删除多个记录。
• 添加了 subscribe_to_collection 工具，用于实时事件订阅（需要 eventsource polyfill）。

修复

• 修正了 authenticate_user 的模式，允许通过环境变量进行管理员身份验证而无需显式提供电子邮件/密码。
• 添加了 eventsource 依赖和 polyfill，以在 Node.js 中启用实时订阅。

v2.0.0 (2025年4月2日)

新增

• 增强了通过环境变量支持管理员身份验证
• 通过 impersonate_user 工具添加了管理员模拟支持
• 改进了身份验证操作的错误处理
• 添加了全面的 TypeScript 类型定义，以改善开发体验
• 添加了对 Cline 集成的支持

修复

• 修正了 PocketBase 客户端实现中的 TypeScript 错误
• 通过适当的类型注解改进了模式字段处理
• 修复了可选模式字段属性的问题

变更

• 更新了身份验证流程，以支持多种身份验证方法
• 通过更详细的示例改进了文档
• 增强了环境变量配置选项

功能

集合管理

• 创建和管理带有自定义模式的集合
• 迁移集合模式并保留数据
• 高级索引管理（创建、删除、列出）
• 模式验证和类型安全
• 检索集合模式和元数据

记录操作

• 对记录执行 CRUD 操作
• 具有过滤、排序和聚合功能的高级查询
• 批量导入/导出功能
• 关系扩展支持
• 分页和基于游标的导航

用户管理

• 用户身份验证和令牌管理
• 用户帐户创建和管理
• 密码管理
• 基于角色的访问控制
• 会话处理

数据库操作

• 数据库备份和恢复
• 多种导出格式（JSON/CSV）
• 数据迁移工具
• 索引优化
• 批量操作

可用工具

集合管理

• create_collection: 使用自定义模式创建新集合
• get_collection_schema: 获取集合的模式详细信息
• migrate_collection: 保留数据的情况下迁移集合模式
• manage_indexes: 创建、删除或列出集合索引

记录操作

• create_record: 在集合中创建新记录
• list_records: 列出记录，可选过滤器和分页
• update_record: 更新现有记录
• delete_record: 删除记录
• query_collection: 带有过滤、排序和聚合的高级查询
• batch_update_records: 一次调用更新多条记录
• batch_delete_records: 一次调用删除多条记录
• subscribe_to_collection: 订阅集合中的实时更改（需要在 Node.js 环境中使用 eventsource 包）
• import_data: 将数据导入集合，支持创建/更新/插入模式

用户管理

• authenticate_user: 验证用户并获取授权令牌
• create_user: 创建新的用户账户
• list_auth_methods: 列出所有可用的身份验证方法
• authenticate_with_oauth2: 使用 OAuth2 验证用户
• authenticate_with_otp: 使用一次性密码验证用户
• auth_refresh: 刷新授权令牌
• request_verification: 请求电子邮件验证
• confirm_verification: 使用令牌确认电子邮件验证
• request_password_reset: 请求重置密码
• confirm_password_reset: 使用令牌确认重置密码
• request_email_change: 请求更改电子邮件
• confirm_email_change: 使用令牌确认更改电子邮件
• impersonate_user: 模拟另一个用户（仅管理员）

数据库操作

• backup_database: 创建 PocketBase 数据库的备份，并提供格式选项
• import_data: 以多种模式（创建/更新/插入）导入数据

配置

服务器需要以下环境变量：

• POCKETBASE_URL: 您的 PocketBase 实例的 URL（例如，“http://127.0.0.1:8090”）

可选环境变量：

• POCKETBASE_ADMIN_EMAIL: 用于某些操作的管理员邮箱
• POCKETBASE_ADMIN_PASSWORD: 管理员密码
• POCKETBASE_DATA_DIR: 自定义数据目录路径

使用示例

集合管理

// Create a new collection
await mcp.use_tool("pocketbase", "create_collection", {
  name: "posts",
  schema: [
    {
      name: "title",
      type: "text",
      required: true
    },
    {
      name: "content",
      type: "text",
      required: true
    }
  ]
});

// Manage indexes
await mcp.use_tool("pocketbase", "manage_indexes", {
  collection: "posts",
  action: "create",
  index: {
    name: "title_idx",
    fields: ["title"],
    unique: true
  }
});

高级查询

// Query with filtering, sorting, and aggregation
await mcp.use_tool("pocketbase", "query_collection", {
  collection: "posts",
  filter: "created >= '2024-01-01'",
  sort: "-created",
  aggregate: {
    totalLikes: "sum(likes)",
    avgRating: "avg(rating)"
  },
  expand: "author,categories"
});

数据导入/导出

// Import data with upsert mode
await mcp.use_tool("pocketbase", "import_data", {
  collection: "posts",
  data: [
    {
      title: "First Post",
      content: "Hello World"
    },
    {
      title: "Second Post",
      content: "More content"
    }
  ],
  mode: "upsert"
});

// Backup database
await mcp.use_tool("pocketbase", "backup_database", {
  format: "json" // or "csv"
});

模式迁移

// Migrate collection schema
await mcp.use_tool("pocketbase", "migrate_collection", {
  collection: "posts",
  newSchema: [
    {
      name: "title",
      type: "text",
      required: true
    },
    {
      name: "content",
      type: "text",
      required: true
    },
    {
      name: "tags",
      type: "json",
      required: false
    }
  ],
  dataTransforms: {
    // Optional field transformations during migration
    tags: "JSON.parse(oldTags)"
  }
});

批处理与实时操作

// Batch update records
await mcp.use_tool("pocketbase", "batch_update_records", {
  collection: "products",
  records: [
    { id: "record_id_1", data: { price: 19.99 } },
    { id: "record_id_2", data: { status: "published" } }
  ]
});

// Batch delete records
await mcp.use_tool("pocketbase", "batch_delete_records", {
  collection: "products",
  recordIds: ["record_id_3", "record_id_4"]
});

// Subscribe to collection changes (logs events to server console)
// Note: Requires 'eventsource' package installed in the Node.js environment running the server.
await mcp.use_tool("pocketbase", "subscribe_to_collection", {
  collection: "products"
});

// Subscribe to a specific record
await mcp.use_tool("pocketbase", "subscribe_to_collection", {
  collection: "products",
  recordId: "specific_product_id"
});

身份验证方法

// List available authentication methods
await mcp.use_tool("pocketbase", "list_auth_methods", {
  collection: "users"
});

// Authenticate with password
await mcp.use_tool("pocketbase", "authenticate_user", {
  email: "user@example.com",
  password: "securepassword",
  collection: "users"
});

// Authenticate with OAuth2
await mcp.use_tool("pocketbase", "authenticate_with_oauth2", {
  provider: "google",
  code: "auth_code_from_provider",
  codeVerifier: "code_verifier_from_pkce",
  redirectUrl: "https://your-app.com/auth/callback",
  collection: "users"
});

// Request password reset
await mcp.use_tool("pocketbase", "request_password_reset", {
  email: "user@example.com",
  collection: "users"
});

// Confirm password reset
await mcp.use_tool("pocketbase", "confirm_password_reset", {
  token: "verification_token",
  password: "new_password",
  passwordConfirm: "new_password",
  collection: "users"
});

// Refresh authentication token
await mcp.use_tool("pocketbase", "auth_refresh", {
  collection: "users"
});

错误处理

所有工具都包括全面的错误处理，带有详细的错误信息。错误经过适当分类，包括：

• 无效请求错误
• 身份验证错误
• 数据库操作错误
• 模式验证错误
• 网络错误

类型安全

服务器为所有操作提供了 TypeScript 定义，确保使用工具时的类型安全。每个工具的输入模式都是严格类型化并经过验证的。

最佳实践

1. 总是使用适当的错误处理，如 try/catch 块
2. 在执行操作前验证数据
3. 使用合适的索引来提高查询性能
4. 定期备份您的数据库
5. 使用迁移来更改模式
6. 遵循用户管理的安全最佳实践
7. 监控并优化数据库性能

开发

1. 克隆仓库
2. 安装依赖：npm install
3. 将 .env.example 复制为 .env 并进行配置
4. 构建：npm run build
5. 启动你的 PocketBase 实例
6. MCP 服务器将自动连接到你的 PocketBase 实例

通过 Smithery 安装

要通过 Smithery 自动安装 Claude Desktop 的 PocketBase 服务器：

npx -y @smithery/cli install pocketbase-server --client claude

贡献

1. 叉出仓库
2. 创建一个功能分支
3. 提交你的更改
4. 推送到该分支
5. 创建一个 Pull Request