# @gethmy/mcp

MCP (Model Context Protocol) server for [Harmony](https://gethmy.com).
Enables AI coding agents (Claude Code, OpenAI Codex, Cursor, Windsurf) to interact with your Harmony boards.

## Features

- **61+ MCP Tools** for full board control, knowledge graph, and workflow plans
- **Knowledge Graph Memory** - persistent memory with entity types, tiers, scopes, and typed relations
- **Active Learning** - auto-extracts lessons, solutions, and error patterns from completed work sessions
- **Context Assembly** - token-budget-aware memory injection into AI prompts
- **GSD Workflow Plans** - plan/execute/verify/done lifecycle with auto card creation
- **Card Linking** - create relationships between cards (blocks, relates_to, duplicates, is_part_of)
- **Prompt Builder** - generate AI-ready prompts from cards with context
- **Agent Session Tracking** - track work progress with timer badges
- **Auto-Session Detection** - automatically starts/ends sessions when agents interact with cards
- **Auto-Assignment** - automatically assign cards to you when starting agent sessions
- **Memory Sync** - bidirectional sync between local markdown files and remote database
- **Multi-Agent Support** - works with Claude Code, Codex, Cursor, Windsurf
- **Smart Setup** - one command configures everything
- **API Key Authentication** - no database credentials required

## Prerequisites

- [Node.js](https://nodejs.org) >= 20 or [Bun](https://bun.sh) >= 1.0
- A [Harmony](https://gethmy.com) account with an API key

## Quick Start

### 1. Get an API Key

1. Log into [Harmony](https://gethmy.com)
2. Go to **[API Keys](https://gethmy.com/user/keys)**
3. Click **"Generate New Key"**
4. Copy the key (starts with `hmy_`)

### 2. Run Setup

```bash
npx @gethmy/mcp setup
```

The smart setup wizard will:

- Validate your API key
- Detect installed AI agents (Claude Code, Cursor, Windsurf, Codex)
- Install skills globally (recommended) or locally
- Let you select your workspace and project

That's it! You're ready to use Harmony with your AI agent.

## Remote MCP (Hosted)

Connect any MCP-compatible agent to Harmony's hosted endpoint - no local server required.

**Endpoint:** `https://mcp.gethmy.com/mcp`

**Transport:** Streamable HTTP (MCP SDK standard)

**Authentication:** Bearer token using your `hmy_` API key

### Universal Setup with `add-mcp`

The fastest way to connect any agent to the remote endpoint. One command configures Claude Code, Cursor, VS Code, Windsurf, Codex, and more:

```bash
npx add-mcp https://mcp.gethmy.com/mcp -- --header "Authorization: Bearer hmy_your_key_here"
```

**Useful flags:**

| Flag | Description |
| ---- | ----------- |
| `-g` | Install globally (not scoped to a project) |
| `-a <agent>` | Target specific agents (e.g., `-a cursor -a claude-code`) |
| `-y` | Skip interactive prompts |

**Examples:**

```bash
# Install for all detected agents
npx add-mcp https://mcp.gethmy.com/mcp -- --header "Authorization: Bearer hmy_your_key_here"

# Install globally for Cursor and Claude Code only
npx add-mcp https://mcp.gethmy.com/mcp -g -a cursor -a claude-code -- --header "Authorization: Bearer hmy_your_key_here"

# Non-interactive (CI-friendly)
npx add-mcp https://mcp.gethmy.com/mcp -y -- --header "Authorization: Bearer hmy_your_key_here"
```

### Manual Setup (Claude.ai)

If you prefer to configure manually (e.g., in Claude.ai's UI):

1. Get an API key from [Harmony](https://gethmy.com/user/keys)
2. In Claude.ai, add a remote MCP server with URL `https://mcp.gethmy.com/mcp`
3. Set the Authorization header to `Bearer hmy_your_key_here`
4. All 61+ Harmony tools become available in your conversation

**Session management** is automatic - sessions have a 1-hour TTL and are created/renewed transparently.

> **When to use remote vs local:** The remote endpoint (via `add-mcp` or manual config) works with any MCP-compatible agent and requires no local server. Use the local server (`npx @gethmy/mcp setup`) when you need skills, local project context, or memory sync to local markdown files.

### Adding to a New Project

Just run setup again in the new project directory:

```bash
cd my-new-project
npx @gethmy/mcp setup
```

It detects your existing configuration and only asks for the project context.

## CLI Commands

```bash
# Setup (recommended)
npx @gethmy/mcp setup              # Smart setup wizard

# Setup with flags (non-interactive)
npx @gethmy/mcp setup --api-key KEY --global --workspace ID --project ID

# Status and management
npx @gethmy/mcp status             # Show current configuration
npx @gethmy/mcp reset              # Clear all configuration

# Server (called by agents automatically)
npx @gethmy/mcp serve              # Start MCP server
```

### Setup Options

| Flag                       | Description                                          |
| -------------------------- | ---------------------------------------------------- |
| `-k, --api-key <key>`      | API key (skips prompt)                               |
| `-e, --email <email>`      | Your email for auto-assignment                       |
| `-a, --agents <agents...>` | Agents to configure: claude, codex, cursor, windsurf |
| `-g, --global`             | Install skills globally (recommended)                |
| `-l, --local`              | Install skills locally in project directory          |
| `-w, --workspace <id>`     | Set workspace context                                |
| `-p, --project <id>`       | Set project context                                  |
| `--skip-context`           | Skip workspace/project selection                     |
| `-f, --force`              | Overwrite existing configuration                     |

## Supported AI Agents

| Agent            | Workflow Command         | Config Location                       | Transport             |
| ---------------- | ------------------------ | ------------------------------------- | --------------------- |
| **Claude Code**  | `/hmy #42`, `/hmy-plan`  | `~/.claude/settings.json`             | Local (stdio)         |
| **OpenAI Codex** | `/prompts:hmy #42`       | `~/.codex/config.toml`                | Local (stdio)         |
| **Cursor**       | MCP tools auto-available | `.cursor/mcp.json`                    | Local (stdio)         |
| **Windsurf**     | MCP tools auto-available | `~/.codeium/windsurf/mcp_config.json` | Local (stdio)         |
| **Claude.ai**    | MCP tools auto-available | Remote MCP settings in Claude.ai      | Remote (HTTP)         |
| **Any agent**    | MCP tools auto-available | Auto-configured via `npx add-mcp`     | Remote (HTTP)         |

## Skills

### `/hmy` — Card Workflow

When you start working on a card (e.g., `/hmy #42`):

1. **Find** - Locates the card by short ID, UUID, or name
2. **Move** - Moves the card to "In Progress" column
3. **Label** - Adds the "agent" label to indicate AI is working
4. **Assign** - Auto-assigns the card to you (if email is configured)
5. **Track** - Starts a session timer visible in the UI
6. **Implement** - Work on the task with progress updates
7. **Complete** - Move to "Review" when done

### `/hmy-plan` — Plan Workflow

A single command for both creating and executing plans. It auto-detects intent based on the argument:

| Argument | Action |
|----------|--------|
| `UUID` | Fetch and work on existing plan |
| `#42` | Look up card, then its linked plan |
| `mobile auth` | Search existing plans; if found, work on it; if not, offer to create one |
| *(empty)* | Start the new plan creation interview |

**Creating a plan** (`/hmy-plan mobile auth`):
1. Gathers board context and related memories
2. Interviews you with 3-5 focused questions
3. Synthesizes a structured plan document
4. Saves to Harmony via `harmony_create_plan`
5. Optionally advances to execute phase, creating board cards from tasks

**Executing a plan** (`/hmy-plan <existing plan>`):
1. Displays plan summary (status, phase, task counts)
2. Recalls related context from memory
3. Offers options: create single card, create multiple cards, analyze only, or skip
4. Creates cards and advances the plan phase

## Available Tools

### Card Operations

- `harmony_create_card` - Create a new card
- `harmony_update_card` - Update card properties
- `harmony_move_card` - Move card to different column (auto-ends agent session on move to done/review)
- `harmony_archive_card` - Archive a card (soft-delete, can be restored)
- `harmony_unarchive_card` - Restore an archived card back to the board
- `harmony_delete_card` - Delete a card
- `harmony_assign_card` - Assign to team member
- `harmony_search_cards` - Search by title/description
- `harmony_get_card` - Get card details by UUID
- `harmony_get_card_by_short_id` - Get card by short ID (e.g., #42)

### Card Link Operations

- `harmony_add_link_to_card` - Create a link between two cards
- `harmony_remove_link_from_card` - Remove a link between cards
- `harmony_get_card_links` - Get all links for a card

**Link Types:**
| Type | Description |
|------|-------------|
| `relates_to` | Generic relationship between cards |
| `blocks` | Source card blocks target card |
| `duplicates` | Source card duplicates target card |
| `is_part_of` | Source card is part of target card |

### Column Operations

- `harmony_create_column` - Create new column
- `harmony_update_column` - Update column properties
- `harmony_delete_column` - Delete column

### Label Operations

- `harmony_create_label` - Create new label
- `harmony_add_label_to_card` - Add label to card
- `harmony_remove_label_from_card` - Remove label

### Subtask Operations

- `harmony_create_subtask` - Create subtask
- `harmony_toggle_subtask` - Toggle completion
- `harmony_delete_subtask` - Delete subtask

### Context Operations

- `harmony_list_workspaces` - List workspaces
- `harmony_list_projects` - List projects
- `harmony_get_board` - Get board state (supports pagination via `limit`/`offset`, `summary` mode, `columnId` filter, `includeArchived`)
- `harmony_get_workspace_members` - Get team members
- `harmony_set_workspace_context` - Set active workspace
- `harmony_set_project_context` - Set active project
- `harmony_get_context` - Get current context

### Natural Language

- `harmony_process_command` - Process natural language commands

### Agent Session Tracking

- `harmony_start_agent_session` - Start tracking work on a card (with `moveToColumn` and `addLabels` side effects)
- `harmony_update_agent_progress` - Update progress, status, blockers
- `harmony_end_agent_session` - End session (completed/paused); triggers active learning extraction
- `harmony_get_agent_session` - Get current session state
- `harmony_get_agent_profile` - Get aggregate performance profile for an agent

### Auto-Session Detection

Sessions are automatically started when agents call card-mutating tools without an explicit `harmony_start_agent_session`. This ensures work is always tracked, even when agents don't explicitly manage sessions.

**Trigger tools:** `harmony_generate_prompt`, `harmony_update_card`, `harmony_move_card`, `harmony_create_subtask`, `harmony_toggle_subtask`, `harmony_add_label_to_card`, `harmony_remove_label_from_card`

**Behavior:**
- Auto-starts a session when any trigger tool is called on a card without an active session
- Auto-ends after 10 minutes of inactivity
- Switching to a different card auto-ends the previous auto-session
- Explicitly started sessions (via `harmony_start_agent_session`) are never auto-ended
- Auto-ended sessions trigger the full active learning pipeline

### Prompt Generation

- `harmony_generate_prompt` - Generate an AI-ready prompt from a card with assembled memory context

**Parameters:**
| Parameter | Description |
|-----------|-------------|
| `cardId` | Card UUID to generate prompt from |
| `shortId` | Alternative: Card short ID (e.g., 42 for #42) |
| `variant` | `analysis` (understand/plan), `draft` (design solution), `execute` (implement fully) |
| `includeDescription` | Include card description (default: true) |
| `includeSubtasks` | Include subtasks in prompt (default: true) |
| `includeLinks` | Include linked cards in prompt (default: true) |
| `customConstraints` | Additional instructions to append |

The prompt builder automatically infers the agent role based on card labels (bug, feature, design, etc.) and injects relevant memory context using the context assembly engine.

### Memory / Knowledge Graph

Store and retrieve persistent knowledge across sessions. Memories have types, tiers, scopes, confidence scores, and can be linked via typed relations.

**CRUD:**

- `harmony_remember` - Store a memory entity (markdown with YAML frontmatter)
- `harmony_recall` - Retrieve memories by type, tags, scope, or text query
- `harmony_update_memory` - Update an existing memory entity
- `harmony_forget` - Archive or delete a memory entity
- `harmony_memory_search` - Full-text search across the knowledge base
- `harmony_relate` - Create a typed relationship between two memory entities

**Entity Types:** `agent`, `task`, `decision`, `context`, `pattern`, `error`, `solution`, `preference`, `relationship`, `commitment`, `lesson`, `project`, `handoff`, `procedure`

**Memory Tiers:** `draft` (working notes) → `episode` (session summaries) → `reference` (durable knowledge)

**Scopes:** `private`, `project`, `workspace`, `global`

**Relation Types:** `learned_from`, `resolved_by`, `contradicts`, `supports`, `depends_on`, `part_of`, `caused_by`, `relates_to`

### Memory Vault & Sync

- `harmony_vault_index` - Compact index of all memory entities (markdown table)
- `harmony_resolve_links` - Batch-scan for `[[wiki-links]]` and auto-create relations
- `harmony_sync` - Bidirectional sync between local markdown files (`~/.harmony/memory/`) and remote database (directions: `pull`, `push`, `full`)

### Memory Lifecycle

- `harmony_promote_memory` - Promote entity tier: `draft` → `episode` or `episode` → `reference`
- `harmony_prune_draft` - Remove stale draft memories (dry-run mode by default)
- `harmony_consolidate_memories` - Cluster similar draft/episode memories and merge into reference entities (dry-run by default)
- `harmony_backfill_embeddings` - Generate vector embeddings for entities missing them
- `harmony_backfill_relations` - Retroactively create semantic relations across existing entities

### Context Debugging

- `harmony_get_context_manifest` - Debug what memories were loaded/excluded in a prompt assembly
- `harmony_debug_context` - Explain why a specific memory was or wasn't included (relevance score breakdown)
- `harmony_export_memory_graph` - Export knowledge graph as DOT format for Graphviz visualization

### GSD Workflow Plans

Create and manage project plans with a phased workflow: **plan** → **execute** → **verify** → **done**.

- `harmony_list_plans` - List plans in a project (filter by status or workflow phase)
- `harmony_create_plan` - Create a new plan with embedded tasks
- `harmony_get_plan` - Get plan by ID or card ID
- `harmony_update_plan` - Update plan title, content, status, or phase
- `harmony_advance_plan` - Advance to next phase with side effects:
  - **plan → execute:** auto-creates Kanban cards from plan tasks, sets plan active
  - **execute → verify:** checks card completion status
  - **verify → done:** archives plan, creates memory entities

### Onboarding & Account

- `harmony_onboard` - Complete end-to-end onboarding: signup → workspace → project → API key
- `harmony_signup` - Create a new user account
- `harmony_create_workspace` - Create a new workspace
- `harmony_create_project` - Create a new project with template columns (kanban, scrum, or simple)
- `harmony_send_invitations` - Send workspace invitations to team members
- `harmony_generate_api_key` - Generate an API key for the authenticated user

## Direct API Access

You can also call the Harmony API directly from any HTTP client:

```bash
curl -X GET "https://gethmy.com/api/v1/workspaces" \
  -H "X-API-Key: hmy_your_key_here"
```

### API Endpoints

| Endpoint                        | Method | Description                |
| ------------------------------- | ------ | -------------------------- |
| `/v1/workspaces`                | GET    | List workspaces            |
| `/v1/workspaces/:id/projects`   | GET    | List projects in workspace |
| `/v1/workspaces/:id/members`    | GET    | Get workspace members      |
| `/v1/board/:projectId`          | GET    | Get full board state       |
| `/v1/cards`                     | POST   | Create card                |
| `/v1/cards/:id`                 | GET    | Get card                   |
| `/v1/cards/:id`                 | PATCH  | Update card                |
| `/v1/cards/:id`                 | DELETE | Delete card                |
| `/v1/cards/:id/move`            | POST   | Move card                  |
| `/v1/cards/:id/prompt`          | GET    | Generate prompt from card  |
| `/v1/cards/:id/links`           | GET    | Get card links             |
| `/v1/cards/:id/links`           | POST   | Create card link           |
| `/v1/cards/:id/labels`          | POST   | Add label to card          |
| `/v1/cards/:id/labels/:labelId` | DELETE | Remove label               |
| `/v1/search?q=query`            | GET    | Search cards               |
| `/v1/columns`                   | POST   | Create column              |
| `/v1/columns/:id`               | PATCH  | Update column              |
| `/v1/columns/:id`               | DELETE | Delete column              |
| `/v1/labels`                    | POST   | Create label               |
| `/v1/subtasks`                  | POST   | Create subtask             |
| `/v1/subtasks/:id/toggle`       | POST   | Toggle subtask             |
| `/v1/subtasks/:id`              | DELETE | Delete subtask             |
| `/v1/links/:id`                 | DELETE | Delete card link           |
| `/v1/nlu`                       | POST   | Process natural language   |

## Configuration

### Global Configuration

Stored in `~/.harmony-mcp/config.json`:

```json
{
  "apiKey": "hmy_...",
  "apiUrl": "https://gethmy.com/api",
  "userEmail": "you@example.com",
  "activeWorkspaceId": null,
  "activeProjectId": null
}
```

### Local Project Configuration

Stored in `.harmony-mcp.json` in your project root:

```json
{
  "workspaceId": "uuid-here",
  "projectId": "uuid-here"
}
```

**Priority**: Local config overrides global config for workspace and project context.

**Security**: API key is never stored locally (only in global config) to prevent accidental commits.

### Auto-Assignment

When your email is configured during setup, cards are automatically assigned to you when you start an agent session (e.g., via `/hmy #42`). This helps track who is working on what.

To update your email:

```bash
npx @gethmy/mcp setup --email you@example.com
```

The email must match your Harmony account email to work correctly.

### Viewing Configuration

```bash
npx @gethmy/mcp status
```

Example output:

```
Status: Configured

API:
  Key: hmy_abc1...
  URL: https://gethmy.com/api
  Email: y***@example.com

Skills:
  Installed: Yes (global)
    ~/.agents/skills/hmy/SKILL.md

Context:
  Local config: .harmony-mcp.json
    Workspace: my-team-id
    Project: my-project-id
  Global config: ~/.harmony-mcp/config.json
    Workspace: (not set)
    Project: (not set)

  Active (effective):
    Workspace: my-team-id ← local
    Project: my-project-id ← local
```

### Recommended .gitignore

Add this to prevent accidentally committing local config:

```
.harmony-mcp.json
```

## Architecture

```
┌─────────────────┐      MCP Protocol       ┌──────────────────┐
│  Claude Code    │ ───────────────────────▶│  @gethmy/mcp     │
│  Cursor         │      (local stdio)      │  (local server)  │
│  Windsurf       │                         └────────┬─────────┘
│  Codex          │                                  │
└─────────────────┘                                  │ API Key Auth
                                                     ▼
┌─────────────────┐    Streamable HTTP      ┌──────────────────┐
│  Claude.ai      │ ───────────────────────▶│  Remote MCP      │
│  Any MCP client │    (Bearer: hmy_xxx)    │  mcp.gethmy.com  │──┐
└─────────────────┘                         └──────────────────┘  │
                                                                   │
                                                     ┌─────────────┘
                                                     ▼
                                          ┌──────────────────┐
                                          │  Harmony API     │
                                          │  (Edge Function) │
                                          └────────┬─────────┘
                                                   │
                                                   ▼
                                          ┌──────────────────┐
                                          │    Database      │
                                          │    (Supabase)    │
                                          └──────────────────┘
```

**Key Benefits:**

- No database credentials needed - just a Harmony API key
- Any Harmony user can use it
- Business logic stays in Harmony
- Centralized security and rate limiting
