npm - harmony-mcp - Versions diffs - 1.5.0 → 1.5.1 - Mend

harmony-mcp 1.5.0 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +115 -140
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -10,69 +10,83 @@ 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 **Settings → API 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:
+- 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
-### Alternative: Global Install
+That's it! You're ready to use Harmony with your AI agent.
-If you prefer a global installation:
+### 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 +95,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
@@ -208,74 +193,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 +257,51 @@ 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.
-# Or separately
-harmony-mcp set-workspace <id> --local
-harmony-mcp set-project <id> --local
+To update your email:
+```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 +314,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 +333,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/package.json CHANGED Viewed

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