harmony-mcp 1.3.1 → 1.3.3

package/README.md

@@ -8,6 +8,7 @@ MCP (Model Context Protocol) server for Harmony Kanban board. Enables AI coding
 - **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
 - **One-Command Setup** - auto-configure all supported agents
 - **Natural Language Processing** via voice-nlu edge function
@@ -15,43 +16,37 @@ MCP (Model Context Protocol) server for Harmony Kanban board. Enables AI coding
 
 ## Quick Start
 
-### 1. Install
-
-```bash
-npm install -g harmony-mcp
-```
-
-### 2. Generate an API Key
+### 1. Generate an API Key
 
 1. Log into [Harmony](https://gethmy.com)
-2. Go to **Settings → API Keys**
+2. Go to **Account → API Keys**
 3. Click **"Generate New Key"**
 4. Copy the key (it starts with `hmy_`)
 
-### 3. Configure
+### 2. Run Setup (Recommended)
 
 ```bash
-harmony-mcp configure --api-key hmy_your_key_here
+npx harmony-mcp setup
 ```
 
-### 4. Initialize for Your AI Agents
+This interactive wizard will:
+- Prompt for your API key
+- Auto-detect your installed AI agents (Claude Code, Cursor, Windsurf, Codex)
+- Configure all detected agents automatically
+- Optionally install globally for faster startup
 
-```bash
-# Auto-detect and configure all installed agents
-harmony-mcp init --detect
+### Alternative: Global Install
 
-# Or configure all supported agents
-harmony-mcp init --all
+If you prefer a global installation:
 
-# Or configure specific agents
-harmony-mcp init --agent claude codex cursor windsurf
+```bash
+npm install -g harmony-mcp
+harmony-mcp setup
 ```
 
-This creates the necessary configuration files and workflow prompts for each agent.
-
-### Manual Setup (Alternative)
+### Manual Setup
 
-If you prefer manual setup for Claude Code:
+For manual configuration of Claude Code:
 
 ```bash
 claude mcp add harmony -- harmony-mcp serve
@@ -86,26 +81,38 @@ 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
+4. **Assign** - Auto-assigns the card to you (if `userEmail` 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
 
 ## 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 init -w WS -p PROJ # Initialize with local workspace/project context
-harmony-mcp status             # Show current config (global and local)
-harmony-mcp reset              # Clear configuration
-harmony-mcp set-workspace ID   # Set active workspace (global)
-harmony-mcp set-workspace ID -l # Set active workspace (local project)
-harmony-mcp set-project ID     # Set active project (global)
-harmony-mcp set-project ID -l  # Set active project (local project)
-harmony-mcp serve              # Start MCP server
+# Setup (recommended)
+harmony-mcp setup                     # Interactive setup wizard (recommended)
+
+# Legacy configuration commands
+harmony-mcp configure                 # Set up API key (interactive)
+harmony-mcp configure -k KEY -e EMAIL # Set up with API key and email
+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 init -w WS -p PROJ        # Initialize with local workspace/project context
+
+# Status and management
+harmony-mcp status                    # Show current config (global and local)
+harmony-mcp reset                     # Clear configuration
+harmony-mcp set-workspace ID          # Set active workspace (global)
+harmony-mcp set-workspace ID -l       # Set active workspace (local project)
+harmony-mcp set-project ID            # Set active project (global)
+harmony-mcp set-project ID -l         # Set active project (local project)
+harmony-mcp set-user-email EMAIL      # Set email for auto-assignment
+harmony-mcp clear-user-email          # Disable auto-assignment
+
+# Server
+harmony-mcp serve                     # Start MCP server
 ```
 
 ## Available Tools
@@ -245,10 +252,27 @@ Your global configuration is stored in `~/.harmony-mcp/config.json`:
   "apiKey": "hmy_...",
   "apiUrl": "https://gethmy.com/api",
   "activeWorkspaceId": null,
-  "activeProjectId": null
+  "activeProjectId": null,
+  "userEmail": "you@example.com"
 }
 ```
 
+### Auto-Assignment
+
+When `userEmail` is configured, 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 enable auto-assignment:
+```bash
+harmony-mcp set-user-email you@example.com
+```
+
+To disable auto-assignment:
+```bash
+harmony-mcp clear-user-email
+```
+
+The email must match your Harmony account email to work correctly.
+
 ### Local Project Configuration
 
 For multi-project workflows, you can set project-specific context using local configuration. This is stored in `.harmony-mcp.json` in your project root:
@@ -287,6 +311,7 @@ Example output:
 Status: Configured
 API Key: hmy_abc1...
 API URL: https://gethmy.com/api
+User Email: y***@example.com
 
 Global Context:
   Workspace: <global-ws-id>