hanary-mcp 0.22.1

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.

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
• Full Compatibility: Works with both Claude Code and OpenCode

Installation

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

# Or install globally
uv tool install hanary-mcp

Configuration

Claude Code Setup

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

export HANARY_API_TOKEN='your-token-here'

2. Add to your project's .mcp.json:

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

Or add via CLI:

claude mcp add hanary -- uvx hanary-mcp --squad your-squad-slug

Environment Variables

Set these in your shell profile (.bashrc, .zshrc, etc.):

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 after user-confirmed criteria
-> get_top_task for the next focus

list_tasks, search_tasks, get_tasks_summary, and get_task_tree are context tools. They help inspect related work, duplicates, blockers, hierarchy, or review state, but they should not replace get_top_task as the source of current focus.

Task Management

• get_top_task - Get the current AI focus from the user's confirmed priority order
• get_overall_top_task - Get the user's highest-priority task across personal and accessible squad work
• get_task - Inspect a specific task with its purpose, process notes, 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
• get_task_tree - Inspect hierarchy and decomposition without treating the tree as a new priority order
• create_task - Create a new task. 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 after the user confirms 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
• move_task / batch_move_tasks - Clarify hierarchy after user confirmation; moving does not make work executable by itself
• hold_task / unhold_task - Pause or resume focus eligibility only after explicit user intent

Squad

• 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, and provide rank with it. rank is ignored unless planning_status: "prioritized" is explicit, and required when it is explicit.

Completion Policy

complete_task should be called only after the user confirms the work is sufficiently complete. Use completion_criteria to record or update how the user knows the task is done, and 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
.venv/bin/python -m unittest discover -s tests

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 after user-confirmed 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

Add MCP server to .mcp.json in your project or use the CLI:

claude mcp add hanary -- uvx 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": ["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