1<!--
 2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
 3
 4SPDX-License-Identifier: CC0-1.0
 5-->
 6
 7# AGENTS.md
 8
 9MCP server exposing Lunatask (task/habit tracker) to LLMs via SSE. Primary use case: Home Assistant voice assistant says "remind me to call mom tomorrow" → HA's LLM calls this server's `create_task` tool → task appears in Lunatask.
10
11## Commands
12
13```sh
14just          # Run all checks (fmt, lint, staticcheck, test, vuln, reuse)
15just build    # Build with version info
16just run      # Build and run
17```
18
19## Architecture
20
21```
22cmd/lunatask-mcp-server.go  → Config, tool registration, SSE server
23tools/                      → MCP tool handlers
24lunatask/                   → HTTP client for Lunatask API
25```
26
27**Data flow**: SSE request → MCP server → tool handler → lunatask client → Lunatask API
28
29**Domain model**: Areas contain Goals. Habits are separate. Tasks belong to an Area and optionally a Goal.
30
31## Adding New Functionality
32
33**New MCP tool**: 
341. Add handler method to `tools/` (on `Handlers` struct)
352. Register tool with `mcpServer.AddTool()` in `cmd/lunatask-mcp-server.go`
36
37**New API endpoint**: Add method to `lunatask/Client` with request/response types
38
39## Key Patterns
40
41- **Tool descriptions are prompts**: The verbose `mcp.WithDescription()` strings guide the *calling* LLM's behavior—they explain workflows, valid values, and when to use each tool
42- **Error returns**: Handlers return `(result, nil)` with `IsError: true`—application errors go in the result, not the Go error
43- **Enum translation**: Human strings (`"high"`) → API integers (`1`) in handlers before calling client
44- **Provider interfaces**: `tools/` defines interfaces (`AreaProvider`, etc.) that `cmd/` types implement, keeping packages decoupled
45
46## Gotchas
47
48- Area/goal/habit IDs are static in config, not fetched—Lunatask API has no list endpoint
49- `CreateTask` returns `(nil, nil)` on HTTP 204 (task already exists)—not an error
50- `update_task` MCP tool requires `name` even for partial updates
51- No tests exist yet
52- All files need SPDX headers (`just reuse` checks this)
53
54## Contributing
55
56Patches via [pr.pico.sh](https://pr.pico.sh/r/amolith/llm-projects):
57
58```sh
59git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
60```