Servidor MCP PocketBase avanzado
Un servidor MCP integral que proporciona herramientas sofisticadas para interactuar con bases de datos de PocketBase. Este servidor permite operaciones avanzadas de bases de datos, gestión de esquemas y manipulación de datos mediante el Protocolo de Contexto de Modelo (MCP).
Registro de cambios
v2.0.0 (2 de abril de 2025)
Agregado
- Soporte mejorado de autenticación de administrador con variables de entorno
- Se agregó soporte para la suplantación de administrador a través de la herramienta
impersonate_user - Manejo mejorado de errores para operaciones de autenticación
- Se agregaron definiciones de tipos de TypeScript completas para una mejor experiencia de desarrollo
- Se agregó soporte para la integración de Cline
Fijado
- Se corrigieron errores de TypeScript en la implementación del cliente PocketBase
- Manejo mejorado de campos de esquema con anotaciones de tipo adecuadas
- Se solucionaron problemas con las propiedades de campos de esquema opcionales
Cambió
- Se actualizó el flujo de autenticación para admitir múltiples métodos de autenticación.
- Documentación mejorada con ejemplos más detallados
- Opciones de configuración de variables de entorno mejoradas
Características
Gestión de cobros
- Crear y administrar colecciones con esquemas personalizados
- Migrar esquemas de recopilación con preservación de datos
- Gestión avanzada de índices (crear, eliminar, listar)
- Validación de esquemas y seguridad de tipos
- Recuperar esquemas de colección y metadatos
Operaciones de registro
- Operaciones CRUD para registros
- Consultas avanzadas con filtrado, ordenación y agregación
- Capacidades de importación y exportación por lotes
- Apoyo para la expansión de relaciones
- Paginación y navegación basada en cursor
Gestión de usuarios
- Autenticación de usuarios y gestión de tokens
- Creación y gestión de cuentas de usuario
- Gestión de contraseñas
- Control de acceso basado en roles
- Manejo de sesiones
Operaciones de base de datos
- Copia de seguridad y restauración de bases de datos
- Múltiples formatos de exportación (JSON/CSV)
- Herramientas de migración de datos
- Optimización de índices
- Operaciones por lotes
Herramientas disponibles
Gestión de cobros
create_collection : Crea una nueva colección con un esquema personalizadoget_collection_schema : Obtener detalles del esquema para una colecciónmigrate_collection : Migrar el esquema de colección con preservación de datosmanage_indexes : Crea, elimina o enumera índices de colección
Operaciones de registro
create_record : Crea un nuevo registro en una colecciónlist_records : Lista de registros con filtros y paginación opcionalesupdate_record : Actualizar un registro existentedelete_record : Eliminar un registroquery_collection : consulta avanzada con filtrado, ordenación y agregaciónimport_data : Importa datos a una colección con modos de creación, actualización y actualización.
Gestión de usuarios
authenticate_user : Autenticar un usuario y obtener el token de autenticacióncreate_user : Crea una nueva cuenta de usuariolist_auth_methods : enumera todos los métodos de autenticación disponiblesauthenticate_with_oauth2 : Autenticar un usuario con OAuth2authenticate_with_otp : Autenticar un usuario con una contraseña de un solo usoauth_refresh : Actualizar el token de autenticaciónrequest_verification : Solicitar verificación de correo electrónicoconfirm_verification : Confirmar la verificación del correo electrónico con el tokenrequest_password_reset : Solicitar restablecimiento de contraseñaconfirm_password_reset : Confirmar el restablecimiento de contraseña con tokenrequest_email_change : Solicitar cambio de correo electrónicoconfirm_email_change : Confirmar el cambio de correo electrónico con el tokenimpersonate_user : Suplantar la identidad de otro usuario (solo administrador)
Operaciones de base de datos
backup_database : Crea una copia de seguridad de la base de datos de PocketBase con opciones de formatoimport_data : Importa datos con varios modos (crear/actualizar/insertar)
Configuración
El servidor requiere las siguientes variables de entorno:
Variables de entorno opcionales:
POCKETBASE_ADMIN_EMAIL : Correo electrónico de administrador para ciertas operacionesPOCKETBASE_ADMIN_PASSWORD : Contraseña de administradorPOCKETBASE_DATA_DIR : Ruta del directorio de datos personalizado
Ejemplos de uso
Gestión de cobros
// Create a new collection
await mcp.use_tool("pocketbase", "create_collection", {
name: "posts",
schema: [
{
name: "title",
type: "text",
required: true
},
{
name: "content",
type: "text",
required: true
}
]
});
// Manage indexes
await mcp.use_tool("pocketbase", "manage_indexes", {
collection: "posts",
action: "create",
index: {
name: "title_idx",
fields: ["title"],
unique: true
}
});
Consultas avanzadas
// Query with filtering, sorting, and aggregation
await mcp.use_tool("pocketbase", "query_collection", {
collection: "posts",
filter: "created >= '2024-01-01'",
sort: "-created",
aggregate: {
totalLikes: "sum(likes)",
avgRating: "avg(rating)"
},
expand: "author,categories"
});
Importación/exportación de datos
// Import data with upsert mode
await mcp.use_tool("pocketbase", "import_data", {
collection: "posts",
data: [
{
title: "First Post",
content: "Hello World"
},
{
title: "Second Post",
content: "More content"
}
],
mode: "upsert"
});
// Backup database
await mcp.use_tool("pocketbase", "backup_database", {
format: "json" // or "csv"
});
Migración de esquemas
// Migrate collection schema
await mcp.use_tool("pocketbase", "migrate_collection", {
collection: "posts",
newSchema: [
{
name: "title",
type: "text",
required: true
},
{
name: "content",
type: "text",
required: true
},
{
name: "tags",
type: "json",
required: false
}
],
dataTransforms: {
// Optional field transformations during migration
tags: "JSON.parse(oldTags)"
}
});
Métodos de autenticación
// List available authentication methods
await mcp.use_tool("pocketbase", "list_auth_methods", {
collection: "users"
});
// Authenticate with password
await mcp.use_tool("pocketbase", "authenticate_user", {
email: "user@example.com",
password: "securepassword",
collection: "users"
});
// Authenticate with OAuth2
await mcp.use_tool("pocketbase", "authenticate_with_oauth2", {
provider: "google",
code: "auth_code_from_provider",
codeVerifier: "code_verifier_from_pkce",
redirectUrl: "https://your-app.com/auth/callback",
collection: "users"
});
// Request password reset
await mcp.use_tool("pocketbase", "request_password_reset", {
email: "user@example.com",
collection: "users"
});
// Confirm password reset
await mcp.use_tool("pocketbase", "confirm_password_reset", {
token: "verification_token",
password: "new_password",
passwordConfirm: "new_password",
collection: "users"
});
// Refresh authentication token
await mcp.use_tool("pocketbase", "auth_refresh", {
collection: "users"
});
Manejo de errores
Todas las herramientas incluyen un completo sistema de gestión de errores con mensajes detallados. Los errores se tipifican correctamente e incluyen:
- Errores de solicitud no válida
- Errores de autenticación
- Errores de operación de la base de datos
- Errores de validación del esquema
- Errores de red
Seguridad de tipos
El servidor incluye definiciones de TypeScript para todas las operaciones, lo que garantiza la seguridad de tipos al usar las herramientas. El esquema de entrada de cada herramienta está estrictamente tipado y validado.
Mejores prácticas
- Utilice siempre un manejo de errores adecuado con los bloques try/catch
- Validar datos antes de realizar operaciones
- Utilice índices apropiados para un mejor rendimiento de las consultas
- Realice copias de seguridad periódicas de su base de datos
- Utilice migraciones para cambios de esquema
- Siga las mejores prácticas de seguridad para la gestión de usuarios
- Supervisar y optimizar el rendimiento de la base de datos
Desarrollo
- Clonar el repositorio
- Instalar dependencias:
npm install - Copiar
.env.example a .env y configurar - Construir:
npm run build - Inicie su instancia de PocketBase
- El servidor MCP se conectará automáticamente a su instancia de PocketBase
Para instalar PocketBase Server para Claude Desktop automáticamente a través de Smithery :
npx -y @smithery/cli install pocketbase-server --client claude
Contribuyendo
- Bifurcar el repositorio
- Crear una rama de características
- Confirme sus cambios
- Empujar hacia la rama
- Crear una solicitud de extracción