vikunja-mcp: Instructions file for Claude Code

CLAUDE.md

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

Essential Development Commands

Pre-Commit Requirements (ALL must pass)

npm run lint           # ESLint validation
npm run test:coverage  # Jest with 90%+ branches, 95%+ lines coverage requirement  
npm run typecheck      # TypeScript compilation check

Development Workflow

npm run build          # TypeScript compilation to dist/
npm run dev            # Watch mode development server with tsx
npm run test:watch     # Jest in watch mode for TDD

# Single test execution
jest tests/tools/tasks.test.ts              # Specific test file
jest -t "should create task"                # Specific test case by pattern
jest tests/tools/tasks-filters.test.ts      # Test specific functionality

Build and Release

npm run format         # Prettier formatting for src/ and tests/
npm run prepare        # Pre-publish build step
npm run version:patch  # Bump patch version

Architecture Overview

MCP Server Pattern

This is a Model Context Protocol (MCP) server that exposes Vikunja task management operations as tools for AI assistants. The architecture follows a modular design with dependency injection:

• Entry Point: src/index.ts - Initializes McpServer with stdio transport
• Tool Registry: src/tools/index.ts - Centralized registration with conditional loading
• Client Factory: src/client.ts - Session-aware Vikunja API client management
• Auth Manager: Centralized authentication with JWT/API token auto-detection

Tool Design Pattern

Each Vikunja entity follows a consistent subcommand-based pattern:

server.tool('vikunja_tasks', {
  subcommand: z.enum(['create', 'get', 'update', 'delete', 'list']),
  // ... Zod validation schema
}, async (args) => {
  // Route to specific operation handlers
})

Critical Architecture Decisions (Post-Refactoring v0.2.0)

1. Simplified Storage Architecture (90% Code Reduction)
   • Eliminated over-engineered 33-file storage system (9,803 lines)
   • Replaced with SimpleFilterStorage.ts (393 lines) for essential functionality
   • Thread-safe operations with AsyncMutex
   • Session-isolated storage with automatic cleanup
   • Located in src/storage/SimpleFilterStorage.ts