harmony-mcp 1.9.6 → 1.9.7

package/README.md

@@ -5,14 +5,18 @@ Enables AI coding agents (Claude Code, OpenAI Codex, Cursor, Windsurf) to intera
 
 ## Features
 
-- **29 MCP Tools** for full board control (cards, columns, labels, subtasks, links)
+- **43+ 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-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
@@ -39,6 +43,31 @@ The smart setup wizard will:
 
 That's it! You're ready to use Harmony with your AI agent.
 
+## Remote MCP (Hosted)
+
+If your AI tool supports remote MCP servers natively (e.g., Claude.ai), you can connect directly 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
+
+```
+Authorization: Bearer hmy_your_key_here
+```
+
+**How to connect from Claude.ai:**
+
+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 43+ 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:** Use the remote endpoint when your client supports it natively (like Claude.ai) and you don't need local file access. Use the local server (`npx harmony-mcp setup`) when your agent needs stdio transport or you want skills and local project context.
+
 ### Adding to a New Project
 
 Just run setup again in the new project directory:
@@ -83,12 +112,13 @@ 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`               | `~/.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)    |
 
 ## Card Workflow
 
@@ -108,7 +138,7 @@ When you start working on a card (e.g., `/hmy #42`):
 
 - `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_delete_card` - Delete a card
 - `harmony_assign_card` - Assign to team member
 - `harmony_search_cards` - Search by title/description
@@ -151,7 +181,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)
 - `harmony_get_workspace_members` - Get team members
 - `harmony_set_workspace_context` - Set active workspace
 - `harmony_set_project_context` - Set active project
@@ -163,14 +193,14 @@ 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
 
 ### 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 +213,64 @@ 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`
+
+**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
 
-- `analysis` - Understand the problem and create a plan
-- `draft` - Design a solution approach
-- `execute` - Full implementation (default)
+- `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`)
 
-The prompt builder automatically infers the agent role based on card labels (bug, feature, design, etc.) and includes relevant context from linked cards.
+### 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)
+
+### Active Learning & Review
+
+When an agent session ends, the system auto-extracts learnings: blockers produce `error` entities, completed sessions produce `lesson` entities, and bug fixes produce `solution` entities. Lower-confidence entries go into a review queue.
+
+- `harmony_review_learnings` - List pending auto-extracted memories awaiting review
+- `harmony_approve_learning` - Approve or reject a pending learning
+
+### Context Debugging
+
+- `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
+
+### GSD Workflow Plans
+
+Create and manage project plans with a phased workflow: **plan** → **execute** → **verify** → **done**.
+
+- `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
 
 ## Direct API Access
 
@@ -213,20 +294,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
@@ -318,11 +399,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) │