hanary-mcp 0.22.32

Hanary MCP Server - Task management for Claude Code, OpenCode & OpenAI Codex

Hanary MCP Server

Hanary MCP Server for Claude Code & OpenCode - task management that keeps new work outside the priority list until the user decides.

What Hanary MCP Is For

Hanary MCP is an operating layer for AI coding assistants. It lets agents read, start, update, and complete work from Hanary while preserving the user's priority decisions.

The key rule is: agents may capture and organize new work, but they should not silently insert it into the active priority order. New tasks default to needs_decision, staying outside top-task, start, and complete candidates until the user explicitly chooses to prioritize them.

Use Hanary MCP when you want Claude Code, OpenCode, or Codex to work from your confirmed Hanary task structure instead of inventing its own task order.

Mental model:

• Hanary owns the user's task hierarchy and priority order.
• The AI assistant follows that order.
• New work is captured safely as needs_decision.
• Only explicit user intent promotes work into the active priority list.
• executor_type: "ai" means user-approved execution delegation, not AI-owned priority judgment.
• planning_status answers when work belongs in priority; executor_type answers who can execute it.
• Human-owned tasks are ownership and completion boundaries, not safe advisory work boundaries: guide mode and safe non-destructive advisory help are allowed when the user asks to start, asks for guidance, or asks what to do next.
• Meaning, priority, and completion judgment stay with the user.

API vs MCP

Hanary's REST API remains the canonical product API. Use it for first-party apps, mobile or desktop clients, custom integrations, and any workflow where you control the application code that calls Hanary.

MCP is the AI-assistant integration surface on top of that API. Use it when you want tools like Claude Code, OpenCode, or Codex to discover Hanary actions automatically through tools/list, call them through tools/call, and receive the priority-boundary guidance directly in tool schemas and server instructions.

In practice:

• REST API is for application integrations.
• MCP is for agent integrations.
• hanary-mcp is the installable stdio bridge plus commands, skills, and agent guidance for local coding assistants.

MCP is not required to perform Hanary operations, but it avoids rebuilding the same tool wrapper for every AI host and keeps the assistant's behavior aligned with Hanary's user-owned priority model.

Features

• MCP Server: Direct tool integration with Claude Code and OpenCode
• Slash Commands: /hanary-status, /hanary-start, /hanary-done
• Skills: Task management workflow with estimation patterns
• Agents: Task planner that drafts complex work decomposition for user review
• Project Sync: Safe checks, diffs, and updates for generated assistant files
• Full Compatibility: Works with both Claude Code and OpenCode

Installation

# Using uvx (recommended)
uvx --from hanary-mcp hanary-mcp --squad my-project

# Or install globally
uv tool install hanary-mcp

Configuration

Project-Scoped Setup (Recommended)

Use project-scoped setup when different repositories should bind to different Hanary squads. Run this from the project root:

uvx --from hanary-mcp hanary-mcp init --squad your-squad-slug .

This creates project-local integration files:

• .mcp.json for Claude Code
• opencode.json for OpenCode
• .codex/config.toml for OpenAI Codex

Repeat the command in each project with that project's squad slug. This keeps AI assistants working inside the right Hanary squad without sharing one global --squad value across all projects.

The value after --squad is the squad slug, not the display name. For example, if Hanary shows FutureGate (futuregate), use futuregate:

uvx --from hanary-mcp hanary-mcp init --squad futuregate .

After setup, verify the local binding:

uvx --from hanary-mcp hanary-mcp doctor --squad your-squad-slug

Inside an AI assistant, use get_current_scope when the active project or squad is unclear before creating, starting, completing, or reordering tasks. In project-scoped squad mode, the MCP server exposes the squad as the working boundary: use get_top_task for "what should I do next" inside that project. get_overall_top_task is intentionally not exposed in squad mode; use a separate personal/global Hanary MCP only when the user explicitly asks to leave the project scope.

Keeping Project Files Synced

Use hanary-mcp sync after upgrading hanary-mcp when an existing project should receive updated commands, skills, agents, or generated MCP config.

Start with a status check:

uvx --from hanary-mcp hanary-mcp sync --squad your-squad-slug .

Review diffs before writing:

uvx --from hanary-mcp hanary-mcp sync --squad your-squad-slug --dry-run .

Write only safe changes:

uvx --from hanary-mcp hanary-mcp sync --squad your-squad-slug --write .

sync --write creates missing files and updates files that still match the last managed template hash. It does not overwrite user-modified files. Local config files such as .mcp.json, opencode.json, and .codex/config.toml are marked for review instead of being overwritten, because they may contain squad slugs, tokens, uv cache settings, or other project-specific choices.

Use init --force only when you intentionally want to overwrite existing generated files. It can replace local edits in .codex/config.toml, .mcp.json, and opencode.json; after using it, re-check any OS-specific command, token, and cache settings.

The sync manifest is stored in .hanary-mcp-sync.json. It records template hashes for files managed by hanary-mcp, so future upgrades can distinguish safe generated-file updates from user edits. AI guidance changes are listed separately in sync output because they affect assistant judgment boundaries.

Claude Code Setup

1. Set your API token as a system environment variable:

export HANARY_API_TOKEN='your-token-here'

On Windows PowerShell, set a persistent user environment variable:

[Environment]::SetEnvironmentVariable("HANARY_API_TOKEN", "your-token-here", "User")

Or set it only for the current PowerShell session:

$env:HANARY_API_TOKEN = "your-token-here"

Restart your AI coding assistant after changing environment variables. Existing Codex, Claude Code, or OpenCode processes do not inherit newly saved user environment variables; if they start the MCP server without the token, you may see an initialize/handshake failure such as connection closed.

2. Prefer hanary-mcp init above, or add this to your project's .mcp.json manually:

{
  "mcpServers": {
    "hanary": {
      "command": "uvx",
      "args": ["--refresh-package", "hanary-mcp", "--from", "hanary-mcp", "hanary-mcp", "--squad", "your-squad-slug"]
    }
  }
}

Global CLI registration is useful only when one Hanary squad should be used everywhere:

claude mcp add hanary -- uvx --refresh-package hanary-mcp --from hanary-mcp hanary-mcp --squad your-squad-slug

Do not use global CLI registration with --squad when you need project-by-project squad separation. In that case, keep the --squad binding in each project's .mcp.json or .codex/config.toml instead.

OpenAI Codex Notes

hanary-mcp init generates .codex/config.toml for the current operating system. On macOS/Linux it uses zsh -lc so shell profile environment variables can load. On native Windows it runs uvx directly because zsh is not available by default:

[mcp_servers.hanary]
command = "uvx"
args = ["--refresh-package", "hanary-mcp", "--from", "hanary-mcp", "hanary-mcp", "--squad", "your-squad-slug"]

[mcp_servers.hanary.env]
UV_CACHE_DIR = ".uv-cache"

Keep UV_CACHE_DIR in the project root, such as .uv-cache, so Codex sandboxed runs can write to it. If you edit the Codex config manually on Windows, avoid copying a macOS/Linux zsh -lc command into that file.

Environment Variables

Set these in your shell profile (.bashrc, .zshrc, etc.) or OS user environment:

Variable	Required	Description
HANARY_API_TOKEN	Yes	Your Hanary API token
HANARY_API_URL	No	API URL (default: https://hanary.org)

Available Tools

Default Agent Workflow

Use Hanary MCP around one confirmed focus at a time:

get_top_task -> get_task/update_task for context and notes -> start_task
-> do the work -> stop_task/complete_task against user-defined criteria
-> get_top_task for the next focus

list_tasks, search_tasks, list_completed_tasks, get_tasks_summary, and get_task_tree are context tools. They help inspect related work, historical completed work, duplicates, blockers, hierarchy, or review state, but they should not replace get_top_task as the source of current focus. In get_tasks_summary, status_counts uses explicit status meanings: started/in-progress task context means started_at is set and completed_at is nil. This is separate from active time tracking; use get_task with include_time_summary=true to inspect has_active_session and active_session_started_at. When this server is started with --squad, get_top_task is the project focus boundary. Do not switch to overall/global focus unless the user explicitly asks to work outside the current project squad.

If get_top_task returns is_llm_boundary=true, treat it as an execution boundary, not as permission to pick from a list and not as an advisory stop signal. The response may include human_prioritized_candidates: these are user-prioritized tasks that are still marked executor_type: "human". Report that prioritized work exists but has not been delegated to AI for execution. Do not change executor_type, start execution work, or skip to a lower-priority AI task unless the user explicitly delegates AI execution or explicitly chooses that lower-priority work. If advisory_allowed=true and the user asks to start, asks for help, asks what to do next, or asks to work together, default to guide mode instead of only asking for AI delegation and stopping. Starting advisory time tracking for the current top-priority human-owned task is allowed in that flow; it is a collaboration record, not AI execution delegation.

That boundary does not block safe advisory support. Human-owned tasks create an ownership and completion boundary, not a safe advisory work boundary. If advisory_allowed=true and the user asks to start, asks for help with the human-owned task, asks what to do next, or says completion/final approval remains theirs, the assistant should continue in guide mode without asking for extra permission for non-destructive support work. Guide mode begins by briefly stating that the task remains human-owned, then reading the task context and providing the first 1-3 concrete user actions.

Safe autonomous advisory work includes reading Hanary task details, completion criteria, notes, and approach; reading related local documents; running read-only inspection commands such as rg, ls, sed, and git status; public research; summarizing findings; first-step guidance; checklists; verification plans; evidence organization; draft communication; interpretations of user-provided results; and creating new non-overwriting support artifacts such as Markdown reports under docs/, guides/, reports/, or notes/. When creating such an artifact, record its path and a short summary in Hanary notes and leave completion approval to the user.

Advisory time tracking is allowed for the current top-priority human-owned task when advisory_allowed=true and the user asks to start, asks for help, asks what to do next, or asks to work together. start_task in this case records advisory work as a collaboration record; it does not change executor_type, grant completion authority, or grant priority authority. Maintain an already active session; do not stop user-started sessions without confirmation, and do not stop any advisory session unless the user asks to stop, wrap up, or says the work is here for now.

External Reply or Approval Wait

When the current top task is waiting only on an external reply or approval, do not leave it occupying focus indefinitely and do not hold it automatically. Inspect its completion criteria, notes, approach, and children; confirm that the external request has been sent, no independently executable work remains, and time tracking is inactive. Never stop an active session automatically for this transition. Then call assess_task_hold to get a non-mutating hold_recommended result with the waiting reason, waiting time, resume condition, and next_actionable_task. Ask before calling hold_task unless the user already gave explicit intent such as "hold this until the reply arrives." hold_task preserves rank and planning_status; unhold_task returns the task to that existing priority when the resume condition occurs.

Prerequisites vs Hold

add_dependency represents a prerequisite relationship. Its legacy fields map blocking_task_id to the prerequisite and blocked_task_id to the dependent task. While any prerequisite is incomplete, the dependent task and its descendants are excluded from top-task selection and cannot start. This blocked state is derived: rank and planning_status do not change, and completing all prerequisites restores actionability automatically.

Use a dependency when a real Hanary task must finish first. Use hold_task when progress depends on an external reply or condition that has no Hanary task. Do not apply both mechanisms for the same waiting reason.

The assistant must ask first before modifying, deleting, or overwriting existing files; changing source code, circuit designs, or config; completing tasks; stopping user-started time sessions; stopping any time session without a user stop/wrap-up request; changing executor_type; changing priority; committing, pushing, or deploying; sending external messages; placing orders, payments, or bookings; or define completion criteria for the user; or making/replacing the user's final judgment or completion approval.

Task Management

• get_current_scope - Show whether this MCP server is in personal mode or bound to a project squad
• get_top_task - Get the current AI focus without bypassing the user's confirmed priority order
• get_overall_top_task - Personal mode only: get the user's highest-priority task across personal and accessible squad work. This tool is not exposed when the MCP server is bound to a project squad.
• get_task - Inspect a specific task with its purpose, attempts & decisions, references & results, children, ancestors, and time summary
• list_tasks - List tasks as supporting context; use get_tasks_summary for overviews
• search_tasks - Find related tasks, duplicates, or blockers without choosing focus automatically
• list_completed_tasks - List completed tasks by completed_at date range for historical recall and retrospectives
• get_task_tree - Inspect hierarchy and decomposition without treating the tree as a new priority order
• create_task - Create a new task. In personal mode, pass a squad_slug selected from list_my_squads to create squad work; omit it for personal work. Defaults to needs_decision; use planning_status: "prioritized" only when the user explicitly wants immediate priority placement.
• update_task - Update task title, description, completion criteria, or notes
• complete_task - Mark task as completed against user-defined completion criteria
• uncomplete_task - Mark task as incomplete
• delete_task - Soft delete a task
• reorder_task / batch_reorder_tasks - Change priority order only after explicit user-confirmed placement
• prioritize_task / batch_prioritize_tasks - Atomically promote existing tasks into the priority chain using an explicit user-confirmed order
• move_task / batch_move_tasks - Clarify hierarchy inside the current personal or squad scope after user confirmation. They never expose personal work to a squad; use relocate_task_to_squad for that visibility change.
• list_reference_child_violations - Read-only audit for legacy personal task roots hidden under squad-reference pointers or actual squad tasks without inherited squad scope. It never moves or shares tasks.
• relocate_task_to_squad - After explicit user choice, move one repairable personal task subtree into its target squad. Pass a confirmation summarizing that choice. In personal mode, also pass the target squad_slug; project-bound mode uses its configured squad.
• assess_task_hold - Evaluate an external-wait hold candidate without changing task state or time tracking
• hold_task / unhold_task - Pause or resume focus eligibility at the existing priority only after explicit user intent

Squad

• list_my_squads - List squad display names and unique slugs. In personal mode, use it to resolve a user-named squad before passing its returned slug to create_task.
• get_squad - Get squad details and shared-problem context
• list_squad_members - List members who share the squad problem context
• list_squad_events - List events and deadlines for shared-problem coordination
• get_online_members - Check current presence when coordination is needed

Messages

• list_messages - List squad messages for recent decisions, blockers, and shared context
• create_message - Send a squad message around the shared problem, decisions, or blockers

Inquiry

• list_questions / get_question - Review questions used for Socratic analysis
• add_claim / add_premise - Draft claims and premises for user review; AI drafts are not final judgment

Task Creation Policy

create_task records new work without assuming it belongs in the priority list. By default, new tasks are created as needs_decision, so they stay outside top-task, start, or complete candidates until the user decides whether to break them down or place them into priority. Use planning_status: "prioritized" only when the user explicitly wants the task placed in the priority order now. rank is ignored unless planning_status: "prioritized" is explicit, and is required for prioritized creation except for the first executable child under a prioritized parent with no prioritized siblings. Use get_task on the parent first when unsure; its child_creation_policy reports the parent planning_status, direct incomplete child counts by planning status, prioritized child count, and whether rankless first executable child creation is allowed.

When a user in personal mode asks to add work to a named squad, call list_my_squads before creating. Prefer an exact returned slug; otherwise require one unique exact display-name match. If there is no exact match or multiple squads share the display name, ask the user to choose from the returned names and slugs instead of guessing. Call create_task with that returned squad_slug. In project-bound mode, task creation always stays in the configured --squad, and a per-call squad_slug override is rejected.

A task with squad_ref_id is a personal dashboard reference to a squad, not an actual squad task parent. Never use that reference as parent_id. Create a squad root task with squad_slug and no parent, or create a child under an actual squad task whose squad_id identifies the same squad.

Use list_reference_child_violations to detect legacy personal children that already exist under squad references or actual squad tasks without inherited squad scope. The audit is read-only: it returns each entry's violation_type, repairable flag, blocking_reasons, descendant_count, and target squad without moving or sharing anything. Present those findings and require an explicit user choice before calling relocate_task_to_squad, because relocation exposes the entire task subtree to squad members. Relocate only entries marked repairable, and pass a non-empty confirmation summarizing the user's choice. The wrapper rewrites each repairable entry's partial suggested_action for the active mode: in personal mode it passes the entry's returned target_squad_slug as relocate_task_to_squad.squad_slug; in project-bound mode it omits a per-call squad override and stays in the configured squad.

References & Results and child tasks have different jobs. Use notes for links, research notes, command output, formulas, and deliverables. Use approach for Attempts & Decisions: what was tried, where it got stuck, and why judgment or direction changed. If a checklist item can be executed independently, have its result recorded separately, and be judged complete on its own, create it as a child task candidate with parent_id instead of burying it in notes. Measurements, tests, checks, and concrete actions often belong in child task candidates when they can be performed one by one. Creating child task candidates clarifies hierarchy only; it does not make them executable or prioritized unless the user explicitly asks for priority placement.

If the user explicitly asks to make a new child task executable now and there are no prioritized siblings under its prioritized parent, create it in one call with parent_id and planning_status: "prioritized"; Hanary places that first executable child at rank: 0 without a comparison. needs_decision and priority_pending siblings do not block this first executable child exception because they are not priority comparison targets. If prioritized siblings already exist, ask the user for sibling order and include a rank from the user's confirmed order. Otherwise, even the first child task under a parent remains a needs_decision candidate.

For existing tasks, plain reordering does not finalize execution readiness. After the user explicitly confirms or delegates priority, use prioritize_task for one existing task or batch_prioritize_tasks for a complete sibling order. These tools atomically update planning_status and sibling ranks. The batch tool rejects omitted existing prioritized siblings by default; use append_after only when the user explicitly keeps them after the listed tasks.

planning_status and executor_type are separate axes. planning_status answers when the task belongs in the priority chain; executor_type answers who can execute it. A clear coding task can be planning_status: "prioritized" and executor_type: "ai" when the user has placed it into priority and the cause, likely fix location, and verifiable completion criteria are known. A human task can also be prioritized when it requires hardware assembly, measurement, purchase, installation, field operation, external approval, or final human judgment.

When executor_type is omitted, Hanary may infer it from the title, description, completion criteria, purpose, background, approach, and notes. Clear implementation, refactor, test, documentation, and research tasks are AI candidates. Human-only physical work, approval, field operation, and final judgment tasks are human candidates. Mixed work should usually be split: create the AI implementation task separately from the human real-device or field validation task.

Priority placement and AI delegation are separate decisions. A task can be planning_status: "prioritized" and still remain a human task. In that case get_top_task should stop execution actions at the boundary and explain that the user must explicitly delegate AI execution or explicitly choose lower-priority AI work before the assistant changes executor_type, starts execution work, or moves down the priority list. If advisory_allowed=true, the assistant should default to guide mode when the user asks to start, asks for help, or asks what to do next.

For human tasks, guidance is still useful and allowed. The assistant can help the person perform the task through safe autonomous advisory work: read-only inspection, public research, summaries, checklists, verification plans, safety/risk notes, evidence organization, draft communication, draft measurement criteria for user confirmation, new non-overwriting support documents, and interpretations of results the user reports back. This is advisory support, not task execution or final judgment. The assistant should give the first 1-3 concrete user steps rather than stopping at an AI delegation prompt.

For the current top-priority human task, advisory time tracking is also allowed as a collaboration record when the user asks to start, asks for help, asks what to do next, or asks to work together. This use of start_task does not delegate completion, change executor type, or change priority. Stopping time tracking is intentionally stricter: do not stop a user-started session without confirmation, and do not stop any advisory session unless the user asks to stop, wrap up, or says the work is here for now.

When starting a child task while an ancestor task has an active session, start_task defaults to ancestor_session_action: "ask" and returns a confirmation payload instead of silently stopping the ancestor session. After the user confirms, call start_task with ancestor_session_action: "switch" or use switch_active_session(from_task_id, to_task_id) to stop the ancestor session and start the child session.

Completion Policy

complete_task should be called against user-defined completion criteria. If the criteria are clear and verifiable, the agent may judge completion from evidence such as tests, deployment status, or document changes. If the criteria are missing, vague, or depend on taste, values, social agreement, or priority judgment, ask the user to define or confirm them. completion_criteria is required when completing through MCP so the user's completion standard is recorded; do not invent that criterion on the user's behalf.

Development

# Clone and install
git clone https://github.com/hanary/hanary-mcp.git
cd hanary-mcp
uv sync

# Run locally
HANARY_API_TOKEN=your_token uv run hanary-mcp --squad test

# Run tests
uv run --with pytest python -m pytest

Enhanced Features

Beyond the MCP tools, this project includes commands, skills, and agents for better UX.

Slash Commands

Command	Description
/hanary-status	Show current task status and squad overview
/hanary-start	Begin working on top priority task
/hanary-done	Complete current task against user-defined completion criteria and get next

Skills

• hanary-workflow: Complete task management workflow with estimation patterns and best practices

Agents

• task-planner: Drafts structured subtasks and estimates for user review

Platform Setup

Claude Code

Files auto-discovered from .claude/ directory:

.claude/
├── commands/          # /hanary-status, /hanary-start, /hanary-done
├── skills/
│   └── hanary-workflow/
│       └── SKILL.md
└── agents/
    └── task-planner.md

For project-specific squad separation, use the .mcp.json generated by hanary-mcp init --squad ... in each project. Global CLI registration binds hanary to one squad across projects, so use it only for a single shared default:

claude mcp add hanary -- uvx --refresh-package hanary-mcp --from hanary-mcp hanary-mcp

OpenCode

Files auto-discovered from .opencode/ directory:

.opencode/
├── commands/          # /hanary-status, /hanary-start, /hanary-done
└── agents/
    └── task-planner.md

Skills are shared via .claude/skills/ (OpenCode reads both .opencode/skills/ and .claude/skills/).

Configuration in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcpServers": {
    "hanary": {
      "command": "uvx",
      "args": ["--refresh-package", "hanary-mcp", "--from", "hanary-mcp", "hanary-mcp"]
    }
  }
}

Note: HANARY_API_TOKEN must be set as a system environment variable.

Directory Structure

hanary-mcp/
├── .claude/                    # Claude Code files
│   ├── commands/
│   │   ├── hanary-status.md
│   │   ├── hanary-start.md
│   │   └── hanary-done.md
│   ├── skills/
│   │   └── hanary-workflow/
│   │       ├── SKILL.md
│   │       └── references/
│   └── agents/
│       └── task-planner.md
├── .opencode/                  # OpenCode files
│   ├── commands/
│   │   ├── hanary-status.md
│   │   ├── hanary-start.md
│   │   └── hanary-done.md
│   └── agents/
│       └── task-planner.md
├── .mcp.json                   # MCP server config
├── opencode.json               # OpenCode config
└── src/hanary_mcp/             # MCP Server implementation

License

MIT