feat: fastmcp 3.4.2 uplift — annotations, structured output, resources, prompts, context (#34)

* feat: fastmcp 3.4.2 uplift — annotations, structured output, resources, prompts, context

* feat: deepen tool annotations — titles + read/write/destructive tags across all 32 tools

Add per-tool human-friendly ToolAnnotations.title and coarse capability
tags (read/write/destructive) to every tool registration. Semantics:
readOnlyHint on get-*/search-*/show-*/review/insights; destructiveHint on
delete-area/merge-areas/bulk-cancel; complete-task stays idempotent (not
destructive — reversible in Things 3); idempotentHint on modify/schedule/
defer; openWorldHint=False everywhere (Things is a local macOS app).

Additive only: no tool renames, no parameter changes, no output_schema
changes. Adds tests/test_tool_annotations.py contract tests.

Author: CaseyRo

pyproject.toml

@@ -33,7 +33,7 @@ classifiers = [
 ]
 dependencies = [
     "httpx>=0.28.1",
-    "fastmcp>=3.2.4",
+    "fastmcp>=3.4.2,<4.0.0",
     "pydantic-settings>=2.12.0",
     "things-py>=1.0.1",
     "rich>=14.0.0",

src/things_mcp/fast_server.py

@@ -48,6 +48,8 @@
 from .tools_gtd_reflect import register_gtd_reflect_tools
 from .tools_utility import register_utility_tools
 from .tools_batch import register_batch_tools
+from .resources import register_resources
+from .prompts import register_prompts
 
 # Configure enhanced logging
 # Console shows DEBUG if THINGS_MCP_DEBUG=true, otherwise INFO
@@ -68,6 +70,10 @@
 register_utility_tools(mcp)  # Utility (search, list, show, cache)
 register_batch_tools(mcp)  # Batch (bulk-capture, bulk-complete, etc.)
 
+# Register ambient GTD-state resources and guided-workflow prompts
+register_resources(mcp)  # things:// resources (inbox count, today, stalled, etc.)
+register_prompts(mcp)  # Guided GTD prompts (weekly-review, process-inbox, plan)
+
 
 def _print_shutdown_summary():
     """Print a beautiful shutdown summary with stats."""

src/things_mcp/prompts.py

@@ -0,0 +1,104 @@
+"""MCP prompts: guided, selectable GTD workflows.
+
+These wrap the server's signature multi-step rituals — the weekly review, inbox
+processing to zero, and project planning — into first-class, discoverable
+``@mcp.prompt`` entries. The narrative guidance previously lived only in tool
+docstrings and server instructions; exposing it as prompts lets a client surface
+the GTD ritual as a single click and have the model walk it step by step using
+the existing tools.
+
+Each prompt returns a plain string, which FastMCP delivers as the initial user
+message of the workflow.
+"""
+
+from __future__ import annotations
+
+from fastmcp import FastMCP
+
+
+def register_prompts(mcp: FastMCP) -> None:
+    """Register guided GTD-workflow prompts with the server."""
+
+    @mcp.prompt(
+        name="weekly-review",
+        title="Run a GTD Weekly Review",
+        description=(
+            "Guide me through David Allen's weekly review: get current, get "
+            "clear, get creative. Uses weekly-review, process-inbox, and the "
+            "bulk-* tools."
+        ),
+        tags={"reflect", "workflow"},
+    )
+    def weekly_review_prompt() -> str:
+        return (
+            "Walk me through a complete GTD weekly review for my Things 3 setup. "
+            "Follow these steps and use the matching tools:\n\n"
+            "1. **Get current** — Call `weekly-review` to surface stalled "
+            "projects, waiting-for items, someday/maybe, and what I completed.\n"
+            "2. **Get clear** — If the inbox is not empty, call "
+            "`process-inbox(all=True)`, then propose a single `bulk-triage` call "
+            "with a GTD decision (do / defer / delegate / delete / assign) for "
+            "each item. Show me the plan before executing.\n"
+            "3. **Get projects moving** — For every stalled project, suggest a "
+            "concrete next action and offer to add it.\n"
+            "4. **Review the horizons** — Walk the someday/maybe list and ask "
+            "which items should become active now.\n"
+            "5. **Wrap up** — Summarise what changed and what still needs my "
+            "attention.\n\n"
+            "Pause for my confirmation before any write that completes, cancels, "
+            "or reschedules tasks."
+        )
+
+    @mcp.prompt(
+        name="process-inbox-to-zero",
+        title="Process the Inbox to Zero",
+        description=(
+            "Clarify every inbox item with the GTD decision tree and clear the "
+            "inbox in one batch. Uses process-inbox and bulk-triage."
+        ),
+        tags={"clarify", "workflow"},
+    )
+    def process_inbox_prompt() -> str:
+        return (
+            "Help me process my Things inbox to zero using the GTD clarify "
+            "workflow:\n\n"
+            "1. Call `process-inbox(all=True)` to load every inbox item with its "
+            "suggested category.\n"
+            "2. For each item, apply the GTD decision tree:\n"
+            "   - Not actionable → **delete** (cancel) or **defer** to "
+            "someday/maybe.\n"
+            "   - Actionable, < 2 minutes → flag it so I can **do it now**.\n"
+            "   - Actionable, mine, later → **schedule** or **defer** with a "
+            "`when`.\n"
+            "   - Actionable, someone else's → **delegate** (capture who).\n"
+            "   - Multi-step outcome → **assign** to a project.\n"
+            "3. Assemble one `bulk-triage` call with a decision per item and show "
+            "it to me for approval before executing.\n"
+            "4. After triage, confirm the inbox is empty and report the action "
+            "breakdown.\n\n"
+            "Ask me whenever an item's correct decision is genuinely ambiguous."
+        )
+
+    @mcp.prompt(
+        name="plan-project",
+        title="Plan a New Project",
+        description=(
+            "Turn a desired outcome into a Things project with a clean next "
+            "action and supporting tasks. Uses plan-project."
+        ),
+        tags={"organize", "workflow"},
+    )
+    def plan_project_prompt(outcome: str) -> str:
+        return (
+            f"I want to plan a project for this outcome: {outcome}\n\n"
+            "Apply GTD natural planning:\n"
+            "1. Restate the **successful outcome** in one sentence (what 'done' "
+            "looks like).\n"
+            "2. Brainstorm the concrete tasks needed to get there.\n"
+            "3. Identify the single **next action** — the very next physical, "
+            "visible step — and put it first.\n"
+            "4. Suggest a GTD context tag (@computer, @phone, …) for each task "
+            "and an area of focus for the project.\n"
+            "5. Show me the proposed project and task list, then call "
+            "`plan-project` to create it atomically once I approve."
+        )

src/things_mcp/resources.py

@@ -0,0 +1,204 @@
+"""MCP resources: ambient, read-only GTD context under the ``things://`` scheme.
+
+Resources let an agent passively pull current GTD state (inbox count, today's
+list, stalled projects, triage stats) and static reference data (the GTD context
+tag taxonomy, server config) *without spending a tool call*. They mirror data the
+review tools already compute — they just expose it as addressable, cacheable
+context the model can read on its own initiative.
+
+All resources are read-only by definition. Mutations still go through the
+existing ``@mcp.tool`` write tools.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import date
+from typing import Any
+
+from fastmcp import FastMCP
+
+from . import reader as db
+from .logging_config import get_logger
+from .settings import get_settings, get_transport
+from .triage_tracker import triage_tracker
+
+logger = get_logger(__name__)
+
+
+# GTD context tags shipped as a discoverable taxonomy. Mirrors the contexts
+# documented in the server instructions and CLAUDE.md.
+GTD_CONTEXT_TAGS: list[dict[str, str]] = [
+    {"tag": "@computer", "meaning": "Anything requiring a computer / desk."},
+    {"tag": "@phone", "meaning": "Calls or tasks done on the phone."},
+    {"tag": "@office", "meaning": "Requires being at the office."},
+    {"tag": "@home", "meaning": "Requires being at home."},
+    {"tag": "@errands", "meaning": "Out-and-about tasks (shops, post, bank)."},
+    {"tag": "@anywhere", "meaning": "Context-free; can be done from anywhere."},
+    {
+        "tag": "waiting-for",
+        "meaning": "Delegated — awaiting someone else (see delegate-task).",
+    },
+]
+
+
+def _stalled_projects(today_str: str) -> list[dict[str, str]]:
+    """Return incomplete projects that have no available next action.
+
+    Mirrors the weekly-review stalled-project computation: a project is stalled
+    when none of its incomplete to-dos are available (anytime / today / no start).
+    """
+    from collections import defaultdict
+
+    projects = db.projects() or []
+    all_incomplete = db.todos(status="incomplete") or []
+
+    todos_by_project: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for t in all_incomplete:
+        proj_uuid = t.get("project")
+        if proj_uuid:
+            todos_by_project[proj_uuid].append(t)
+
+    stalled: list[dict[str, str]] = []
+    for project in projects:
+        if project.get("status") != "incomplete":
+            continue
+        proj_todos = todos_by_project.get(project.get("uuid"), [])
+        available = [
+            t
+            for t in proj_todos
+            if t.get("start") in (None, "Anytime", "Today")
+            or t.get("start_date") is None
+            or t.get("start_date") == today_str
+        ]
+        if not available:
+            stalled.append(
+                {"uuid": project.get("uuid", ""), "title": project.get("title", "")}
+            )
+    return stalled
+
+
+def register_resources(mcp: FastMCP) -> None:
+    """Register ambient GTD-state and reference resources with the server."""
+
+    @mcp.resource(
+        "things://inbox/count",
+        name="inbox-count",
+        title="Inbox Count",
+        description="Number of unclarified items currently in the Things inbox.",
+        mime_type="application/json",
+        tags={"reflect", "ambient"},
+    )
+    def inbox_count() -> str:
+        inbox = db.inbox() or []
+        return json.dumps({"inbox_count": len(inbox)})
+
+    @mcp.resource(
+        "things://today",
+        name="today",
+        title="Today's Tasks",
+        description=(
+            "Today's scheduled tasks plus overdue items — the GTD 'hard "
+            "landscape' for right now. Read this to orient before planning a day."
+        ),
+        mime_type="application/json",
+        tags={"engage", "reflect", "ambient"},
+    )
+    def today() -> str:
+        today_str = date.today().isoformat()
+        today_tasks = db.today() or []
+        all_todos = db.todos(status="incomplete") or []
+        overdue = [
+            {"title": t.get("title", ""), "deadline": t.get("deadline")}
+            for t in all_todos
+            if t.get("deadline") and t.get("deadline") < today_str
+        ]
+        return json.dumps(
+            {
+                "date": today_str,
+                "today_count": len(today_tasks),
+                "overdue_count": len(overdue),
+                "today": [t.get("title", "") for t in today_tasks],
+                "overdue": overdue,
+            }
+        )
+
+    @mcp.resource(
+        "things://stalled-projects",
+        name="stalled-projects",
+        title="Stalled Projects",
+        description=(
+            "Incomplete projects with no available next action — the core "
+            "weekly-review signal. Each stalled project needs a next action added."
+        ),
+        mime_type="application/json",
+        tags={"reflect", "organize", "ambient"},
+    )
+    def stalled_projects() -> str:
+        today_str = date.today().isoformat()
+        stalled = _stalled_projects(today_str)
+        return json.dumps({"stalled_count": len(stalled), "projects": stalled})
+
+    @mcp.resource(
+        "things://triage/stats",
+        name="triage-stats",
+        title="Triage Stats (7 days)",
+        description=(
+            "Anonymised triage activity over the last 7 days: totals, action "
+            "breakdown, busiest day, and the no-context cancel rate. No task "
+            "titles or content are stored."
+        ),
+        mime_type="application/json",
+        tags={"reflect", "ambient", "stats"},
+    )
+    def triage_stats() -> str:
+        try:
+            summary = triage_tracker.get_summary(days=7)
+        except Exception:
+            logger.debug("triage stats resource failed (non-critical)", exc_info=True)
+            summary = {"total": 0}
+        return json.dumps(summary)
+
+    @mcp.resource(
+        "things://contexts",
+        name="gtd-contexts",
+        title="GTD Context Tags",
+        description=(
+            "The GTD context-tag taxonomy this server recognises (@computer, "
+            "@phone, …). Use these with get-tasks(context=…) to filter by where "
+            "or how a task can be done."
+        ),
+        mime_type="application/json",
+        tags={"reference", "taxonomy"},
+    )
+    def gtd_contexts() -> str:
+        return json.dumps({"contexts": GTD_CONTEXT_TAGS})
+
+    @mcp.resource(
+        "things://config",
+        name="server-config",
+        title="Server Config",
+        description=(
+            "Non-secret server configuration: host, port, transport, and "
+            "whether a Things auth token is configured (needed for writes). "
+            "Secrets are never exposed."
+        ),
+        mime_type="application/json",
+        tags={"reference", "status"},
+    )
+    def server_config() -> str:
+        settings = get_settings()
+        try:
+            from . import __version__ as version
+        except ImportError:
+            version = "unknown"
+        token = settings.things_auth_token.get_secret_value()
+        return json.dumps(
+            {
+                "version": version,
+                "host": settings.things_mcp_host,
+                "port": settings.things_mcp_port,
+                "transport": get_transport(),
+                "auth_token_configured": bool(token),
+            }
+        )