harmony-mcp 1.0.0

package/README.md

@@ -0,0 +1,181 @@
+# 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.
+
+## Features
+
+- **20+ MCP Tools** for full board control (cards, columns, labels, subtasks)
+- **Natural Language Processing** via voice-nlu edge function
+- **API Key Authentication** - no database credentials required
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g harmony-mcp
+```
+
+### 2. Generate an API Key
+
+1. Log into [Harmony](https://gethmy.com)
+2. Go to **Settings → API Keys**
+3. Click **"Generate New Key"**
+4. Copy the key (it starts with `hmy_`)
+
+### 3. Configure
+
+```bash
+harmony-mcp configure --api-key hmy_your_key_here
+```
+
+Or run interactively:
+
+```bash
+harmony-mcp configure
+```
+
+### 4. Add to Claude Code
+
+```bash
+claude mcp add harmony -- harmony-mcp serve
+```
+
+Or add manually to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "harmony": {
+      "command": "harmony-mcp",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+That's it! Your API key is stored securely in `~/.harmony-mcp/config.json`.
+
+## CLI Commands
+
+```bash
+harmony-mcp configure          # Set up API key
+harmony-mcp status             # Show current config
+harmony-mcp reset              # Clear configuration
+harmony-mcp set-workspace ID   # Set active workspace
+harmony-mcp set-project ID     # Set active project
+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
+- `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
+
+### 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
+
+## Direct API Access
+
+You can also call the Harmony API directly from any HTTP client:
+
+```bash
+curl -X GET "https://YOUR_PROJECT.supabase.co/functions/v1/harmony-api/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 |
+| `/nlu` | POST | Process natural language |
+
+## Configuration
+
+Your configuration is stored in `~/.harmony-mcp/config.json`:
+
+```json
+{
+  "apiKey": "hmy_...",
+  "apiUrl": "https://xxx.supabase.co/functions/v1/harmony-api",
+  "activeWorkspaceId": null,
+  "activeProjectId": null
+}
+```
+
+## Architecture
+
+```
+┌─────────────────┐      MCP Protocol       ┌──────────────────┐
+│  Claude Code    │ ───────────────────────▶│  harmony-mcp     │
+│  Claude Desktop │                         │  (local server)  │
+│  Custom Agents  │                         └────────┬─────────┘
+└─────────────────┘                                  │
+                                                     │ API Key Auth
+                                                     ▼
+                                          ┌──────────────────┐
+                                          │  Harmony API     │
+                                          │  (Edge Function) │
+                                          └────────┬─────────┘
+                                                   │
+                                                   ▼
+                                          ┌──────────────────┐
+                                          │    Supabase      │
+                                          │    (Database)    │
+                                          └──────────────────┘
+```
+
+**Key Benefits:**
+- No Supabase credentials needed - just a Harmony API key
+- Any Harmony user can use it
+- Business logic stays in Harmony
+- Centralized security and rate limiting