@gethmy/mcp 1.0.0 → 2.0.0

package/README.md

@@ -1,18 +1,23 @@
-# harmony-mcp
+# @gethmy/mcp
 
 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
 
-- **29 MCP Tools** for full board control (cards, columns, labels, subtasks, links)
+- **61+ MCP Tools** for full board control, knowledge graph, and workflow plans
+- **Knowledge Graph Memory** - persistent memory with entity types, tiers, scopes, and typed relations
+- **Active Learning** - auto-extracts lessons, solutions, and error patterns from completed work sessions
+- **Context Assembly** - token-budget-aware memory injection into AI prompts
+- **GSD Workflow Plans** - plan/execute/verify/done lifecycle with auto card creation
 - **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-Session Detection** - automatically starts/ends sessions when agents interact with cards
 - **Auto-Assignment** - automatically assign cards to you when starting agent sessions
+- **Memory Sync** - bidirectional sync between local markdown files and remote database
 - **Multi-Agent Support** - works with Claude Code, Codex, Cursor, Windsurf
 - **Smart Setup** - one command configures everything
-- **Natural Language Processing** via voice-nlu edge function
 - **API Key Authentication** - no database credentials required
 
 ## Quick Start
@@ -27,7 +32,7 @@ Enables AI coding agents (Claude Code, OpenAI Codex, Cursor, Windsurf) to intera
 ### 2. Run Setup
 
 ```bash
-npx harmony-mcp setup
+npx @gethmy/mcp setup
 ```
 
 The smart setup wizard will:
@@ -39,13 +44,65 @@ The smart setup wizard will:
 
 That's it! You're ready to use Harmony with your AI agent.
 
+## Remote MCP (Hosted)
+
+Connect any MCP-compatible agent to Harmony's hosted endpoint - no local server required.
+
+**Endpoint:** `https://mcp.gethmy.com/mcp`
+
+**Transport:** Streamable HTTP (MCP SDK standard)
+
+**Authentication:** Bearer token using your `hmy_` API key
+
+### Universal Setup with `add-mcp`
+
+The fastest way to connect any agent to the remote endpoint. One command configures Claude Code, Cursor, VS Code, Windsurf, Codex, and more:
+
+```bash
+npx add-mcp https://mcp.gethmy.com/mcp -- --header "Authorization: Bearer hmy_your_key_here"
+```
+
+**Useful flags:**
+
+| Flag | Description |
+| ---- | ----------- |
+| `-g` | Install globally (not scoped to a project) |
+| `-a <agent>` | Target specific agents (e.g., `-a cursor -a claude-code`) |
+| `-y` | Skip interactive prompts |
+
+**Examples:**
+
+```bash
+# Install for all detected agents
+npx add-mcp https://mcp.gethmy.com/mcp -- --header "Authorization: Bearer hmy_your_key_here"
+
+# Install globally for Cursor and Claude Code only
+npx add-mcp https://mcp.gethmy.com/mcp -g -a cursor -a claude-code -- --header "Authorization: Bearer hmy_your_key_here"
+
+# Non-interactive (CI-friendly)
+npx add-mcp https://mcp.gethmy.com/mcp -y -- --header "Authorization: Bearer hmy_your_key_here"
+```
+
+### Manual Setup (Claude.ai)
+
+If you prefer to configure manually (e.g., in Claude.ai's UI):
+
+1. Get an API key from [Harmony](https://gethmy.com/user/keys)
+2. In Claude.ai, add a remote MCP server with URL `https://mcp.gethmy.com/mcp`
+3. Set the Authorization header to `Bearer hmy_your_key_here`
+4. All 61+ Harmony tools become available in your conversation
+
+**Session management** is automatic - sessions have a 1-hour TTL and are created/renewed transparently.
+
+> **When to use remote vs local:** The remote endpoint (via `add-mcp` or manual config) works with any MCP-compatible agent and requires no local server. Use the local server (`npx @gethmy/mcp setup`) when you need skills, local project context, or memory sync to local markdown files.
+
 ### Adding to a New Project
 
 Just run setup again in the new project directory:
 
 ```bash
 cd my-new-project
-npx harmony-mcp setup
+npx @gethmy/mcp setup
 ```
 
 It detects your existing configuration and only asks for the project context.
@@ -54,17 +111,17 @@ It detects your existing configuration and only asks for the project context.
 
 ```bash
 # Setup (recommended)
-npx harmony-mcp setup              # Smart setup wizard
+npx @gethmy/mcp setup              # Smart setup wizard
 
 # Setup with flags (non-interactive)
-npx harmony-mcp setup --api-key KEY --global --workspace ID --project ID
+npx @gethmy/mcp setup --api-key KEY --global --workspace ID --project ID
 
 # Status and management
-npx harmony-mcp status             # Show current configuration
-npx harmony-mcp reset              # Clear all configuration
+npx @gethmy/mcp status             # Show current configuration
+npx @gethmy/mcp reset              # Clear all configuration
 
 # Server (called by agents automatically)
-npx harmony-mcp serve              # Start MCP server
+npx @gethmy/mcp serve              # Start MCP server
 ```
 
 ### Setup Options
@@ -83,14 +140,18 @@ npx harmony-mcp serve              # Start MCP server
 
 ## Supported AI Agents
 
-| 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` |
+| Agent            | Workflow Command         | Config Location                       | Transport             |
+| ---------------- | ------------------------ | ------------------------------------- | --------------------- |
+| **Claude Code**  | `/hmy #42`, `/hmy-plan`  | `~/.claude/settings.json`             | Local (stdio)         |
+| **OpenAI Codex** | `/prompts:hmy #42`       | `~/.codex/config.toml`                | Local (stdio)         |
+| **Cursor**       | MCP tools auto-available | `.cursor/mcp.json`                    | Local (stdio)         |
+| **Windsurf**     | MCP tools auto-available | `~/.codeium/windsurf/mcp_config.json` | Local (stdio)         |
+| **Claude.ai**    | MCP tools auto-available | Remote MCP settings in Claude.ai      | Remote (HTTP)         |
+| **Any agent**    | MCP tools auto-available | Auto-configured via `npx add-mcp`     | Remote (HTTP)         |
+
+## Skills
 
-## Card Workflow
+### `/hmy` — Card Workflow
 
 When you start working on a card (e.g., `/hmy #42`):
 
@@ -102,13 +163,39 @@ When you start working on a card (e.g., `/hmy #42`):
 6. **Implement** - Work on the task with progress updates
 7. **Complete** - Move to "Review" when done
 
+### `/hmy-plan` — Plan Workflow
+
+A single command for both creating and executing plans. It auto-detects intent based on the argument:
+
+| Argument | Action |
+|----------|--------|
+| `UUID` | Fetch and work on existing plan |
+| `#42` | Look up card, then its linked plan |
+| `mobile auth` | Search existing plans; if found, work on it; if not, offer to create one |
+| *(empty)* | Start the new plan creation interview |
+
+**Creating a plan** (`/hmy-plan mobile auth`):
+1. Gathers board context and related memories
+2. Interviews you with 3-5 focused questions
+3. Synthesizes a structured plan document
+4. Saves to Harmony via `harmony_create_plan`
+5. Optionally advances to execute phase, creating board cards from tasks
+
+**Executing a plan** (`/hmy-plan <existing plan>`):
+1. Displays plan summary (status, phase, task counts)
+2. Recalls related context from memory
+3. Offers options: create single card, create multiple cards, analyze only, or skip
+4. Creates cards and advances the plan phase
+
 ## 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_move_card` - Move card to different column (auto-ends agent session on move to done/review)
+- `harmony_archive_card` - Archive a card (soft-delete, can be restored)
+- `harmony_unarchive_card` - Restore an archived card back to the board
 - `harmony_delete_card` - Delete a card
 - `harmony_assign_card` - Assign to team member
 - `harmony_search_cards` - Search by title/description
@@ -151,7 +238,7 @@ When you start working on a card (e.g., `/hmy #42`):
 
 - `harmony_list_workspaces` - List workspaces
 - `harmony_list_projects` - List projects
-- `harmony_get_board` - Get full board state
+- `harmony_get_board` - Get board state (supports pagination via `limit`/`offset`, `summary` mode, `columnId` filter, `includeArchived`)
 - `harmony_get_workspace_members` - Get team members
 - `harmony_set_workspace_context` - Set active workspace
 - `harmony_set_project_context` - Set active project
@@ -163,14 +250,28 @@ When you start working on a card (e.g., `/hmy #42`):
 
 ### Agent Session Tracking
 
-- `harmony_start_agent_session` - Start tracking work on a card
+- `harmony_start_agent_session` - Start tracking work on a card (with `moveToColumn` and `addLabels` side effects)
 - `harmony_update_agent_progress` - Update progress, status, blockers
-- `harmony_end_agent_session` - End session (completed/paused)
+- `harmony_end_agent_session` - End session (completed/paused); triggers active learning extraction
 - `harmony_get_agent_session` - Get current session state
+- `harmony_get_agent_profile` - Get aggregate performance profile for an agent
+
+### Auto-Session Detection
+
+Sessions are automatically started when agents call card-mutating tools without an explicit `harmony_start_agent_session`. This ensures work is always tracked, even when agents don't explicitly manage sessions.
+
+**Trigger tools:** `harmony_generate_prompt`, `harmony_update_card`, `harmony_move_card`, `harmony_create_subtask`, `harmony_toggle_subtask`, `harmony_add_label_to_card`, `harmony_remove_label_from_card`
+
+**Behavior:**
+- Auto-starts a session when any trigger tool is called on a card without an active session
+- Auto-ends after 10 minutes of inactivity
+- Switching to a different card auto-ends the previous auto-session
+- Explicitly started sessions (via `harmony_start_agent_session`) are never auto-ended
+- Auto-ended sessions trigger the full active learning pipeline
 
 ### Prompt Generation
 
-- `harmony_generate_prompt` - Generate an AI-ready prompt from a card
+- `harmony_generate_prompt` - Generate an AI-ready prompt from a card with assembled memory context
 
 **Parameters:**
 | Parameter | Description |
@@ -183,13 +284,70 @@ When you start working on a card (e.g., `/hmy #42`):
 | `includeLinks` | Include linked cards in prompt (default: true) |
 | `customConstraints` | Additional instructions to append |
 
-**Variants:**
+The prompt builder automatically infers the agent role based on card labels (bug, feature, design, etc.) and injects relevant memory context using the context assembly engine.
+
+### Memory / Knowledge Graph
+
+Store and retrieve persistent knowledge across sessions. Memories have types, tiers, scopes, confidence scores, and can be linked via typed relations.
+
+**CRUD:**
+
+- `harmony_remember` - Store a memory entity (markdown with YAML frontmatter)
+- `harmony_recall` - Retrieve memories by type, tags, scope, or text query
+- `harmony_update_memory` - Update an existing memory entity
+- `harmony_forget` - Archive or delete a memory entity
+- `harmony_memory_search` - Full-text search across the knowledge base
+- `harmony_relate` - Create a typed relationship between two memory entities
+
+**Entity Types:** `agent`, `task`, `decision`, `context`, `pattern`, `error`, `solution`, `preference`, `relationship`, `commitment`, `lesson`, `project`, `handoff`, `procedure`
+
+**Memory Tiers:** `draft` (working notes) → `episode` (session summaries) → `reference` (durable knowledge)
+
+**Scopes:** `private`, `project`, `workspace`, `global`
+
+**Relation Types:** `learned_from`, `resolved_by`, `contradicts`, `supports`, `depends_on`, `part_of`, `caused_by`, `relates_to`
+
+### Memory Vault & Sync
+
+- `harmony_vault_index` - Compact index of all memory entities (markdown table)
+- `harmony_resolve_links` - Batch-scan for `[[wiki-links]]` and auto-create relations
+- `harmony_sync` - Bidirectional sync between local markdown files (`~/.harmony/memory/`) and remote database (directions: `pull`, `push`, `full`)
+
+### Memory Lifecycle
+
+- `harmony_promote_memory` - Promote entity tier: `draft` → `episode` or `episode` → `reference`
+- `harmony_prune_draft` - Remove stale draft memories (dry-run mode by default)
+- `harmony_consolidate_memories` - Cluster similar draft/episode memories and merge into reference entities (dry-run by default)
+- `harmony_backfill_embeddings` - Generate vector embeddings for entities missing them
+- `harmony_backfill_relations` - Retroactively create semantic relations across existing entities
+
+### Context Debugging
 
-- `analysis` - Understand the problem and create a plan
-- `draft` - Design a solution approach
-- `execute` - Full implementation (default)
+- `harmony_get_context_manifest` - Debug what memories were loaded/excluded in a prompt assembly
+- `harmony_debug_context` - Explain why a specific memory was or wasn't included (relevance score breakdown)
+- `harmony_export_memory_graph` - Export knowledge graph as DOT format for Graphviz visualization
 
-The prompt builder automatically infers the agent role based on card labels (bug, feature, design, etc.) and includes relevant context from linked cards.
+### GSD Workflow Plans
+
+Create and manage project plans with a phased workflow: **plan** → **execute** → **verify** → **done**.
+
+- `harmony_list_plans` - List plans in a project (filter by status or workflow phase)
+- `harmony_create_plan` - Create a new plan with embedded tasks
+- `harmony_get_plan` - Get plan by ID or card ID
+- `harmony_update_plan` - Update plan title, content, status, or phase
+- `harmony_advance_plan` - Advance to next phase with side effects:
+  - **plan → execute:** auto-creates Kanban cards from plan tasks, sets plan active
+  - **execute → verify:** checks card completion status
+  - **verify → done:** archives plan, creates memory entities
+
+### Onboarding & Account
+
+- `harmony_onboard` - Complete end-to-end onboarding: signup → workspace → project → API key
+- `harmony_signup` - Create a new user account
+- `harmony_create_workspace` - Create a new workspace
+- `harmony_create_project` - Create a new project with template columns (kanban, scrum, or simple)
+- `harmony_send_invitations` - Send workspace invitations to team members
+- `harmony_generate_api_key` - Generate an API key for the authenticated user
 
 ## Direct API Access
 
@@ -213,20 +371,20 @@ curl -X GET "https://gethmy.com/api/v1/workspaces" \
 | `/v1/cards/:id`                 | PATCH  | Update card                |
 | `/v1/cards/:id`                 | DELETE | Delete card                |
 | `/v1/cards/:id/move`            | POST   | Move card                  |
+| `/v1/cards/:id/prompt`          | GET    | Generate prompt from card  |
+| `/v1/cards/:id/links`           | GET    | Get card links             |
+| `/v1/cards/:id/links`           | POST   | Create card link           |
+| `/v1/cards/:id/labels`          | POST   | Add label to card          |
+| `/v1/cards/:id/labels/:labelId` | DELETE | Remove label               |
 | `/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
@@ -267,7 +425,7 @@ When your email is configured during setup, cards are automatically assigned to
 To update your email:
 
 ```bash
-npx harmony-mcp setup --email you@example.com
+npx @gethmy/mcp setup --email you@example.com
 ```
 
 The email must match your Harmony account email to work correctly.
@@ -275,7 +433,7 @@ The email must match your Harmony account email to work correctly.
 ### Viewing Configuration
 
 ```bash
-npx harmony-mcp status
+npx @gethmy/mcp status
 ```
 
 Example output:
@@ -318,11 +476,18 @@ Add this to prevent accidentally committing local config:
 ```
 ┌─────────────────┐      MCP Protocol       ┌──────────────────┐
 │  Claude Code    │ ───────────────────────▶│  harmony-mcp     │
-│  Cursor         │                         │  (local server)  │
+│  Cursor         │      (local stdio)      │  (local server)  │
 │  Windsurf       │                         └────────┬─────────┘
 │  Codex          │                                  │
 └─────────────────┘                                  │ API Key Auth
                                                      ▼
+┌─────────────────┐    Streamable HTTP      ┌──────────────────┐
+│  Claude.ai      │ ───────────────────────▶│  Remote MCP      │
+│  Any MCP client │    (Bearer: hmy_xxx)    │  mcp.gethmy.com  │──┐
+└─────────────────┘                         └──────────────────┘  │
+                                                                   │
+                                                     ┌─────────────┘
+                                                     ▼
                                           ┌──────────────────┐
                                           │  Harmony API     │
                                           │  (Edge Function) │