Servidor MCP de Nextcloud Calendar

MCP Nextcloud Calendar

Un servidor de Model Context Protocol (MCP) para la integración con Nextcloud Calendar.

Características

Obtener calendarios de Nextcloud
Funciones de organización adaptadas a TDAH
Soporte de protocolo MCP (HTTP Streamable y HTTP+SSE heredado)

Uso

Uso con npx

La forma más sencilla de usar este paquete es con npx:

npx mcp-nextcloud-calendar

Instalación

Para desarrollo o instalación local:

# Install globally
npm install -g mcp-nextcloud-calendar

# Or install locally
npm install mcp-nextcloud-calendar

Configuración del Cliente MCP

Para usar con un cliente MCP (como Claude), añade esta configuración a los ajustes de tu cliente MCP:

{
  "mcpServers": {
    "nextcloud-calendar": {
      "command": "npx",
      "args": ["-y", "mcp-nextcloud-calendar"],
      "env": {
        "NEXTCLOUD_BASE_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_APP_TOKEN": "your-app-token"
      }
    }
  }
}

Especificar una Versión

Puedes fijar una versión específica del paquete:

{
  "mcpServers": {
    "nextcloud-calendar": {
      "command": "npx",
      "args": ["-y", "mcp-nextcloud-calendar@0.1.0"],
      "env": {
        "NEXTCLOUD_BASE_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_APP_TOKEN": "your-app-token"
      }
    }
  }
}

Configuración

Variables de Entorno

El servidor utiliza estas variables de entorno, con valores predeterminados cuando es posible:

Variable	Descripción	Predeterminado	Requerida
PORT	Puerto del servidor	3001	No
SERVER_NAME	Identificador del servidor MCP	nextcloud-calendar-server	No
NODE_ENV	Entorno (desarrollo/producción)	development	No
NEXTCLOUD_BASE_URL	URL de tu servidor Nextcloud	-	Sí
NEXTCLOUD_USERNAME	Tu nombre de usuario de Nextcloud	-	Sí
NEXTCLOUD_APP_TOKEN	Tu token de aplicación de Nextcloud	-	Sí
KEEP_ALIVE_INTERVAL	Intervalo de keep-alive (ms)	30000	No

Configuración de Desarrollo

Para desarrollo local:

Clona el repositorio
Instala las dependencias:

npm install

Crea un archivo .env en la raíz del proyecto:

cp .env.example .env

Edita el archivo .env con tus credenciales de Nextcloud.

Obtener un Token de Aplicación de Nextcloud

Inicia sesión en tu instancia de Nextcloud
Ve a Configuración → Seguridad → Contraseñas de aplicación
Crea una nueva contraseña de aplicación con un nombre como "MCP Calendar"
Copia el token generado a tu archivo .env

Desarrollo

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm run test

# Run linting
npm run lint

# Format code
npm run format

Endpoints de API

/mcp - Endpoint MCP principal (transporte HTTP Streamable)
/sse y /messages - Endpoints MCP heredados (transporte HTTP+SSE)
GET /health - Endpoint de verificación de salud
GET /api/calendars - Listar todos los calendarios

Herramientas MCP

Las siguientes herramientas MCP están registradas y disponibles para los clientes:

Gestión de Calendarios

Herramienta	Descripción	Parámetros
`listCalendars`	Recupera todos los calendarios accesibles	Ninguno
`createCalendar`	Crea un nuevo calendario	`displayName` (requerido), `color` (opcional), `category` (opcional), `focusPriority` (opcional)
`updateCalendar`	Actualiza un calendario existente	`id` (requerido), `displayName` (opcional), `color` (opcional), `category` (opcional), `focusPriority` (opcional)
`deleteCalendar`	Elimina un calendario	`id` (requerido)

⚠️ Advertencia de Permisos: Las herramientas updateCalendar y deleteCalendar pueden requerir permisos especiales en tu instancia de Nextcloud. Las operaciones de calendario están sujetas al sistema de permisos de Nextcloud.

Gestión de Eventos

Herramienta	Descripción	Parámetros
`listEvents`	Recupera eventos de un calendario	`calendarId` (requerido), `start` (opcional), `end` (opcional)
`getEvent`	Obtiene un evento específico	`calendarId` (requerido), `eventId` (requerido)
`createEvent`	Crea un nuevo evento	`calendarId` (requerido), `summary` (requerido), `start` (requerido), `end` (requerido), `description` (opcional), `location` (opcional)
`updateEvent`	Actualiza un evento existente	`calendarId` (requerido), `eventId` (requerido), [más cualquier propiedad del evento a actualizar]
`deleteEvent`	Elimina un evento	`calendarId` (requerido), `eventId` (requerido)

Problemas Conocidos y Limitaciones

Nota: Este paquete se encuentra actualmente en desarrollo temprano (0.1.x). Las APIs y herramientas pueden cambiar sin previo aviso en futuras versiones.

Las operaciones de actualización y eliminación de calendarios pueden requerir permisos específicos en tu instancia de Nextcloud
El manejo de errores para códigos de error específicos de Nextcloud aún está en mejora
Los calendarios grandes con muchos eventos pueden experimentar problemas de rendimiento

Por favor, reporta cualquier problema en el repositorio de GitHub.

Licencia

ISC

Nextcloud Calendar

Documentación