@gethmy/mcp 1.0.0

package/README.md

@@ -0,0 +1,343 @@
+# harmony-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
+
+- **29 MCP Tools** for full board control (cards, columns, labels, subtasks, links)
+- **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-Assignment** - automatically assign cards to you when starting agent sessions
+- **Multi-Agent Support** - works with Claude Code, Codex, Cursor, Windsurf
+- **Smart Setup** - one command configures everything
+- **Natural Language Processing** via voice-nlu edge function
+- **API Key Authentication** - no database credentials required
+
+## 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 harmony-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.
+
+### Adding to a New Project
+
+Just run setup again in the new project directory:
+
+```bash
+cd my-new-project
+npx harmony-mcp setup
+```
+
+It detects your existing configuration and only asks for the project context.
+
+## CLI Commands
+
+```bash
+# Setup (recommended)
+npx harmony-mcp setup              # Smart setup wizard
+
+# Setup with flags (non-interactive)
+npx harmony-mcp setup --api-key KEY --global --workspace ID --project ID
+
+# Status and management
+npx harmony-mcp status             # Show current configuration
+npx harmony-mcp reset              # Clear all configuration
+
+# Server (called by agents automatically)
+npx harmony-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                       |
+| ---------------- | ------------------------ | ------------------------------------- |
+| **Claude Code**  | `/hmy #42`               | `~/.claude/settings.json`             |
+| **OpenAI Codex** | `/prompts:hmy #42`       | `~/.codex/config.toml`                |
+| **Cursor**       | MCP tools auto-available | `.cursor/mcp.json`                    |
+| **Windsurf**     | MCP tools auto-available | `~/.codeium/windsurf/mcp_config.json` |
+
+## 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
+
+## 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
+- `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 full board state
+- `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
+- `harmony_update_agent_progress` - Update progress, status, blockers
+- `harmony_end_agent_session` - End session (completed/paused)
+- `harmony_get_agent_session` - Get current session state
+
+### Prompt Generation
+
+- `harmony_generate_prompt` - Generate an AI-ready prompt from a card
+
+**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 |
+
+**Variants:**
+
+- `analysis` - Understand the problem and create a plan
+- `draft` - Design a solution approach
+- `execute` - Full implementation (default)
+
+The prompt builder automatically infers the agent role based on card labels (bug, feature, design, etc.) and includes relevant context from linked cards.
+
+## 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/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/cards/:id/labels`          | POST   | Add label to card          |
+| `/v1/cards/:id/labels/:labelId` | DELETE | Remove label               |
+| `/v1/subtasks`                  | POST   | Create subtask             |
+| `/v1/subtasks/:id/toggle`       | POST   | Toggle subtask             |
+| `/v1/subtasks/:id`              | DELETE | Delete subtask             |
+| `/v1/cards/:id/links`           | GET    | Get card links             |
+| `/v1/cards/:id/links`           | POST   | Create card link           |
+| `/v1/links/:id`                 | DELETE | Delete card link           |
+| `/v1/cards/:id/prompt`          | GET    | Generate prompt from card  |
+| `/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 harmony-mcp setup --email you@example.com
+```
+
+The email must match your Harmony account email to work correctly.
+
+### Viewing Configuration
+
+```bash
+npx harmony-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    │ ───────────────────────▶│  harmony-mcp     │
+│  Cursor         │                         │  (local server)  │
+│  Windsurf       │                         └────────┬─────────┘
+│  Codex          │                                  │
+└─────────────────┘                                  │ API Key Auth
+                                                     ▼
+                                          ┌──────────────────┐
+                                          │  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