From edbac80f747e7d13a9d73038d9a8abcd79fe2d21 Mon Sep 17 00:00:00 2001
From: Amolith <amolith@secluded.site>
Date: Tue, 23 Dec 2025 21:22:11 -0700
Subject: [PATCH] docs: document MCP server architecture

Assisted-by: Claude Opus 4.5 via Crush
---
 AGENTS.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 615ce83c0daac5443d1e847aba0ae6ec500855ca..091709e6cd9e8c45956ef47401e47373b9b12970 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -46,6 +46,7 @@ cmd/
   goal/              → goal list/show (read-only)
   journal/           → journal add
   habit/             → habit track
+  mcp/               → MCP server command (stdio/sse/http transports)
 internal/
   client/            → Lunatask API client factory (uses system keyring)
   config/            → TOML config at ~/.config/lune/config.toml
@@ -54,6 +55,10 @@ internal/
   stats/             → Usage statistics helpers
   ui/                → Lipgloss styles (Success, Warning, Error, H1, H2, FormatDate)
   validate/          → Input validation (delegates to go-lunatask Parse* functions)
+  mcp/
+    shared/          → Provider types (AreaProvider, HabitProvider) and error helpers
+    tools/           → MCP tool handlers (task/, habit/, timestamp/)
+    resources/       → MCP resource handlers (areas/, habits/, notebooks/)
 ```
 
 **Command flow**: `fang.Execute()` wraps Cobra with version/commit info and
@@ -85,6 +90,27 @@ see `cmd/task/add.go:56-63` for examples. Use `completion.Areas`, `completion.Go
 etc. for config-based completions, or `completion.Static("val1", "val2")` for
 fixed options.
 
+## MCP server patterns
+
+The `lune mcp` command starts a Model Context Protocol server for LLM tool
+integration. Architecture:
+
+- **Resources** (`internal/mcp/resources/`): Read-only data from config (areas,
+  habits, notebooks). Each has a `Handler` with `HandleRead` method.
+- **Tools** (`internal/mcp/tools/`): Actions that call the Lunatask API. Each
+  tool uses `*Input`/`*Output` structs with `jsonschema:"required"` tags for
+  MCP schema generation.
+- **Shared** (`internal/mcp/shared/`): Provider types decouple config from MCP
+  handlers; `ErrorResult()` returns structured tool errors.
+
+**Tool handler pattern**: Tools use `mcp.AddTool()` with typed input structs.
+Validation happens in `parse*Input()` functions returning `*mcp.CallToolResult`
+for errors (not Go errors). Parse functions call `lunatask.Parse*()` for enums
+and `dateutil.Parse()` for dates.
+
+**Config-driven tools**: `cfg.MCP.Tools.*` booleans enable/disable individual
+tools. All default to enabled via `cfg.MCP.MCPDefaults()`.
+
 ## Core dependencies
 
 Reference docs via context7 or doc-agent when unsure:
@@ -107,6 +133,8 @@ Reference docs via context7 or doc-agent when unsure:
   `/websites/pkg_go_dev_github_com_spf13_cobra`): CLI framework.
 - `github.com/markusmobius/go-dateparser` (context7:
   `/markusmobius/go-dateparser`): Natural language date parsing.
+- `github.com/modelcontextprotocol/go-sdk/mcp` (context7:
+  `/modelcontextprotocol/go-sdk`): MCP server SDK for LLM tool integration.
 
 ## Gotchas