使用说明

高级PocketBase MCP服务器

一个全面的MCP服务器，提供与PocketBase数据库交互的复杂工具。此服务器通过模型上下文协议（MCP）实现高级数据库操作、模式管理和数据操作。 现在有了Cloudflare Workers的全面支持和用于无服务器部署的持久对象！

更新日志

v4.0.0（2025年6月30日）-Cloudflare Workers和持久对象支持

新增-无服务器部署和生产就绪

🚀 Cloudflare员工支持：完整的无服务器部署功能
- worker.ts：具有路由和请求处理功能的Cloudflare Worker主入口点
- durable-object.ts：用于有状态MCP会话的高级持久对象实现
- agent-worker-compatible.ts：工人优化的PocketBase MCP代理
- 通过持久对象实现实时MCP连接的完整WebSocket支持
🔧 生产部署工具：已准备好部署配置
- wrangler.toml：完成Cloudflare Workers配置
- Dockerfile 和 Dockerfile.test：Docker支持开发和测试
- tsconfig.worker.json：特定于工作者的TypeScript配置
🛡️ 超级管理员身份验证：运行时管理员权限升级
- pocketbase_super_admin_auth 工具：在运行时以超级管理员身份进行身份验证
- 以编程方式启用管理操作（集合创建、架构更改）
- 全面的安全分析和能力测试
📊 高级诊断：生产监控和调试工具
- debug_pocketbase_auth：身份验证和连接测试
- check_pocketbase_write_permissions：编写操作能力分析
- analyze_pocketbase_capabilities：完整的安全模型文档
- 生产与开发环境检测和指导

增强型-无服务器架构

🌐 多个部署选项:
- 传统Node.js服务器（现有）
- Cloudflare持久对象工人（新）
- Docker容器化支持（新）
⚡ 性能优化:
- 持久的对象休眠以提高成本效益
- 连接池和会话管理
- 具有指数回退的自动重试逻辑
🔐 企业安全:
- 生产安全模式检测
- 具有旁路功能的管理员操作限制
- 全面的审计日志记录和会话跟踪

文档

📖 完整的部署指南:
- CLOUDFLARE_DEPLOYMENT.md：逐步部署Cloudflare
- SUPER_ADMIN_AUTH.md：超级管理员身份验证使用指南
- OPERATION_CAPABILITIES.md：生产安全模型说明
🔄 迁移支持: CLOUDFLARE_AGENT.md 用于过渡到无服务器

技术改进

跨Node.js和Cloudflare Workers的完全TypeScript兼容性
多个部署目标的环境变量管理
针对网络和身份验证失败的全面错误处理
长时间运行会话的资源清理和内存管理

此主要版本将Advanced PocketBase MCP Server转换为生产就绪、支持无服务器的解决方案，可以部署在Cloudflare的全球边缘网络上，同时保持与传统部署的完全兼容性。

更新日志

v3.0.0（2025年6月10日）

已添加-完整的全栈SaaS后端集成

电子邮件服务集成：完整的电子邮件功能，支持SMTP和SendGrid
- 10个全面的电子邮件MCP工具：创建/更新/删除模板，发送模板化/自定义电子邮件
- 电子邮件记录和模板管理系统
- 连接测试和默认模板设置
增强条纹服务：先进的支付处理能力
- 10个额外的Stripe MCP工具，用于完整的支付管理
- 付款意向创建、客户管理、订阅处理
- 完整的webhook处理和产品同步
全栈SaaS自动化：5个完整的工作流自动化工具
- register_user_with_automation：通过电子邮件和Stripe客户创建完成用户注册
- create_subscription_flow：通过电子邮件通知进行端到端订阅设置
- process_payment_webhook_with_email：通过自动电子邮件通知进行Webhook处理
- setup_complete_saas_backend：一键SaaS后端初始化
- cancel_subscription_with_email：通过客户通知取消订阅
生产就绪监控：后端状态监控和健康检查
- get_saas_backend_status：全面的生产准备状态报告
- 服务健康检查、收集验证、模板验证
- 生产准备评估和建议

增强的服务

电子邮件服务：已添加 updateTemplate() 和 testConnection() 方法
条纹服务：已添加 createPaymentIntent(), retrieveCustomer(), updateCustomer(), cancelSubscription() 方法
高级收藏：自动设置 stripe_products, stripe_customers, stripe_subscriptions, stripe_payments, email_templates, email_logs

固定的

TypeScript语法错误：已解决index.ts中的所有编译错误
导入语句：修复了email.ts服务中格式错误的导入
工具注册：更正了MCP工具注册语法和结构

技术改进

所有新服务和工具的完全类型安全
对所有电子邮件和支付操作进行全面的错误处理
具有适当关注点分离的模块化服务架构
所有外部服务的基于环境的配置

此版本将Advanced PocketBase MCP Server转换为完整的全栈SaaS后端解决方案，通过模型上下文协议提供用户管理、支付处理、电子邮件通信和业务自动化所需的一切。

更新日志

v2.3.0（2025年6月12日）

已添加-SDK兼容性和现代化

完整的SDK兼容性：与最新PocketBase JavaScript SDK v0.2.6.1完全兼容
现代类型定义：完全重写 src/types/pocketbase.d.ts 以匹配实际的SDK API
- 为CollectionService、RecordService、FileService、HealthService、RealtimeService添加了正确的接口
- 更新了具有正确方法签名的AuthStore、AuthData、AuthMethods列表
- 删除了当前SDK版本中不存在的不兼容功能
身份验证方法现代化：更新了所有身份验证工具，以使用当前的SDK模式
- 固定的 authenticate_with_otp 使用 requestOTP() 用于启动OTP流
- 更新 authenticate_with_oauth2 使用 authWithOAuth2Code() 具有适当的参数
- 纠正了方法套管 authWithOtp 到 authWithOTP 匹配SDK
- 修复了所有已弃用的AuthStore引用 model 要更正的属性 record 财产

已修复SDK兼容性问题

删除了不兼容的功能：使用不存在的SDK方法清理工具
- 移除 get_collection_scaffolds 工具（使用不存在 collections.getScaffolds())
- 移除 import_collections 工具（使用不存在 collections.import())
- 替换 createBatch() 批处理操作工具中具有顺序执行的API调用
界面清理：已删除 ExtendedPocketBase 接口，使用标准 PocketBase 直接键入
语法更正：修复了各种语法错误，包括缺少括号和分号
构建系统：成功编译TypeScript项目，没有错误，服务器正常启动

增强

工具注册：所有MCP工具注册现在都遵循具有现代SDK功能的正确模式
错误处理：改进了所有身份验证和数据操作中的错误处理
类型安全：增强的TypeScript支持，具有与SDK v0.2.6.1匹配的准确类型定义
文档：创建了全面的CHANGELOG.md，记录了所有更改和突破性更改

技术改进

已验证与MCP TypeScript SDK v1.12.1的兼容性
确保所有工具实现都使用实际的PocketBase SDK v0.2.6.1方法
将批处理操作替换为顺序执行，以在SDK限制范围内工作
提高了整体代码的稳定性和可维护性

此版本确保Advanced PocketBase MCP Server与最新SDK版本完全兼容，并遵循现代开发模式。

v2.2.0（2025年6月7日）

添加

苏格兰和南方能源公司运输支持：添加了服务器发送事件传输，以实现实时流媒体功能
多种运输方式：现在支持stdio、HTTP和SSE传输
实时流媒体：增强 stream_collection_changes 带有MCP通知系统的工具
HTTP服务器模式：具有健康检查端点的新HTTP服务器
快速集成：为HTTP/SSE服务器功能添加了Express.js
流式HTTP协议：支持最新MCP协议版本2025-03-26
向后兼容：保持对传统HTTP+SSE协议2024-11-05的支持

更新

MCP-SDK：更新到最新版本1.12.1
PocketBase SDK：更新到最新版本0.26.1
TypeScript支持：增强的类型定义和错误处理
软件包脚本：为不同的服务器模式添加了新的npm脚本

增强

文档：包含SSE示例的全面README更新
错误处理：改进了错误消息和类型安全性
开发经验：更好的TypeScript集成和调试

技术改进

添加Express类型以更好地支持TypeScript
增强了SSE连接的会话管理
改进运输生命周期管理
服务器关闭时更好地清理资源

更新日志

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错误
通过正确的类型注释改进了模式字段处理
修复了可选架构字段属性的问题

改变

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

🚀 部署选项

Smithery平台（托管主机）⭐ 推荐给初学者

部署到Smithery的托管平台，用于托管MCP服务器，无需基础设施管理：

优点：

🌐 托管MCP服务器，带交互式网络游乐场
🔧 零基础设施或部署复杂性
🔍 内置测试和发现工具
📊 使用分析和监控仪表板
🛡️ 自动安全更新和维护

快速设置：

访问 Smithery PocketBase服务器
点击“部署”并连接您的GitHub帐户
配置PocketBase URL和可选管理员凭据
立即开始使用网络游乐场

配置选项：

pocketbaseUrl：您的PocketBase实例URL（必填）
adminEmail：提升操作的管理员电子邮件（可选）
adminPassword：提升操作的管理员密码（可选）
debug：启用调试日志记录（可选，默认值：false）

Cloudflare员工（生产规模）

使用持久对象部署到Cloudflare的全球边缘网络，用于有状态的MCP会话：

快速部署：

# Clone and deploy
git clone https://github.com/your-username/advanced-pocketbase-mcp-server
cd advanced-pocketbase-mcp-server
npm install
npm run build
npx wrangler deploy

优点：

⚡ 延迟低于100ms的全球边缘部署
💰 按次付费定价（提供免费套餐）
🔄 自动扩展和负载平衡
🛡️ 内置安全和DDoS保护
📊 先进的诊断和监控工具

传统的Node.js服务器

开发和传统托管的标准部署：

npm install
npm run build
npm start

Docker部署

适用于任何平台的容器化部署：

docker build -t pocketbase-mcp-server .
docker run -p 3000:3000 -e POCKETBASE_URL=your_url pocketbase-mcp-server

特性

馆藏管理

使用自定义模式创建和管理集合
迁移具有数据保留功能的收集模式
高级索引管理（创建、删除、列表）
模式验证和类型安全
检索集合架构和元数据

记录操作

记录的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：订阅集合中的实时更改（需要 eventsource Node.js环境中的包）
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：以各种模式导入数据（创建/更新/追加销售）

🔧 生产诊断和管理工具

debug_pocketbase_auth：测试身份验证和连接状态
check_pocketbase_write_permissions：分析写入操作能力
analyze_pocketbase_capabilities：可用文件与受限操作
pocketbase_super_admin_auth: 在运行时以超级管理员身份进行身份验证
get_server_status：全面的服务器状态和配置
health_check：简单的健康检查终点

🛡️ 超级管理员操作

使用后 pocketbase_super_admin_auth，这些管理员级别的操作变得可用：

集合创建和模式修改
用户管理和身份验证设置
系统配置更改
数据库管理任务

备注：出于安全考虑，生产环境中的管理操作可能会受到限制。使用诊断工具了解部署的安全模型。

配置

Smithery平台（托管主机）

部署时通过Smithery的web界面进行配置：

必修的：

pocketbaseUrl：您的PocketBase实例URL

可选：

adminEmail：超级管理员身份验证的管理员电子邮件
adminPassword：提升操作的管理员密码
debug：启用调试日志以进行故障排除

Node.js部署

所需的环境变量：

POCKETBASE_URL：PocketBase实例的URL（例如，“http://127.0.0.1:8090")

可选环境变量：

POCKETBASE_ADMIN_EMAIL：某些操作的管理员电子邮件
POCKETBASE_ADMIN_PASSWORD：管理员密码
POCKETBASE_DATA_DIR：自定义数据目录路径

Cloudflare员工部署

在中配置 wrangler.toml 或通过Cloudflare仪表板：

[env.production.vars]
POCKETBASE_URL = "https://your-pocketbase-instance.com"
POCKETBASE_ADMIN_EMAIL = "admin@example.com"

[env.production.secrets]
POCKETBASE_ADMIN_PASSWORD = "your-super-secure-password"

环境特定考虑因素：

发展：使用具有完全管理员访问权限的本地PocketBase实例
生产：使用具有潜在管理员限制的托管PocketBase
边缘：Cloudflare Workers提供持久对象的全球部署

生产安全和超级管理员身份验证

管理员凭据启用 pocketbase_super_admin_auth 工具
生产环境可能会出于安全考虑限制管理员API访问
使用诊断工具(analyze_pocketbase_capabilities)了解您的部署
超级管理工具在凭据有效时绕过生产限制

用法示例

馆藏管理

// 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定义，确保使用工具时的类型安全。每个工具的输入模式都经过严格的类型化和验证。

最佳实践

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

发展

Smithery平台开发

克隆存储库
安装依赖项： npm install
安装Smithery CLI： npm install -g @smithery/cli
启动开发服务器： npm run smithery:dev
打开自动生成的游乐场URL进行测试

本地开发（Node.js）

克隆存储库
安装依赖项： npm install
复制 .env.example 到 .env 并配置
构建： npm run build
启动PocketBase实例
运行： npm start

Cloudflare员工发展

克隆存储库
安装依赖项： npm install
配置 wrangler.toml 使用您的设置
构建： npm run build
部署： npx wrangler deploy
测试： npx wrangler tail 用于实时日志

测试超级管理员功能

# Test the super admin authentication tool
node test-super-admin-tool.js

# Run all diagnostic tools to verify setup
# Use your MCP client to call:
# - debug_pocketbase_auth
# - check_pocketbase_write_permissions  
# - analyze_pocketbase_capabilities
# - pocketbase_super_admin_auth

文件结构

src/
├── smithery-entry.ts             # Smithery platform entry point
├── worker.ts                     # Cloudflare Worker entry point
├── durable-object.ts             # Durable Object implementation
├── agent-worker-compatible.ts    # Worker-optimized MCP agent
├── main.ts                       # Node.js server entry point
├── index.ts                      # Legacy Node.js entry point
└── services/                     # Email, Stripe services

通过Smithery安装

配备100多种工具的完整高级PocketBase服务器

Smithery部署现在包括 完全综合代理 具有所有高级功能：

🎯 所有可用工具类别（总计100+个工具）：

🗃️ PocketBase收藏管理 （30多种工具）：创建、管理和迁移具有完整模式支持的集合
📊 PocketBase记录CRUD （20+工具）：通过高级查询和批处理完成记录操作
🔐 PocketBase身份验证 （15+工具）：用户管理、OAuth2、OTP、管理员操作和超级管理员身份验证
⚡ PocketBase实时和WebSocket （10+工具）：实时数据流、订阅和实时更新
💳 Stripe支付处理 （25+工具）：完整的支付基础设施，包括客户、产品、订阅和webhooks
📧 电子邮件和通信 （15+工具）：SMTP、SendGrid、模板管理和自动化电子邮件工作流
🤖 SaaS自动化工作流程 （10+工具）：端到端业务流程自动化
🔧 实用工具和诊断工具 （10+工具）：健康检查、监控和故障排除

选项1：直接安装（推荐）

要安装 完整的高级PocketBase服务器 随着 100+工具 克劳德桌面自动通过史密瑟里:

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

Smithery部署带来的好处

🗄️ PocketBase原油操作 （30+工具）-完整的数据库管理
🔐 管理和身份验证工具 （20+工具）-用户管理和安全
⚡ 实时和WebSocket工具 （10+工具）-实时数据流
💳 Stripe支付处理 （25+工具）-完整的支付工作流程
📧 电子邮件和通信工具 （15+工具）-电子邮件模板和通知
🛠️ 实用工具和诊断工具 （10+工具）-系统监控和调试
📚 资源和提示 -通过示例增强AI交互

选项2：Web平台部署

访问 Smithery PocketBase服务器
点击“部署”按钮
连接您的GitHub帐户并配置设置
使用网络游乐场测试您的服务器

选项3：使用Smithery CLI进行开发

对于想要修改服务器的开发人员：

# Install Smithery CLI
npm install -g @smithery/cli

# Clone and develop
git clone https://github.com/your-username/advanced-pocketbase-mcp-server
cd advanced-pocketbase-mcp-server
npm install

# Start development server with hot reload
npm run smithery:dev

# Build for production
npm run smithery:build

贡献

分叉存储库
创建要素分支
提交您的更改
推到分支
创建拉取请求

使用说明

高级PocketBase MCP服务器

更新日志

v4.0.0（2025年6月30日）-Cloudflare Workers和持久对象支持

新增-无服务器部署和生产就绪

增强型-无服务器架构

文档

技术改进

更新日志

v3.0.0（2025年6月10日）

已添加-完整的全栈SaaS后端集成

增强的服务

固定的

技术改进

更新日志

v2.3.0（2025年6月12日）

已添加-SDK兼容性和现代化

已修复SDK兼容性问题

增强

技术改进

v2.2.0（2025年6月7日）

添加

更新

增强

技术改进

更新日志

v2.1.0（2025年4月3日）

添加

固定的

v2.0.0（2025年4月2日）

添加

固定的

改变

🚀 部署选项

Smithery平台（托管主机）⭐ 推荐给初学者

Cloudflare员工（生产规模）

传统的Node.js服务器

Docker部署

特性

馆藏管理

记录操作

用户管理

数据库操作

可用工具

馆藏管理

记录操作

用户管理

数据库操作

🔧 生产诊断和管理工具

🛡️ 超级管理员操作

配置

Smithery平台（托管主机）

Node.js部署

Cloudflare员工部署

生产安全和超级管理员身份验证

用法示例

馆藏管理

高级查询

数据导入/导出

架构迁移

批处理和实时操作

身份验证方法

错误处理

类型安全

最佳实践

发展

Smithery平台开发

本地开发（Node.js）

Cloudflare员工发展

测试超级管理员功能

文件结构

通过Smithery安装

配备100多种工具的完整高级PocketBase服务器

🎯 所有可用工具类别（总计100+个工具）：

选项1：直接安装（推荐）

Smithery部署带来的好处

选项2：Web平台部署

选项3：使用Smithery CLI进行开发

贡献

相关 MCP