PocketBase MCP Server

# PocketBase MCP Server A comprehensive Model Context Protocol (MCP) server for PocketBase, providing both user and superuser functionality through a rich set of tools. ## Features ### 🔐 User Authentication - User login/logout with email and password - User registration with validation - Password reset workflows - Token refresh functionality - Current user information retrieval ### 👨‍💼 Administrative Functions - Superuser authentication - User management (create, read, update, delete) - User impersonation for testing - Application settings management ### 📊 Collection & Record Management - Full CRUD operations for collections - Collection schema management - Record creation, reading, updating, and deletion - Advanced filtering and pagination - Bulk record operations ### 📁 File Management - File upload to records - File URL generation with thumbnail support - File deletion and management - Private file access tokens ### 🔧 System Operations - Health checks - System logs retrieval and analysis - Backup creation and management - Email testing functionality - Server information retrieval ## Installation 1. **Clone and setup the project:** ```bash cd pb_mcp npm install ``` 2. **Configure environment variables:** The `.env` file should contain: ```env POCKETBASE_URL=http://10.69.100.111:8090 SUPER_USER_LOGIN=your-admin@email.com SUPER_USER_PASSWORD=your-admin-password NODE_ENV=development LOG_LEVEL=info ``` 3. **Build the project:** ```bash npm run build ``` ## Usage ### Development Mode ```bash npm run dev ``` ### Production Mode ```bash npm run start ``` ### Running Tests ```bash # Run all tests npm test # Run tests in watch mode npm run test:watch # Run tests with coverage npm run test:coverage ``` ### Code Quality ```bash # Run linting npm run lint # Fix linting issues npm run lint:fix # Type checking npm run typecheck ``` ## MCP Tools Overview ### Authentication Tools #### `pb_auth_login` Authenticate a user with email and password. **Parameters:** - `email` (string, required): User email address - `password` (string, required): User password - `options` (object, optional): Additional auth options **Example:** ```json { "email": "user@example.com", "password": "securepassword", "options": { "expand": "profile", "fields": "id,email,username" } } ``` #### `pb_auth_register` Register a new user account. **Parameters:** - `email` (string, required): User email address - `password` (string, required): Password (minimum 8 characters) - `passwordConfirm` (string, required): Password confirmation - `username` (string, optional): Username - `name` (string, optional): Display name #### `pb_auth_refresh` Refresh the current authentication token. #### `pb_auth_logout` Logout the current user and clear authentication. #### `pb_auth_get_user` Get information about the currently authenticated user. #### `pb_auth_request_password_reset` Request a password reset email. **Parameters:** - `email` (string, required): Email address for password reset #### `pb_auth_confirm_password_reset` Confirm password reset with token. **Parameters:** - `token` (string, required): Reset token from email - `password` (string, required): New password - `passwordConfirm` (string, required): Password confirmation ### Admin Tools #### `pb_admin_login` Authenticate as superuser/admin. #### `pb_admin_list_users` List all users (admin only). **Parameters:** - `page` (number, optional): Page number (default: 1) - `perPage` (number, optional): Items per page (default: 30) - `sort` (string, optional): Sort criteria - `filter` (string, optional): Filter criteria #### `pb_admin_create_user` Create a new user (admin only). #### `pb_admin_update_user` Update an existing user (admin only). #### `pb_admin_delete_user` Delete a user (admin only). #### `pb_admin_impersonate_user` Impersonate a user for testing (admin only). **Parameters:** - `recordId` (string, required): User ID to impersonate - `duration` (number, optional): Token duration in seconds #### `pb_admin_get_settings` Get application settings (admin only). #### `pb_admin_update_settings` Update application settings (admin only). ### Collection Tools #### `pb_collections_list` List all collections (admin only). #### `pb_collections_get` Get a specific collection by ID or name (admin only). #### `pb_collections_create` Create a new collection (admin only). **Parameters:** - `name` (string, required): Collection name - `type` (string, required): Collection type ("base", "auth", "view") - `schema` (array, optional): Field definitions - `listRule` (string, optional): List access rule - `createRule` (string, optional): Create access rule - etc. #### `pb_collections_update` Update an existing collection (admin only). #### `pb_collections_delete` Delete a collection (admin only). ### Record Tools #### `pb_records_list` List records from a collection with filtering and pagination. **Parameters:** - `collection` (string, required): Collection name or ID - `page` (number, optional): Page number - `perPage` (number, optional): Items per page - `sort` (string, optional): Sort criteria - `filter` (string, optional): Filter criteria - `expand` (string, optional): Relations to expand - `fields` (string, optional): Fields to return #### `pb_records_get` Get a specific record by ID. #### `pb_records_create` Create a new record. #### `pb_records_update` Update an existing record. #### `pb_records_delete` Delete a record. #### `pb_records_bulk_create` Create multiple records at once. ### File Tools #### `pb_files_get_url` Get the URL for a file attached to a record. **Parameters:** - `collection` (string, required): Collection name - `recordId` (string, required): Record ID - `filename` (string, required): File name - `thumb` (string, optional): Thumbnail size #### `pb_files_upload` Upload a file to a record field. **Parameters:** - `collection` (string, required): Collection name - `recordId` (string, required): Record ID - `fieldName` (string, required): Field name - `fileData` (string, required): Base64 encoded file data - `fileName` (string, required): Original file name - `mimeType` (string, optional): File MIME type #### `pb_files_delete` Delete a file from a record field. #### `pb_files_get_token` Get a file access token for private files. #### `pb_files_list_record_files` List all files attached to a record. ### System Tools #### `pb_health_check` Check the health status of the PocketBase server. #### `pb_server_info` Get PocketBase server information and configuration. #### `pb_logs_list` Get system logs (admin only). #### `pb_logs_stats` Get log statistics (admin only). #### `pb_backups_create` Create a new backup (admin only). #### `pb_backups_list` List all available backups (admin only). #### `pb_system_test_email` Send a test email (admin only). ## Architecture ### Project Structure ``` pb_mcp/ ├── src/ │ ├── server.ts # Main MCP server │ ├── pocketbase-service.ts # PocketBase client wrapper │ ├── tools/ # Individual MCP tools │ │ ├── auth.ts # User authentication tools │ │ ├── admin.ts # Superuser/admin tools │ │ ├── collections.ts # Collection management │ │ ├── records.ts # Record CRUD operations │ │ ├── files.ts # File management │ │ └── system.ts # Health, logs, backups │ ├── types/ # TypeScript definitions │ │ ├── pocketbase.ts # PocketBase types │ │ └── mcp.ts # MCP tool types │ └── utils/ # Utility functions │ ├── config.ts # Environment configuration │ └── logger.ts # Logging utility ├── tests/ # Test files ├── package.json ├── tsconfig.json ├── .eslintrc.js └── jest.config.js ``` ### Design Principles 1. **Type Safety**: Full TypeScript implementation with strict type checking 2. **Error Handling**: Comprehensive error handling with proper error types 3. **Authentication**: Dual client support for user and admin operations 4. **Validation**: Parameter validation using Zod schemas 5. **Logging**: Structured logging for debugging and monitoring 6. **Testing**: Comprehensive test coverage for all functionality ## Development ### Adding New Tools 1. **Define the tool schema** in the appropriate file under `src/tools/` 2. **Implement the handler function** with proper error handling 3. **Add parameter validation** using Zod schemas 4. **Export the tool and handler** from the module 5. **Register the tool** in `src/server.ts` 6. **Write tests** for the new functionality ### Configuration The server uses environment variables for configuration: - `POCKETBASE_URL`: PocketBase server URL - `SUPER_USER_LOGIN`: Superuser email - `SUPER_USER_PASSWORD`: Superuser password - `NODE_ENV`: Environment (development/production/test) - `LOG_LEVEL`: Logging level (debug/info/warn/error) ### Error Handling The server implements comprehensive error handling: - **PocketBaseError**: Custom error class for PocketBase-specific errors - **Parameter validation**: Zod schema validation with detailed error messages - **Graceful degradation**: Proper error responses for all failure cases - **Logging**: All errors are logged with context information ## Testing The project includes comprehensive test coverage: - **Unit tests**: Individual component testing - **Integration tests**: Full workflow testing - **Mock tests**: External dependency mocking - **Coverage reports**: Code coverage analysis Run tests with: ```bash npm test # Run all tests npm run test:watch # Watch mode npm run test:coverage # With coverage ``` ## Security Considerations - **Environment variables**: Sensitive credentials stored in environment variables - **Authentication tokens**: Proper token management and refresh - **Parameter validation**: All inputs validated before processing - **Error messages**: No sensitive information leaked in error responses - **Admin operations**: Proper authentication checks for admin-only functions ## Troubleshooting ### Common Issues 1. **Connection errors**: Verify PocketBase URL and server availability 2. **Authentication failures**: Check superuser credentials in `.env` 3. **Permission errors**: Ensure proper collection access rules 4. **Type errors**: Run `npm run typecheck` to identify type issues ### Debug Logging Set `LOG_LEVEL=debug` in your `.env` file for detailed logging. ### Health Check Use the `pb_health_check` tool to verify server connectivity and status. ## Contributing 1. Fork the repository 2. Create a feature branch 3. Implement your changes with tests 4. Run linting and type checking 5. Submit a pull request ## License MIT License - see LICENSE file for details. ## Support For issues and questions: - Check the troubleshooting section - Review the test files for usage examples - Create an issue in the repository