2.13.3 • Published yesterdayCLI

@gethmy/mcp

Licence

—

Version

2.13.3

Deps

Size

1.1 MB

Vulns

Weekly

1.1K

Summary Dependency Versions

@gethmy/mcp

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

Features

71 MCP Tools for full board control, knowledge graph, and workflow plans
7 Global Skills — /hmy, /hmy-plan, /hmy-cleanup, /hmy-standup, /hmy-memory-prune, /hmy-upgrade, /hmy-review, served from the DB-backed skill hub with auto-update and admin-managed versioning
Knowledge Graph Memory — Phase 1 surface: hybrid retrieval (vector + lexical + RRF), session-scoped working memory, activity feed. See docs/memory.md
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, Claude.ai
Smart Setup - one command configures everything
Browser Sign-In - secure OAuth setup (loopback + PKCE), no key to copy or paste; API keys still supported for CI

Prerequisites

Node.js >= 20 or Bun >= 1.0
A Harmony account with an API key

Quick Start

Run Setup

npx @gethmy/mcp setup

The smart setup wizard will:

Sign you in through your browser (OAuth — no API key to copy or paste). You can also create a free account or paste an existing key from the same prompt.
Detect installed AI agents (Claude Code, Cursor, 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.

Prefer an API key? Generate one at gethmy.com/user/keys (starts with hmy_) and choose "Paste an API key" in the setup prompt, or pass --api-key for unattended CI. Browser sign-in is the recommended path for interactive setup.

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, 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 70 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) — authorizes in your browser, no API key handling
npx @gethmy/mcp setup              # Smart setup wizard

# Setup with flags (non-interactive)
npx @gethmy/mcp setup --global --workspace ID --project ID
# --api-key is supported for unattended CI only (deprecated — see below)

# 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>`	Deprecated — insecure (leaks via argv/shell history). Unattended CI only; interactive setup uses browser sign-in.
`-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)
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)

Seven global skills ship with the MCP server and are installed automatically by npx @gethmy/mcp setup. They live in the skill_resource Postgres table, are fetched via GET /v1/skills/<name>, and render-time composed with a shared auto-update preamble.

For the full skill hub architecture (storage, versioning, auto-update, admin management), see docs/skills.md.

`/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

`/hmy-cleanup` — Board Audit

Scans the board for stale cards — long-idle, missing owners, or stuck in review — and proposes cleanup actions. Read-only by default; opt-in to apply suggestions.

`/hmy-standup` — Daily Summary

Generates a structured standup summary: what shipped, what's in progress, what's blocked, and where agents need input. Pulls from card activity, plan progress, and the memory activity feed.

Auto-Update

Every skill ships with an hmy-update-check preamble that fires on invocation. It compares local versions against /v1/skills/version and prompts (or silently auto-installs, if ~/.hmy/config.yaml has auto_upgrade: true). Snooze levels: 24h / 48h / 7d.

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_list_agents - List a workspace's virtual agents (daemons); use the id with harmony_assign_card (agentId)
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

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)

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. Browser sign-in writes OAuth tokens (and nulls apiKey); API-key setup writes apiKey instead. The server prefers a live OAuth token and refreshes it automatically:

{
  "apiKey": null,
  "oauthAccessToken": "hmy_at_...",
  "oauthRefreshToken": "...",
  "oauthExpiresAt": 1750000000,
  "oauthClientId": "...",
  "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    │ ───────────────────────▶│  @gethmy/mcp     │
│  Cursor         │      (local stdio)      │  (local server)  │
│  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

Testing

bun run test:unit          # fast — covers dispatch + skills
bun run test:integration   # spins up real memory pipeline
bun run typecheck          # type-only check

MCP bridge verification harness

Three test files pin the contract every MCP client depends on. They are mandatory — agents lose tools silently if any of these drift:

File	What it pins
`src/__tests__/skills.test.ts`	`buildSkillFile` renderer contract: version-marker injection, body trimming, version-parse edge cases. Fed by `FetchedSkill` fixtures (DB-backed via `/v1/skills` post-#162 Phase 0).
`src/__tests__/tool-dispatch.test.ts`	`TOOLS` registry shape, name uniqueness + `harmony_*` namespace, `inputSchema` validity, handler routing via `registerHandlers`, tool skill namespace boundary.
`src/__tests__/mcp-integration.test.ts`	End-to-end `Client ↔ Server` round-trip over `InMemoryTransport` — `listTools`, `callTool`, `listResources`, `readResource`, plus error paths.

Adding a new tool

Append the entry to TOOLS in src/server.ts (name, description, inputSchema).
Add a case "harmony_..." branch in handleToolCall.
Run bun run test:unit — the parameterized assertions in tool-dispatch.test.ts automatically cover the new entry's shape.
If the tool needs a unique round-trip assertion, extend mcp-integration.test.ts with one extra case.

Adding a new skill

Define MY_SKILL_CONTENT in src/skills.ts.
Add it to SKILL_DEFINITIONS with name, description, argumentHint, and content.
Bump SKILLS_VERSION so installed clients refresh on next startup.
Run bun run test:unit — the parameterized assertions in skills.test.ts automatically cover the new skill.

CI gates the full test:unit suite on every PR that touches src/server.ts, src/skills.ts, or any file under src/__tests__/.

Keywords

mcp model-context-protocol claude codex cursor windsurf kanban harmony ai llm project-management coding-assistant