harmony-mcp 1.5.0 → 1.5.2

package/README.md

@@ -1,6 +1,7 @@
 # harmony-mcp
 
-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.
+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
 
@@ -10,69 +11,84 @@ MCP (Model Context Protocol) server for Harmony Kanban board. Enables AI coding
 - **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
+- **Smart Setup** - one command configures everything
 - **Natural Language Processing** via voice-nlu edge function
 - **API Key Authentication** - no database credentials required
 
 ## Quick Start
 
-### 1. Generate an API Key
+### 1. Get an API Key
 
 1. Log into [Harmony](https://gethmy.com)
-2. Go to **Account → API Keys**
+2. Go to **[API Keys](https://gethmy.com/user/keys)**
 3. Click **"Generate New Key"**
-4. Copy the key (it starts with `hmy_`)
+4. Copy the key (starts with `hmy_`)
 
-### 2. Run Setup (Recommended)
+### 2. Run Setup
 
 ```bash
 npx harmony-mcp setup
 ```
 
-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
+The smart setup wizard will:
 
-### Alternative: Global Install
+- 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
 
-If you prefer a global installation:
+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
-npm install -g harmony-mcp
-harmony-mcp setup
+cd my-new-project
+npx harmony-mcp setup
 ```
 
-### Manual Setup
+It detects your existing configuration and only asks for the project context.
 
-For manual configuration of Claude Code:
+## CLI Commands
 
 ```bash
-claude mcp add harmony -- harmony-mcp serve
-```
+# Setup (recommended)
+npx harmony-mcp setup              # Smart setup wizard
 
-Or add to `~/.claude/settings.json`:
+# Setup with flags (non-interactive)
+npx harmony-mcp setup --api-key KEY --global --workspace ID --project ID
 
-```json
-{
-  "mcpServers": {
-    "harmony": {
-      "command": "harmony-mcp",
-      "args": ["serve"]
-    }
-  }
-}
+# 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            | 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 |
+| 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
 
@@ -81,40 +97,11 @@ 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 `userEmail` is configured)
+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
 
-## CLI Commands
-
-```bash
-# 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
 
 ### Card Operations
@@ -197,6 +184,7 @@ harmony-mcp serve                     # Start MCP server
 | `customConstraints` | Additional instructions to append |
 
 **Variants:**
+
 - `analysis` - Understand the problem and create a plan
 - `draft` - Design a solution approach
 - `execute` - Full implementation (default)
@@ -208,74 +196,58 @@ The prompt builder automatically infers the agent role based on card labels (bug
 You can also call the Harmony API directly from any HTTP client:
 
 ```bash
-curl -X GET "https://gethmy.com/api/workspaces" \
+curl -X GET "https://gethmy.com/api/v1/workspaces" \
   -H "X-API-Key: hmy_your_key_here"
 ```
 
 ### 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             |
-| `/cards/:id/links`           | GET    | Get card links             |
-| `/cards/:id/links`           | POST   | Create card link           |
-| `/links/:id`                 | DELETE | Delete card link           |
-| `/cards/:id/prompt`          | GET    | Generate prompt from card  |
-| `/nlu`                       | POST   | Process natural language   |
+| 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
 
-Your global configuration is stored in `~/.harmony-mcp/config.json`:
+Stored in `~/.harmony-mcp/config.json`:
 
 ```json
 {
   "apiKey": "hmy_...",
   "apiUrl": "https://gethmy.com/api",
+  "userEmail": "you@example.com",
   "activeWorkspaceId": null,
-  "activeProjectId": null,
-  "userEmail": "you@example.com"
+  "activeProjectId": null
 }
 ```
 
-### 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:
+Stored in `.harmony-mcp.json` in your project root:
 
 ```json
 {
@@ -288,45 +260,52 @@ For multi-project workflows, you can set project-specific context using local co
 
 **Security**: API key is never stored locally (only in global config) to prevent accidental commits.
 
-#### Setting Local Context
+### Auto-Assignment
 
-```bash
-# During initialization
-harmony-mcp init --workspace <ws-id> --project <proj-id>
+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:
 
-# Or separately
-harmony-mcp set-workspace <id> --local
-harmony-mcp set-project <id> --local
+```bash
+npx harmony-mcp setup --email you@example.com
 ```
 
-#### Viewing Configuration
+The email must match your Harmony account email to work correctly.
+
+### Viewing Configuration
 
 ```bash
-harmony-mcp status
+npx harmony-mcp status
 ```
 
 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>
-  Project: <global-proj-id>
-
-Local Context (.harmony-mcp.json):
-  Workspace: <local-ws-id>
-  Project: <local-proj-id>
 
-Active (effective):
-  Workspace: <local-ws-id>  ← local
-  Project: <local-proj-id>  ← local
+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
+### Recommended .gitignore
 
 Add this to prevent accidentally committing local config:
 
@@ -339,10 +318,10 @@ Add this to prevent accidentally committing local config:
 ```
 ┌─────────────────┐      MCP Protocol       ┌──────────────────┐
 │  Claude Code    │ ───────────────────────▶│  harmony-mcp     │
-│  Claude Desktop │                         │  (local server)  │
-│  Custom Agents  │                         └────────┬─────────┘
-└─────────────────┘                                  │
-                                                     │ API Key Auth
+│  Cursor         │                         │  (local server)  │
+│  Windsurf       │                         └────────┬─────────┘
+│  Codex          │                                  │
+└─────────────────┘                                  │ API Key Auth
                                                      ▼
                                           ┌──────────────────┐
                                           │  Harmony API     │
@@ -358,7 +337,7 @@ Add this to prevent accidentally committing local config:
 
 **Key Benefits:**
 
-- No Database 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

package/dist/cli.js

@@ -29478,24 +29478,24 @@ function areSkillsInstalled(cwd) {
     foundPaths.push(globalSkillPath);
     return { installed: true, location: "global", paths: foundPaths };
   }
-  const claudeGlobalCommand = join(home, ".claude", "commands", "hmy.md");
-  if (existsSync(claudeGlobalCommand)) {
-    foundPaths.push(claudeGlobalCommand);
-    return { installed: true, location: "global", paths: foundPaths };
-  }
-  const claudeGlobalSkill = join(home, ".claude", "skills", "hmy", "SKILL.md");
+  const claudeGlobalSkill = join(home, ".claude", "skills", "hmy.md");
   if (existsSync(claudeGlobalSkill)) {
     foundPaths.push(claudeGlobalSkill);
     return { installed: true, location: "global", paths: foundPaths };
   }
-  const localSkillPath = join(workingDir, ".claude", "skills", "hmy", "SKILL.md");
+  const claudeGlobalSkillAlt = join(home, ".claude", "skills", "hmy", "SKILL.md");
+  if (existsSync(claudeGlobalSkillAlt)) {
+    foundPaths.push(claudeGlobalSkillAlt);
+    return { installed: true, location: "global", paths: foundPaths };
+  }
+  const localSkillPath = join(workingDir, ".claude", "skills", "hmy.md");
   if (existsSync(localSkillPath)) {
     foundPaths.push(localSkillPath);
     return { installed: true, location: "local", paths: foundPaths };
   }
-  const localCommandPath = join(workingDir, ".claude", "commands", "hmy.md");
-  if (existsSync(localCommandPath)) {
-    foundPaths.push(localCommandPath);
+  const localSkillPathAlt = join(workingDir, ".claude", "skills", "hmy", "SKILL.md");
+  if (existsSync(localSkillPathAlt)) {
+    foundPaths.push(localSkillPathAlt);
     return { installed: true, location: "local", paths: foundPaths };
   }
   return { installed: false, location: null, paths: [] };
@@ -31864,8 +31864,9 @@ function getAgentFiles(agentId, cwd, installMode = "global") {
   const symlinks = [];
   switch (agentId) {
     case "claude": {
-      const commandContent = `---
-description: Start working on a Harmony card (moves to In Progress, adds agent label)
+      const skillContent = `---
+name: hmy
+description: Start working on a Harmony card. Use when given a card reference like #42, UUID, or card name to implement.
 argument-hint: <card-reference>
 ---
 
@@ -31873,18 +31874,18 @@ ${HARMONY_WORKFLOW_PROMPT.replace("Your agent identifier", "claude-code").replac
 `;
       if (installMode === "global") {
         files.push({
-          path: join3(GLOBAL_SKILLS_DIR, "claude", "hmy.md"),
-          content: commandContent,
+          path: join3(GLOBAL_SKILLS_DIR, "hmy", "SKILL.md"),
+          content: skillContent,
           type: "text"
         });
         symlinks.push({
-          target: join3(GLOBAL_SKILLS_DIR, "claude", "hmy.md"),
-          link: join3(home, ".claude", "commands", "hmy.md")
+          target: join3(GLOBAL_SKILLS_DIR, "hmy"),
+          link: join3(home, ".claude", "skills", "hmy")
         });
       } else {
         files.push({
-          path: join3(cwd, ".claude", "commands", "hmy.md"),
-          content: commandContent,
+          path: join3(cwd, ".claude", "skills", "hmy", "SKILL.md"),
+          content: skillContent,
           type: "text"
         });
       }

package/dist/index.js

@@ -27241,24 +27241,24 @@ function areSkillsInstalled(cwd) {
     foundPaths.push(globalSkillPath);
     return { installed: true, location: "global", paths: foundPaths };
   }
-  const claudeGlobalCommand = join(home, ".claude", "commands", "hmy.md");
-  if (existsSync(claudeGlobalCommand)) {
-    foundPaths.push(claudeGlobalCommand);
-    return { installed: true, location: "global", paths: foundPaths };
-  }
-  const claudeGlobalSkill = join(home, ".claude", "skills", "hmy", "SKILL.md");
+  const claudeGlobalSkill = join(home, ".claude", "skills", "hmy.md");
   if (existsSync(claudeGlobalSkill)) {
     foundPaths.push(claudeGlobalSkill);
     return { installed: true, location: "global", paths: foundPaths };
   }
-  const localSkillPath = join(workingDir, ".claude", "skills", "hmy", "SKILL.md");
+  const claudeGlobalSkillAlt = join(home, ".claude", "skills", "hmy", "SKILL.md");
+  if (existsSync(claudeGlobalSkillAlt)) {
+    foundPaths.push(claudeGlobalSkillAlt);
+    return { installed: true, location: "global", paths: foundPaths };
+  }
+  const localSkillPath = join(workingDir, ".claude", "skills", "hmy.md");
   if (existsSync(localSkillPath)) {
     foundPaths.push(localSkillPath);
     return { installed: true, location: "local", paths: foundPaths };
   }
-  const localCommandPath = join(workingDir, ".claude", "commands", "hmy.md");
-  if (existsSync(localCommandPath)) {
-    foundPaths.push(localCommandPath);
+  const localSkillPathAlt = join(workingDir, ".claude", "skills", "hmy", "SKILL.md");
+  if (existsSync(localSkillPathAlt)) {
+    foundPaths.push(localSkillPathAlt);
     return { installed: true, location: "local", paths: foundPaths };
   }
   return { installed: false, location: null, paths: [] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harmony-mcp",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "type": "module",
   "main": "dist/index.js",