@gethmy/mcp 2.2.0 → 2.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"
@@ -62,6 +62,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
+    "@harmony/memory": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.25.3",
     "commander": "^14.0.3",
     "hono": "^4.11.7",

package/src/__tests__/auto-session.test.ts

@@ -51,16 +51,16 @@ describe("auto-start", () => {
 
     expect(client.startAgentSession).toHaveBeenCalledTimes(1);
     expect(client.startAgentSession).toHaveBeenCalledWith(CARD_A, {
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
       status: "working",
     });
     expect(getActiveSessions().size).toBe(1);
     const session = getActiveSessions().get(CARD_A);
     expect(session).toBeDefined();
     expect(session!.isExplicit).toBe(false);
-    expect(session!.agentIdentifier).toBe("auto");
-    expect(session!.agentName).toBe("Auto-detected Agent");
+    expect(session!.agentIdentifier).toBe("unknown");
+    expect(session!.agentName).toBe("Unknown Agent");
   });
 
   test("does NOT trigger on autoStart=false", async () => {
@@ -109,7 +109,7 @@ describe("auto-start", () => {
 
     // Should still be tracked despite API error
     expect(getActiveSessions().size).toBe(1);
-    expect(getActiveSessions().get(CARD_A)!.agentIdentifier).toBe("auto");
+    expect(getActiveSessions().get(CARD_A)!.agentIdentifier).toBe("unknown");
   });
 
   test("uses clientGetter when no client in options", async () => {
@@ -328,8 +328,8 @@ describe("inactivity timeout", () => {
       startedAt: Date.now() - INACTIVITY_TIMEOUT_MS - 1000,
       lastActivityAt: Date.now() - INACTIVITY_TIMEOUT_MS - 1000,
       isExplicit: false,
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
     });
 
     checkInactivity();
@@ -355,8 +355,8 @@ describe("inactivity timeout", () => {
       startedAt: Date.now(),
       lastActivityAt: Date.now(), // just now — well within timeout
       isExplicit: false,
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
     });
 
     checkInactivity();
@@ -398,8 +398,8 @@ describe("inactivity timeout", () => {
       startedAt: Date.now() - INACTIVITY_TIMEOUT_MS - 5000,
       lastActivityAt: Date.now() - INACTIVITY_TIMEOUT_MS - 5000,
       isExplicit: false,
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
     });
 
     // CARD_B — still active
@@ -408,8 +408,8 @@ describe("inactivity timeout", () => {
       startedAt: Date.now() - 1000,
       lastActivityAt: Date.now() - 1000,
       isExplicit: false,
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
     });
 
     // CARD_C — timed out but explicit
@@ -442,8 +442,8 @@ describe("inactivity timeout", () => {
       startedAt: 0,
       lastActivityAt: 0,
       isExplicit: false,
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
     });
 
     // Should not throw
@@ -464,8 +464,8 @@ describe("inactivity timeout", () => {
       startedAt: Date.now() - INACTIVITY_TIMEOUT_MS - 5000,
       lastActivityAt: Date.now() - INACTIVITY_TIMEOUT_MS - 5000,
       isExplicit: false,
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
     });
 
     // Refresh activity
@@ -495,8 +495,8 @@ describe("markExplicit", () => {
 
     markExplicit(CARD_A);
     expect(getActiveSessions().get(CARD_A)!.isExplicit).toBe(true);
-    // agentIdentifier should remain "auto" since it was auto-started
-    expect(getActiveSessions().get(CARD_A)!.agentIdentifier).toBe("auto");
+    // agentIdentifier should remain "unknown" since no clientInfo was provided
+    expect(getActiveSessions().get(CARD_A)!.agentIdentifier).toBe("unknown");
   });
 
   test("creates new tracking entry for unknown card", () => {
@@ -583,8 +583,8 @@ describe("shutdown", () => {
       startedAt: Date.now(),
       lastActivityAt: Date.now(),
       isExplicit: false,
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
     });
 
     await shutdownAllSessions();
@@ -606,8 +606,8 @@ describe("shutdown", () => {
       startedAt: Date.now(),
       lastActivityAt: Date.now(),
       isExplicit: false,
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
     });
     getActiveSessions().set(CARD_B, {
       cardId: CARD_B,
@@ -633,8 +633,8 @@ describe("shutdown", () => {
       startedAt: Date.now(),
       lastActivityAt: Date.now(),
       isExplicit: false,
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
     });
 
     // Should not throw
@@ -660,16 +660,16 @@ describe("shutdown", () => {
       startedAt: Date.now(),
       lastActivityAt: Date.now(),
       isExplicit: false,
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
     });
     getActiveSessions().set(CARD_B, {
       cardId: CARD_B,
       startedAt: Date.now(),
       lastActivityAt: Date.now(),
       isExplicit: false,
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
     });
 
     await shutdownAllSessions();
@@ -826,8 +826,8 @@ describe("edge cases", () => {
       startedAt: 0,
       lastActivityAt: 0,
       isExplicit: false,
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
     });
 
     checkInactivity();
@@ -850,8 +850,8 @@ describe("edge cases", () => {
       startedAt: 0,
       lastActivityAt: 0,
       isExplicit: false,
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier: "unknown",
+      agentName: "Unknown Agent",
     });
 
     checkInactivity();

package/src/api-client.ts

@@ -952,6 +952,211 @@ export class HarmonyApiClient {
   }> {
     return this.request("POST", "/api-keys", { name });
   }
+
+  // ============ PROMPT GENERATION ============
+
+  /**
+   * Generate a prompt for a card with full memory context assembly.
+   *
+   * This is the shared entry point for prompt generation — used by the MCP
+   * server tool handler and the agent daemon. It fetches the card, assembles
+   * relevant memories, and produces a role-framed prompt.
+   */
+  async generateCardPrompt(options: {
+    cardId: string;
+    workspaceId: string;
+    projectId?: string;
+    variant?: "analysis" | "draft" | "execute";
+    customConstraints?: string;
+    contextOptions?: Partial<{
+      includeSubtasks: boolean;
+      includeLinks: boolean;
+      includeDescription: boolean;
+    }>;
+  }): Promise<{
+    prompt: string;
+    variant: string;
+    category: string;
+    role: string;
+    contextSummary: {
+      hasDescription: boolean;
+      labelCount: number;
+      subtaskCount: number;
+      completedSubtasks: number;
+      linkedCardCount: number;
+      memoryCount: number;
+    };
+    tokenEstimate: number;
+    assemblyId?: string;
+    cardId: string;
+    shortId: number;
+    title: string;
+  }> {
+    const { assembleContext, cacheManifest, generatePrompt } =
+      await loadPromptModules();
+
+    // Fetch card data
+    const cardResult = await this.getCard(options.cardId);
+    const cardData = cardResult.card as CardPromptData;
+
+    // Try to get column info
+    let columnData: { name: string } | null = null;
+    const projectIdForBoard = options.projectId || cardData.project_id;
+    if (projectIdForBoard) {
+      try {
+        const board = await this.getBoard(projectIdForBoard, { summary: true });
+        const column = (
+          board.columns as Array<{ id: string; name: string }>
+        ).find((col) => col.id === cardData.column_id);
+        if (column) {
+          columnData = { name: column.name };
+        }
+      } catch {
+        // Column info not available, continue without it
+      }
+    }
+
+    const variant = options.variant || "execute";
+
+    // Assemble memory context
+    let assembledContextStr: string | undefined;
+    let assemblyId: string | undefined;
+    let memories: MemoryItem[] | undefined;
+
+    try {
+      if (options.workspaceId && cardData.title) {
+        const cardLabels = (cardData.labels || []).map((l) => l.name);
+        const taskContext = [cardData.title, cardData.description || ""]
+          .filter(Boolean)
+          .join(" ");
+
+        const assembled = await assembleContext({
+          workspaceId: options.workspaceId,
+          projectId: options.projectId,
+          taskContext,
+          cardLabels,
+          cardId: cardData.id,
+          client: this,
+        });
+
+        if (assembled.context) {
+          assembledContextStr = assembled.context;
+          assemblyId = assembled.manifest.assemblyId;
+          cacheManifest(assembled.manifest);
+        }
+      }
+    } catch (err) {
+      // Context assembly failed, try legacy fallback
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug(`[generateCardPrompt] Context assembly failed: ${msg}`);
+      try {
+        if (options.workspaceId && cardData.title) {
+          const memoryResult = await this.searchMemoryEntities(
+            options.workspaceId,
+            cardData.title,
+            {
+              project_id: options.projectId,
+              limit: 5,
+            },
+          );
+          if (memoryResult.entities?.length > 0) {
+            memories = (memoryResult.entities as MemoryItem[]).map((e) => ({
+              id: e.id,
+              type: e.type,
+              title: e.title,
+              content: e.content,
+              confidence: e.confidence,
+              tags: e.tags || [],
+            }));
+          }
+        }
+      } catch (fallbackErr) {
+        const fallbackMsg =
+          fallbackErr instanceof Error
+            ? fallbackErr.message
+            : String(fallbackErr);
+        console.debug(
+          `[generateCardPrompt] Memory fallback also failed: ${fallbackMsg}`,
+        );
+      }
+    }
+
+    const result = generatePrompt({
+      card: cardData,
+      column: columnData,
+      variant,
+      contextOptions: options.contextOptions,
+      customConstraints: options.customConstraints,
+      memories,
+      assembledContext: assembledContextStr,
+      assemblyId,
+    });
+
+    return {
+      ...result,
+      cardId: cardData.id,
+      shortId: cardData.short_id,
+      title: cardData.title,
+    };
+  }
+}
+
+// Shared types for generateCardPrompt to avoid inline assertions
+interface CardPromptData {
+  id: string;
+  short_id: number;
+  title: string;
+  description?: string | null;
+  priority: string;
+  due_date?: string | null;
+  done: boolean;
+  labels?: Array<{ name: string; color: string }>;
+  subtasks?: Array<{ title: string; completed: boolean }>;
+  links?: Array<{
+    target_card: { short_id: number; title: string };
+    display_type: string;
+    direction: "outgoing" | "incoming";
+  }>;
+  assignee?: { full_name?: string; email: string } | null;
+  column_id?: string;
+  project_id?: string;
+}
+
+interface MemoryItem {
+  id: string;
+  type: string;
+  title: string;
+  content: string;
+  confidence: number;
+  tags: string[];
+}
+
+// Cached dynamic imports for context-assembly and prompt-builder
+let _promptModules: {
+  assembleContext: Awaited<
+    typeof import("./context-assembly.js")
+  >["assembleContext"];
+  cacheManifest: Awaited<
+    typeof import("./context-assembly.js")
+  >["cacheManifest"];
+  generatePrompt: Awaited<
+    typeof import("./prompt-builder.js")
+  >["generatePrompt"];
+} | null = null;
+
+async function loadPromptModules() {
+  if (!_promptModules) {
+    const [ca, pb] = await Promise.all([
+      import("./context-assembly.js"),
+      import("./prompt-builder.js"),
+    ]);
+    _promptModules = {
+      assembleContext: ca.assembleContext,
+      cacheManifest: ca.cacheManifest,
+      generatePrompt: pb.generatePrompt,
+    };
+  }
+  return _promptModules;
 }
 
 // Singleton instance

package/src/auto-session.ts

@@ -4,6 +4,10 @@
  * Automatically detects agent session boundaries by monitoring tool calls.
  * Sessions auto-start when card-mutating tools are called, and auto-end
  * after 10 minutes of inactivity or when a different card is worked on.
+ *
+ * Agent identity is resolved from the MCP client's `initialize` handshake
+ * (clientInfo.name), so "Claude Code", "Cursor", "Codex", etc. are
+ * detected automatically — no hardcoded fallback needed.
  */
 
 import type { HarmonyApiClient } from "./api-client.js";
@@ -24,6 +28,43 @@ export type EndSessionCallback = (
   status: "completed" | "paused",
 ) => Promise<void>;
 
+/** MCP client identity from the `initialize` handshake */
+export interface ClientInfo {
+  name: string;
+  version?: string;
+}
+
+/** Well-known MCP client names → human-friendly display names */
+const CLIENT_DISPLAY_NAMES: Record<string, string> = {
+  "claude-code": "Claude Code",
+  "claude-desktop": "Claude Desktop",
+  cursor: "Cursor",
+  windsurf: "Windsurf",
+  cline: "Cline",
+  continue: "Continue",
+  "codex-cli": "OpenAI Codex",
+  zed: "Zed",
+  "gemini-cli": "Gemini CLI",
+};
+
+/** Derive a slug-style identifier from a client name */
+function toIdentifier(name: string): string {
+  return name.toLowerCase().replace(/\s+/g, "-");
+}
+
+/** Resolve agent identity from MCP client info */
+export function resolveAgentIdentity(info: ClientInfo | null): {
+  agentIdentifier: string;
+  agentName: string;
+} {
+  if (!info?.name) {
+    return { agentIdentifier: "unknown", agentName: "Unknown Agent" };
+  }
+  const key = toIdentifier(info.name);
+  const displayName = CLIENT_DISPLAY_NAMES[key] ?? info.name; // use raw name if not in map
+  return { agentIdentifier: key, agentName: displayName };
+}
+
 /** Tools that trigger auto-start of a session */
 export const AUTO_START_TRIGGERS = new Set([
   "harmony_generate_prompt",
@@ -42,18 +83,22 @@ const activeSessions = new Map<string, TrackedSession>();
 let inactivityTimer: ReturnType<typeof setInterval> | null = null;
 let endCallback: EndSessionCallback | null = null;
 let clientGetter: (() => HarmonyApiClient) | null = null;
+let clientInfoGetter: (() => ClientInfo | null) | null = null;
 
 /**
  * Initialize auto-session tracking.
  * @param callback Called when an auto-session ends (runs the learning pipeline)
  * @param getClient Function to get the current API client
+ * @param getClientInfo Function to get MCP client identity from the initialize handshake
  */
 export function initAutoSession(
   callback: EndSessionCallback,
   getClient: () => HarmonyApiClient,
+  getClientInfo?: () => ClientInfo | null,
 ): void {
   endCallback = callback;
   clientGetter = getClient;
+  clientInfoGetter = getClientInfo ?? null;
 
   if (inactivityTimer) clearInterval(inactivityTimer);
   inactivityTimer = setInterval(checkInactivity, CHECK_INTERVAL_MS);
@@ -95,11 +140,15 @@ export async function trackActivity(
     await autoEndSession(client, otherCardId, "completed");
   }
 
+  // Resolve agent identity from MCP client info
+  const info = clientInfoGetter?.() ?? null;
+  const { agentIdentifier, agentName } = resolveAgentIdentity(info);
+
   // Start a new auto-session
   try {
     await client.startAgentSession(cardId, {
-      agentIdentifier: "auto",
-      agentName: "Auto-detected Agent",
+      agentIdentifier,
+      agentName,
       status: "working",
     });
   } catch {
@@ -111,8 +160,8 @@ export async function trackActivity(
     startedAt: now,
     lastActivityAt: now,
     isExplicit: false,
-    agentIdentifier: "auto",
-    agentName: "Auto-detected Agent",
+    agentIdentifier,
+    agentName,
   });
 }
 
@@ -176,6 +225,7 @@ export function destroyAutoSession(): void {
   activeSessions.clear();
   endCallback = null;
   clientGetter = null;
+  clientInfoGetter = null;
 }
 
 /**

package/src/cli.ts

@@ -29,6 +29,11 @@ program
   .command("serve")
   .description("Start the MCP server (stdio transport)")
   .action(async () => {
+    if (!isConfigured()) {
+      console.error("No API key configured.");
+      console.error("Run: npx @gethmy/mcp setup");
+      process.exit(1);
+    }
     await refreshSkills();
     const server = new HarmonyMCPServer();
     await server.run();
@@ -147,6 +152,8 @@ program
   .option("-p, --project <id>", "Set project context")
   .option("--skip-context", "Skip workspace/project selection")
   .option("--skip-docs", "Skip project docs scaffold/verification")
+  .option("--new", "Create a new account (skip the choice prompt)")
+  .option("-n, --name <name>", "Full name (for account creation)")
   .action(async (options) => {
     await runSetup({
       force: options.force,
@@ -162,6 +169,8 @@ program
       projectId: options.project,
       skipContext: options.skipContext,
       skipDocs: options.skipDocs,
+      newAccount: options.new,
+      name: options.name,
     });
   });
 

package/src/onboard.ts

@@ -0,0 +1,93 @@
+import { requestWithBearer, signupUser } from "./api-client.js";
+import { getApiUrl } from "./config.js";
+
+export interface OnboardParams {
+  email: string;
+  password: string;
+  fullName: string;
+  workspaceName?: string;
+  projectName?: string;
+  template?: string;
+  keyName?: string;
+  apiUrl?: string;
+}
+
+export interface OnboardResult {
+  user: { id: string; email: string; full_name: string };
+  workspace: { id: string; name: string; slug: string; created_at: string };
+  project: { id: string; name: string; slug: string };
+  columns: unknown[];
+  apiKey: {
+    rawKey: string;
+    prefix: string;
+  };
+}
+
+export async function onboardNewUser(
+  params: OnboardParams,
+): Promise<OnboardResult> {
+  const {
+    email,
+    password,
+    fullName,
+    workspaceName = `${fullName}'s Workspace`,
+    projectName = "My First Board",
+    template = "kanban",
+    keyName = "mcp-agent",
+    apiUrl = getApiUrl(),
+  } = params;
+
+  // 1. Signup
+  const signupResult = await signupUser(apiUrl, {
+    email,
+    password,
+    full_name: fullName,
+  });
+  const token = signupResult.session.access_token;
+
+  // 2. Create workspace
+  const workspaceResult = await requestWithBearer<{
+    workspace: {
+      id: string;
+      name: string;
+      slug: string;
+      created_at: string;
+    };
+  }>(apiUrl, token, "POST", "/workspaces", {
+    name: workspaceName,
+  });
+
+  // 3. Create project
+  const projectResult = await requestWithBearer<{
+    project: { id: string; name: string; slug: string };
+    columns: unknown[];
+  }>(apiUrl, token, "POST", "/projects", {
+    workspaceId: workspaceResult.workspace.id,
+    name: projectName,
+    template,
+  });
+
+  // 4. Generate API key
+  const keyResult = await requestWithBearer<{
+    apiKey: {
+      id: string;
+      name: string;
+      prefix: string;
+      created_at: string;
+    };
+    rawKey: string;
+  }>(apiUrl, token, "POST", "/api-keys", {
+    name: keyName,
+  });
+
+  return {
+    user: signupResult.user,
+    workspace: workspaceResult.workspace,
+    project: projectResult.project,
+    columns: projectResult.columns,
+    apiKey: {
+      rawKey: keyResult.rawKey,
+      prefix: keyResult.apiKey.prefix,
+    },
+  };
+}

package/src/remote.ts

@@ -25,7 +25,8 @@ import { registerHandlers, type ToolDeps } from "./server.js";
 // ---------------------------------------------------------------------------
 // Config from env
 // ---------------------------------------------------------------------------
-const HARMONY_API_URL = process.env.HARMONY_API_URL || "https://app.gethmy.com/api";
+const HARMONY_API_URL =
+  process.env.HARMONY_API_URL || "https://app.gethmy.com/api";
 const PORT = parseInt(process.env.PORT || "3002", 10);
 
 // ---------------------------------------------------------------------------