# Hanary MCP Server

[Hanary](https://hanary.org) MCP Server for Claude Code & OpenCode - squad-bound task management.

## 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 for complex work decomposition
- **Full Compatibility**: Works with both Claude Code and OpenCode

## Installation

```bash
# 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:

```bash
export HANARY_API_TOKEN='your-token-here'
```

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

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

Or add via CLI:

```bash
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

### Task Management

- `list_tasks` - List tasks in the squad
- `create_task` - Create a new task
- `update_task` - Update task title/description
- `complete_task` - Mark task as completed
- `uncomplete_task` - Mark task as incomplete
- `delete_task` - Soft delete a task
- `get_top_task` - Get highest priority incomplete task

### Squad

- `get_squad` - Get squad details
- `list_squad_members` - List squad members

### Messages

- `list_messages` - List squad messages
- `create_message` - Send a message

## Development

```bash
# 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
```

## 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 and get next |

### Skills

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

### Agents

- **task-planner**: Decomposes complex work into structured tasks with estimates

## 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:

```bash
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`:

```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
