@fadlee/pocketbase-mcp 1.0.0

package/build/src/tools/schemas/migration.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Tool input schemas for migration and backup operations
+ */
+export declare const migrateCollectionSchema: {
+    type: string;
+    properties: {
+        collection: {
+            type: string;
+            description: string;
+        };
+        fields: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+                properties: {
+                    name: {
+                        type: string;
+                        description: string;
+                    };
+                    type: {
+                        type: string;
+                        description: string;
+                        enum: string[];
+                    };
+                    required: {
+                        type: string;
+                        description: string;
+                    };
+                    options: {
+                        type: string;
+                        description: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+        dataTransforms: {
+            type: string;
+            description: string;
+        };
+        name: {
+            type: string;
+            description: string;
+        };
+        listRule: {
+            type: string;
+            description: string;
+        };
+        viewRule: {
+            type: string;
+            description: string;
+        };
+        createRule: {
+            type: string;
+            description: string;
+        };
+        updateRule: {
+            type: string;
+            description: string;
+        };
+        deleteRule: {
+            type: string;
+            description: string;
+        };
+    };
+    required: string[];
+};
+export declare const backupDatabaseSchema: {
+    type: string;
+    properties: {
+        format: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+    };
+};
+export declare const importDataSchema: {
+    type: string;
+    properties: {
+        collection: {
+            type: string;
+            description: string;
+        };
+        data: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+            };
+        };
+        mode: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+    };
+    required: string[];
+};
+export declare const manageIndexesSchema: {
+    type: string;
+    properties: {
+        collection: {
+            type: string;
+            description: string;
+        };
+        action: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        index: {
+            type: string;
+            description: string;
+            properties: {
+                name: {
+                    type: string;
+                };
+                fields: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                };
+                unique: {
+                    type: string;
+                };
+            };
+        };
+    };
+    required: string[];
+};

package/build/src/tools/schemas/migration.js

@@ -0,0 +1,146 @@
+/**
+ * Tool input schemas for migration and backup operations
+ */
+export const migrateCollectionSchema = {
+    type: "object",
+    properties: {
+        collection: {
+            type: "string",
+            description: "Collection name",
+        },
+        fields: {
+            type: "array",
+            description: "New collection fields configuration",
+            items: {
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "Field name",
+                    },
+                    type: {
+                        type: "string",
+                        description: "Field type",
+                        enum: [
+                            "text",
+                            "number",
+                            "bool",
+                            "email",
+                            "url",
+                            "date",
+                            "select",
+                            "relation",
+                            "file",
+                            "json",
+                            "editor",
+                            "autodate",
+                        ],
+                    },
+                    required: {
+                        type: "boolean",
+                        description: "Whether the field is required",
+                    },
+                    options: {
+                        type: "object",
+                        description: "Field-specific options",
+                    },
+                },
+                required: ["name", "type"],
+            },
+        },
+        dataTransforms: {
+            type: "object",
+            description: "Field transformation mappings for converting old field values to new ones",
+        },
+        name: {
+            type: "string",
+            description: "Optional new collection name if you want to rename the collection",
+        },
+        listRule: {
+            type: "string",
+            description: "Optional new rule for listing records",
+        },
+        viewRule: {
+            type: "string",
+            description: "Optional new rule for viewing records",
+        },
+        createRule: {
+            type: "string",
+            description: "Optional new rule for creating records",
+        },
+        updateRule: {
+            type: "string",
+            description: "Optional new rule for updating records",
+        },
+        deleteRule: {
+            type: "string",
+            description: "Optional new rule for deleting records",
+        },
+    },
+    required: ["collection", "fields"],
+};
+export const backupDatabaseSchema = {
+    type: "object",
+    properties: {
+        format: {
+            type: "string",
+            enum: ["json", "csv"],
+            description: "Export format (default: json)",
+        },
+    },
+};
+export const importDataSchema = {
+    type: "object",
+    properties: {
+        collection: {
+            type: "string",
+            description: "Collection name",
+        },
+        data: {
+            type: "array",
+            description: "Array of records to import",
+            items: {
+                type: "object",
+            },
+        },
+        mode: {
+            type: "string",
+            enum: ["create", "update", "upsert"],
+            description: "Import mode (default: create)",
+        },
+    },
+    required: ["collection", "data"],
+};
+export const manageIndexesSchema = {
+    type: "object",
+    properties: {
+        collection: {
+            type: "string",
+            description: "Collection name",
+        },
+        action: {
+            type: "string",
+            enum: ["create", "delete", "list"],
+            description: "Action to perform",
+        },
+        index: {
+            type: "object",
+            description: "Index configuration (for create)",
+            properties: {
+                name: {
+                    type: "string",
+                },
+                fields: {
+                    type: "array",
+                    items: {
+                        type: "string",
+                    },
+                },
+                unique: {
+                    type: "boolean",
+                },
+            },
+        },
+    },
+    required: ["collection", "action"],
+};

package/build/src/tools/schemas/record.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Tool input schemas for record-related operations
+ */
+export declare const createRecordSchema: {
+    type: string;
+    properties: {
+        collection: {
+            type: string;
+            description: string;
+        };
+        data: {
+            type: string;
+            description: string;
+        };
+        expand: {
+            type: string;
+            description: string;
+        };
+        fields: {
+            type: string;
+            description: string;
+        };
+    };
+    required: string[];
+};
+export declare const listRecordsSchema: {
+    type: string;
+    properties: {
+        collection: {
+            type: string;
+            description: string;
+        };
+        filter: {
+            type: string;
+            description: string;
+        };
+        sort: {
+            type: string;
+            description: string;
+        };
+        page: {
+            type: string;
+            description: string;
+        };
+        perPage: {
+            type: string;
+            description: string;
+        };
+        expand: {
+            type: string;
+            description: string;
+        };
+        fields: {
+            type: string;
+            description: string;
+        };
+        skipTotal: {
+            type: string;
+            description: string;
+        };
+    };
+    required: string[];
+};
+export declare const updateRecordSchema: {
+    type: string;
+    properties: {
+        collection: {
+            type: string;
+            description: string;
+        };
+        id: {
+            type: string;
+            description: string;
+        };
+        data: {
+            type: string;
+            description: string;
+        };
+        expand: {
+            type: string;
+            description: string;
+        };
+        fields: {
+            type: string;
+            description: string;
+        };
+    };
+    required: string[];
+};
+export declare const deleteRecordSchema: {
+    type: string;
+    properties: {
+        collection: {
+            type: string;
+            description: string;
+        };
+        id: {
+            type: string;
+            description: string;
+        };
+    };
+    required: string[];
+};

package/build/src/tools/schemas/record.js

@@ -0,0 +1,103 @@
+/**
+ * Tool input schemas for record-related operations
+ */
+export const createRecordSchema = {
+    type: "object",
+    properties: {
+        collection: {
+            type: "string",
+            description: "Collection name",
+        },
+        data: {
+            type: "object",
+            description: "Record data with field values matching the collection schema",
+        },
+        expand: {
+            type: "string",
+            description: "Comma-separated list of relation fields to expand in the response (e.g. 'author,comments.user')",
+        },
+        fields: {
+            type: "string",
+            description: "Comma-separated fields to return in the response (e.g. 'id,title,author')",
+        },
+    },
+    required: ["collection", "data"],
+};
+export const listRecordsSchema = {
+    type: "object",
+    properties: {
+        collection: {
+            type: "string",
+            description: "Collection name",
+        },
+        filter: {
+            type: "string",
+            description: "Filter query using PocketBase filter syntax (e.g. 'status = true && created > \"2022-08-01 10:00:00\"')",
+        },
+        sort: {
+            type: "string",
+            description: "Sort field and direction (e.g. '-created,title' for descending created date followed by ascending title)",
+        },
+        page: {
+            type: "number",
+            description: "Page number for pagination (default: 1)",
+        },
+        perPage: {
+            type: "number",
+            description: "Items per page (default: 50, max: 500)",
+        },
+        expand: {
+            type: "string",
+            description: "Comma-separated list of relation fields to expand (e.g. 'author,comments.user')",
+        },
+        fields: {
+            type: "string",
+            description: "Comma-separated fields to return in the response (e.g. 'id,title,author')",
+        },
+        skipTotal: {
+            type: "boolean",
+            description: "If set to true, the total count query will be skipped to improve performance",
+        },
+    },
+    required: ["collection"],
+};
+export const updateRecordSchema = {
+    type: "object",
+    properties: {
+        collection: {
+            type: "string",
+            description: "Collection name",
+        },
+        id: {
+            type: "string",
+            description: "Record ID",
+        },
+        data: {
+            type: "object",
+            description: "Updated record data with field values matching the collection schema. Can use field modifiers like fieldName+, +fieldName, fieldName-.",
+        },
+        expand: {
+            type: "string",
+            description: "Comma-separated list of relation fields to expand in the response (e.g. 'author,comments.user')",
+        },
+        fields: {
+            type: "string",
+            description: "Comma-separated fields to return in the response (e.g. 'id,title,author')",
+        },
+    },
+    required: ["collection", "id", "data"],
+};
+export const deleteRecordSchema = {
+    type: "object",
+    properties: {
+        collection: {
+            type: "string",
+            description: "Collection name",
+        },
+        id: {
+            type: "string",
+            description: "Record ID",
+        },
+    },
+    required: ["collection", "id"],
+};

package/build/src/types/index.d.ts

@@ -0,0 +1,188 @@
+import type { CollectionModel, CollectionField } from "pocketbase";
+declare module "pocketbase" {
+    interface PocketBase {
+        admins: {
+            authWithPassword(email: string, password: string): Promise<any>;
+        };
+    }
+}
+export type ToolHandler = (args: any) => Promise<ToolResponse>;
+export interface ToolResponse {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+}
+export interface CollectionFieldConfig {
+    name: string;
+    type: string;
+    required?: boolean;
+    system?: boolean;
+    unique?: boolean;
+    min?: number;
+    max?: number;
+    pattern?: string;
+    autogeneratePattern?: string;
+    collectionId?: string;
+    cascadeDelete?: boolean;
+    maxSelect?: number;
+    onCreate?: boolean;
+    onUpdate?: boolean;
+    presentable?: boolean;
+    hidden?: boolean;
+    values?: string[];
+    id?: string;
+}
+export interface CreateCollectionArgs {
+    name: string;
+    type?: "base" | "auth" | "view";
+    fields: CollectionFieldConfig[];
+    listRule?: string;
+    viewRule?: string;
+    createRule?: string;
+    updateRule?: string;
+    deleteRule?: string;
+    indexes?: string[];
+    viewQuery?: string;
+    passwordAuth?: {
+        enabled: boolean;
+        identityFields: string[];
+    };
+}
+export interface UpdateCollectionArgs {
+    collection: string;
+    name?: string;
+    type?: "base" | "auth" | "view";
+    fields?: CollectionFieldConfig[];
+    listRule?: string;
+    viewRule?: string;
+    createRule?: string;
+    updateRule?: string;
+    deleteRule?: string;
+    indexes?: string[];
+    viewQuery?: string;
+    passwordAuth?: {
+        enabled: boolean;
+        identityFields: string[];
+    };
+}
+export interface TruncateCollectionArgs {
+    collection: string;
+}
+export interface CreateRecordArgs {
+    collection: string;
+    data: Record<string, any>;
+    expand?: string;
+    fields?: string;
+}
+export interface ListRecordsArgs {
+    collection: string;
+    filter?: string;
+    sort?: string;
+    page?: number;
+    perPage?: number;
+    expand?: string;
+    fields?: string;
+    skipTotal?: boolean;
+}
+export interface UpdateRecordArgs {
+    collection: string;
+    id: string;
+    data: Record<string, any>;
+    expand?: string;
+    fields?: string;
+}
+export interface DeleteRecordArgs {
+    collection: string;
+    id: string;
+}
+export interface AuthenticateUserArgs {
+    collection?: string;
+    email: string;
+    password: string;
+    autoRefreshThreshold?: number;
+}
+export interface CreateUserArgs {
+    collection?: string;
+    email: string;
+    password: string;
+    passwordConfirm: string;
+    verified?: boolean;
+    emailVisibility?: boolean;
+    additionalData?: Record<string, any>;
+}
+export interface AnalyzeCollectionDataArgs {
+    collection: string;
+    options?: {
+        sampleSize?: number;
+        fields?: string[];
+    };
+}
+export interface QueryCollectionArgs {
+    collection: string;
+    filter?: string;
+    sort?: string;
+    aggregate?: Record<string, string>;
+    expand?: string;
+}
+export interface MigrateCollectionArgs {
+    collection: string;
+    fields: CollectionFieldConfig[];
+    dataTransforms?: Record<string, any>;
+    name?: string;
+    listRule?: string;
+    viewRule?: string;
+    createRule?: string;
+    updateRule?: string;
+    deleteRule?: string;
+}
+export interface BackupDatabaseArgs {
+    format?: "json" | "csv";
+}
+export interface ImportDataArgs {
+    collection: string;
+    data: Record<string, any>[];
+    mode?: "create" | "update" | "upsert";
+}
+export interface ManageIndexesArgs {
+    collection: string;
+    action: "create" | "delete" | "list";
+    index?: {
+        name: string;
+        fields: string[];
+        unique?: boolean;
+    };
+}
+export interface GeneratePbSchemaArgs {
+    sourceCode: string;
+    options?: {
+        includeAuthentication?: boolean;
+        includeTimestamps?: boolean;
+    };
+}
+export interface GenerateTypescriptInterfacesArgs {
+    collections?: string[];
+    options?: {
+        includeRelations?: boolean;
+    };
+}
+export interface UploadFileArgs {
+    collection: string;
+    recordId: string;
+    fileField: string;
+    fileContent: string;
+    fileName: string;
+}
+export interface DownloadFileArgs {
+    collection: string;
+    recordId: string;
+    fileField: string;
+}
+export interface UploadFileFromUrlArgs {
+    collection: string;
+    recordId: string;
+    fileField: string;
+    url: string;
+    fileName?: string;
+}
+export type { CollectionModel, CollectionField };

package/build/src/types/index.js

@@ -0,0 +1 @@
+export {};

package/build/src/utils/errors.d.ts

@@ -0,0 +1,17 @@
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Create a standardized MCP error with proper error message formatting
+ */
+export declare function createMcpError(code: ErrorCode, message: string, error?: unknown): McpError;
+/**
+ * Handle and format errors from PocketBase operations
+ */
+export declare function handlePocketBaseError(operation: string, error: unknown): McpError;
+/**
+ * Validate required parameters and throw appropriate errors
+ */
+export declare function validateRequiredParams(params: Record<string, any>, requiredFields: string[]): void;
+/**
+ * Validate enum values
+ */
+export declare function validateEnumValue(value: any, allowedValues: string[], fieldName: string): void;