Pocketbase Server

JavaScript

MIT License

DynamicEndpoints

最近更新：16天前

pocketbase-mcp-server

概述

高级 PocketBase MCP 服务器

这是一个全面的 MCP 服务器，提供了与 PocketBase 数据库交互的高级工具。此服务器通过 Model Context Protocol (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: 自定义数据目录路径

使用示例

集合管理

typescript 复制代码

// 创建新集合
await mcp.use_tool("pocketbase", "create_collection", {
  name: "posts",
  schema: [
    {
      name: "title",
      type: "text",
      required: true
    },
    {
      name: "content",
      type: "text",
      required: true
    }
  ]
});

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

高级查询

typescript 复制代码

// 具有过滤、排序和聚合功能的查询
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"
});

数据导入/导出

typescript 复制代码

// 以追加模式导入数据
await mcp.use_tool("pocketbase", "import_data", {
  collection: "posts",
  data: [
    {
      title: "First Post",
      content: "Hello World"
    },
    {
      title: "Second Post",
      content: "More content"
    }
  ],
  mode: "upsert"
});

// 备份数据库
await mcp.use_tool("pocketbase", "backup_database", {
  format: "json" // 或 "csv"
});

模式迁移

typescript 复制代码

// 迁移集合模式
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: {
    // 迁移期间的可选字段转换
    tags: "JSON.parse(oldTags)"
  }
});

批量和实时操作

typescript 复制代码

// 批量更新记录
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" } }
  ]
});

// 批量删除记录
await mcp.use_tool("pocketbase", "batch_delete_records", {
  collection: "products",
  recordIds: ["record_id_3", "record_id_4"]
});

// 订阅集合更改（将事件记录到服务器控制台）
// 注意：需要在运行服务器的 Node.js 环境中安装 'eventsource' 包。
await mcp.use_tool("pocketbase", "subscribe_to_collection", {
  collection: "products"
});

// 订阅特定记录
await mcp.use_tool("pocketbase", "subscribe_to_collection", {
  collection: "products",
  recordId: "specific_product_id"
});

身份验证方法

typescript 复制代码

// 列出可用的身份验证方法
await mcp.use_tool("pocketbase", "list_auth_methods", {
  collection: "users"
});

// 通过密码进行身份验证
await mcp.use_tool("pocketbase", "authenticate_user", {
  email: "user@example.com",
  password: "securepassword",
  collection: "users"
});

// 通过 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"
});

// 请求密码重置
await mcp.use_tool("pocketbase", "request_password_reset", {
  email: "user@example.com",
  collection: "users"
});

// 确认密码重置
await mcp.use_tool("pocketbase", "confirm_password_reset", {
  token: "verification_token",
  password: "new_password",
  passwordConfirm: "new_password",
  collection: "users"
});

// 刷新身份验证令牌
await mcp.use_tool("pocketbase", "auth_refresh", {
  collection: "users"
});

错误处理

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

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

类型安全

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

最佳实践

始终使用 try/catch 块进行适当的错误处理
在执行操作之前验证数据
使用适当的索引以提高查询性能
定期备份数据库
使用迁移进行模式更改
遵循用户管理的安全最佳实践
监控和优化数据库性能

开发

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

通过 Smithery 安装

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

bash 复制代码

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

贡献

叉仓库
创建一个功能分支
提交您的更改
推送到分支
创建拉取请求