calendario mcp-nextcloud

Calendario de MCP Nextcloud

Un servidor de Protocolo de Contexto de Modelo (MCP) para la integración del Calendario de Nextcloud.

Características

Obtener calendarios de Nextcloud
Características de una organización amigable con el TDAH
Compatibilidad con el protocolo MCP (HTTP de transmisión continua y HTTP+SSE heredado)

Uso

Uso con npx

La forma más sencilla de utilizar 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 utilizar con un cliente MCP (como Claude), agregue esta configuración a la configuración de su 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"
      }
    }
  }
}

Especificación de una versión

Puedes anclar a 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 sea posible:

Variable	Descripción	Por defecto	Requerido
PUERTO	Puerto del servidor	3001	No
NOMBRE DEL SERVIDOR	Identificador del servidor MCP	servidor de calendario de nextcloud	No
NODO_ENV	Medio ambiente (desarrollo/producción)	desarrollo	No
URL BASE DE LA SIGUIENTE NUBE	La URL de su servidor Nextcloud	-	Sí
NEXTCLOUD_NOMBRE_USUARIO	Su nombre de usuario de Nextcloud	-	Sí
TOKEN DE LA APLICACIÓN NEXTCLOUD	Su token de aplicación de Nextcloud	-	Sí
INTERVALO DE MANTENER VIVO	Intervalo de mantenimiento de conexión (ms)	30000	No

Configuración de desarrollo

Para el desarrollo local:

Clonar el repositorio
Instalar dependencias:

npm install

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

cp .env.example .env

Edite el archivo .env con sus credenciales de Nextcloud.

Obtener un token de aplicación de Nextcloud

Inicie sesión en su instancia de Nextcloud
Vaya a Configuración → Seguridad → Contraseñas de aplicaciones
Crea una nueva contraseña para la aplicación con un nombre como "Calendario MCP".
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

Puntos finales de API

/mcp - Punto final MCP principal (transporte HTTP transmitible)
/sse y /messages : puntos finales MCP heredados (transporte HTTP+SSE)
GET /health - Punto final de comprobación de estado
GET /api/calendars - Listar todos los calendarios

Herramientas MCP

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

Gestión del calendario

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

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

Gestión de eventos

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

Problemas y limitaciones conocidos

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

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

Informe cualquier problema en el repositorio de GitHub.

Licencia

ISC

mcp-nextcloud-calendar