harmony-mcp 1.0.4 → 1.1.1

package/README.md

@@ -1,10 +1,13 @@
 # harmony-mcp
 
-MCP (Model Context Protocol) server for Harmony Kanban board. Enables Claude Code, Claude Desktop, and other LLMs to interact with your Harmony boards.
+MCP (Model Context Protocol) server for Harmony Kanban board. Enables AI coding agents (Claude Code, OpenAI Codex, Cursor, Windsurf) to interact with your Harmony boards.
 
 ## Features
 
 - **20+ MCP Tools** for full board control (cards, columns, labels, subtasks)
+- **Agent Session Tracking** - track work progress with timer badges
+- **Multi-Agent Support** - works with Claude Code, Codex, Cursor, Windsurf
+- **One-Command Setup** - auto-configure all supported agents
 - **Natural Language Processing** via voice-nlu edge function
 - **API Key Authentication** - no database credentials required
 
@@ -29,19 +32,30 @@ npm install -g harmony-mcp
 harmony-mcp configure --api-key hmy_your_key_here
 ```
 
-Or run interactively:
+### 4. Initialize for Your AI Agents
 
 ```bash
-harmony-mcp configure
+# Auto-detect and configure all installed agents
+harmony-mcp init --detect
+
+# Or configure all supported agents
+harmony-mcp init --all
+
+# Or configure specific agents
+harmony-mcp init --agent claude codex cursor windsurf
 ```
 
-### 4. Add to Claude Code
+This creates the necessary configuration files and workflow prompts for each agent.
+
+### Manual Setup (Alternative)
+
+If you prefer manual setup for Claude Code:
 
 ```bash
 claude mcp add harmony -- harmony-mcp serve
 ```
 
-Or add manually to `~/.claude/settings.json`:
+Or add to `~/.claude/settings.json`:
 
 ```json
 {
@@ -54,12 +68,34 @@ Or add manually to `~/.claude/settings.json`:
 }
 ```
 
-That's it! Your API key is stored securely in `~/.harmony-mcp/config.json`.
+## Supported AI Agents
+
+| Agent            | MCP Config                            | Workflow Command         |
+| ---------------- | ------------------------------------- | ------------------------ |
+| **Claude Code**  | `~/.claude/settings.json`             | `/hmy #42`               |
+| **OpenAI Codex** | `~/.codex/config.toml`                | `/prompts:hmy #42`       |
+| **Cursor**       | `.cursor/mcp.json`                    | MCP tools auto-available |
+| **Windsurf**     | `~/.codeium/windsurf/mcp_config.json` | MCP tools auto-available |
+
+## 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. **Track** - Starts a session timer visible in the UI
+5. **Implement** - Work on the task with progress updates
+6. **Complete** - Move to "Review" when done
 
 ## CLI Commands
 
 ```bash
 harmony-mcp configure          # Set up API key
+harmony-mcp init               # Initialize for AI agents (interactive)
+harmony-mcp init --all         # Configure all supported agents
+harmony-mcp init --detect      # Auto-detect and configure installed agents
+harmony-mcp init --agent X Y   # Configure specific agents
 harmony-mcp status             # Show current config
 harmony-mcp reset              # Clear configuration
 harmony-mcp set-workspace ID   # Set active workspace
@@ -70,6 +106,7 @@ harmony-mcp serve              # Start MCP server
 ## 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
@@ -79,21 +116,25 @@ harmony-mcp serve              # Start MCP server
 - `harmony_get_card` - Get card details
 
 ### 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
@@ -103,8 +144,16 @@ harmony-mcp serve              # Start MCP server
 - `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
+
 ## Direct API Access
 
 You can also call the Harmony API directly from any HTTP client:
@@ -116,28 +165,28 @@ curl -X GET "https://gethmy.com/api/workspaces" \
 
 ### API Endpoints
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/workspaces` | GET | List workspaces |
-| `/workspaces/:id/projects` | GET | List projects in workspace |
-| `/workspaces/:id/members` | GET | Get workspace members |
-| `/board/:projectId` | GET | Get full board state |
-| `/cards` | POST | Create card |
-| `/cards/:id` | GET | Get card |
-| `/cards/:id` | PATCH | Update card |
-| `/cards/:id` | DELETE | Delete card |
-| `/cards/:id/move` | POST | Move card |
-| `/search?q=query` | GET | Search cards |
-| `/columns` | POST | Create column |
-| `/columns/:id` | PATCH | Update column |
-| `/columns/:id` | DELETE | Delete column |
-| `/labels` | POST | Create label |
-| `/cards/:id/labels` | POST | Add label to card |
-| `/cards/:id/labels/:labelId` | DELETE | Remove label |
-| `/subtasks` | POST | Create subtask |
-| `/subtasks/:id/toggle` | POST | Toggle subtask |
-| `/subtasks/:id` | DELETE | Delete subtask |
-| `/nlu` | POST | Process natural language |
+| Endpoint                     | Method | Description                |
+| ---------------------------- | ------ | -------------------------- |
+| `/workspaces`                | GET    | List workspaces            |
+| `/workspaces/:id/projects`   | GET    | List projects in workspace |
+| `/workspaces/:id/members`    | GET    | Get workspace members      |
+| `/board/:projectId`          | GET    | Get full board state       |
+| `/cards`                     | POST   | Create card                |
+| `/cards/:id`                 | GET    | Get card                   |
+| `/cards/:id`                 | PATCH  | Update card                |
+| `/cards/:id`                 | DELETE | Delete card                |
+| `/cards/:id/move`            | POST   | Move card                  |
+| `/search?q=query`            | GET    | Search cards               |
+| `/columns`                   | POST   | Create column              |
+| `/columns/:id`               | PATCH  | Update column              |
+| `/columns/:id`               | DELETE | Delete column              |
+| `/labels`                    | POST   | Create label               |
+| `/cards/:id/labels`          | POST   | Add label to card          |
+| `/cards/:id/labels/:labelId` | DELETE | Remove label               |
+| `/subtasks`                  | POST   | Create subtask             |
+| `/subtasks/:id/toggle`       | POST   | Toggle subtask             |
+| `/subtasks/:id`              | DELETE | Delete subtask             |
+| `/nlu`                       | POST   | Process natural language   |
 
 ## Configuration
 
@@ -169,13 +218,14 @@ Your configuration is stored in `~/.harmony-mcp/config.json`:
                                                    │
                                                    ▼
                                           ┌──────────────────┐
-                                          │    Supabase      │
-                                          │    (Database)    │
+                                          │    Database      │
+                                          │    (Supabase)    │
                                           └──────────────────┘
 ```
 
 **Key Benefits:**
-- No Supabase credentials needed - just a Harmony API key
+
+- 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