Package Exports

@gethmy/mcp
@gethmy/mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@gethmy/mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@gethmy/mcp

MCP (Model Context Protocol) server for Harmony. Enables AI coding agents (Claude Code, OpenAI Codex, Cursor, Windsurf) to interact with your Harmony boards.

Features

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
API Key Authentication - no database credentials required

Quick Start

1. Get an API Key

Log into Harmony
Go to API Keys
Click "Generate New Key"
Copy the key (starts with hmy_)

2. Run Setup

npx @gethmy/mcp setup

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

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:

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:

# 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):

Get an API key from Harmony
In Claude.ai, add a remote MCP server with URL https://mcp.gethmy.com/mcp
Set the Authorization header to Bearer hmy_your_key_here
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:

cd my-new-project
npx @gethmy/mcp setup

It detects your existing configuration and only asks for the project context.

CLI Commands

# Setup (recommended)
npx @gethmy/mcp setup              # Smart setup wizard

# Setup with flags (non-interactive)
npx @gethmy/mcp setup --api-key KEY --global --workspace ID --project ID

# Status and management
npx @gethmy/mcp status             # Show current configuration
npx @gethmy/mcp reset              # Clear all configuration

# Server (called by agents automatically)
npx @gethmy/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	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

`/hmy` — Card Workflow

When you start working on a card (e.g., /hmy #42):

Find - Locates the card by short ID, UUID, or name
Move - Moves the card to "In Progress" column
Label - Adds the "agent" label to indicate AI is working
Assign - Auto-assigns the card to you (if email is configured)
Track - Starts a session timer visible in the UI
Implement - Work on the task with progress updates
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):

Gathers board context and related memories
Interviews you with 3-5 focused questions
Synthesizes a structured plan document
Saves to Harmony via harmony_create_plan
Optionally advances to execute phase, creating board cards from tasks

Executing a plan (/hmy-plan <existing plan>):

Displays plan summary (status, phase, task counts)
Recalls related context from memory
Offers options: create single card, create multiple cards, analyze only, or skip
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 (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
harmony_get_card - Get card details by UUID
harmony_get_card_by_short_id - Get card by short ID (e.g., #42)

Card Link Operations

harmony_add_link_to_card - Create a link between two cards
harmony_remove_link_from_card - Remove a link between cards
harmony_get_card_links - Get all links for a card

Link Types:

Type	Description
`relates_to`	Generic relationship between cards
`blocks`	Source card blocks target card
`duplicates`	Source card duplicates target card
`is_part_of`	Source card is part of target card

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 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
harmony_get_context - Get current context

Natural Language

harmony_process_command - Process natural language commands

Agent Session Tracking

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); 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 with assembled memory context

Parameters:

Parameter	Description
`cardId`	Card UUID to generate prompt from
`shortId`	Alternative: Card short ID (e.g., 42 for #42)
`variant`	`analysis` (understand/plan), `draft` (design solution), `execute` (implement fully)
`includeDescription`	Include card description (default: true)
`includeSubtasks`	Include subtasks in prompt (default: true)
`includeLinks`	Include linked cards in prompt (default: true)
`customConstraints`	Additional instructions to append

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

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_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

You can also call the Harmony API directly from any HTTP client:

curl -X GET "https://gethmy.com/api/v1/workspaces" \
  -H "X-API-Key: hmy_your_key_here"

API Endpoints

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/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/subtasks`	POST	Create subtask
`/v1/subtasks/:id/toggle`	POST	Toggle subtask
`/v1/subtasks/:id`	DELETE	Delete subtask
`/v1/links/:id`	DELETE	Delete card link
`/v1/nlu`	POST	Process natural language

Configuration

Global Configuration

Stored in ~/.harmony-mcp/config.json:

{
  "apiKey": "hmy_...",
  "apiUrl": "https://gethmy.com/api",
  "userEmail": "you@example.com",
  "activeWorkspaceId": null,
  "activeProjectId": null
}

Local Project Configuration

Stored in .harmony-mcp.json in your project root:

{
  "workspaceId": "uuid-here",
  "projectId": "uuid-here"
}

Priority: Local config overrides global config for workspace and project context.

Security: API key is never stored locally (only in global config) to prevent accidental commits.

Auto-Assignment

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:

npx @gethmy/mcp setup --email you@example.com

The email must match your Harmony account email to work correctly.

Viewing Configuration

npx @gethmy/mcp status

Example output:

Status: Configured

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

Add this to prevent accidentally committing local config:

.harmony-mcp.json

Architecture

┌─────────────────┐      MCP Protocol       ┌──────────────────┐
│  Claude Code    │ ───────────────────────▶│  harmony-mcp     │
│  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) │
                                          └────────┬─────────┘
                                                   │
                                                   ▼
                                          ┌──────────────────┐
                                          │    Database      │
                                          │    (Supabase)    │
                                          └──────────────────┘

Key Benefits:

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

@gethmy/mcp

Package Exports

Readme

@gethmy/mcp

Features

Quick Start

1. Get an API Key

2. Run Setup

Remote MCP (Hosted)

Universal Setup with add-mcp

Manual Setup (Claude.ai)

Adding to a New Project

CLI Commands

Setup Options

Supported AI Agents

Skills

/hmy — Card Workflow

/hmy-plan — Plan Workflow

Available Tools

Card Operations

Card Link Operations

Column Operations

Label Operations

Subtask Operations

Context Operations

Natural Language

Agent Session Tracking

Auto-Session Detection

Prompt Generation

Memory / Knowledge Graph

Memory Vault & Sync

Memory Lifecycle

Context Debugging

GSD Workflow Plans

Onboarding & Account

Direct API Access

API Endpoints

Configuration

Global Configuration

Local Project Configuration

Auto-Assignment

Viewing Configuration

Recommended .gitignore

Architecture

Universal Setup with `add-mcp`

`/hmy` — Card Workflow

`/hmy-plan` — Plan Workflow