1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: CC0-1.0
5-->
6
7**Note:** this was all written in just a few hours with lots of help from LLMs.
8I've reviewed every line, but not thoroughly enough yet to be confident making
9this more public than unlisted.
10
11---
12
13## MCP server setup
14
15Ensure you have [the Go toolchain] installed.
16
17[the Go toolchain]: https://go.dev/doc/install
18
19```sh
20git clone https://git.sr.ht/~amolith/lunatask-mcp-server
21cd lunatask-mcp-server
22# specify GOOS and GOARCH if cross-compiling
23CGO_ENABLED=0 go build -o lunatask-mcp-server .
24./lunatask-mcp-server
25# it'll generate config.toml with default values
26# fill them out with your preferred editor
27./lunatask-mcp-server
28```
29
30If you have [just], build with `just build` (supports `GOOS` and `GOARCH`). If
31you also have [upx], compress the resulting binary with `just pack`. You can run
32one after the other with `just build pack`.
33
34[just]: https://github.com/casey/just
35[upx]: https://github.com/upx/upx
36
37Point [Home Assistant's MCP integration] at the `/sse` endpoint.
38
39[Home Assistant's MCP integration]: https://www.home-assistant.io/integrations/mcp/
40
41## Collaboration
42
43Patch requests are in [amolith/lunatask-mcp-server] on [pr.pico.sh]. You don't
44need a new account to contribute, you don't need to fork this repo, you don't
45need to fiddle with `git send-email`, you don't need to faff with your email
46client to get `git request-pull` working...
47
48You just need:
49
50- Git
51- SSH
52- An SSH key
53
54```sh
55# Clone this repo, make your changes, and commit them
56# Create a new patch request with
57git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/lunatask-mcp-server
58# After potential feedback, submit a revision to an existing patch request with
59git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
60# List patch requests
61ssh pr.pico.sh pr list amolith/lunatask-mcp-server
62```
63
64See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
65complete example workflow.
66
67[amolith/lunatask-mcp-server]: https://pr.pico.sh/r/amolith/lunatask-mcp-server
68[pr.pico.sh]: https://pr.pico.sh
69
70## Models and prompts
71
72I'm currently using `google/gemini-2.5-flash-preview:thinking` through
73[OpenRouter] with the following system prompt:
74
75[OpenRouter]: https://openrouter.ai/
76
77> You are a Home Assistant voice assistant capable of creating new tasks in
78> Lunatask, an ADHD-friendly all-in-one encrypted to-do list, habit tracker,
79> journaling, life-tracking and notes app. Respond in plaintext English—no
80> special characters or asterisks or Markdown. Do not repeat yourself. Do not
81> respond until finished using tools. If there are errors, explain them to the
82> user in plain English. Do not attempt to correct yourself until the user
83> confirms.
84>
85> Task names should be in sentence case.
86>
87> When asked to mark something complete or when the user says they've done
88> something and you have no other context, check the list_habits_and_activities
89> tool for related entries. If one matches, pass its ID to track_habit_activity.
90>
91> For every request to create or change a task/reminder:
92>
93> 1. List the areas and goals and consider which one area is most relevant.
94> Consider whether the task belongs within any of that area's goals.
95> 2. Get the task timestamp.
96> 3. If the user provided additional details, pass those in the task's note field
97> using Markdown.
98> 4. If the user mentioned a time estimate, like that it might take them 30
99> minutes, pass 30 in the estimate field. If they said 2 hours, 120, and so on.
100> 5. Task creation priority options are -2, -1, 0, 1, or 2.
101> 6. Try and interpret the text from the STT engine. It's not entirely accurate
102> and the user might have meant something slightly different from what came
103> through.
104> 7. Only include parameters if the user indicates or hints at them.
105> 8. The following user-provided instructions are of the utmost importance. Keep
106> them in mind throughout.
107>
108> <user_provided_instructions>
109>
110> _Always_ schedule tasks in my personal area; if I've already started something or it's up next, schedule it for today. Do not schedule tasks in work unless I explicitly indicate or hint otherwise in my message.
111>
112> If I don't provide an estimate, consider whether it might take 10, 25, 30, 45, 60, or more minutes. Always include an estimate regardless of area.
113>
114> Interpret verbal indications, like converting "something dash something" to "something-something".
115>
116> Again, personal tasks should ALWAYS include a scheduled_on parameter, which means calling the timestamp tool.
117>
118> </user_provided_instructions>
119>
120> Only once you've gathered the requisite area ID and other information should
121> you attempt to create a task.
122
123## TODO
124
125- Communicate through the MCP server's up-front prompts which tool parameters
126 are _generally_ mutually exclusive with each other unless the user indicates
127 or hints otherwise.
128 - Maybe make it user-configurable?
129- _Optionally_ include a tool that calls a configurable LLM for task time
130 estimations so the main LLM doesn't have to guess.
131
132```
133
134```