Architecture & Design.md

Architecture & Design

This document provides a comprehensive guide to the codebase architecture and core design decisions. The project uses a clean three-layer architecture that separates concerns between MCP server handling, business logic, and API client operations.

Architecture Overview

This is an MCP (Model Context Protocol) server that exposes Lunatask API functionality to LLMs. The codebase uses a clean three-layer architecture:

Layer 1: Main Entry Point (cmd/lunatask-mcp-server.go)

  • Loads TOML configuration from config.toml (or custom path via -c/--config)
  • Creates and configures the MCP SSE server (Server-Sent Events transport)
  • Implements Provider interfaces (AreaProvider, GoalProvider, HabitProvider) that wrap config structs
  • Registers all MCP tools with their handlers
  • Validates configuration on startup (areas/goals must have names and IDs, timezone must be valid)

Layer 2: Tools Package (tools/)

  • Bridges MCP tool calls to Lunatask API client
  • Handles MCP request/response formatting
  • Performs pre-validation and argument transformation (e.g., string priorities → integers)
  • Consumes Provider interfaces to access configuration without tight coupling
  • Contains handlers for: timestamp parsing, area/goal listing, task CRUD, habit tracking

Layer 3: Lunatask Package (lunatask/)

  • Low-level HTTP client for Lunatask REST API (https://api.lunatask.app/v1)
  • Defines request/response types with JSON tags
  • Uses go-playground/validator for request validation
  • Contains API methods for tasks (CreateTask, UpdateTask, DeleteTask) and habits (TrackHabitActivity)

Key Design Patterns

Provider Interfaces: The tools package defines AreaProvider, GoalProvider, and HabitProvider interfaces. The main package's config structs implement these, allowing tools to access config data without importing main or knowing config structure details.

String-to-Integer Mapping: MCP tools accept human-readable strings that get translated to API integers:

  • Priority: "lowest"=-2, "low"=-1, "neutral"=0, "high"=1, "highest"=2
  • Eisenhower matrix: "uncategorised"=0, "both urgent and important"=1, "urgent, but not important"=2, "important, but not urgent"=3, "neither urgent nor important"=4

Natural Language Date Parsing: Uses github.com/ijt/go-anytime with timezone support. The get_timestamp tool parses expressions like "tomorrow at 3pm" into RFC3339 timestamps. Timezone is configured in config.toml using IANA/Olson format (e.g., America/New_York).

Validation Happens at Two Levels

  1. Tools layer: Type checking, area/goal relationship validation, string-to-int translation
  2. Lunatask layer: go-playground/validator tags enforce API constraints (UUID format, string lengths, numeric ranges, enum values)

This prevents invalid requests from reaching the API and provides better error messages.