Configuration Guide

This document describes the configuration system for the Lunatask MCP server. The server uses TOML for configuration files rather than JSON, following the project philosophy that configuration should be human-readable and editable. Configuration is validated on startup to ensure all required fields are present and correctly formatted.

First-Run Behavior

On first run, the server generates config.toml with placeholder values and exits. Users must:

1. Add their Lunatask API access token
2. Configure areas with real IDs from Lunatask (areas can have nested goals)
3. Configure habits with real IDs
4. Set timezone in IANA format (e.g., America/New_York, not EST)
5. Optionally customize server host/port (defaults to localhost:8080)

Configuration Structure

The config uses TOML (not JSON) per project philosophy. Example structure:

access_token = "your-token"
timezone = "America/New_York"

[server]
host = "localhost"
port = 8080

[[area]]
name = "Work"
id = "uuid-here"

  [[area.goal]]
  name = "Q1 Project"
  id = "uuid-here"

[[habit]]
name = "Exercise"
id = "uuid-here"

Additional Notes

• For valid timezone values, see the IANA timezone database: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
• Configuration is validated on startup using go-playground/validator tags in the lunatask package