Name: PocketBase迁移管理服务器
Author: Step-by-Step-technology

使用说明

🚀 PocketBase MCP服务器

一个完整的MCP（模型上下文协议）服务器，用于通过REST API管理PocketBase迁移。生成并执行迁移以创建、修改和删除PocketBase集合。

📥 从GitHub安装

克隆并安装

# Clone the repository
git clone https://github.com/Step-by-Step-technology/pocketbase-mcp.git
cd pocketbase-mcp

# Install dependencies
npm install

# Compile TypeScript
npm run build

快速设置

创建MCP配置文件 (~/.cline_desktop_config.json 或同等）：

{
  "mcpServers": {
    "pocketbase-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_TOKEN": "your_pocketbase_admin_token",
        "POCKETBASE_MIGRATIONS_DIR": "/absolute/path/to/pb_migrations"
      }
    }
  }
}

重新启动MCP客户端 （斜桌面、光标等）

测试安装:

# Start the server in development mode
npm run dev

📦 全局安装（可选）

# Install globally (if you want to use it as CLI)
npm install -g .

# Then run
pocketbase-mcp

GitHub存储库： https://github.com/Step-by-Step-technology/pocketbase-mcp

✨ 特性

✅ 可用工具（20个完整工具）

🏗️ 迁移工具（13个工具）

工具	描述	状态
`pocketbase-create-collection-migration`	生成迁移以创建新集合（支持关系字段）	✅ 工作完美
`pocketbase-update-collection`	生成迁移以修改收集规则	✅ 新
`pocketbase-delete-collection`	生成迁移以删除集合	✅ 新
`pocketbase-update-collection-fields`	生成迁移以修改集合字段（支持关系字段）	✅ 新
`pocketbase-add-field-migration`	生成迁移以将单个字段添加到集合中（支持关系字段）	✅ 新
`pocketbase-remove-field-migration`	生成迁移以从集合中删除单个字段	✅ 新
`pocketbase-revert-migration`	生成迁移以还原之前的迁移	✅ 新
`pocketbase-execute-any-migration`	执行任何类型的迁移（创建、修改、删除）-现在支持关系字段	✅ 改进
`pocketbase-execute-migration`	执行创建迁移（保留原始工具）	✅ 工作完美
`pocketbase-list-migrations`	列出所有可用的迁移	✅ 现有
`pocketbase-view-migration`	显示迁移的内容	✅ 现有
`pocketbase-list-collections`	列出所有PocketBase集合	✅ 现有
`pocketbase-view-collection`	显示收藏详细信息	✅ 现有

📊 CRUD工具（7个工具）

工具	描述	状态
`pocketbase-fetch-record`	从PocketBase集合中获取特定记录	✅ 新
`pocketbase-list-records`	按页码列出集合中的所有记录	✅ 新
`pocketbase-create-record`	在PocketBase集合中创建新记录	✅ 新
`pocketbase-update-record`	更新PocketBase集合中的现有记录	✅ 新
`pocketbase-get-collection-schema`	获取集合的架构（字段和类型）	✅ 新
`pocketbase-upload-file`	将文件上传到PocketBase集合	✅ 新
`pocketbase-download-file`	从PocketBase集合下载文件	✅ 新

总计：20个完整的MCP工具 -迁移+CRUD+文件管理

🚀 安装（备选）

如果您已经在本地克隆了项目或正在使用现有版本：

先决条件

Node.js 18+
PocketBase正在运行
Pocketbase管理令牌

本地安装

# Move to the pocketbase-mcp folder
cd pocketbase-mcp

# Install dependencies
npm install

# Compile TypeScript
npm run build

注：有关GitHub的完整安装，请参阅 📥 从GitHub安装上面的部分。

配置

环境变量在MCP配置文件中配置(cline_mcp_settings.json):

{
  "mcpServers": {
    "pocketbase-mcp": {
      "command": "node",
      "args": ["/absolute/path/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_TOKEN": "your_pocketbase_admin_token",
        "POCKETBASE_MIGRATIONS_DIR": "/absolute/path/pb_migrations"
      }
    }
  }
}

所需变量：

POCKETBASE_URL：PocketBase实例的URL（例如。， http://127.0.0.1:8090)
POCKETBASE_TOKEN：PocketBase管理令牌（通过管理界面获取）
POCKETBASE_MIGRATIONS_DIR：迁移目录的绝对路径

📦 项目结构

pocketbase-mcp/
├── src/
│   ├── index.ts                    # MCP entry point
│   ├── pocketbase-migration.ts     # Migration generator
│   └── pocketbase-tools.ts         # All MCP tools
├── dist/                           # Compiled files
├── pb_migrations/                  # Generated migrations
├── package.json
├── tsconfig.json
├── README.md
└── GUIDE_COMPLET.md

🛠️ 用法

启动MCP服务器

# Development
npm run dev

# Production
npm run build
node dist/index.js

Cline桌面配置

添加到 ~/.cline_desktop_config.json:

{
  "mcpServers": {
    "pocketbase-mcp": {
      "command": "node",
      "args": ["/absolute/path/pocketbase-mcp/dist/index.js"],
      "env": {
        "POCKETBASE_URL": "http://127.0.0.1:8090",
        "POCKETBASE_TOKEN": "your_token",
        "POCKETBASE_MIGRATIONS_DIR": "/absolute/path/pb_migrations"
      }
    }
  }
}

📝 完整示例

1.创建收藏

{
  "collectionName": "products",
  "fields": [
    {
      "name": "title",
      "type": "text",
      "required": true,
      "max": 200
    },
    {
      "name": "price",
      "type": "number",
      "required": true,
      "min": 0
    },
    {
      "name": "category",
      "type": "select",
      "required": true,
      "values": ["electronics", "clothing", "books", "food", "home"]
    }
  ],
  "type": "base"
}

2.修改收款规则

{
  "collectionName": "products",
  "listRule": "@request.auth.id != ''",
  "createRule": "@request.auth.id != ''",
  "updateRule": "@request.auth.id != ''",
  "deleteRule": "@request.auth.id != ''"
}

3.修改集合字段

{
  "collectionName": "products",
  "fields": [
    {
      "name": "title",
      "type": "text",
      "required": true,
      "max": 200
    },
    {
      "name": "description",
      "type": "text",
      "required": false,
      "max": 1000
    },
    {
      "name": "price",
      "type": "number",
      "required": true,
      "min": 0
    },
    {
      "name": "stock",
      "type": "number",
      "required": false,
      "min": 0
    }
  ]
}

4.删除收藏

{
  "collectionName": "old_collection"
}

5.执行迁移

{
  "migrationFile": "1768985344_update_products.js"
}

6.向集合中添加字段

{
  "collectionName": "products",
  "field": {
    "name": "stock",
    "type": "number",
    "required": false,
    "min": 0
  }
}

7.从集合中删除字段

{
  "collectionName": "products",
  "fieldName": "stock"
}

8.恢复迁移

{
  "migrationFile": "1768987877_add_field_stock_to_products.js"
}

🔄 完成工作流程

步骤1：创建迁移

# Use the pocketbase-create-collection-migration tool
# → Generates a file in pb_migrations/

步骤2：执行迁移

# Use the pocketbase-execute-any-migration tool
# → Executes the migration via REST API

步骤3：验证

# Use pocketbase-list-collections
# → Verifies that the collection was created

步骤4：必要时进行修改

# Use pocketbase-update-collection
# → Generates a modification migration
# → Execute with pocketbase-execute-any-migration

🎯 高级用例

使用身份验证规则进行创建迁移

{
  "collectionName": "user_posts",
  "fields": [
    {
      "name": "title",
      "type": "text",
      "required": true,
      "max": 200
    },
    {
      "name": "content",
      "type": "text",
      "required": false,
      "max": 5000
    }
  ],
  "listRule": "@request.auth.id != ''",
  "createRule": "@request.auth.id != ''",
  "updateRule": "@request.auth.id = author",
  "deleteRule": "@request.auth.id = author"
}

身份验证集合迁移

{
  "collectionName": "users",
  "type": "auth",
  "fields": [
    {
      "name": "username",
      "type": "text",
      "required": true,
      "max": 100
    },
    {
      "name": "avatar",
      "type": "file",
      "required": false,
      "maxSelect": 1
    }
  ]
}

⚙️ 技术配置

环境变量

变量	描述	默认值
`POCKETBASE_URL`	PocketBase实例的URL	`http://127.0.0.1:8090`
`POCKETBASE_TOKEN`	PocketBase管理令牌	（必需）
`POCKETBASE_ADMIN_TOKEN`	替代令牌	（可选）
`POCKETBASE_MIGRATIONS_DIR`	迁移目录	`./pb_migrations`

NPM脚本

{
  "scripts": {
    "build": "tsc",
    "dev": "tsx watch src/index.ts",
    "start": "node dist/index.js"
  }
}

🆕 新功能（2026年1月）

✨ 新增3个工具

1. `pocketbase-add-field-migration`

目的：将单个字段添加到现有集合中
优势：精细粒度-无需重写所有字段

使用示例:

{
  "collectionName": "products",
  "field": {
    "name": "stock",
    "type": "number",
    "required": false,
    "min": 0
  }
}

2. `pocketbase-remove-field-migration`

目的：从现有集合中删除单个字段
优势：有针对性地删除，不影响其他字段

使用示例:

{
  "collectionName": "products",
  "fieldName": "stock"
}

3. `pocketbase-revert-migration`

目的：还原以前的迁移
优势：安全性-撤消更改的能力

使用示例:

{
  "migrationFile": "1768987877_add_field_stock_to_products.js"
}

🔧 ……的改进 `pocketbase-execute-any-migration`

新检测：现在识别6种类型的迁移：
1. create -收藏创建
2. update -规则修改
3. update_fields -修改所有字段
4. add_field -添加单个字段
5. remove_field -删除单个字段
6. delete -收藏删除
兼容性：不会破坏现有功能-原始功能 pocketbase-execute-migration 工具被保存

🔗 关系字段支持（2026年1月）

✨ 增强对关系字段的支持

MCP服务器现在完全支持 关系字段 在PocketBase系列中。这包括使用集合之间的外键关系创建、更新和管理集合。

关键改进

固定的 parseMigrationFields() 函数 在 src/pocketbase-migration.ts:
- 正确处理 collectionId 关系字段的参数
- 正确序列化关系字段配置
- 支持 maxSelect 和 cascadeDelete 选项
增强 pocketbase-execute-any-migration 工具:
- 现在可以正确处理包含关系字段的迁移文件
- 正确处理具有复杂字段关系的迁移执行
更新 pocketbase-update-collection-fields 工具:
- 支持在现有集合中添加/修改关系字段
- 保持与现有集合的向后兼容性

📋 关系字段示例

创建具有关系字段的集合

{
  "collectionName": "user_roles",
  "fields": [
    {
      "name": "user_ref",
      "type": "relation",
      "required": true,
      "collectionId": "users",
      "maxSelect": 1,
      "cascadeDelete": false
    },
    {
      "name": "role_ref",
      "type": "relation",
      "required": true,
      "collectionId": "roles",
      "maxSelect": 1,
      "cascadeDelete": false
    },
    {
      "name": "assigned_at",
      "type": "date",
      "required": true
    },
    {
      "name": "assigned_by",
      "type": "relation",
      "required": true,
      "collectionId": "users",
      "maxSelect": 1,
      "cascadeDelete": false
    }
  ],
  "type": "base"
}

向现有集合添加关系字段

{
  "collectionName": "posts",
  "field": {
    "name": "author",
    "type": "relation",
    "required": true,
    "collectionId": "users",
    "maxSelect": 1,
    "cascadeDelete": true
  }
}

🛠️ 技术细节

这些修复解决了以下问题：

Bug in parseMigrationFields()：该函数未正确处理 collectionId 关系字段的参数，导致在创建具有关系的集合时迁移失败。
迁移执行：The pocketbase-execute-any-migration 该工具现在可以正确检测并执行包含关系字段的迁移，而不会出现错误。
字段配置：关系字段现在支持所有PocketBase选项：
- collectionId：相关集合的ID（必填）
- maxSelect：相关记录的最大数量（默认值：1）
- cascadeDelete：删除父项时是否删除相关记录（默认：false）

✅ 测试

关系现场支持已通过以下方式进行了彻底测试：

✅ 创建具有关系字段的集合：工作得很好
✅ 向现有集合添加关系字段：工作得很好
✅ 使用关系字段执行迁移：工作得很好
✅ 真实世界用例：用户角色系统 users ↔ roles 关系

🎯 现实世界示例：用户角色系统

使用增强的关系字段支持实现了完整的用户角色系统：

roles 收集：存储角色定义（级别0-9，超级管理员级别99）
user_roles 收集：将用户链接到具有关系字段的角色的联接表
访问规则：配置了正确的身份验证规则
默认角色分配：所有新用户自动获得级别1（基本用户）

这展示了关系字段支持在使用PocketBase构建复杂数据库模式中的实际应用。

🧪 测试

该项目已成功通过以下测试：

✅ 手动测试 所有功能
✅ 实际迁移 在PocketBase上执行
✅ 完成验证 13个MCP工具中
✅ 新功能测试:
- 字段添加：✅ 作品
- 字段删除：✅ 作品
- 迁移还原：✅ 作品

要测试MCP服务器，请执行以下操作：

# Start the server in development mode
npm run dev

# Then use the tools via Cline Desktop or other MCP client

🔧 发展

代码结构

src/pocketbase-migration.ts：迁移生成逻辑
- createMigrationFile()：收藏创建
- createUpdateMigrationFile()：收藏修改
- createDeleteMigrationFile()：删除收藏
- createUpdateFieldsMigrationFile()：字段修改
- parseMigrationFields()：解析迁移中的字段
src/pocketbase-tools.ts：MCP工具定义
- 10个完整的Zod验证工具
- 稳健的错误处理
- REST API到PocketBase
src/index.ts：主MCP服务器
- 服务器配置
- 连接管理
- 日志记录与监视

添加新工具

在中添加定义 pocketbase-tools.ts
实现业务逻辑
使用MCP工具手动测试
README中的文档

📊 项目统计

10个完整的MCP工具
4种类型的迁移 支持（创建、修改、删除、字段修改）
100%TypeScript 通过Zod验证
完整的REST API 到PocketBase
稳健的错误处理
完整的文件

🚀 在GitHub上部署

为GitHub准备项目

# Initialize git
git init

# Add files
git add .

# Initial commit
git commit -m "Initial commit: Complete PocketBase MCP Server"

# Create a repo on GitHub
# Link the remote repo
git remote add origin https://github.com/your-username/pocketbase-mcp.git

# Push the code
git push -u origin main

.gitignore中要包含的文件

# Dependencies
node_modules/

# Build outputs
dist/

# Environment variables
.env
.env.local

# PocketBase migrations (optional)
pb_migrations/

# IDE
.vscode/
.idea/

# OS
.DS_Store

用于发布的Package.json

确保你的 package.json 包含：

{
  "name": "pocketbase-mcp",
  "version": "1.0.0",
  "description": "MCP Server for PocketBase migrations",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "dev": "tsx watch src/index.ts",
    "start": "node dist/index.js"
  },
  "keywords": ["mcp", "pocketbase", "migrations", "database"],
  "author": "Step by Step",
  "license": "MIT",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.22.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.0.0",
    "tsx": "^4.0.0"
  }
}

使用说明

🚀 PocketBase MCP服务器

📥 从GitHub安装

克隆并安装

快速设置

📦 全局安装（可选）

✨ 特性

✅ 可用工具（20个完整工具）

🏗️ 迁移工具（13个工具）

📊 CRUD工具（7个工具）

🚀 安装（备选）

先决条件

本地安装

配置

📦 项目结构

🛠️ 用法

启动MCP服务器

Cline桌面配置

📝 完整示例

1.创建收藏

2.修改收款规则

3.修改集合字段

4.删除收藏

5.执行迁移

6.向集合中添加字段

7.从集合中删除字段

8.恢复迁移

🔄 完成工作流程

步骤1：创建迁移

步骤2：执行迁移

步骤3：验证

步骤4：必要时进行修改

🎯 高级用例

使用身份验证规则进行创建迁移

身份验证集合迁移

⚙️ 技术配置

环境变量

NPM脚本

🆕 新功能（2026年1月）

✨ 新增3个工具

1. pocketbase-add-field-migration

2. pocketbase-remove-field-migration

3. pocketbase-revert-migration

🔧 ……的改进 pocketbase-execute-any-migration

🔗 关系字段支持（2026年1月）

✨ 增强对关系字段的支持

关键改进

📋 关系字段示例

创建具有关系字段的集合

向现有集合添加关系字段

🛠️ 技术细节

✅ 测试

🎯 现实世界示例：用户角色系统

🧪 测试

🔧 发展

代码结构

添加新工具

📊 项目统计

🚀 在GitHub上部署

为GitHub准备项目

.gitignore中要包含的文件

用于发布的Package.json

相关 MCP

Obsidian笔记搜索服务

n8n工作流管理服务

Web漏洞扫描MCP服务器

知识库AI代理服务器

Neo N3 区块链 MCP 服务器

F5设备管理服务器

1. `pocketbase-add-field-migration`

2. `pocketbase-remove-field-migration`

3. `pocketbase-revert-migration`

🔧 ……的改进 `pocketbase-execute-any-migration`