Task-Anchor-MCP AGENTS.md

Task Anchor — Agent Instructions

This project includes a Task Anchor MCP server that provides ADHD executive function enforcement. If you have MCP support, connect to it. If not, follow the manual protocol below.

MCP Server Setup

The server runs as a Python package:

{
  "mcpServers": {
    "task-anchor": {
      "command": "python",
      "args": ["-m", "task_anchor.server"],
      "cwd": "/absolute/path/to/TaskAnchor/mcp-server"
    }
  }
}

Or if installed via pip (pip install -e . from mcp-server/):

{
  "mcpServers": {
    "task-anchor": {
      "command": "task-anchor"
    }
  }
}

State files live in .claude/skills/task-anchor/ inside the repo root. Override with env var: TASK_ANCHOR_DIR=/absolute/path/to/state/dir

Package Structure

mcp-server/
├── pyproject.toml
└── task_anchor/
    ├── config.py           — absolute path resolution (immune to cwd, env-overridable)
    ├── models.py           — TaskLock dataclass, drift signal weights + thresholds
    ├── storage.py          — atomic file I/O, cross-platform locking (fcntl/msvcrt)
    ├── drift.py            — scoring engine, completion validation, history logging
    ├── flow.py             — flow mode activate/deactivate/auto-expire
    ├── tone.py             — tone persistence + message resolver
    ├── messages.py         — message registry (aggregator, integrity-checked at import)
    ├── messages_core.py    — templates: lock, drift, parked, scope
    ├── messages_session.py — templates: completion, session, flow, celebration
    ├── helpers.py          — shared utilities (git branch, load lock, session log)
    ├── streak.py           — daily streak tracking, completion celebration (stderr only)
    ├── tools.py            — MCP tool schema definitions (14 tools)
    ├── handlers.py         — core tool handler coroutines (lock, drift, parked, scope, tone, flow)
    ├── handlers_session.py — session lifecycle handlers (checkpoint, resume)
    └── server.py           — MCP wiring, route table, entry point