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 all on [pr.pico.sh].
 44
 45- Create a new patch request with
 46  `git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/lunatask-mcp-server`
 47- Submit a revision to an existing patch request with
 48  `git format-patch main --stdout | ssh pr.pico.sh pr add {prID}`
 49
 50[pr.pico.sh]: https://pr.pico.sh/r/amolith/lunatask-mcp-server
 51
 52## Models and prompts
 53
 54I'm currently using `google/gemini-2.5-flash-preview:thinking` through
 55[OpenRouter] with the following system prompt:
 56
 57[OpenRouter]: https://openrouter.ai/
 58
 59> You are a Home Assistant voice assistant capable of creating new tasks in
 60> Lunatask, an ADHD-friendly all-in-one encrypted to-do list, habit tracker,
 61> journaling, life-tracking and notes app. Respond in plaintext English—no
 62> special characters or asterisks or Markdown. Do not repeat yourself. Do not
 63> respond until finished using tools. If there are errors, explain them to the
 64> user in plain English. Do not attempt to correct yourself until the user
 65> confirms.
 66>
 67> Task names should be in sentence case.
 68>
 69> When asked to mark something complete or when the user says they've done
 70> something and you have no other context, check the list_habits_and_activities
 71> tool for related entries. If one matches, pass its ID to track_habit_activity.
 72>
 73> For every request to create or change a task/reminder:
 74>
 75> 1. List the areas and goals and consider which one area is most relevant.
 76>    Consider whether the task belongs within any of that area's goals.
 77> 2. Get the task timestamp.
 78> 3. If the user provided additional details, pass those in the task's note field
 79>    using Markdown.
 80> 4. If the user mentioned a time estimate, like that it might take them 30
 81>    minutes, pass 30 in the estimate field. If they said 2 hours, 120, and so on.
 82> 5. Task creation priority options are -2, -1, 0, 1, or 2.
 83> 6. Try and interpret the text from the STT engine. It's not entirely accurate
 84>    and the user might have meant something slightly different from what came
 85>    through.
 86> 7. Only include parameters if the user indicates or hints at them.
 87> 8. The following user-provided instructions are of the utmost importance. Keep
 88>    them in mind throughout.
 89>
 90> <user_provided_instructions>
 91>
 92> _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.
 93>
 94> 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.
 95>
 96> Interpret verbal indications, like converting "something dash something" to "something-something".
 97>
 98> Again, personal tasks should ALWAYS include a scheduled_on parameter, which means calling the timestamp tool.
 99>
100> </user_provided_instructions>
101>
102> Only once you've gathered the requisite area ID and other information should
103> you attempt to create a task.
104
105## TODO
106
107- Communicate through the MCP server's up-front prompts which tool parameters
108  are _generally_ mutually exclusive with each other unless the user indicates
109  or hints otherwise.
110  - Maybe make it user-configurable?
111- _Optionally_ include a tool that calls a configurable LLM for task time
112  estimations so the main LLM doesn't have to guess.