@fadlee/pocketbase-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 DynamicEndpoints
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# PocketBase MCP Server
+
+Seamless integration between PocketBase and MCP clients through the Model Context Protocol (MCP). This server enables MCP-compatible applications to directly interact with PocketBase databases for collection management, record operations, schema generation, and data analysis.
+
+## ✨ Key Features
+
+- **🗄️ Collection Management**: Create, migrate, and manage collections with custom schemas
+- **📝 Record Operations**: Full CRUD operations with advanced querying and filtering
+- **🔄 Schema Generation**: Bidirectional conversion between TypeScript interfaces and PocketBase schemas
+- **📊 Data Analysis**: Intelligent insights and analytics for your collections
+- **🔐 Authentication**: User management and authentication workflows
+- **⚡ Performance**: Optimized for speed with built-in caching and connection pooling
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install -g @fadlee/pocketbase-mcp
+```
+
+### MCP Client Setup
+
+#### For Cursor AI
+1. Open Cursor AI Settings (`Cmd+,` / `Ctrl+,`)
+2. Navigate to **AI** → **Model Context Protocol Servers**
+3. Add new server:
+   - **Name**: `pocketbase`
+   - **Command**: `npx`
+   - **Args**: `@fadlee/pocketbase-mcp --url=http://127.0.0.1:8090`
+
+#### For Other MCP Clients
+Refer to your MCP client's documentation for server configuration. Use:
+- **Server Command**: `npx @fadlee/pocketbase-mcp`
+- **Arguments**: `--url=http://127.0.0.1:8090`
+
+### Basic Configuration
+
+```bash
+# Using command line
+npx @fadlee/pocketbase-mcp --url=http://127.0.0.1:8090
+
+# Using environment variables
+export POCKETBASE_URL=http://127.0.0.1:8090
+npx @fadlee/pocketbase-mcp
+```
+
+## 💡 Usage Examples
+
+### Create Collections from TypeScript
+```typescript
+// Describe your interface to your MCP client
+interface User {
+  username: string;
+  email: string;
+  isActive: boolean;
+  profile: UserProfile;
+}
+```
+
+### Generate TypeScript from PocketBase
+```
+Generate TypeScript interfaces from my PocketBase collections
+```
+
+### Data Analysis
+```
+Analyze the "products" collection and provide insights
+```
+
+## 🛠️ Available Tools
+
+**Collection Management**: `create_collection`, `list_collections`, `delete_collection`, `get_collection_schema`, `update_collection`, `truncate_collection`, `migrate_collection`
+
+**Record Operations**: `create_record`, `list_records`, `update_record`, `delete_record`, `query_collection`
+
+**Authentication**: `authenticate_user`, `create_user`
+
+**Code Generation**: `generate_pb_schema`, `generate_typescript_interfaces`
+
+**Analysis**: `analyze_collection_data`, `backup_database`, `import_data`
+
+**File Management**: `upload_file`, `download_file`, `upload_file_from_url`
+
+**Advanced**: `manage_indexes`
+
+> 📖 **[Complete API Reference →](./docs/api-reference.md)**
+
+## 📚 Documentation
+
+- **[Getting Started](./docs/getting-started.md)** - Installation and configuration guide
+- **[Developer Guide](./docs/developer-guide.md)** - How to extend the server with new tools
+- **[API Reference](./docs/api-reference.md)** - Complete tool reference and examples
+- **[Architecture](./docs/architecture.md)** - System design and architectural decisions
+- **[Contributing](./docs/contributing.md)** - Guidelines for contributors
+
+## 🏗️ Architecture
+
+Built with a modular, extensible architecture:
+
+```
+src/
+├── tools/          # Modular tool system
+│   ├── schemas/    # Input validation
+│   └── handlers/   # Business logic
+├── utils/          # Shared utilities
+├── types/          # TypeScript definitions
+└── config/         # Configuration management
+```
+
+**Key Benefits**:
+- 🔧 **Extensible**: Easy to add new tools
+- 🛡️ **Type-Safe**: Full TypeScript coverage
+- ⚡ **Performance**: Optimized for speed
+- 🧪 **Testable**: Comprehensive test coverage
+
+## Contributing
+
+Contributions are always welcome! Please create an issue or pull request.
+
+## License
+
+MIT

package/build/src/config/cli.d.ts

@@ -0,0 +1,9 @@
+export interface CLIConfig {
+    url?: string;
+    adminEmail?: string;
+    adminPassword?: string;
+}
+/**
+ * Parse command line arguments for PocketBase MCP Server
+ */
+export declare function parseCliArgs(): CLIConfig;

package/build/src/config/cli.js

@@ -0,0 +1,31 @@
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+/**
+ * Parse command line arguments for PocketBase MCP Server
+ */
+export function parseCliArgs() {
+    const argv = yargs(hideBin(process.argv))
+        .option("url", {
+        alias: "u",
+        type: "string",
+        description: "PocketBase URL",
+    })
+        .option("admin-email", {
+        alias: "e",
+        type: "string",
+        description: "Admin email for authentication",
+    })
+        .option("admin-password", {
+        alias: "p",
+        type: "string",
+        description: "Admin password for authentication",
+    })
+        .help()
+        .alias("help", "h")
+        .parseSync();
+    return {
+        url: argv.url,
+        adminEmail: argv["admin-email"],
+        adminPassword: argv["admin-password"],
+    };
+}

package/build/src/config/environment.d.ts

@@ -0,0 +1,9 @@
+export interface EnvironmentConfig {
+    pocketbaseUrl?: string;
+    adminEmail?: string;
+    adminPassword?: string;
+}
+/**
+ * Load and parse environment variables for PocketBase MCP Server
+ */
+export declare function loadEnvironmentConfig(): EnvironmentConfig;

package/build/src/config/environment.js

@@ -0,0 +1,13 @@
+import dotenv from "dotenv";
+/**
+ * Load and parse environment variables for PocketBase MCP Server
+ */
+export function loadEnvironmentConfig() {
+    // Load environment variables from .env file
+    dotenv.config();
+    return {
+        pocketbaseUrl: process.env.POCKETBASE_URL,
+        adminEmail: process.env.POCKETBASE_ADMIN_EMAIL,
+        adminPassword: process.env.POCKETBASE_ADMIN_PASSWORD,
+    };
+}

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

@@ -0,0 +1,13 @@
+import { CLIConfig } from "./cli.js";
+import { EnvironmentConfig } from "./environment.js";
+export interface ServerConfig {
+    url: string;
+    adminEmail?: string;
+    adminPassword?: string;
+}
+/**
+ * Create unified server configuration by merging CLI args and environment variables
+ * CLI arguments take precedence over environment variables
+ */
+export declare function createServerConfig(): ServerConfig;
+export { CLIConfig, EnvironmentConfig };

package/build/src/config/index.js

@@ -0,0 +1,20 @@
+import { parseCliArgs } from "./cli.js";
+import { loadEnvironmentConfig } from "./environment.js";
+/**
+ * Create unified server configuration by merging CLI args and environment variables
+ * CLI arguments take precedence over environment variables
+ */
+export function createServerConfig() {
+    const cliConfig = parseCliArgs();
+    const envConfig = loadEnvironmentConfig();
+    // Prioritize CLI args over environment variables
+    const url = cliConfig.url || envConfig.pocketbaseUrl;
+    if (!url) {
+        throw new Error("PocketBase URL is required. Provide it via --url parameter or POCKETBASE_URL environment variable.");
+    }
+    return {
+        url,
+        adminEmail: cliConfig.adminEmail || envConfig.adminEmail,
+        adminPassword: cliConfig.adminPassword || envConfig.adminPassword,
+    };
+}

package/build/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/src/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { createServerConfig } from "./config/index.js";
+import { startServer } from "./server.js";
+// Main entry point
+async function main() {
+    try {
+        // Create server configuration from CLI args and environment
+        const config = createServerConfig();
+        // Start the MCP server
+        await startServer(config);
+    }
+    catch (error) {
+        console.error("Failed to start PocketBase MCP Server:", error);
+        process.exit(1);
+    }
+}
+// Start the server
+main().catch((error) => {
+    console.error("Unhandled error:", error);
+    process.exit(1);
+});

package/build/src/server.d.ts

@@ -0,0 +1,10 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { ServerConfig } from "./config/index.js";
+/**
+ * Create and configure the MCP server
+ */
+export declare function createServer(config: ServerConfig): Server;
+/**
+ * Start the MCP server
+ */
+export declare function startServer(config: ServerConfig): Promise<void>;

package/build/src/server.js

@@ -0,0 +1,211 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import PocketBase from "pocketbase";
+import { handlePocketBaseError } from "./utils/errors.js";
+// Import all schemas
+import { createCollectionSchema, deleteCollectionSchema, getCollectionSchemaSchema, listCollectionsSchema, truncateCollectionSchema, createRecordSchema, listRecordsSchema, updateRecordSchema, deleteRecordSchema, authenticateUserSchema, createUserSchema, analyzeCollectionDataSchema, queryCollectionSchema, migrateCollectionSchema, backupDatabaseSchema, importDataSchema, manageIndexesSchema, generatePbSchemaSchema, generateTypescriptInterfacesSchema, uploadFileSchema, downloadFileSchema, uploadFileFromUrlSchema, } from "./tools/index.js";
+// Import all handlers
+import { createCreateCollectionHandler, createDeleteCollectionHandler, createGetCollectionSchemaHandler, createListCollectionsHandler, createTruncateCollectionHandler, createCreateRecordHandler, createListRecordsHandler, createUpdateRecordHandler, createDeleteRecordHandler, createAuthenticateUserHandler, createCreateUserHandler, createAnalyzeCollectionDataHandler, createQueryCollectionHandler, createMigrateCollectionHandler, createBackupDatabaseHandler, createImportDataHandler, createManageIndexesHandler, createGeneratePbSchemaHandler, createGenerateTypescriptInterfacesHandler, createUploadFileHandler, createDownloadFileHandler, createUploadFileFromUrlHandler, } from "./tools/index.js";
+/**
+ * Create and configure the MCP server
+ */
+export function createServer(config) {
+    const server = new Server({
+        name: "@fadlee/pocketbase-mcp",
+        version: "1.0.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Initialize PocketBase client
+    const pb = new PocketBase(config.url);
+    // Authenticate admin if credentials provided
+    if (config.adminEmail && config.adminPassword) {
+        pb.collection("_superusers").authWithPassword(config.adminEmail, config.adminPassword)
+            .catch((error) => {
+            console.error("Failed to authenticate admin:", error);
+        });
+    }
+    // Tool definitions with their schemas and handlers
+    const tools = [
+        // Collection tools
+        {
+            name: "create_collection",
+            description: "Create a new collection in PocketBase",
+            inputSchema: createCollectionSchema,
+            handler: createCreateCollectionHandler(pb),
+        },
+        {
+            name: "delete_collection",
+            description: "Delete a collection from PocketBase",
+            inputSchema: deleteCollectionSchema,
+            handler: createDeleteCollectionHandler(pb),
+        },
+        {
+            name: "get_collection_schema",
+            description: "Get schema details for a collection",
+            inputSchema: getCollectionSchemaSchema,
+            handler: createGetCollectionSchemaHandler(pb),
+        },
+        {
+            name: "list_collections",
+            description: "List all collections with optional sorting",
+            inputSchema: listCollectionsSchema,
+            handler: createListCollectionsHandler(pb),
+        },
+        {
+            name: "truncate_collection",
+            description: "Delete all records associated with the specified collection",
+            inputSchema: truncateCollectionSchema,
+            handler: createTruncateCollectionHandler(pb),
+        },
+        // Record tools
+        {
+            name: "create_record",
+            description: "Create a new record in a collection",
+            inputSchema: createRecordSchema,
+            handler: createCreateRecordHandler(pb),
+        },
+        {
+            name: "list_records",
+            description: "List records from a collection with optional filters",
+            inputSchema: listRecordsSchema,
+            handler: createListRecordsHandler(pb),
+        },
+        {
+            name: "update_record",
+            description: "Update an existing record",
+            inputSchema: updateRecordSchema,
+            handler: createUpdateRecordHandler(pb),
+        },
+        {
+            name: "delete_record",
+            description: "Delete a record",
+            inputSchema: deleteRecordSchema,
+            handler: createDeleteRecordHandler(pb),
+        },
+        // Auth tools
+        {
+            name: "authenticate_user",
+            description: "Authenticate a user and get auth token",
+            inputSchema: authenticateUserSchema,
+            handler: createAuthenticateUserHandler(pb),
+        },
+        {
+            name: "create_user",
+            description: "Create a new user account",
+            inputSchema: createUserSchema,
+            handler: createCreateUserHandler(pb),
+        },
+        // Analysis tools
+        {
+            name: "analyze_collection_data",
+            description: "Analyze data patterns and provide insights about a collection",
+            inputSchema: analyzeCollectionDataSchema,
+            handler: createAnalyzeCollectionDataHandler(pb),
+        },
+        {
+            name: "query_collection",
+            description: "Advanced query with filtering, sorting, and aggregation",
+            inputSchema: queryCollectionSchema,
+            handler: createQueryCollectionHandler(pb),
+        },
+        // Migration tools
+        {
+            name: "migrate_collection",
+            description: "Add, remove, or modify fields from a collection",
+            inputSchema: migrateCollectionSchema,
+            handler: createMigrateCollectionHandler(pb),
+        },
+        {
+            name: "backup_database",
+            description: "Create a backup of the PocketBase database",
+            inputSchema: backupDatabaseSchema,
+            handler: createBackupDatabaseHandler(pb),
+        },
+        {
+            name: "import_data",
+            description: "Import data into a collection",
+            inputSchema: importDataSchema,
+            handler: createImportDataHandler(pb),
+        },
+        {
+            name: "manage_indexes",
+            description: "Manage collection indexes",
+            inputSchema: manageIndexesSchema,
+            handler: createManageIndexesHandler(pb),
+        },
+        // Generation tools
+        {
+            name: "generate_pb_schema",
+            description: "Generate a PocketBase schema based on TypeScript interfaces or database diagram",
+            inputSchema: generatePbSchemaSchema,
+            handler: createGeneratePbSchemaHandler(pb),
+        },
+        {
+            name: "generate_typescript_interfaces",
+            description: "Generate TypeScript interfaces from PocketBase collections",
+            inputSchema: generateTypescriptInterfacesSchema,
+            handler: createGenerateTypescriptInterfacesHandler(pb),
+        },
+        // File tools
+        {
+            name: "upload_file",
+            description: "Upload a file to a record in PocketBase",
+            inputSchema: uploadFileSchema,
+            handler: createUploadFileHandler(pb),
+        },
+        {
+            name: "download_file",
+            description: "Download a file from a record in PocketBase",
+            inputSchema: downloadFileSchema,
+            handler: createDownloadFileHandler(pb),
+        },
+        {
+            name: "upload_file_from_url",
+            description: "Upload a file from URL to a record in PocketBase",
+            inputSchema: uploadFileFromUrlSchema,
+            handler: createUploadFileFromUrlHandler(pb),
+        },
+    ];
+    // Register list_tools handler
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: tools.map(tool => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+            })),
+        };
+    });
+    // Register call_tool handler
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const tool = tools.find(t => t.name === name);
+        if (!tool) {
+            throw new Error(`Unknown tool: ${name}`);
+        }
+        try {
+            const result = await tool.handler(args || {});
+            return {
+                content: result.content,
+            };
+        }
+        catch (error) {
+            throw handlePocketBaseError(`tool ${name}`, error);
+        }
+    });
+    return server;
+}
+/**
+ * Start the MCP server
+ */
+export async function startServer(config) {
+    const server = createServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("PocketBase MCP Server started successfully");
+    console.error(`Connected to PocketBase at: ${config.url}`);
+}

package/build/src/tools/handlers/analysis.d.ts

@@ -0,0 +1,10 @@
+import type PocketBase from "pocketbase";
+import type { ToolHandler } from "../../types/index.js";
+/**
+ * Analyze data patterns and provide insights about a collection
+ */
+export declare function createAnalyzeCollectionDataHandler(pb: PocketBase): ToolHandler;
+/**
+ * Advanced query with filtering, sorting, and aggregation
+ */
+export declare function createQueryCollectionHandler(pb: PocketBase): ToolHandler;

package/build/src/tools/handlers/analysis.js

@@ -0,0 +1,127 @@
+import { handlePocketBaseError } from "../../utils/errors.js";
+import { createJsonResponse } from "../../utils/response.js";
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Analyze data patterns and provide insights about a collection
+ */
+export function createAnalyzeCollectionDataHandler(pb) {
+    return async (args) => {
+        try {
+            const { collection, options = {} } = args;
+            const sampleSize = options.sampleSize || 100;
+            // Get collection info and records
+            const collectionInfo = await pb.collections.getOne(collection);
+            const records = await pb
+                .collection(collection)
+                .getList(1, sampleSize);
+            // Initialize analysis structure
+            const analysis = {
+                collectionName: collection,
+                recordCount: records.totalItems,
+                fields: [],
+                insights: [],
+            };
+            if (records.items.length === 0) {
+                analysis.insights.push("No records available for analysis");
+                return createJsonResponse(analysis);
+            }
+            // Analyze each field
+            const fields = collectionInfo.fields || [];
+            for (const field of fields) {
+                if (options.fields && !options.fields.includes(field.name)) {
+                    continue;
+                }
+                const fieldAnalysis = {
+                    name: field.name,
+                    type: field.type,
+                    nonNullValues: 0,
+                    uniqueValues: new Set(),
+                    min: null,
+                    max: null,
+                };
+                // Analyze field values
+                for (const record of records.items) {
+                    const value = record[field.name];
+                    if (value !== null && value !== undefined) {
+                        fieldAnalysis.nonNullValues++;
+                        fieldAnalysis.uniqueValues.add(JSON.stringify(value));
+                        // For numeric fields, track min/max
+                        if (field.type === "number") {
+                            if (fieldAnalysis.min === null || value < fieldAnalysis.min) {
+                                fieldAnalysis.min = value;
+                            }
+                            if (fieldAnalysis.max === null || value > fieldAnalysis.max) {
+                                fieldAnalysis.max = value;
+                            }
+                        }
+                    }
+                }
+                // Process analysis results
+                const processedAnalysis = {
+                    ...fieldAnalysis,
+                    uniqueValueCount: fieldAnalysis.uniqueValues.size,
+                    fillRate: `${((fieldAnalysis.nonNullValues / records.items.length) * 100).toFixed(2)}%`,
+                    uniqueValues: undefined, // Remove the Set before serializing
+                };
+                analysis.fields.push(processedAnalysis);
+                // Generate insights
+                if (processedAnalysis.uniqueValueCount === records.items.length &&
+                    records.items.length > 5) {
+                    analysis.insights.push(`Field '${field.name}' contains all unique values, consider using it as an identifier.`);
+                }
+                if (processedAnalysis.nonNullValues === 0) {
+                    analysis.insights.push(`Field '${field.name}' has no values. Consider removing it or ensuring it's populated.`);
+                }
+            }
+            return createJsonResponse(analysis);
+        }
+        catch (error) {
+            throw handlePocketBaseError("analyze collection data", error);
+        }
+    };
+}
+/**
+ * Advanced query with filtering, sorting, and aggregation
+ */
+export function createQueryCollectionHandler(pb) {
+    return async (args) => {
+        try {
+            const collection = pb.collection(args.collection);
+            const options = {};
+            if (args.filter)
+                options.filter = args.filter;
+            if (args.sort)
+                options.sort = args.sort;
+            if (args.expand)
+                options.expand = args.expand;
+            const records = await collection.getList(1, 100, options);
+            const result = { items: records.items };
+            if (args.aggregate) {
+                const aggregations = {};
+                for (const [name, expr] of Object.entries(args.aggregate)) {
+                    const [func, field] = expr.split("(");
+                    const cleanField = field.replace(")", "");
+                    switch (func) {
+                        case "sum":
+                            aggregations[name] = records.items.reduce((sum, record) => sum + (record[cleanField] || 0), 0);
+                            break;
+                        case "avg":
+                            aggregations[name] =
+                                records.items.reduce((sum, record) => sum + (record[cleanField] || 0), 0) / records.items.length;
+                            break;
+                        case "count":
+                            aggregations[name] = records.items.length;
+                            break;
+                        default:
+                            throw new McpError(ErrorCode.InvalidParams, `Unsupported aggregation function: ${func}`);
+                    }
+                }
+                result.aggregations = aggregations;
+            }
+            return createJsonResponse(result);
+        }
+        catch (error) {
+            throw handlePocketBaseError("query collection", error);
+        }
+    };
+}

package/build/src/tools/handlers/auth.d.ts

@@ -0,0 +1,10 @@
+import type PocketBase from "pocketbase";
+import type { ToolHandler } from "../../types/index.js";
+/**
+ * Authenticate a user and get auth token
+ */
+export declare function createAuthenticateUserHandler(pb: PocketBase): ToolHandler;
+/**
+ * Create a new user account
+ */
+export declare function createCreateUserHandler(pb: PocketBase): ToolHandler;