harmony-mcp 1.0.4 → 1.1.1

package/dist/index.js

@@ -23167,6 +23167,22 @@ class HarmonyApiClient {
   async deleteSubtask(subtaskId) {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }
+  async startAgentSession(cardId, data) {
+    return this.request("POST", `/cards/${cardId}/agent-context`, data);
+  }
+  async updateAgentProgress(cardId, data) {
+    return this.request("POST", `/cards/${cardId}/agent-context`, data);
+  }
+  async endAgentSession(cardId, data) {
+    return this.request("DELETE", `/cards/${cardId}/agent-context`, data);
+  }
+  async getAgentSession(cardId, options) {
+    const params = new URLSearchParams;
+    if (options?.includeEnded)
+      params.set("include_ended", "true");
+    const query = params.toString() ? `?${params.toString()}` : "";
+    return this.request("GET", `/cards/${cardId}/agent-context${query}`);
+  }
   async processNLU(data) {
     return this.request("POST", "/nlu", data);
   }
@@ -23451,6 +23467,60 @@ var TOOLS = {
       },
       required: ["command"]
     }
+  },
+  harmony_start_agent_session: {
+    description: "Start an agent work session on a card. Tracks progress, status, and blockers. Call this when beginning work on a card.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card ID to start working on" },
+        agentIdentifier: { type: "string", description: "Unique agent identifier (e.g., claude-code)" },
+        agentName: { type: "string", description: "Human-readable agent name (e.g., Claude Code)" },
+        currentTask: { type: "string", description: "Initial task description" },
+        estimatedMinutesRemaining: { type: "number", description: "Estimated time to completion in minutes" }
+      },
+      required: ["cardId", "agentIdentifier", "agentName"]
+    }
+  },
+  harmony_update_agent_progress: {
+    description: "Update progress on an active agent session. Use to report progress percentage, current task, blockers, or status changes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card ID with active session" },
+        agentIdentifier: { type: "string", description: "Agent identifier" },
+        agentName: { type: "string", description: "Agent name" },
+        status: { type: "string", enum: ["working", "blocked", "paused"], description: "Current status" },
+        progressPercent: { type: "number", description: "Progress percentage (0-100)" },
+        currentTask: { type: "string", description: "What the agent is currently doing" },
+        blockers: { type: "array", items: { type: "string" }, description: "List of blocking issues" },
+        estimatedMinutesRemaining: { type: "number", description: "Updated time estimate" }
+      },
+      required: ["cardId", "agentIdentifier", "agentName"]
+    }
+  },
+  harmony_end_agent_session: {
+    description: "End an agent work session on a card. Call this when work is complete or paused.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card ID to end session on" },
+        status: { type: "string", enum: ["completed", "paused"], description: "Final status (default: completed)" },
+        progressPercent: { type: "number", description: "Final progress percentage" }
+      },
+      required: ["cardId"]
+    }
+  },
+  harmony_get_agent_session: {
+    description: "Get the current agent session for a card, including progress, status, and blockers.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card ID to check" },
+        includeEnded: { type: "boolean", description: "Include ended sessions in history" }
+      },
+      required: ["cardId"]
+    }
   }
 };
 var RESOURCES = [
@@ -23767,6 +23837,49 @@ Include: cards moved recently, current in-progress items, blocked or high-priori
         });
         return { success: true, ...result };
       }
+      case "harmony_start_agent_session": {
+        const cardId = exports_external.string().uuid().parse(args.cardId);
+        const agentIdentifier = exports_external.string().min(1).parse(args.agentIdentifier);
+        const agentName = exports_external.string().min(1).parse(args.agentName);
+        const result = await client2.startAgentSession(cardId, {
+          agentIdentifier,
+          agentName,
+          status: "working",
+          currentTask: args.currentTask,
+          estimatedMinutesRemaining: args.estimatedMinutesRemaining
+        });
+        return { success: true, ...result };
+      }
+      case "harmony_update_agent_progress": {
+        const cardId = exports_external.string().uuid().parse(args.cardId);
+        const agentIdentifier = exports_external.string().min(1).parse(args.agentIdentifier);
+        const agentName = exports_external.string().min(1).parse(args.agentName);
+        const result = await client2.updateAgentProgress(cardId, {
+          agentIdentifier,
+          agentName,
+          status: args.status,
+          progressPercent: args.progressPercent,
+          currentTask: args.currentTask,
+          blockers: args.blockers,
+          estimatedMinutesRemaining: args.estimatedMinutesRemaining
+        });
+        return { success: true, ...result };
+      }
+      case "harmony_end_agent_session": {
+        const cardId = exports_external.string().uuid().parse(args.cardId);
+        const result = await client2.endAgentSession(cardId, {
+          status: args.status || "completed",
+          progressPercent: args.progressPercent
+        });
+        return { success: true, ...result };
+      }
+      case "harmony_get_agent_session": {
+        const cardId = exports_external.string().uuid().parse(args.cardId);
+        const result = await client2.getAgentSession(cardId, {
+          includeEnded: args.includeEnded === true || args.includeEnded === "true"
+        });
+        return { success: true, ...result };
+      }
       default:
         throw new Error(`Unknown tool: ${name}`);
     }

package/dist/init.js

@@ -0,0 +1,413 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/init.ts
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+var HARMONY_WORKFLOW_PROMPT = `# Harmony Card Workflow
+
+You are starting work on a Harmony card. Follow this workflow:
+
+## Step 1: Find the Card
+
+The user provided: $ARGUMENTS
+
+Parse the card reference:
+- If it starts with \`#\` followed by numbers (e.g., \`#42\`), use \`harmony_get_card_by_short_id\` with the number
+- If it looks like a UUID, use \`harmony_get_card\` directly
+- Otherwise, use \`harmony_search_cards\` to find by name
+
+## Step 2: Move to In Progress
+
+Once you have the card:
+1. Get the board using \`harmony_get_board\` to find the "In Progress" column ID
+2. Use \`harmony_move_card\` to move the card to "In Progress"
+
+## Step 3: Add Agent Label
+
+1. From the board response, find the label named "agent"
+2. Use \`harmony_add_label_to_card\` to add it to the card
+
+## Step 4: Start Agent Session
+
+After adding the agent label, start tracking your work session:
+1. Use \`harmony_start_agent_session\` with:
+   - \`cardId\`: The card ID
+   - \`agentIdentifier\`: Your agent identifier
+   - \`agentName\`: Your agent name
+   - \`currentTask\`: A brief description of what you're about to do
+
+This enables the timer badge on the card to show your progress in real-time.
+
+## Step 5: Display Card Details
+
+Show the user:
+- Card title and short ID
+- Description (if any)
+- Priority
+- Current labels
+- Due date (if set)
+
+## Step 6: Implement the Solution
+
+Based on the card's title and description:
+1. Understand what needs to be done
+2. Explore the codebase as needed
+3. Implement the required changes
+4. Test the changes
+
+**During implementation, update your progress periodically:**
+- Use \`harmony_update_agent_progress\` to report:
+  - \`progressPercent\`: Estimated completion (0-100)
+  - \`currentTask\`: What you're currently doing
+  - \`blockers\`: Any issues blocking progress (set \`status: "blocked"\` if blocked)
+
+## Step 7: Complete Work
+
+When implementation is complete:
+1. Use \`harmony_end_agent_session\` with:
+   - \`cardId\`: The card ID
+   - \`status\`: "completed"
+   - \`progressPercent\`: 100
+2. Use \`harmony_move_card\` to move the card to the "Review" column
+3. Summarize what was accomplished
+
+## Important Notes
+- Always read the card description carefully before starting
+- If the task is unclear, ask for clarification
+- Make commits as appropriate during implementation
+- The "agent" label indicates AI is working on the card
+- Update progress at meaningful milestones, not constantly
+- If you need to pause work, call \`harmony_end_agent_session\` with \`status: "paused"\`
+`;
+function ensureDir(dirPath) {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+function writeFileIfNotExists(filePath, content, force) {
+  if (existsSync(filePath) && !force) {
+    return { created: false, skipped: true };
+  }
+  ensureDir(dirname(filePath));
+  writeFileSync(filePath, content, "utf-8");
+  return { created: true, skipped: false };
+}
+function mergeJsonFile(filePath, updates, force) {
+  if (!existsSync(filePath)) {
+    ensureDir(dirname(filePath));
+    writeFileSync(filePath, JSON.stringify(updates, null, 2), "utf-8");
+    return { created: true, skipped: false, merged: false };
+  }
+  try {
+    const existing = JSON.parse(readFileSync(filePath, "utf-8"));
+    if (updates.mcpServers && existing.mcpServers) {
+      if (existing.mcpServers.harmony && !force) {
+        return { created: false, skipped: true, merged: false };
+      }
+      existing.mcpServers = { ...existing.mcpServers, ...updates.mcpServers };
+    } else {
+      Object.assign(existing, updates);
+    }
+    writeFileSync(filePath, JSON.stringify(existing, null, 2), "utf-8");
+    return { created: false, skipped: false, merged: true };
+  } catch {
+    if (force) {
+      writeFileSync(filePath, JSON.stringify(updates, null, 2), "utf-8");
+      return { created: true, skipped: false, merged: false };
+    }
+    return { created: false, skipped: true, merged: false };
+  }
+}
+function initClaude(cwd, force) {
+  const result = {
+    agent: "claude",
+    filesCreated: [],
+    filesSkipped: []
+  };
+  const commandContent = `---
+description: Start working on a Harmony card (moves to In Progress, adds agent label)
+argument-hint: <card-reference>
+---
+
+${HARMONY_WORKFLOW_PROMPT.replace("Your agent identifier", "claude-code").replace("Your agent name", "Claude Code")}
+`;
+  const commandPath = join(cwd, ".claude", "commands", "hmy.md");
+  const { created, skipped } = writeFileIfNotExists(commandPath, commandContent, force);
+  if (created)
+    result.filesCreated.push(commandPath);
+  if (skipped)
+    result.filesSkipped.push(commandPath);
+  const globalConfigPath = join(homedir(), ".claude", "settings.json");
+  const mcpConfig = {
+    mcpServers: {
+      harmony: {
+        command: "harmony-mcp",
+        args: ["serve"]
+      }
+    }
+  };
+  const configResult = mergeJsonFile(globalConfigPath, mcpConfig, force);
+  if (configResult.created || configResult.merged) {
+    result.filesCreated.push(globalConfigPath);
+  } else if (configResult.skipped) {
+    result.filesSkipped.push(globalConfigPath);
+  }
+  return result;
+}
+function initCodex(cwd, force) {
+  const result = {
+    agent: "codex",
+    filesCreated: [],
+    filesSkipped: []
+  };
+  const agentsContent = `# Harmony Integration
+
+This project uses Harmony for task management. When working on tasks:
+
+## Starting Work on a Card
+
+When given a card reference (e.g., #42 or a card name), follow this workflow:
+
+1. Use \`harmony_get_card_by_short_id\` or \`harmony_search_cards\` to find the card
+2. Move the card to "In Progress" using \`harmony_move_card\`
+3. Add the "agent" label using \`harmony_add_label_to_card\`
+4. Start a session with \`harmony_start_agent_session\` (agentIdentifier: "codex", agentName: "OpenAI Codex")
+5. Show the card details to the user
+6. Implement the solution based on the card description
+7. Update progress periodically with \`harmony_update_agent_progress\`
+8. When done, call \`harmony_end_agent_session\` and move to "Review"
+
+## Available Harmony Tools
+
+- \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\` - Find cards
+- \`harmony_move_card\` - Move cards between columns
+- \`harmony_add_label_to_card\`, \`harmony_remove_label_from_card\` - Manage labels
+- \`harmony_start_agent_session\`, \`harmony_update_agent_progress\`, \`harmony_end_agent_session\` - Track work
+- \`harmony_get_board\` - Get board state
+`;
+  const agentsPath = join(cwd, "AGENTS.md");
+  const { created: agentsCreated, skipped: agentsSkipped } = writeFileIfNotExists(agentsPath, agentsContent, force);
+  if (agentsCreated)
+    result.filesCreated.push(agentsPath);
+  if (agentsSkipped)
+    result.filesSkipped.push(agentsPath);
+  const promptContent = `---
+name: hmy
+description: Start working on a Harmony card
+arguments:
+  - name: card
+    description: Card reference (#42, UUID, or name)
+    required: true
+---
+
+${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "{{card}}").replace("Your agent identifier", "codex").replace("Your agent name", "OpenAI Codex")}
+`;
+  const promptsDir = join(homedir(), ".codex", "prompts");
+  const promptPath = join(promptsDir, "hmy.md");
+  const { created: promptCreated, skipped: promptSkipped } = writeFileIfNotExists(promptPath, promptContent, force);
+  if (promptCreated)
+    result.filesCreated.push(promptPath);
+  if (promptSkipped)
+    result.filesSkipped.push(promptPath);
+  const configPath = join(homedir(), ".codex", "config.toml");
+  const mcpConfigSection = `
+# Harmony MCP Server
+[mcp_servers.harmony]
+command = "harmony-mcp"
+args = ["serve"]
+`;
+  if (!existsSync(configPath)) {
+    ensureDir(dirname(configPath));
+    writeFileSync(configPath, mcpConfigSection, "utf-8");
+    result.filesCreated.push(configPath);
+  } else {
+    const existingConfig = readFileSync(configPath, "utf-8");
+    if (!existingConfig.includes("[mcp_servers.harmony]")) {
+      writeFileSync(configPath, existingConfig + `
+` + mcpConfigSection, "utf-8");
+      result.filesCreated.push(configPath);
+    } else if (force) {
+      const updated = existingConfig.replace(/\[mcp_servers\.harmony\][\s\S]*?(?=\[|$)/, mcpConfigSection.trim() + `
+
+`);
+      writeFileSync(configPath, updated, "utf-8");
+      result.filesCreated.push(configPath);
+    } else {
+      result.filesSkipped.push(configPath);
+    }
+  }
+  return result;
+}
+function initCursor(cwd, force) {
+  const result = {
+    agent: "cursor",
+    filesCreated: [],
+    filesSkipped: []
+  };
+  const mcpConfigPath = join(cwd, ".cursor", "mcp.json");
+  const mcpConfig = {
+    mcpServers: {
+      harmony: {
+        command: "harmony-mcp",
+        args: ["serve"]
+      }
+    }
+  };
+  const mcpResult = mergeJsonFile(mcpConfigPath, mcpConfig, force);
+  if (mcpResult.created || mcpResult.merged) {
+    result.filesCreated.push(mcpConfigPath);
+  } else if (mcpResult.skipped) {
+    result.filesSkipped.push(mcpConfigPath);
+  }
+  const ruleContent = `---
+description: Harmony card workflow rule
+globs:
+  - "**/*"
+alwaysApply: false
+---
+
+# Harmony Integration
+
+When the user asks you to work on a Harmony card (references like #42, card names, or UUIDs):
+
+${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Your agent identifier", "cursor").replace("Your agent name", "Cursor AI")}
+`;
+  const rulePath = join(cwd, ".cursor", "rules", "harmony.mdc");
+  const { created: ruleCreated, skipped: ruleSkipped } = writeFileIfNotExists(rulePath, ruleContent, force);
+  if (ruleCreated)
+    result.filesCreated.push(rulePath);
+  if (ruleSkipped)
+    result.filesSkipped.push(rulePath);
+  return result;
+}
+function initWindsurf(cwd, force) {
+  const result = {
+    agent: "windsurf",
+    filesCreated: [],
+    filesSkipped: []
+  };
+  const globalMcpPath = join(homedir(), ".codeium", "windsurf", "mcp_config.json");
+  const mcpConfig = {
+    mcpServers: {
+      harmony: {
+        command: "harmony-mcp",
+        args: ["serve"],
+        disabled: false,
+        alwaysAllow: []
+      }
+    }
+  };
+  const mcpResult = mergeJsonFile(globalMcpPath, mcpConfig, force);
+  if (mcpResult.created || mcpResult.merged) {
+    result.filesCreated.push(globalMcpPath);
+  } else if (mcpResult.skipped) {
+    result.filesSkipped.push(globalMcpPath);
+  }
+  const ruleContent = `---
+trigger: model_decision
+description: Activate when user asks to work on a Harmony card (references like #42, card names, or task management)
+---
+
+# Harmony Card Workflow
+
+When working on a Harmony card:
+
+${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Your agent identifier", "windsurf").replace("Your agent name", "Windsurf AI")}
+`;
+  const rulePath = join(cwd, ".windsurf", "rules", "harmony.md");
+  const { created: ruleCreated, skipped: ruleSkipped } = writeFileIfNotExists(rulePath, ruleContent, force);
+  if (ruleCreated)
+    result.filesCreated.push(rulePath);
+  if (ruleSkipped)
+    result.filesSkipped.push(rulePath);
+  return result;
+}
+function initHarmony(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const force = options.force || false;
+  const agents = options.agents || ["claude", "codex", "cursor", "windsurf"];
+  const results = [];
+  for (const agent of agents) {
+    try {
+      switch (agent) {
+        case "claude":
+          results.push(initClaude(cwd, force));
+          break;
+        case "codex":
+          results.push(initCodex(cwd, force));
+          break;
+        case "cursor":
+          results.push(initCursor(cwd, force));
+          break;
+        case "windsurf":
+          results.push(initWindsurf(cwd, force));
+          break;
+        default:
+          results.push({
+            agent,
+            filesCreated: [],
+            filesSkipped: [],
+            error: `Unknown agent: ${agent}`
+          });
+      }
+    } catch (error) {
+      results.push({
+        agent,
+        filesCreated: [],
+        filesSkipped: [],
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  return results;
+}
+function detectAgents(cwd = process.cwd()) {
+  const detected = [];
+  if (existsSync(join(cwd, ".claude")) || existsSync(join(homedir(), ".claude"))) {
+    detected.push("claude");
+  }
+  if (existsSync(join(cwd, "AGENTS.md")) || existsSync(join(homedir(), ".codex"))) {
+    detected.push("codex");
+  }
+  if (existsSync(join(cwd, ".cursor"))) {
+    detected.push("cursor");
+  }
+  if (existsSync(join(cwd, ".windsurf")) || existsSync(join(cwd, ".windsurfrules")) || existsSync(join(homedir(), ".codeium", "windsurf"))) {
+    detected.push("windsurf");
+  }
+  return detected;
+}
+var SUPPORTED_AGENTS = ["claude", "codex", "cursor", "windsurf"];
+export {
+  initHarmony,
+  detectAgents,
+  SUPPORTED_AGENTS
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "harmony-mcp",
-  "version": "1.0.4",
-  "description": "MCP server for Harmony Kanban board - enables Claude Code to manage your boards",
+  "version": "1.1.1",
+  "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -13,28 +13,32 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/nicholasgriffintn/harmony.git"
+    "url": "https://github.com/Way/getharmony/tree/main/packages/mcp-server"
   },
   "homepage": "https://gethmy.com",
   "bugs": {
-    "url": "https://github.com/nicholasgriffintn/harmony/issues"
+    "url": "https://github.com/Way/getharmony/issues"
   },
   "keywords": [
     "mcp",
     "model-context-protocol",
     "claude",
+    "codex",
+    "cursor",
+    "windsurf",
     "kanban",
     "harmony",
     "ai",
     "llm",
-    "project-management"
+    "project-management",
+    "coding-assistant"
   ],
   "engines": {
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "bun build src/index.ts src/cli.ts --outdir dist --target node",
-    "build:bun": "bun build src/index.ts src/http.ts src/cli.ts --outdir dist --target bun",
+    "build": "bun build src/index.ts src/cli.ts src/init.ts --outdir dist --target node",
+    "build:bun": "bun build src/index.ts src/http.ts src/cli.ts src/init.ts --outdir dist --target bun",
     "dev": "bun --watch src/index.ts",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run build"