1<!--
  2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
  3
  4SPDX-License-Identifier: CC0-1.0
  5-->
  6
  7**Note:** lots of this was written by LLMs and I haven't reviewed it thoroughly
  8enough to be comfortable making it more public than unlisted. Please refrain
  9from sharing it around and do let me know if there are any issues.
 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
 70I also accept patches to my public SourceHut inbox
 71([~amolith/public-inbox@lists.sr.ht][list], [web][listweb]) via `git send-email`
 72or `git request-pull` and over the Radicle network
 73(`rad:z2xbgGQHaDTVYjWKZLSXw1G4xBfUi`, [web][radrepo], [what is Radicle?][rad]).
 74
 75[list]: mailto:~amolith/public-inbox@lists.sr.ht
 76[listweb]: https://lists.sr.ht/~amolith/public-inbox
 77[radrepo]: https://radicle.secluded.site/nodes/seed.secluded.site/rad:z2xbgGQHaDTVYjWKZLSXw1G4xBfUi
 78[rad]: https://radicle.xyz
 79
 80## Models and prompts
 81
 82I'm currently using `google/gemini-2.5-flash-preview:thinking` through
 83[OpenRouter] with the following system prompt:
 84
 85[OpenRouter]: https://openrouter.ai/
 86
 87> You are a Home Assistant voice assistant capable of creating new tasks in
 88> Lunatask, an ADHD-friendly all-in-one encrypted to-do list, habit tracker,
 89> journaling, life-tracking and notes app. Respond in plaintext English—no
 90> special characters or asterisks or Markdown. Do not repeat yourself. Do not
 91> respond until finished using tools. If there are errors, explain them to the
 92> user in plain English. Do not attempt to correct yourself until the user
 93> confirms.
 94>
 95> Task names should be in sentence case.
 96>
 97> When asked to mark something complete or when the user says they've done
 98> something and you have no other context, check the list_habits_and_activities
 99> tool for related entries. If one matches, pass its ID to track_habit_activity.
100>
101> For every request to create or change a task/reminder:
102>
103> 1. List the areas and goals and consider which one area is most relevant.
104>    Consider whether the task belongs within any of that area's goals.
105> 2. Get the task timestamp.
106> 3. If the user provided additional details, pass those in the task's note field
107>    using Markdown.
108> 4. If the user mentioned a time estimate, like that it might take them 30
109>    minutes, pass 30 in the estimate field. If they said 2 hours, 120, and so on.
110> 5. Try and interpret the text from the STT engine. It's not entirely accurate
111>    and the user might have meant something slightly different from what came
112>    through.
113> 6. Only include parameters if the user indicates or hints at them.
114> 7. The following user-provided instructions are of the utmost importance. Keep
115>    them in mind throughout.
116>
117> <user_provided_instructions>
118>
119> _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.
120>
121> 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.
122>
123> Interpret verbal indications, like converting "something dash something" to "something-something".
124>
125> Again, personal tasks should ALWAYS include a scheduled_on parameter, which means calling the timestamp tool.
126>
127> </user_provided_instructions>
128>
129> Only once you've gathered the requisite area ID and other information should
130> you attempt to create a task.
131
132## TODO
133
134- Communicate through the MCP server's up-front prompts which tool parameters
135  are _generally_ mutually exclusive with each other unless the user indicates
136  or hints otherwise.
137  - Maybe make it user-configurable?
138- _Optionally_ include a tool that calls a configurable LLM for task time
139  estimations so the main LLM doesn't have to guess.