mcp-nextcloud-calendar: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Build and Run

• npm run build - Build the project (compiles TypeScript)
• npm run start - Run the built application
• npm run dev - Build and run the application in development mode
• npm run dev:watch - Watch for changes and rebuild automatically

Testing and Code Quality

• npm run test - Run tests with Jest
• npm run lint - Run ESLint for static code analysis
• npm run format - Format code with Prettier
• npm run format:check - Check code formatting without modifying files

MCP Tool Registration

To add new functionality, register tools with the MCP server in src/index.ts:

server.registerTool({
  name: 'toolName',
  description: 'Description of what the tool does',
  parameters: {
    // Define parameters here
  },
  execute: async (params) => {
    // Implementation goes here
  }
});

Logging

The application uses a structured logging system with multiple log levels:

import { createLogger } from './services/logger.js';

// Create a logger for your component
const logger = createLogger('ComponentName');

// Log at different levels
logger.debug('Detailed debugging information');
logger.info('General information');
logger.warn('Warning conditions');
logger.error('Error conditions');

Set the LOG_LEVEL environment variable to control verbosity:

• DEBUG - Show all logs

• INFO - Show info, warn, and error logs (default)

• WARN - Show only warnings and errors

• ERROR - Show only errors

• npm run typecheck - Run TypeScript type checking without emitting files

Project Architecture

Overview

This project is a Model Context Protocol (MCP) server for Nextcloud Calendar integration. It allows fetching calendars from Nextcloud, manipulating calendar data, and exposes this functionality through MCP-compatible endpoints.

Core Components

1. MCP Server Implementation
   • Implements the Model Context Protocol for AI agent integration
   • Supports both the latest Streamable HTTP transport (March 2025 spec) and legacy HTTP+SSE transport
   • Handles session management and connection keep-alive