口袋基础-MCP

Name: 口袋基础-MCP
Author: mabeldata

作者：mabeldata24 星标更新：2025-04-23

安装使用来源：spider==github.com

项目介绍

PocketBase MCP 服务器

这是一个与 PocketBase 实例交互的 MCP 服务器。它允许您获取、列出、创建、更新和管理 PocketBase 集合中的记录和文件。

安装

通过 Smithery 安装

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

npx -y @smithery/cli install @mabeldata/pocketbase-mcp --client claude

克隆仓库（如果尚未克隆）：

git clone <repository_url>
cd pocketbase-mcp

安装依赖项：
```
npm install
```
构建服务器：
```
npm run build
```
这会将 TypeScript 代码编译成 build/ 目录下的 JavaScript，并使入口点可执行。

配置

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

POCKETBASE_API_URL：您的 PocketBase 实例的 URL（例如，http://127.0.0.1:8090）。默认值为 http://127.0.0.1:8090。
POCKETBASE_ADMIN_TOKEN：您的 PocketBase 实例的管理员身份验证令牌。这是必需的。 您可以从 PocketBase 管理界面生成此令牌，参见 API KEYS。

在将服务器添加到 Cline 时需要配置这些变量（参见 Cline 安装部分）。

可用工具

该服务器提供了以下工具，按类别组织：

记录管理

fetch_record：根据 ID 从 PocketBase 集合中获取单个记录。

输入模式：

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称。"
    },
    "id": {
      "type": "string",
      "description": "要获取的记录的 ID。"
    }
  },
  "required": [
    "collection",
    "id"
  ]
}

list_records：列出 PocketBase 集合中的记录。支持分页、过滤、排序和扩展关系。

输入模式：

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称。"
    },
    "page": {
      "type": "number",
      "description": "页码（默认为 1）。",
      "minimum": 1
    },
    "perPage": {
      "type": "number",
      "description": "每页项目数（默认为 25）。",
      "minimum": 1,
      "maximum": 100
    },
    "filter": {
      "type": "string",
      "description": "用于 PocketBase 查询的过滤字符串。"
    },
    "sort": {
      "type": "string",
      "description": "用于 PocketBase 查询的排序字符串（例如，\\"fieldName,-otherFieldName\\")。"
    },
    "expand": {
      "type": "string",
      "description": "用于 PocketBase 查询的扩展字符串（例如，\\"relation1,relation2.subRelation\\")。"
    }
  },
  "required": [
    "collection"
  ]
}

create_record：在 PocketBase 集合中创建新记录。

输入模式：

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称。"
    },
    "data": {
      "type": "object",
      "description": "新记录的数据。",
      "additionalProperties": true
    }
  },
  "required": [
    "collection",
    "data"
  ]
}

update_record：更新 PocketBase 集合中的现有记录。

输入模式：

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称。"
    },
    "id": {
      "type": "string",
      "description": "要更新的记录的 ID。"
    },
    "data": {
      "type": "object",
      "description": "要更新的数据。",
      "additionalProperties": true
    }
  },
  "required": [
    "collection",
    "id",
    "data"
  ]
}

get_collection_schema：获取 PocketBase 集合的模式。

输入模式：

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称。"
    }
  },
  "required": [
    "collection"
  ]
}

upload_file：将文件上传到 PocketBase 集合记录中的特定字段。

输入模式：

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称。"
    },
    "recordId": {
      "type": "string",
      "description": "要上传文件的记录的 ID。"
    },
    "fileField": {
      "type": "string",
      "description": "PocketBase 集合中的文件字段名称。"
    },
    "fileContent": {
      "type": "string",
      "description": "要上传的文件内容。"
    },
    "fileName": {
      "type": "string",
      "description": "文件名。"
    }
  },
  "required": [
    "collection",
    "recordId",
    "fileField",
    "fileContent",
    "fileName"
  ]
}

list_collections：列出 PocketBase 实例中的所有集合。
- 输入模式：
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

download_file：获取存储在 PocketBase 集合记录中的文件的下载 URL。

输入模式：

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称。"
    },
    "recordId": {
      "type": "string",
      "description": "要从中下载文件的记录的 ID。"
    },
    "fileField": {
      "type": "string",
      "description": "PocketBase 集合中的文件字段名称。"
    },
    "downloadPath": {
      "type": "string",
      "description": "下载文件应保存的位置路径（注意：此工具当前返回 URL，实际下载需单独处理）。"
    }
  },
  "required": [
    "collection",
    "recordId",
    "fileField",
    "downloadPath"
  ]
}

注意：此工具返回文件 URL。实际下载需要客户端使用此 URL 来完成。

集合管理

list_collections：列出 PocketBase 实例中的所有集合。
- 输入模式：
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

get_collection_schema：获取 PocketBase 集合的模式。

输入模式：

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "PocketBase 集合的名称。"
    }
  },
  "required": [
    "collection"
  ]
}

日志管理

注意： 日志 API 需要管理员身份验证，并且可能在某些 PocketBase 实例或配置中不可用。这些工具与 PocketBase 日志 API 交互，如在 https://pocketbase.io/docs/api-logs/ 中所述。

list_logs：列出 PocketBase 的 API 请求日志，支持过滤、排序和分页。

输入模式：

{
  "type": "object",
  "properties": {
    "page": {
      "type": "number",
      "description": "页码（默认为 1）。",
      "minimum": 1
    },
    "perPage": {
      "type": "number",
      "description": "每页项目数（默认为 30，最大 500）。",
      "minimum": 1,
      "maximum": 500
    },
    "filter": {
      "type": "string",
      "description": "PocketBase 过滤字符串（例如，\"method='GET'\"）。"
    }
  },
  "required": []
}

get_log：根据 ID 获取单个 API 请求日志。

输入模式：

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "要获取的日志的 ID。"
    }
  },
  "required": [
    "id"
  ]
}

get_logs_stats：获取 API 请求日志统计信息，可选过滤。

输入模式：

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "string",
      "description": "PocketBase 过滤字符串（例如，\"method='GET'\"）。"
    }
  },
  "required": []
}

定时任务管理

注意： 定时任务 API 需要管理员身份验证，并且可能在某些 PocketBase 实例或配置中不可用。这些工具与 PocketBase 定时任务 API 交互。

list_cron_jobs：返回所有已注册的应用级定时任务列表。

输入模式：

{
  "type": "object",
  "properties": {
    "fields": {
      "type": "string",
      "description": "逗号分隔的字符串，表示要在 JSON 响应中返回的字段（默认返回所有字段）。例如：?fields=*,expand.relField.name"
    }
  }
}

run_cron_job：触发单个定时任务。

输入模式：

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "要运行的定时任务的标识符。"
    }
  },
  "required": [
    "jobId"
  ]
}

数据迁移管理

set_migrations_directory：设置迁移文件的创建和读取目录。

输入模式：

{
  "type": "object",
  "properties": {
    "customPath": { 
      "type": "string", 
      "description": "迁移的自定义路径。如果没有提供，默认为当前工作目录下的 'pb_migrations'。" 
    }
  }
}

create_migration：创建一个新的空 PocketBase 迁移文件，带有时间戳名称。

输入模式：

{
  "type": "object",
  "properties": {
    "description": { 
      "type": "string", 
      "description": "迁移文件名的简短描述（例如，'add_user_email_index'）。" 
    }
  },
  "required": ["description"]
}

create_collection_migration：创建一个专门用于创建新的 PocketBase 集合的迁移文件。

输入模式：

{
  "type": "object",
  "properties": {
    "description": { 
      "type": "string", 
      "description": "文件名的可选描述覆盖。" 
    },
    "collectionDefinition": {
      "type": "object",
      "description": "新集合的完整模式定义（包括名称、ID、字段、规则等）。",
      "additionalProperties": true
    }
  },
  "required": ["collectionDefinition"]
}

add_field_migration：创建一个用于向现有集合添加字段的迁移文件。

输入模式：

{
  "type": "object",
  "properties": {
    "collectionNameOrId": { 
      "type": "string", 
      "description": "要更新的集合的名称或 ID。" 
    },
    "fieldDefinition": {
      "type": "object",
      "description": "新字段的模式定义。",
      "additionalProperties": true
    },
    "description": { 
      "type": "string", 
      "description": "文件名的可选描述覆盖。" 
    }
  },
  "required": ["collectionNameOrId", "fieldDefinition"]
}

list_migrations：列出 PocketBase 迁移目录中找到的所有迁移文件。
- 输入模式：
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

apply_migration：应用特定的迁移文件。

输入模式：

{
  "type": "object",
  "properties": {
    "migrationFile": { 
      "type": "string", 
      "description": "要应用的迁移文件名。" 
    }
  },
  "required": ["migrationFile"]
}

revert_migration：回滚特定的迁移文件。

输入模式：

{
  "type": "object",
  "properties": {
    "migrationFile": { 
      "type": "string", 
      "description": "要回滚的迁移文件名。" 
    }
  },
  "required": ["migrationFile"]
}

apply_all_migrations：应用所有待处理的迁移。

输入模式：

{
  "type": "object",
  "properties": {
    "appliedMigrations": { 
      "type": "array", 
      "items": { "type": "string" },
      "description": "已应用迁移文件名的数组。" 
    }
  }
}

revert_to_migration：回滚到特定的目标。

输入模式：

{
  "type": "object",
  "properties": {
    "targetMigration": { 
      "type": "string", 
      "description": "要回滚到的迁移名称（不包含）。使用空字符串以回滚所有。" 
    },
    "appliedMigrations": { 
      "type": "array", 
      "items": { "type": "string" },
      "description": "已应用迁移文件名的数组。" 
    }
  },
  "required": ["targetMigration"]
}

迁移系统

PocketBase MCP 服务器包含一个全面的迁移系统，用于管理数据库模式更改。此系统允许您：

创建带有时间戳名称的迁移文件
生成常见操作的迁移（创建集合、添加字段）
单独或批量应用和回滚迁移
跟踪哪些迁移已被应用

迁移文件格式

迁移文件是带有时间戳前缀和描述性名称的 JavaScript 文件：

// 1744005374_update_transactions_add_debt_link.js
/// <reference path="../pb_data/types.d.ts" />
migrate((app) => {
  // 上迁代码
  return app.save();
}, (app) => {
  // 下迁代码
  return app.save();
});

每个迁移都有一个“上”函数来应用更改和一个“下”函数来回滚更改。

使用示例

设置自定义迁移目录：

await setMigrationsDirectory("./my_migrations");

创建基本迁移：

await createNewMigration("add_user_email_index");

创建集合迁移：

await createCollectionMigration({
  id: "users",
  name: "users",
  fields: [
    { name: "email", type: "email", required: true }
  ]
});

向集合添加字段：

await createAddFieldMigration("users", {
  name: "address",
  type: "text"
});

应用迁移：

// 应用特定迁移
await applyMigration("1744005374_update_transactions_add_debt_link.js", pocketbaseInstance);

// 应用所有待处理迁移
await applyAllMigrations(pocketbaseInstance);

回滚迁移：

// 回滚特定迁移
await revertMigration("1744005374_update_transactions_add_debt_link.js", pocketbaseInstance);

// 回滚到特定点（不包含）
await revertToMigration("1743958155_update_transactions_add_relation_to_itself.js", pocketbaseInstance);

// 回滚所有迁移
await revertToMigration("", pocketbaseInstance);