@gethmy/mcp 2.21.0 → 2.23.0

package/README.md

@@ -1,12 +1,12 @@
 # @gethmy/mcp
 
-MCP (Model Context Protocol) server for [Harmony](https://gethmy.com).
-Enables AI coding agents (Claude Code, OpenAI Codex, Cursor) to interact with your Harmony boards.
+MCP (Model Context Protocol) server for [Harmony](https://gethmy.com), the shared surface for human–agent teams.
+Claude Code, OpenAI Codex, Cursor, and any MCP client claim cards, report progress, and move work on your board.
 
 ## 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](../../docs/skills.md) with auto-update and admin-managed versioning
+- **78 MCP Tools** for full board control, knowledge graph, and workflow plans
+- **Global Skills** — installable in one command, served from the DB-backed [skill hub](../../docs/skills.md) 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](../../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)
@@ -16,7 +16,7 @@ Enables AI coding agents (Claude Code, OpenAI Codex, Cursor) to interact with yo
 - **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
+- **One-Command 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
@@ -32,7 +32,7 @@ Enables AI coding agents (Claude Code, OpenAI Codex, Cursor) to interact with yo
 npx @gethmy/mcp setup
 ```
 
-The smart setup wizard will:
+The 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)
@@ -89,7 +89,7 @@ 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 70 Harmony tools become available in your conversation
+4. All 78 Harmony tools become available in your conversation
 
 **Session management** is automatic - sessions have a 1-hour TTL and are created/renewed transparently.
 
@@ -110,7 +110,7 @@ It detects your existing configuration and only asks for the project context.
 
 ```bash
 # Setup (recommended) — authorizes in your browser, no API key handling
-npx @gethmy/mcp setup              # Smart setup wizard
+npx @gethmy/mcp setup              # Setup wizard
 
 # Setup with flags (non-interactive)
 npx @gethmy/mcp setup --global --workspace ID --project ID
@@ -150,9 +150,9 @@ npx @gethmy/mcp serve              # Start MCP server
 
 ## Skills
 
-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.
+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.
 
-For the full skill hub architecture (storage, versioning, auto-update, admin management), see [docs/skills.md](../../docs/skills.md).
+For the full skill list and the hub architecture (storage, versioning, auto-update, admin management), see [docs/skills.md](../../docs/skills.md).
 
 ### `/hmy` — Card Workflow
 
@@ -200,7 +200,7 @@ Generates a structured standup summary: what shipped, what's in progress, what's
 
 ### 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.
+The server owns auto-update. `refreshSkills()` runs at `serve` startup, calls `GET /v1/skills/version` at most once per 24h, and atomically rewrites only the installed skill files that are behind. Two knobs live in `~/.hmy/config.yaml`: `update_check` (master switch) and `pin` (freeze on the installed version).
 
 ## Available Tools
 
@@ -296,7 +296,7 @@ Sessions are automatically started when agents call card-mutating tools without
 |-----------|-------------|
 | `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) |
+| `variant` | `analysis` (understand/plan), `draft` (design the approach), `execute` (implement fully) |
 | `includeDescription` | Include card description (default: true) |
 | `includeSubtasks` | Include subtasks in prompt (default: true) |
 | `includeLinks` | Include linked cards in prompt (default: true) |
@@ -340,7 +340,7 @@ Create and manage project plans with a phased workflow: **plan** → **execute**
 - `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
+  - **plan → execute:** auto-creates board cards from plan tasks, sets plan active
   - **execute → verify:** checks card completion status
   - **verify → done:** archives plan, creates memory entities
 
@@ -349,7 +349,7 @@ Create and manage project plans with a phased workflow: **plan** → **execute**
 - `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_create_project` - Create a new project with template columns (kanban, scrum, or simple) <!-- copy-guard-ignore: template enum value of the public API, not copy -->
 - `harmony_send_invitations` - Send workspace invitations to team members
 - `harmony_generate_api_key` - Generate an API key for the authenticated user
 

package/dist/cli.js

@@ -4657,6 +4657,11 @@ var TOOLS = {
         steerable: {
           type: "boolean",
           description: "Set true only if this session will poll harmony_get_pending_messages at its checkpoints. Enables the live steering composer for the run; leave unset/false if you won't consume steering messages."
+        },
+        driver: {
+          type: "string",
+          enum: ["daemon", "interactive", "script"],
+          description: 'Who is calling: the agent daemon, a human-driven interactive session, or an automation script. Names you as the holder if another caller hits a 409 on this card. Defaults to "interactive".'
         }
       },
       required: ["cardId", "agentIdentifier", "agentName"]
@@ -6411,7 +6416,8 @@ ${options}
         status: "working",
         currentTask: args.currentTask,
         estimatedMinutesRemaining: optionalNonNegativeNumberArg(args.estimatedMinutesRemaining, "estimatedMinutesRemaining"),
-        steerable: args.steerable === true || args.steerable === "true" ? true : undefined
+        steerable: args.steerable === true || args.steerable === "true" ? true : undefined,
+        driver: args.driver ?? "interactive"
       });
       markExplicit(cardId, {
         agentIdentifier,
@@ -9395,7 +9401,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
 // src/cli.ts
 var require2 = createRequire2(import.meta.url);
 var { version } = require2("../package.json");
-program.name("@gethmy/mcp").description("MCP server for Harmony Kanban board").version(version);
+program.name("@gethmy/mcp").description("MCP server for Harmony — the shared surface for human–agent teams").version(version);
 program.command("serve").description("Start the MCP server (stdio transport)").action(async () => {
   if (!isConfigured()) {
     console.error("No API key configured.");
@@ -9479,7 +9485,7 @@ program.command("reset").description("Remove stored configuration").action(() =>
   console.log(`
 To reconfigure, run: npx @gethmy/mcp setup`);
 });
-program.command("setup").description("Smart setup wizard for Harmony MCP (recommended)").argument("[slug]", "Project slug — resolves to workspace + project in one step (e.g. harmony-6590761b)").option("-f, --force", "Overwrite existing configuration files").option("-k, --api-key <key>", "DEPRECATED (insecure: key leaks via argv/shell history). For unattended CI only — interactive setup uses browser sign-in.").option("-e, --email <email>", "Your email for auto-assignment").option("-a, --agents <agents...>", "Agents to configure: claude, codex, cursor, windsurf").option("-l, --local", "Install skills locally in project directory").option("-g, --global", "Install skills globally (recommended)").option("-w, --workspace <id>", "Set workspace context (UUID)").option("-p, --project <id>", "Set project context (UUID)").option("--skip-context", "Skip workspace/project selection").option("--skip-docs", "Skip project docs scaffold/verification").option("-y, --yes", "Non-interactive: answer every yes/no confirmation with its default. Implied when there is no TTY (pipe / coding agent / CI). Provide the other inputs via flags (--api-key, --agents, --workspace/--project or --skip-context, --skip-docs).").option("--new", "Create a new account (skip the choice prompt)").option("-n, --name <name>", "Full name (for account creation)").option("--allow-all-tools", "Allowlist every Harmony tool (incl. destructive: delete/archive/api-key/invite) without confirmation. Default allowlists only read + routine-write tools; destructive tools keep prompting.").action(async (slug, options) => {
+program.command("setup").description("Setup wizard for Harmony MCP (recommended)").argument("[slug]", "Project slug — resolves to workspace + project in one step (e.g. harmony-6590761b)").option("-f, --force", "Overwrite existing configuration files").option("-k, --api-key <key>", "DEPRECATED (insecure: key leaks via argv/shell history). For unattended CI only — interactive setup uses browser sign-in.").option("-e, --email <email>", "Your email for auto-assignment").option("-a, --agents <agents...>", "Agents to configure: claude, codex, cursor, windsurf").option("-l, --local", "Install skills locally in project directory").option("-g, --global", "Install skills globally (recommended)").option("-w, --workspace <id>", "Set workspace context (UUID)").option("-p, --project <id>", "Set project context (UUID)").option("--skip-context", "Skip workspace/project selection").option("--skip-docs", "Skip project docs scaffold/verification").option("-y, --yes", "Non-interactive: answer every yes/no confirmation with its default. Implied when there is no TTY (pipe / coding agent / CI). Provide the other inputs via flags (--api-key, --agents, --workspace/--project or --skip-context, --skip-docs).").option("--new", "Create a new account (skip the choice prompt)").option("-n, --name <name>", "Full name (for account creation)").option("--allow-all-tools", "Allowlist every Harmony tool (incl. destructive: delete/archive/api-key/invite) without confirmation. Default allowlists only read + routine-write tools; destructive tools keep prompting.").action(async (slug, options) => {
   await runSetup({
     force: options.force,
     apiKey: options.apiKey,

package/dist/index.js

@@ -4652,6 +4652,11 @@ var TOOLS = {
         steerable: {
           type: "boolean",
           description: "Set true only if this session will poll harmony_get_pending_messages at its checkpoints. Enables the live steering composer for the run; leave unset/false if you won't consume steering messages."
+        },
+        driver: {
+          type: "string",
+          enum: ["daemon", "interactive", "script"],
+          description: 'Who is calling: the agent daemon, a human-driven interactive session, or an automation script. Names you as the holder if another caller hits a 409 on this card. Defaults to "interactive".'
         }
       },
       required: ["cardId", "agentIdentifier", "agentName"]
@@ -6406,7 +6411,8 @@ ${options}
         status: "working",
         currentTask: args.currentTask,
         estimatedMinutesRemaining: optionalNonNegativeNumberArg(args.estimatedMinutesRemaining, "estimatedMinutesRemaining"),
-        steerable: args.steerable === true || args.steerable === "true" ? true : undefined
+        steerable: args.steerable === true || args.steerable === "true" ? true : undefined,
+        driver: args.driver ?? "interactive"
       });
       markExplicit(cardId, {
         agentIdentifier,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.21.0",
-  "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
+  "version": "2.23.0",
+  "description": "MCP server for Harmony, the shared surface for human–agent teams — agents claim cards, report progress, and move work on your board.",
   "publishConfig": {
     "access": "public"
   },
@@ -63,8 +63,9 @@
     "build:bun": "bun build src/index.ts src/http.ts src/remote.ts src/cli.ts --outdir dist --target bun",
     "serve:remote": "bun src/remote.ts",
     "dev": "bun --watch src/index.ts",
-    "test": "bun run test:unit && bun run test:integration",
-    "test:unit": "bun test src/__tests__/active-learning.test.ts src/__tests__/context-assembly.test.ts src/__tests__/prompt-builder.test.ts src/__tests__/memory-audit.test.ts src/__tests__/skills.test.ts src/__tests__/hmy-config.test.ts src/__tests__/tool-dispatch.test.ts src/__tests__/mcp-integration.test.ts src/__tests__/auto-session.test.ts src/__tests__/remote-routing.test.ts src/__tests__/setup-confirm.test.ts",
+    "test": "bun run test:unit",
+    "test:unit": "bun scripts/test-isolated.mjs",
+    "test:unit:fast": "bun test src/__tests__ --path-ignore-patterns='**/integration-*'",
     "test:integration": "bun test src/__tests__/integration-memory-system.test.ts src/__tests__/integration-memory-crud.test.ts",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run typecheck && bun run build"

package/src/api-client.ts

@@ -1081,6 +1081,22 @@ export class HarmonyApiClient {
       currentTask?: string;
       blockers?: string[];
       estimatedMinutesRemaining?: number;
+      /**
+       * Model the run was spawned with (#819). Persisted to
+       * `card_agent_context.model_name` at session creation so the board's
+       * "Agent Stats" shows the model from run start — previously it stayed
+       * NULL until the terminal cost frame reported the observed model.
+       */
+      modelName?: string;
+      /**
+       * Who is calling (Task 5, "the drivers"): `daemon` (the local agent
+       * daemon), `interactive` (a human-driven `/hmy` session), or `script`
+       * (e.g. the e2e harness). Names the holder in a 409 conflict message so
+       * a second caller knows who to wait on. Optional and nullable
+       * server-side — omitting it is unchanged (pre-existing callers keep
+       * working); the MCP tool dispatch defaults to `interactive`.
+       */
+      driver?: "daemon" | "interactive" | "script";
     },
   ): Promise<{
     session: unknown;

package/src/cli.ts

@@ -22,7 +22,9 @@ const { version } = require("../package.json");
 
 program
   .name("@gethmy/mcp")
-  .description("MCP server for Harmony Kanban board")
+  .description(
+    "MCP server for Harmony — the shared surface for human–agent teams",
+  )
   .version(version);
 
 program
@@ -146,7 +148,7 @@ program
 
 program
   .command("setup")
-  .description("Smart setup wizard for Harmony MCP (recommended)")
+  .description("Setup wizard for Harmony MCP (recommended)")
   .argument(
     "[slug]",
     "Project slug — resolves to workspace + project in one step (e.g. harmony-6590761b)",

package/src/server.ts

@@ -1550,6 +1550,12 @@ export const TOOLS = {
           description:
             "Set true only if this session will poll harmony_get_pending_messages at its checkpoints. Enables the live steering composer for the run; leave unset/false if you won't consume steering messages.",
         },
+        driver: {
+          type: "string",
+          enum: ["daemon", "interactive", "script"],
+          description:
+            'Who is calling: the agent daemon, a human-driven interactive session, or an automation script. Names you as the holder if another caller hits a 409 on this card. Defaults to "interactive".',
+        },
       },
       required: ["cardId", "agentIdentifier", "agentName"],
     },
@@ -3920,6 +3926,11 @@ async function handleToolCall(
           args.steerable === true || args.steerable === "true"
             ? true
             : undefined,
+        // Every MCP caller is interactive unless it says otherwise — this is
+        // the human-driven `/hmy` surface, not the daemon or the e2e script.
+        driver:
+          (args.driver as "daemon" | "interactive" | "script" | undefined) ??
+          "interactive",
       });
 
       // Mark as explicit so auto-session won't interfere