@gethmy/mcp 1.0.0 → 2.1.0

package/dist/lib/server.js

@@ -0,0 +1,3132 @@
+import { discoverRelatedContext, evaluateLifecycle, syncFull, syncPull, syncPush, } from "@harmony/memory";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { detectContradictions, extractLearnings, extractMidSessionLearnings, } from "./active-learning.js";
+import { getClient, requestWithBearer, resetClient, signupUser, } from "./api-client.js";
+import { AUTO_START_TRIGGERS, destroyAutoSession, initAutoSession, markExplicit, shutdownAllSessions, trackActivity, untrack, } from "./auto-session.js";
+import { getActiveProjectId, getActiveWorkspaceId, getApiUrl, getMemoryDir, getUserEmail, isConfigured, saveConfig, setActiveProject, setActiveWorkspace, } from "./config.js";
+import { consolidateMemories } from "./consolidation.js";
+import { assembleContext, cacheManifest, computeRelevanceScore, getCachedManifest, mapToContextEntity, recordContextFeedback, trackSessionAssembly, } from "./context-assembly.js";
+import { autoExpandGraph } from "./graph-expansion.js";
+import { runLifecycleMaintenance } from "./lifecycle-maintenance.js";
+import { generatePrompt, } from "./prompt-builder.js";
+// Tool definitions
+const TOOLS = {
+    // Card operations
+    harmony_create_card: {
+        description: "Create a new card in a Kanban column",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Card title" },
+                columnId: {
+                    type: "string",
+                    description: "Target column ID (optional, defaults to first column)",
+                },
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional if context set)",
+                },
+                description: { type: "string", description: "Card description" },
+                priority: {
+                    type: "string",
+                    enum: ["low", "medium", "high", "urgent"],
+                    description: "Priority level",
+                },
+                assigneeId: { type: "string", description: "Assignee user ID" },
+            },
+            required: ["title"],
+        },
+    },
+    harmony_update_card: {
+        description: "Update an existing card",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cardId: { type: "string", description: "Card ID to update" },
+                title: { type: "string" },
+                description: { type: "string" },
+                priority: { type: "string", enum: ["low", "medium", "high", "urgent"] },
+                assigneeId: { type: "string", nullable: true },
+                dueDate: { type: "string", nullable: true },
+                done: { type: "boolean", description: "Mark card as done or not done" },
+            },
+            required: ["cardId"],
+        },
+    },
+    harmony_move_card: {
+        description: "Move a card to a different column or position",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cardId: { type: "string", description: "Card ID to move" },
+                columnId: { type: "string", description: "Target column ID" },
+                position: {
+                    type: "number",
+                    description: "Position in column (0-indexed)",
+                },
+            },
+            required: ["cardId", "columnId"],
+        },
+    },
+    harmony_archive_card: {
+        description: "Archive a card (soft-delete). Card can be restored later with unarchive.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cardId: { type: "string", description: "Card ID to archive" },
+            },
+            required: ["cardId"],
+        },
+    },
+    harmony_unarchive_card: {
+        description: "Restore an archived card back to the board.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cardId: { type: "string", description: "Card ID to unarchive" },
+            },
+            required: ["cardId"],
+        },
+    },
+    harmony_delete_card: {
+        description: "Delete a card",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cardId: { type: "string", description: "Card ID to delete" },
+            },
+            required: ["cardId"],
+        },
+    },
+    harmony_assign_card: {
+        description: "Assign a card to a team member",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cardId: { type: "string", description: "Card ID" },
+                assigneeId: {
+                    type: "string",
+                    nullable: true,
+                    description: "User ID (null to unassign)",
+                },
+            },
+            required: ["cardId"],
+        },
+    },
+    harmony_search_cards: {
+        description: "Search for cards by title or description",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query" },
+                projectId: { type: "string", description: "Limit to project" },
+            },
+            required: ["query"],
+        },
+    },
+    harmony_get_card: {
+        description: "Get detailed information about a specific card by UUID",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cardId: { type: "string", description: "Card UUID" },
+            },
+            required: ["cardId"],
+        },
+    },
+    harmony_get_card_by_short_id: {
+        description: "Get a card by its short ID (e.g., #42) within a project",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional if context set)",
+                },
+                shortId: {
+                    type: "number",
+                    description: "Short ID number (e.g., 42 for card #42)",
+                },
+            },
+            required: ["shortId"],
+        },
+    },
+    // Column operations
+    harmony_create_column: {
+        description: "Create a new column in a project",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Column name" },
+                projectId: { type: "string", description: "Project ID" },
+            },
+            required: ["name"],
+        },
+    },
+    harmony_update_column: {
+        description: "Update column properties",
+        inputSchema: {
+            type: "object",
+            properties: {
+                columnId: { type: "string", description: "Column ID" },
+                name: { type: "string" },
+            },
+            required: ["columnId"],
+        },
+    },
+    harmony_delete_column: {
+        description: "Delete a column (cards in it will be deleted)",
+        inputSchema: {
+            type: "object",
+            properties: {
+                columnId: { type: "string", description: "Column ID to delete" },
+            },
+            required: ["columnId"],
+        },
+    },
+    // Label operations
+    harmony_create_label: {
+        description: "Create a new label in a project",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Label name" },
+                color: { type: "string", description: "Hex color code" },
+                projectId: { type: "string", description: "Project ID" },
+            },
+            required: ["name", "color"],
+        },
+    },
+    harmony_add_label_to_card: {
+        description: "Add a label to a card",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cardId: { type: "string" },
+                labelId: { type: "string" },
+            },
+            required: ["cardId", "labelId"],
+        },
+    },
+    harmony_remove_label_from_card: {
+        description: "Remove a label from a card",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cardId: { type: "string" },
+                labelId: { type: "string" },
+            },
+            required: ["cardId", "labelId"],
+        },
+    },
+    // Card link operations
+    harmony_add_link_to_card: {
+        description: "Create a link between two cards. Link types: relates_to, blocks, duplicates, is_part_of",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sourceCardId: {
+                    type: "string",
+                    description: "The card creating the link from",
+                },
+                targetCardId: {
+                    type: "string",
+                    description: "The card being linked to",
+                },
+                linkType: {
+                    type: "string",
+                    enum: ["relates_to", "blocks", "duplicates", "is_part_of"],
+                    description: "Type of relationship: relates_to (generic), blocks (source blocks target), duplicates (source duplicates target), is_part_of (source is part of target)",
+                },
+            },
+            required: ["sourceCardId", "targetCardId", "linkType"],
+        },
+    },
+    harmony_remove_link_from_card: {
+        description: "Remove a link between cards",
+        inputSchema: {
+            type: "object",
+            properties: {
+                linkId: { type: "string", description: "The link ID to remove" },
+            },
+            required: ["linkId"],
+        },
+    },
+    harmony_get_card_links: {
+        description: "Get all links for a card",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cardId: { type: "string", description: "Card ID to get links for" },
+            },
+            required: ["cardId"],
+        },
+    },
+    // Subtask operations
+    harmony_create_subtask: {
+        description: "Create a subtask on a card",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cardId: { type: "string" },
+                title: { type: "string" },
+            },
+            required: ["cardId", "title"],
+        },
+    },
+    harmony_toggle_subtask: {
+        description: "Toggle subtask completion status",
+        inputSchema: {
+            type: "object",
+            properties: {
+                subtaskId: { type: "string" },
+            },
+            required: ["subtaskId"],
+        },
+    },
+    harmony_delete_subtask: {
+        description: "Delete a subtask",
+        inputSchema: {
+            type: "object",
+            properties: {
+                subtaskId: { type: "string" },
+            },
+            required: ["subtaskId"],
+        },
+    },
+    // Context operations
+    harmony_list_workspaces: {
+        description: "List all workspaces the user has access to",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    harmony_list_projects: {
+        description: "List all projects in a workspace",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+            },
+        },
+    },
+    harmony_get_board: {
+        description: "Get board state (columns, cards, labels). Use limit/offset for pagination on large boards. Use summary=true for just column counts without card details.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional if context set)",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max cards to return (default: 50)",
+                },
+                offset: {
+                    type: "number",
+                    description: "Skip N cards for pagination (default: 0)",
+                },
+                columnId: { type: "string", description: "Filter cards by column ID" },
+                summary: {
+                    type: "boolean",
+                    description: "Return only columns with card counts, no card details",
+                },
+                includeArchived: {
+                    type: "boolean",
+                    description: "Include archived cards in results (default: false). Archived cards are excluded by default.",
+                },
+            },
+        },
+    },
+    harmony_get_workspace_members: {
+        description: "Get members of a workspace",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+            },
+        },
+    },
+    harmony_set_workspace_context: {
+        description: "Set the active workspace context for subsequent operations",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string" },
+            },
+            required: ["workspaceId"],
+        },
+    },
+    harmony_set_project_context: {
+        description: "Set the active project context for subsequent operations",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: { type: "string" },
+            },
+            required: ["projectId"],
+        },
+    },
+    harmony_get_context: {
+        description: "Get the current active workspace and project context",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    // Natural language processing
+    harmony_process_command: {
+        description: 'Process a natural language command (e.g., "Create a card called Test in To Do")',
+        inputSchema: {
+            type: "object",
+            properties: {
+                command: { type: "string", description: "Natural language command" },
+                projectId: { type: "string", description: "Project context" },
+                workspaceId: { type: "string", description: "Workspace context" },
+                language: {
+                    type: "string",
+                    enum: ["en-US", "de-DE"],
+                    description: "Language (default: en-US)",
+                },
+                execute: {
+                    type: "boolean",
+                    description: "Execute the resolved action (default: false)",
+                },
+            },
+            required: ["command"],
+        },
+    },
+    // Agent context operations
+    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",
+                },
+                moveToColumn: {
+                    type: "string",
+                    description: 'Column name to move card to (e.g., "In Progress"). Case-insensitive partial match.',
+                },
+                addLabels: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: 'Label names to add to card (e.g., ["agent"]). Case-insensitive match.',
+                },
+            },
+            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", "waiting", "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",
+                },
+                moveToColumn: {
+                    type: "string",
+                    description: 'Column name to move card to after ending session (e.g., "Review"). Case-insensitive partial match.',
+                },
+            },
+            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"],
+        },
+    },
+    harmony_get_agent_profile: {
+        description: "Get aggregate performance profile for an agent. Shows total sessions, completion rate, average duration, and more. Defaults to the current agent if no identifier provided.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agentIdentifier: {
+                    type: "string",
+                    description: "Agent identifier (e.g., 'claude-code'). Defaults to current agent.",
+                },
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+            },
+        },
+    },
+    // Prompt generation
+    harmony_generate_prompt: {
+        description: "Generate an AI-ready prompt from a card. Automatically infers role and focus based on labels (bug, feature, design, etc.). Use this to create context-rich prompts for working on cards.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                cardId: {
+                    type: "string",
+                    description: "Card ID (UUID) to generate prompt from",
+                },
+                shortId: {
+                    type: "number",
+                    description: "Card short ID (e.g., 42 for #42) - alternative to cardId",
+                },
+                projectId: {
+                    type: "string",
+                    description: "Project ID (required if using shortId, optional if context set)",
+                },
+                variant: {
+                    type: "string",
+                    enum: ["analysis", "draft", "execute"],
+                    description: "Prompt variant: analysis (understand/plan), draft (design solution), execute (implement fully). Default: execute",
+                },
+                includeSubtasks: {
+                    type: "boolean",
+                    description: "Include subtasks in prompt (default: true)",
+                },
+                includeLinks: {
+                    type: "boolean",
+                    description: "Include linked cards in prompt (default: true)",
+                },
+                includeDescription: {
+                    type: "boolean",
+                    description: "Include description in prompt (default: true)",
+                },
+                customConstraints: {
+                    type: "string",
+                    description: "Additional instructions to append to the prompt",
+                },
+            },
+            required: [],
+        },
+    },
+    // Plan operations
+    // Memory / Knowledge Graph operations
+    harmony_remember: {
+        description: "Store a memory entity (knowledge, pattern, decision, error/solution pair, etc.) for persistence across sessions. Accepts markdown with YAML frontmatter or structured fields.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Memory title" },
+                content: {
+                    type: "string",
+                    description: "Memory content (markdown body)",
+                },
+                type: {
+                    type: "string",
+                    enum: [
+                        "agent",
+                        "task",
+                        "decision",
+                        "context",
+                        "pattern",
+                        "error",
+                        "solution",
+                        "preference",
+                        "relationship",
+                        "commitment",
+                        "lesson",
+                        "project",
+                        "handoff",
+                        "procedure",
+                    ],
+                    description: "Entity type (default: context)",
+                },
+                scope: {
+                    type: "string",
+                    enum: ["private", "project", "workspace", "global"],
+                    description: "Visibility scope (default: project). Private = only creator can see.",
+                },
+                tier: {
+                    type: "string",
+                    enum: ["draft", "episode", "reference"],
+                    description: "Memory tier: draft (working notes), episode (session summaries), reference (durable knowledge). Auto-inferred from type if not set.",
+                },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Tags for categorization and filtering",
+                },
+                confidence: {
+                    type: "number",
+                    description: "Confidence score 0-1 (default: 1.0)",
+                },
+                metadata: {
+                    type: "object",
+                    description: "Additional structured metadata",
+                },
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional, required if scope is 'project')",
+                },
+            },
+            required: ["title", "content"],
+        },
+    },
+    harmony_recall: {
+        description: "Retrieve memories by type, tags, scope, or text query. Returns matching knowledge entities.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                type: {
+                    type: "string",
+                    enum: [
+                        "agent",
+                        "task",
+                        "decision",
+                        "context",
+                        "pattern",
+                        "error",
+                        "solution",
+                        "preference",
+                        "relationship",
+                        "commitment",
+                        "lesson",
+                        "project",
+                        "handoff",
+                        "procedure",
+                    ],
+                    description: "Filter by entity type",
+                },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Filter by tags (matches any)",
+                },
+                scope: {
+                    type: "string",
+                    enum: ["private", "project", "workspace", "global"],
+                    description: "Filter by scope",
+                },
+                query: {
+                    type: "string",
+                    description: "Text query to filter by title",
+                },
+                minConfidence: {
+                    type: "number",
+                    description: "Minimum confidence threshold (0-1)",
+                },
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional)",
+                },
+                limit: { type: "number", description: "Max results (default: 20)" },
+            },
+        },
+    },
+    harmony_update_memory: {
+        description: "Update an existing memory entity. Can change title, content, tags, confidence, scope, type, or metadata.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                entityId: {
+                    type: "string",
+                    description: "Memory entity UUID to update",
+                },
+                title: { type: "string", description: "New title" },
+                content: { type: "string", description: "New content (markdown body)" },
+                type: {
+                    type: "string",
+                    enum: [
+                        "agent",
+                        "task",
+                        "decision",
+                        "context",
+                        "pattern",
+                        "error",
+                        "solution",
+                        "preference",
+                        "relationship",
+                        "commitment",
+                        "lesson",
+                        "project",
+                        "handoff",
+                        "procedure",
+                    ],
+                    description: "New entity type",
+                },
+                scope: {
+                    type: "string",
+                    enum: ["private", "project", "workspace", "global"],
+                    description: "New visibility scope",
+                },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "New tags (replaces existing)",
+                },
+                confidence: {
+                    type: "number",
+                    description: "New confidence score 0-1",
+                },
+                metadata: {
+                    type: "object",
+                    description: "New metadata (merged with existing)",
+                },
+            },
+            required: ["entityId"],
+        },
+    },
+    harmony_forget: {
+        description: "Archive or delete a memory entity by ID.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                entityId: {
+                    type: "string",
+                    description: "Memory entity UUID to delete",
+                },
+            },
+            required: ["entityId"],
+        },
+    },
+    harmony_relate: {
+        description: "Create a typed relationship between two memory entities. Relation types: learned_from, resolved_by, contradicts, supports, depends_on, part_of, caused_by, relates_to.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sourceId: {
+                    type: "string",
+                    description: "Source entity UUID",
+                },
+                targetId: {
+                    type: "string",
+                    description: "Target entity UUID",
+                },
+                relationType: {
+                    type: "string",
+                    enum: [
+                        "learned_from",
+                        "resolved_by",
+                        "contradicts",
+                        "supports",
+                        "depends_on",
+                        "part_of",
+                        "caused_by",
+                        "relates_to",
+                    ],
+                    description: "Type of relationship between entities",
+                },
+                confidence: {
+                    type: "number",
+                    description: "Relation confidence 0-1 (default: 1.0)",
+                },
+            },
+            required: ["sourceId", "targetId", "relationType"],
+        },
+    },
+    harmony_memory_search: {
+        description: "Full-text and semantic search across the knowledge base. Uses hybrid vector+FTS search (when embeddings are available) for best results. Returns entities ranked by relevance.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search query (full-text search)",
+                },
+                type: {
+                    type: "string",
+                    enum: [
+                        "agent",
+                        "task",
+                        "decision",
+                        "context",
+                        "pattern",
+                        "error",
+                        "solution",
+                        "preference",
+                        "relationship",
+                        "commitment",
+                        "lesson",
+                        "project",
+                        "handoff",
+                        "procedure",
+                    ],
+                    description: "Filter results by entity type",
+                },
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional)",
+                },
+                limit: { type: "number", description: "Max results (default: 20)" },
+            },
+            required: ["query"],
+        },
+    },
+    // Vault index
+    harmony_vault_index: {
+        description: "Get a compact index of all memory entities in the vault. Returns a markdown table with title, type, scope, confidence, tags, summary, and last updated date. Use this for quick overview of stored knowledge.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional, filters to project scope)",
+                },
+                type: {
+                    type: "string",
+                    enum: [
+                        "agent",
+                        "task",
+                        "decision",
+                        "context",
+                        "pattern",
+                        "error",
+                        "solution",
+                        "preference",
+                        "relationship",
+                        "commitment",
+                        "lesson",
+                        "project",
+                        "handoff",
+                        "procedure",
+                    ],
+                    description: "Filter by entity type",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max entities to return (default: 200)",
+                },
+            },
+            required: [],
+        },
+    },
+    // Wiki-link resolution
+    harmony_resolve_links: {
+        description: "Batch-scan all memory entities in a workspace/project for [[wiki-links]] and auto-create 'relates_to' relations. Use this to retroactively link existing entities.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional, limits scan to project)",
+                },
+            },
+            required: [],
+        },
+    },
+    // Memory sync
+    harmony_sync: {
+        description: "Synchronize local markdown memory files with the shared database. Pull downloads remote entities as .md files, push uploads local changes, full does both (pull first, then push). Server wins on conflicts.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                direction: {
+                    type: "string",
+                    enum: ["pull", "push", "full"],
+                    description: "Sync direction: pull (remote->local), push (local->remote), full (pull then push). Default: full",
+                },
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional, limits pull scope)",
+                },
+            },
+            required: [],
+        },
+    },
+    // Plan operations
+    harmony_list_plans: {
+        description: "List plans in a project. Search by name, filter by status or workflow phase. Returns recent plans ordered by last updated.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional if context set)",
+                },
+                search: {
+                    type: "string",
+                    description: "Search plans by title (partial match)",
+                },
+                status: {
+                    type: "string",
+                    enum: ["draft", "active", "archived"],
+                    description: "Filter by plan status",
+                },
+            },
+            required: [],
+        },
+    },
+    harmony_create_plan: {
+        description: "Create a new project plan. Use this to upload implementation plans created during planning. Returns a URL where the plan can be viewed and edited in Harmony.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional if context set)",
+                },
+                title: { type: "string", description: "Plan title" },
+                content: {
+                    type: "string",
+                    description: "Plan content in Markdown format",
+                },
+                source: {
+                    type: "string",
+                    enum: ["user", "agent", "imported"],
+                    description: "Plan source: agent for AI-generated plans (default: agent)",
+                },
+                tasks: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            content: { type: "string", description: "Task description" },
+                            priority: {
+                                type: "string",
+                                enum: ["high", "medium", "low"],
+                                description: "Task priority (default: medium)",
+                            },
+                            status: {
+                                type: "string",
+                                enum: ["pending", "in_progress", "completed"],
+                                description: "Task status (default: pending)",
+                            },
+                        },
+                        required: ["content"],
+                    },
+                    description: "Optional list of tasks to create with the plan",
+                },
+            },
+            required: ["title"],
+        },
+    },
+    harmony_get_plan: {
+        description: "Get a plan by ID or by card ID. Returns the plan content and all associated tasks.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                planId: { type: "string", description: "Plan ID (UUID)" },
+                cardId: {
+                    type: "string",
+                    description: "Card ID - get the plan linked to this card",
+                },
+            },
+            required: [],
+        },
+    },
+    harmony_update_plan: {
+        description: "Update an existing plan. Can update title, content, or status.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                planId: { type: "string", description: "Plan ID to update" },
+                title: { type: "string", description: "New title" },
+                content: {
+                    type: "string",
+                    description: "New content in Markdown format",
+                },
+                status: {
+                    type: "string",
+                    enum: ["draft", "active", "archived"],
+                    description: "New status",
+                },
+            },
+            required: ["planId"],
+        },
+    },
+    // Plan archival (deprecated: was harmony_advance_plan)
+    harmony_advance_plan: {
+        description: "Archive a plan. Plan progress is now derived from card states — this tool just archives the plan.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                planId: { type: "string", description: "Plan ID to archive" },
+                phase: {
+                    type: "string",
+                    enum: ["done"],
+                    description: "Only 'done' is supported (archives the plan)",
+                },
+                summary: {
+                    type: "string",
+                    description: "Optional summary stored as a memory entity.",
+                },
+            },
+            required: ["planId"],
+        },
+    },
+    // Memory lifecycle
+    harmony_prune_draft: {
+        description: "Remove stale draft memories that haven't been accessed recently. Runs in dry-run mode by default to preview what would be pruned.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional)",
+                },
+                dryRun: {
+                    type: "boolean",
+                    description: "Preview what would be pruned without deleting (default: true)",
+                },
+                maxAgeDays: {
+                    type: "number",
+                    description: "Maximum age in days for draft memories to keep (default: 30)",
+                },
+            },
+            required: [],
+        },
+    },
+    harmony_consolidate_memories: {
+        description: "Consolidate similar draft/episode memories into reference entities. Groups similar memories by embedding similarity and merges clusters. Use dryRun to preview before executing.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional)",
+                },
+                dryRun: {
+                    type: "boolean",
+                    description: "Preview what would be consolidated without creating entities (default: true)",
+                },
+                minClusterSize: {
+                    type: "number",
+                    description: "Minimum number of similar entities to form a cluster (default: 2)",
+                },
+            },
+            required: [],
+        },
+    },
+    // Context assembly
+    harmony_get_context_manifest: {
+        description: "Retrieve the context assembly manifest for a given assembly ID to debug what memories were loaded or excluded and why.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                assemblyId: {
+                    type: "string",
+                    description: "Assembly ID from a previous harmony_generate_prompt call",
+                },
+            },
+            required: ["assemblyId"],
+        },
+    },
+    // Debug & visualization
+    harmony_debug_context: {
+        description: "Explain why a specific memory was or wasn't included in context assembly for a given task. Returns relevance score breakdown.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                entityId: {
+                    type: "string",
+                    description: "Memory entity ID to analyze",
+                },
+                taskContext: {
+                    type: "string",
+                    description: "Task context (card title + description) to score against",
+                },
+                cardLabels: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Card labels for tag matching",
+                },
+            },
+            required: ["entityId", "taskContext"],
+        },
+    },
+    harmony_export_memory_graph: {
+        description: "Export the knowledge graph as DOT format for Graphviz visualization. Nodes are colored by tier (draft=yellow, episode=blue, reference=green).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional)",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max entities to include (default: 50)",
+                },
+            },
+            required: [],
+        },
+    },
+    // ============ ONBOARDING TOOLS ============
+    harmony_signup: {
+        description: "Create a new user account. Returns a JWT session for subsequent authenticated calls. No API key required.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                email: { type: "string", description: "User email address" },
+                password: {
+                    type: "string",
+                    description: "Password (min 8 characters)",
+                },
+                fullName: { type: "string", description: "User's full name" },
+            },
+            required: ["email", "password", "fullName"],
+        },
+    },
+    harmony_create_workspace: {
+        description: "Create a new workspace. Requires authentication.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Workspace name" },
+                description: { type: "string", description: "Workspace description" },
+            },
+            required: ["name"],
+        },
+    },
+    harmony_create_project: {
+        description: "Create a new project with template columns. Requires authentication.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID" },
+                name: { type: "string", description: "Project name" },
+                description: { type: "string", description: "Project description" },
+                color: { type: "string", description: "Project color" },
+                template: {
+                    type: "string",
+                    enum: ["kanban", "scrum", "simple"],
+                    description: "Column template: kanban (To Do/In Progress/Done), scrum (Backlog/Sprint/In Progress/Review/Done), simple (Todo/Done). Default: kanban",
+                },
+            },
+            required: ["workspaceId", "name"],
+        },
+    },
+    harmony_send_invitations: {
+        description: "Send workspace invitations to one or more email addresses. Requires admin/owner role.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID" },
+                emails: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Email addresses to invite",
+                },
+                role: {
+                    type: "string",
+                    enum: ["member", "admin"],
+                    description: "Role for invited users (default: member)",
+                },
+                sendEmail: {
+                    type: "boolean",
+                    description: "Send invitation email (default: false)",
+                },
+            },
+            required: ["workspaceId", "emails"],
+        },
+    },
+    harmony_generate_api_key: {
+        description: "Generate an API key for the authenticated user. The raw key is returned once and cannot be retrieved again.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Name for the API key (e.g., 'claude-code')",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    harmony_onboard: {
+        description: "Complete end-to-end onboarding: signup → workspace → project → API key. Saves the API key to config automatically. No prior configuration required.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                email: { type: "string", description: "User email address" },
+                password: {
+                    type: "string",
+                    description: "Password (min 8 characters)",
+                },
+                fullName: { type: "string", description: "User's full name" },
+                workspaceName: {
+                    type: "string",
+                    description: "Workspace name (default: derived from fullName)",
+                },
+                projectName: {
+                    type: "string",
+                    description: "Project name (default: 'My First Project')",
+                },
+                template: {
+                    type: "string",
+                    enum: ["kanban", "scrum", "simple"],
+                    description: "Column template (default: kanban)",
+                },
+                keyName: {
+                    type: "string",
+                    description: "API key name (default: 'mcp-agent')",
+                },
+            },
+            required: ["email", "password", "fullName"],
+        },
+    },
+    // Memory tier promotion
+    harmony_promote_memory: {
+        description: "Promote a memory entity to a higher tier: draft→episode or episode→reference. Tracks promotion reason and source.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                entityId: {
+                    type: "string",
+                    description: "Memory entity ID to promote",
+                },
+                targetTier: {
+                    type: "string",
+                    enum: ["episode", "reference"],
+                    description: "Target tier to promote to",
+                },
+                reason: {
+                    type: "string",
+                    description: "Reason for promotion (e.g., 'proven useful across 5+ sessions')",
+                },
+            },
+            required: ["entityId", "targetTier", "reason"],
+        },
+    },
+    // Vector embeddings
+    harmony_backfill_embeddings: {
+        description: "Generate vector embeddings for knowledge entities that are missing them. Run this after importing memories or when semantic search isn't finding expected results. Idempotent — only processes entities without embeddings.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+                batchSize: {
+                    type: "number",
+                    description: "Number of entities to process per batch (default: 50)",
+                },
+            },
+            required: [],
+        },
+    },
+    harmony_backfill_relations: {
+        description: "Retroactively create semantic relations across all existing memory entities. Iterates entities and runs graph expansion on each. Run after harmony_backfill_embeddings to connect a disconnected knowledge graph.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "Workspace ID (optional if context set)",
+                },
+                projectId: {
+                    type: "string",
+                    description: "Project ID (optional, limits to project)",
+                },
+                maxRelationsPerEntity: {
+                    type: "number",
+                    description: "Maximum relations to create per entity (default: 3)",
+                },
+            },
+            required: [],
+        },
+    },
+};
+// Resource URIs
+const RESOURCES = [
+    {
+        uri: "harmony://context",
+        name: "Current Context",
+        description: "Current active workspace and project",
+        mimeType: "application/json",
+    },
+];
+/**
+ * Reusable end-session pipeline: learning extraction, feedback scoring, lifecycle maintenance.
+ * Called by both explicit harmony_end_agent_session and auto-session timeout/card-switch.
+ */
+export async function runEndSessionPipeline(client, deps, cardId, sessionStatus, endProgressPercent, sessionData) {
+    let learningsExtracted = 0;
+    let feedbackAdjusted = 0;
+    let maintenanceResult;
+    // Fetch card details for learning extraction
+    let cardTitle = "";
+    let cardLabels = [];
+    let cardDescription = "";
+    let cardSubtasks = [];
+    try {
+        const { card } = await client.getCard(cardId);
+        const typedCard = card;
+        cardTitle = typedCard.title || "";
+        cardLabels = (typedCard.labels || []).map((l) => l.name);
+        cardDescription = typedCard.description || "";
+        cardSubtasks = (typedCard.subtasks || []).map((s) => ({
+            title: s.title,
+            done: s.done,
+        }));
+        // Remove "agent" label when session is completed (not paused)
+        if (sessionStatus === "completed" && typedCard.labels?.length) {
+            const agentLabel = typedCard.labels.find((l) => l.name.toLowerCase() === "agent");
+            if (agentLabel) {
+                await client.removeLabelFromCard(cardId, agentLabel.id);
+            }
+        }
+    }
+    catch {
+        // Card fetch failed, continue with defaults
+    }
+    // Active learning: extract memories from session
+    try {
+        let sessionDurationMs;
+        if (sessionData?.created_at) {
+            const startTime = new Date(sessionData.created_at).getTime();
+            if (!Number.isNaN(startTime)) {
+                sessionDurationMs = Date.now() - startTime;
+            }
+        }
+        const sessionContext = {
+            cardId,
+            cardTitle,
+            cardLabels,
+            agentIdentifier: sessionData?.agent_identifier || "unknown",
+            agentName: sessionData?.agent_name || "Unknown Agent",
+            status: sessionStatus,
+            progressPercent: endProgressPercent,
+            blockers: sessionData?.blockers || undefined,
+            currentTask: sessionData?.current_task || undefined,
+            sessionDurationMs,
+            cardDescription: cardDescription || undefined,
+            cardSubtasks: cardSubtasks.length > 0 ? cardSubtasks : undefined,
+        };
+        const learningResult = await extractLearnings(client, sessionContext);
+        learningsExtracted = learningResult.count;
+    }
+    catch {
+        // Learning extraction failed, non-fatal
+    }
+    // Agent performance profile: refresh materialized view + upsert knowledge entity
+    try {
+        const workspaceId = deps.getActiveWorkspaceId();
+        const agentId = sessionData?.agent_identifier || "unknown";
+        if (workspaceId && agentId !== "unknown") {
+            // Fire-and-forget: refresh + upsert agent profile entity
+            (async () => {
+                try {
+                    await client.refreshAgentProfiles(workspaceId);
+                    const { profile } = await client.getAgentProfile(workspaceId, agentId);
+                    if (profile) {
+                        const p = profile;
+                        const title = `Agent Profile: ${agentId}`;
+                        const content = [
+                            `## ${agentId} Performance Profile`,
+                            "",
+                            `- **Total sessions:** ${p.total_sessions}`,
+                            `- **Completed:** ${p.completed_sessions} (${p.completion_rate_pct}%)`,
+                            `- **Paused:** ${p.paused_sessions}`,
+                            `- **Blocked:** ${p.blocked_sessions}`,
+                            `- **Avg duration:** ${Math.round(Number(p.avg_active_duration_ms || 0) / 1000)}s`,
+                            `- **Avg progress:** ${p.avg_completion_progress}%`,
+                            `- **First session:** ${p.first_session_at}`,
+                            `- **Last session:** ${p.last_session_at}`,
+                        ].join("\n");
+                        // Find existing agent entity to update, or create new
+                        const existing = await client.listMemoryEntities({
+                            workspace_id: workspaceId,
+                            type: "agent",
+                            limit: 50,
+                        });
+                        const entities = (existing.entities || []);
+                        const match = entities.find((e) => e.title === title || e.agent_identifier === agentId);
+                        if (match) {
+                            await client.updateMemoryEntity(match.id, {
+                                content,
+                                confidence: 1.0,
+                                metadata: p,
+                            });
+                        }
+                        else {
+                            await client.createMemoryEntity({
+                                workspace_id: workspaceId,
+                                type: "agent",
+                                scope: "workspace",
+                                memory_tier: "reference",
+                                title,
+                                content,
+                                confidence: 1.0,
+                                tags: ["agent-profile", agentId],
+                                agent_identifier: agentId,
+                                metadata: p,
+                            });
+                        }
+                    }
+                }
+                catch {
+                    // Non-fatal: profile upsert failed
+                }
+            })();
+        }
+    }
+    catch {
+        // Non-fatal: agent profile refresh failed
+    }
+    // Feedback-driven scoring
+    try {
+        const feedbackResult = await recordContextFeedback(client, cardId, sessionStatus, endProgressPercent, (sessionData?.blockers?.length ?? 0) > 0);
+        feedbackAdjusted = feedbackResult.adjusted;
+    }
+    catch {
+        // Feedback recording failed, non-fatal
+    }
+    // Lifecycle maintenance
+    try {
+        const workspaceId = deps.getActiveWorkspaceId();
+        if (workspaceId) {
+            const projectId = deps.getActiveProjectId() || undefined;
+            maintenanceResult = await runLifecycleMaintenance(client, workspaceId, projectId);
+            // Auto-consolidation: if workspace has many draft/episode entities
+            const listResult = await client.listMemoryEntities({
+                workspace_id: workspaceId,
+                project_id: projectId,
+                limit: 100,
+            });
+            const draftEpisodeCount = (listResult.entities || []).filter((e) => e.memory_tier === "draft" || e.memory_tier === "episode").length;
+            if (draftEpisodeCount > 50) {
+                consolidateMemories(client, workspaceId, projectId, {
+                    dryRun: false,
+                    minClusterSize: 2,
+                }).catch(() => { });
+            }
+        }
+    }
+    catch {
+        // Lifecycle maintenance failed, non-fatal
+    }
+    return {
+        learningsExtracted,
+        feedbackAdjusted,
+        ...(maintenanceResult && { maintenance: maintenanceResult }),
+    };
+}
+/**
+ * Register MCP tool/resource handlers on a Server instance using the given deps.
+ * This is shared between stdio (HarmonyMCPServer) and remote (HTTP) transports.
+ */
+export function registerHandlers(server, deps) {
+    // List available tools
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: Object.entries(TOOLS).map(([name, tool]) => ({
+            name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        })),
+    }));
+    // Handle tool calls
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        // Auto-session pre-hook: track activity on card-related tools
+        const toolArgs = args || {};
+        const cardIdArg = toolArgs.cardId;
+        const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        if (cardIdArg && UUID_RE.test(cardIdArg) && deps.isConfigured()) {
+            const isAutoStartTrigger = AUTO_START_TRIGGERS.has(name);
+            trackActivity(cardIdArg, {
+                autoStart: isAutoStartTrigger,
+                client: deps.getClient(),
+            }).catch(() => { }); // fire-and-forget
+        }
+        try {
+            const result = await handleToolCall(name, toolArgs, deps);
+            // Auto-session post-hook: for generate_prompt resolved via shortId (no cardId in args)
+            if (name === "harmony_generate_prompt" &&
+                !cardIdArg &&
+                deps.isConfigured()) {
+                try {
+                    const parsed = typeof result === "object" && result !== null ? result : {};
+                    const resolvedCardId = parsed.cardId;
+                    if (resolvedCardId && UUID_RE.test(resolvedCardId)) {
+                        trackActivity(resolvedCardId, {
+                            autoStart: true,
+                            client: deps.getClient(),
+                        }).catch(() => { });
+                    }
+                }
+                catch {
+                    // Non-fatal
+                }
+            }
+            const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+            return {
+                content: [{ type: "text", text }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // List resources
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: RESOURCES,
+    }));
+    // Read resource
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        if (uri === "harmony://context") {
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: "application/json",
+                        text: JSON.stringify({
+                            configured: deps.isConfigured(),
+                            activeWorkspaceId: deps.getActiveWorkspaceId(),
+                            activeProjectId: deps.getActiveProjectId(),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        throw new Error(`Unknown resource: ${uri}`);
+    });
+}
+async function handleToolCall(name, args, deps) {
+    // Unauthenticated tools that don't require an API key
+    const unauthenticatedTools = ["harmony_signup", "harmony_onboard"];
+    if (!unauthenticatedTools.includes(name) && !deps.isConfigured()) {
+        throw new Error('Not configured. Run "npx @gethmy/mcp setup" to set your API key.\n' +
+            "You can generate an API key at https://gethmy.com → Settings → API Keys.\n" +
+            'Or use "harmony_onboard" to create an account and configure automatically.');
+    }
+    const client = deps.isConfigured()
+        ? deps.getClient()
+        : null;
+    // Helper to get project ID from args or context
+    const getProjectId = () => {
+        const id = args.projectId || deps.getActiveProjectId();
+        if (!id) {
+            throw new Error("No project specified. Use harmony_set_project_context or provide projectId.");
+        }
+        return id;
+    };
+    const getWorkspaceId = () => {
+        const id = args.workspaceId || deps.getActiveWorkspaceId();
+        if (!id) {
+            throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
+        }
+        return id;
+    };
+    switch (name) {
+        // Card operations
+        case "harmony_create_card": {
+            const title = z.string().min(1).max(500).parse(args.title);
+            const projectId = args.projectId || getProjectId();
+            const result = await client.createCard(projectId, {
+                title,
+                columnId: args.columnId,
+                description: args.description,
+                priority: args.priority,
+                assigneeId: args.assigneeId,
+            });
+            return { success: true, ...result };
+        }
+        case "harmony_update_card": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const result = await client.updateCard(cardId, {
+                title: args.title,
+                description: args.description,
+                priority: args.priority,
+                assigneeId: args.assigneeId,
+                dueDate: args.dueDate,
+                done: args.done,
+            });
+            return { success: true, ...result };
+        }
+        case "harmony_move_card": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const columnId = z.string().uuid().parse(args.columnId);
+            const position = args.position !== undefined
+                ? z.number().int().min(0).parse(args.position)
+                : undefined;
+            const result = await client.moveCard(cardId, columnId, position);
+            // Auto-end active agent session when moving to Review or Done
+            let sessionEnded = false;
+            try {
+                const { card } = result;
+                if (card?.project_id) {
+                    const board = await client.getBoard(card.project_id, {
+                        summary: true,
+                    });
+                    const columns = board.columns;
+                    const destCol = columns.find((c) => c.id === columnId);
+                    const colName = destCol?.name?.toLowerCase() || "";
+                    const isTerminal = destCol?.mark_cards_done ||
+                        colName === "done" ||
+                        colName === "completed" ||
+                        colName === "review";
+                    if (isTerminal) {
+                        const { session } = await client.getAgentSession(cardId);
+                        if (session) {
+                            await client.endAgentSession(cardId, { status: "completed" });
+                            untrack(cardId);
+                            sessionEnded = true;
+                        }
+                    }
+                }
+            }
+            catch {
+                // Non-fatal — the move already succeeded
+            }
+            return { success: true, sessionEnded, ...result };
+        }
+        case "harmony_archive_card": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const result = await client.archiveCard(cardId);
+            return { success: true, ...result };
+        }
+        case "harmony_unarchive_card": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const result = await client.unarchiveCard(cardId);
+            return { success: true, ...result };
+        }
+        case "harmony_delete_card": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            await client.deleteCard(cardId);
+            return { success: true };
+        }
+        case "harmony_assign_card": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const assigneeId = args.assigneeId
+                ? z.string().uuid().parse(args.assigneeId)
+                : null;
+            const result = await client.updateCard(cardId, { assigneeId });
+            return { success: true, ...result };
+        }
+        case "harmony_search_cards": {
+            const query = z.string().min(1).max(500).parse(args.query);
+            const result = await client.searchCards(query, {
+                projectId: args.projectId,
+            });
+            return { success: true, ...result, count: result.cards.length };
+        }
+        case "harmony_get_card": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const result = await client.getCard(cardId);
+            return { success: true, ...result };
+        }
+        case "harmony_get_card_by_short_id": {
+            const shortId = z.number().int().positive().parse(args.shortId);
+            const projectId = args.projectId || getProjectId();
+            const result = await client.getCardByShortId(projectId, shortId);
+            return { success: true, ...result };
+        }
+        // Column operations
+        case "harmony_create_column": {
+            const name = z.string().min(1).max(100).parse(args.name);
+            const projectId = args.projectId || getProjectId();
+            const result = await client.createColumn(projectId, name);
+            return { success: true, ...result };
+        }
+        case "harmony_update_column": {
+            const columnId = z.string().uuid().parse(args.columnId);
+            const name = z.string().min(1).max(100).parse(args.name);
+            const result = await client.updateColumn(columnId, name);
+            return { success: true, ...result };
+        }
+        case "harmony_delete_column": {
+            const columnId = z.string().uuid().parse(args.columnId);
+            await client.deleteColumn(columnId);
+            return { success: true };
+        }
+        // Label operations
+        case "harmony_create_label": {
+            const name = z.string().min(1).max(50).parse(args.name);
+            const color = z
+                .string()
+                .regex(/^#[0-9a-fA-F]{6}$/)
+                .parse(args.color);
+            const projectId = args.projectId || getProjectId();
+            // Check existing labels to avoid duplicates (case-insensitive)
+            const board = await client.getBoard(projectId, { summary: true });
+            const existing = board.labels.find((l) => l.name.toLowerCase() === name.toLowerCase());
+            if (existing) {
+                return { success: true, ...existing, deduplicated: true };
+            }
+            const result = await client.createLabel(projectId, { name, color });
+            return { success: true, ...result };
+        }
+        case "harmony_add_label_to_card": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const labelId = z.string().uuid().parse(args.labelId);
+            await client.addLabelToCard(cardId, labelId);
+            return { success: true };
+        }
+        case "harmony_remove_label_from_card": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const labelId = z.string().uuid().parse(args.labelId);
+            await client.removeLabelFromCard(cardId, labelId);
+            return { success: true };
+        }
+        // Card link operations
+        case "harmony_add_link_to_card": {
+            const sourceCardId = z.string().uuid().parse(args.sourceCardId);
+            const targetCardId = z.string().uuid().parse(args.targetCardId);
+            const linkType = z
+                .enum(["relates_to", "blocks", "duplicates", "is_part_of"])
+                .parse(args.linkType);
+            const result = await client.addLinkToCard(sourceCardId, targetCardId, linkType);
+            return { success: true, ...result };
+        }
+        case "harmony_remove_link_from_card": {
+            const linkId = z.string().uuid().parse(args.linkId);
+            await client.removeLinkFromCard(linkId);
+            return { success: true };
+        }
+        case "harmony_get_card_links": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const result = await client.getCardLinks(cardId);
+            return result;
+        }
+        // Subtask operations
+        case "harmony_create_subtask": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const title = z.string().min(1).max(500).parse(args.title);
+            const result = await client.createSubtask(cardId, title);
+            return { success: true, ...result };
+        }
+        case "harmony_toggle_subtask": {
+            const subtaskId = z.string().uuid().parse(args.subtaskId);
+            const result = await client.toggleSubtask(subtaskId);
+            return { success: true, ...result };
+        }
+        case "harmony_delete_subtask": {
+            const subtaskId = z.string().uuid().parse(args.subtaskId);
+            await client.deleteSubtask(subtaskId);
+            return { success: true };
+        }
+        // Context operations
+        case "harmony_list_workspaces": {
+            const result = await client.listWorkspaces();
+            return { success: true, ...result };
+        }
+        case "harmony_list_projects": {
+            const workspaceId = getWorkspaceId();
+            const result = await client.listProjects(workspaceId);
+            return { success: true, ...result };
+        }
+        case "harmony_get_board": {
+            const projectId = getProjectId();
+            const options = {};
+            // MCP tool arguments come as strings, parse numbers
+            if (args.limit !== undefined)
+                options.limit = Number(args.limit);
+            if (args.offset !== undefined)
+                options.offset = Number(args.offset);
+            if (args.columnId)
+                options.columnId = String(args.columnId);
+            if (args.summary === true || args.summary === "true")
+                options.summary = true;
+            if (args.includeArchived === true || args.includeArchived === "true")
+                options.includeArchived = true;
+            const result = await client.getBoard(projectId, options);
+            return { success: true, board: result };
+        }
+        case "harmony_get_workspace_members": {
+            const workspaceId = getWorkspaceId();
+            const result = await client.getWorkspaceMembers(workspaceId);
+            return { success: true, ...result };
+        }
+        case "harmony_set_workspace_context": {
+            const workspaceId = z.string().uuid().parse(args.workspaceId);
+            deps.setActiveWorkspace(workspaceId);
+            return { success: true, activeWorkspaceId: workspaceId };
+        }
+        case "harmony_set_project_context": {
+            const projectId = z.string().uuid().parse(args.projectId);
+            deps.setActiveProject(projectId);
+            return { success: true, activeProjectId: projectId };
+        }
+        case "harmony_get_context": {
+            return {
+                success: true,
+                context: {
+                    activeWorkspaceId: deps.getActiveWorkspaceId(),
+                    activeProjectId: deps.getActiveProjectId(),
+                },
+            };
+        }
+        // Natural language processing
+        case "harmony_process_command": {
+            const command = z.string().min(1).max(500).parse(args.command);
+            const result = await client.processNLU({
+                command,
+                projectId: args.projectId || deps.getActiveProjectId() || undefined,
+                workspaceId: args.workspaceId ||
+                    deps.getActiveWorkspaceId() ||
+                    undefined,
+                language: args.language || "en-US",
+                execute: args.execute === true,
+            });
+            return { success: true, ...result };
+        }
+        // Agent context operations
+        case "harmony_start_agent_session": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const agentIdentifier = z
+                .string()
+                .min(1)
+                .max(100)
+                .parse(args.agentIdentifier);
+            const agentName = z.string().min(1).max(100).parse(args.agentName);
+            const moveToColumn = args.moveToColumn;
+            const addLabels = args.addLabels;
+            let movedTo = null;
+            const labelsAdded = [];
+            // Handle card setup if moveToColumn or addLabels requested
+            if (moveToColumn || addLabels?.length) {
+                try {
+                    const { card } = await client.getCard(cardId);
+                    const projectId = card.project_id;
+                    if (projectId) {
+                        const board = await client.getBoard(projectId, {
+                            summary: true,
+                        });
+                        const columns = board.columns;
+                        const labels = board.labels;
+                        if (moveToColumn) {
+                            const col = columns.find((c) => c.name.toLowerCase().includes(moveToColumn.toLowerCase()));
+                            if (col) {
+                                await client.moveCard(cardId, col.id);
+                                movedTo = col.name;
+                            }
+                        }
+                        if (addLabels?.length) {
+                            for (const labelName of addLabels) {
+                                const label = labels.find((l) => l.name.toLowerCase() === labelName.toLowerCase());
+                                if (label) {
+                                    await client.addLabelToCard(cardId, label.id);
+                                    labelsAdded.push(label.name);
+                                }
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Setup failed, continue with session start
+                }
+            }
+            // Auto-assign to configured user if userEmail is set
+            let assignedTo = null;
+            const userEmail = deps.getUserEmail();
+            if (userEmail) {
+                try {
+                    const workspaceId = deps.getActiveWorkspaceId();
+                    if (workspaceId) {
+                        const { members } = await client.getWorkspaceMembers(workspaceId);
+                        const user = members.find((m) => m.email === userEmail);
+                        if (user) {
+                            await client.updateCard(cardId, { assigneeId: user.id });
+                            assignedTo = user.email;
+                        }
+                    }
+                }
+                catch {
+                    // Auto-assign failed, continue without assignment
+                }
+            }
+            const result = await client.startAgentSession(cardId, {
+                agentIdentifier,
+                agentName,
+                status: "working",
+                currentTask: args.currentTask,
+                estimatedMinutesRemaining: args.estimatedMinutesRemaining,
+            });
+            // Mark as explicit so auto-session won't interfere
+            markExplicit(cardId);
+            // Prefetch relevant context (non-blocking, best-effort)
+            let prefetchedMemoryIds = [];
+            try {
+                const workspaceId = deps.getActiveWorkspaceId();
+                if (workspaceId) {
+                    // Get card details for context
+                    const { card } = await client.getCard(cardId);
+                    const typedCard = card;
+                    const cardLabels = (typedCard.labels || []).map((l) => l.name);
+                    const taskContext = [
+                        typedCard.title || "",
+                        typedCard.description || "",
+                    ]
+                        .filter(Boolean)
+                        .join(" ");
+                    // Assemble context to find seed entities
+                    const assembled = await assembleContext({
+                        workspaceId,
+                        projectId: getActiveProjectId() || undefined,
+                        taskContext,
+                        cardLabels,
+                        cardId,
+                        tokenBudget: 2000, // Smaller budget for prefetch
+                        client,
+                    });
+                    prefetchedMemoryIds = assembled.memories.map((m) => m.id);
+                    // Track assembly for feedback loop
+                    if (assembled.manifest.assemblyId) {
+                        cacheManifest(assembled.manifest);
+                        trackSessionAssembly(cardId, assembled.manifest.assemblyId);
+                    }
+                    // Walk graph from seed entities to discover more context
+                    if (prefetchedMemoryIds.length > 0) {
+                        const graphResult = await discoverRelatedContext(client, prefetchedMemoryIds.slice(0, 5), // Limit seeds
+                        2, // 2 hops
+                        10);
+                        const additionalIds = graphResult.entities
+                            .map((e) => e.id)
+                            .filter((id) => !prefetchedMemoryIds.includes(id));
+                        prefetchedMemoryIds.push(...additionalIds);
+                    }
+                }
+            }
+            catch {
+                // Prefetch failed, non-fatal
+            }
+            return {
+                success: true,
+                assignedTo,
+                movedTo,
+                labelsAdded,
+                prefetchedMemoryCount: prefetchedMemoryIds.length,
+                ...result,
+            };
+        }
+        case "harmony_update_agent_progress": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const agentIdentifier = z
+                .string()
+                .min(1)
+                .max(100)
+                .parse(args.agentIdentifier);
+            const agentName = z.string().min(1).max(100).parse(args.agentName);
+            const progressPercent = args.progressPercent !== undefined
+                ? z.number().min(0).max(100).parse(args.progressPercent)
+                : undefined;
+            const result = await client.updateAgentProgress(cardId, {
+                agentIdentifier,
+                agentName,
+                status: args.status,
+                progressPercent,
+                currentTask: args.currentTask,
+                blockers: args.blockers,
+                estimatedMinutesRemaining: args.estimatedMinutesRemaining,
+            });
+            // Mid-session learning extraction (fire-and-forget)
+            let midSessionLearnings = 0;
+            try {
+                const { card } = await client.getCard(cardId);
+                const typedCard = card;
+                const midResult = await extractMidSessionLearnings(client, {
+                    cardId,
+                    cardTitle: typedCard.title || "",
+                    agentIdentifier,
+                    agentName,
+                    currentTask: args.currentTask,
+                    status: args.status,
+                    blockers: args.blockers,
+                    progressPercent,
+                });
+                midSessionLearnings = midResult.count;
+            }
+            catch {
+                // Non-fatal: mid-session learning extraction failure
+            }
+            return { success: true, midSessionLearnings, ...result };
+        }
+        case "harmony_end_agent_session": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const moveToColumn = args.moveToColumn;
+            const sessionStatus = args.status || "completed";
+            const endProgressPercent = args.progressPercent !== undefined
+                ? z.number().min(0).max(100).parse(args.progressPercent)
+                : undefined;
+            const result = await client.endAgentSession(cardId, {
+                status: sessionStatus,
+                progressPercent: endProgressPercent,
+            });
+            // Remove from auto-session tracking
+            untrack(cardId);
+            let movedTo = null;
+            const _learningsExtracted = 0;
+            // Get card info for move and learning extraction
+            let _cardTitle = "";
+            let _cardLabels = [];
+            let _cardDescription = "";
+            let _cardSubtasks = [];
+            try {
+                const { card } = await client.getCard(cardId);
+                const typedCard = card;
+                _cardTitle = typedCard.title || "";
+                _cardLabels = (typedCard.labels || []).map((l) => l.name);
+                _cardDescription = typedCard.description || "";
+                _cardSubtasks = (typedCard.subtasks || []).map((s) => ({
+                    title: s.title,
+                    done: s.done,
+                }));
+                const projectId = typedCard.project_id;
+                // Remove "agent" label when session is completed (not paused)
+                if (sessionStatus === "completed" && typedCard.labels?.length) {
+                    const agentLabel = typedCard.labels.find((l) => l.name.toLowerCase() === "agent");
+                    if (agentLabel) {
+                        await client.removeLabelFromCard(cardId, agentLabel.id);
+                    }
+                }
+                if (moveToColumn && projectId) {
+                    const board = await client.getBoard(projectId, {
+                        summary: true,
+                    });
+                    const columns = board.columns;
+                    const col = columns.find((c) => c.name.toLowerCase().includes(moveToColumn.toLowerCase()));
+                    if (col) {
+                        await client.moveCard(cardId, col.id);
+                        movedTo = col.name;
+                    }
+                }
+            }
+            catch {
+                // Card fetch/move failed, continue
+            }
+            // Run shared end-session pipeline (learning, feedback, maintenance)
+            const sessionObj = result.session;
+            const pipelineResult = await runEndSessionPipeline(client, deps, cardId, sessionStatus, endProgressPercent, sessionObj);
+            return {
+                success: true,
+                movedTo,
+                learningsExtracted: pipelineResult.learningsExtracted,
+                feedbackAdjusted: pipelineResult.feedbackAdjusted,
+                ...(pipelineResult.maintenance &&
+                    (pipelineResult.maintenance.archived > 0 ||
+                        pipelineResult.maintenance.pruned > 0 ||
+                        pipelineResult.maintenance.promoted > 0) && {
+                    maintenance: pipelineResult.maintenance,
+                }),
+                ...result,
+            };
+        }
+        case "harmony_get_agent_session": {
+            const cardId = z.string().uuid().parse(args.cardId);
+            const result = await client.getAgentSession(cardId, {
+                includeEnded: args.includeEnded === true || args.includeEnded === "true",
+            });
+            return { success: true, ...result };
+        }
+        case "harmony_get_agent_profile": {
+            const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
+            if (!workspaceId) {
+                return {
+                    success: false,
+                    error: "No workspace context. Provide workspaceId or set context.",
+                };
+            }
+            const agentIdentifier = args.agentIdentifier || "claude-code";
+            const result = await client.getAgentProfile(workspaceId, agentIdentifier);
+            return { success: true, ...result };
+        }
+        // Prompt generation
+        case "harmony_generate_prompt": {
+            // Get card - either by UUID or short ID
+            let cardData;
+            let columnData = null;
+            if (args.cardId) {
+                const cardId = z.string().uuid().parse(args.cardId);
+                const cardResult = await client.getCard(cardId);
+                cardData = cardResult.card;
+            }
+            else if (args.shortId !== undefined) {
+                const shortId = z.number().int().positive().parse(args.shortId);
+                const projectId = args.projectId || deps.getActiveProjectId();
+                if (!projectId) {
+                    throw new Error("Project ID required when using shortId. Use harmony_set_project_context or provide projectId.");
+                }
+                const cardResult = await client.getCardByShortId(projectId, shortId);
+                cardData = cardResult.card;
+            }
+            else {
+                throw new Error("Either cardId or shortId must be provided");
+            }
+            // Try to get column info from board
+            const projectIdForBoard = args.projectId ||
+                getActiveProjectId() ||
+                cardData.project_id;
+            if (projectIdForBoard) {
+                try {
+                    const board = await client.getBoard(projectIdForBoard, {
+                        summary: true,
+                    });
+                    const columnId = cardData
+                        .column_id;
+                    const column = board.columns.find((col) => col.id === columnId);
+                    if (column) {
+                        columnData = { name: column.name };
+                    }
+                }
+                catch {
+                    // Column info not available, continue without it
+                }
+            }
+            const variant = args.variant || "execute";
+            const contextOptions = {};
+            if (args.includeSubtasks !== undefined) {
+                contextOptions.includeSubtasks =
+                    args.includeSubtasks === true || args.includeSubtasks === "true";
+            }
+            if (args.includeLinks !== undefined) {
+                contextOptions.includeLinks =
+                    args.includeLinks === true || args.includeLinks === "true";
+            }
+            if (args.includeDescription !== undefined) {
+                contextOptions.includeDescription =
+                    args.includeDescription === true ||
+                        args.includeDescription === "true";
+            }
+            // Assemble context using the context assembly engine
+            let assembledContextStr;
+            let assemblyId;
+            let memories;
+            try {
+                const workspaceId = deps.getActiveWorkspaceId();
+                if (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,
+                        projectId: getActiveProjectId() || undefined,
+                        taskContext,
+                        cardLabels,
+                        cardId: cardData.id,
+                        client,
+                    });
+                    if (assembled.context) {
+                        assembledContextStr = assembled.context;
+                        assemblyId = assembled.manifest.assemblyId;
+                        cacheManifest(assembled.manifest);
+                    }
+                }
+            }
+            catch {
+                // Context assembly failed, try legacy fallback
+                try {
+                    const workspaceId = deps.getActiveWorkspaceId();
+                    if (workspaceId && cardData.title) {
+                        const memoryResult = await client.searchMemoryEntities(workspaceId, cardData.title, {
+                            project_id: getActiveProjectId() || undefined,
+                            limit: 5,
+                        });
+                        if (memoryResult.entities?.length > 0) {
+                            memories = memoryResult.entities.map((e) => {
+                                const entity = e;
+                                return {
+                                    id: entity.id,
+                                    type: entity.type,
+                                    title: entity.title,
+                                    content: entity.content,
+                                    confidence: entity.confidence,
+                                    tags: entity.tags || [],
+                                };
+                            });
+                        }
+                    }
+                }
+                catch {
+                    // Memory fetch also failed, continue without memories
+                }
+            }
+            const result = generatePrompt({
+                card: cardData,
+                column: columnData,
+                variant,
+                contextOptions,
+                customConstraints: args.customConstraints,
+                memories,
+                assembledContext: assembledContextStr,
+                assemblyId,
+            });
+            return {
+                success: true,
+                cardId: cardData.id,
+                shortId: cardData.short_id,
+                title: cardData.title,
+                ...result,
+            };
+        }
+        // Memory / Knowledge Graph operations
+        case "harmony_remember": {
+            const title = z.string().min(1).max(300).parse(args.title);
+            const content = z.string().min(1).max(50000).parse(args.content);
+            const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
+            if (!workspaceId) {
+                throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
+            }
+            const entityType = args.type || "context";
+            const entityTags = args.tags || [];
+            const result = await client.createMemoryEntity({
+                workspace_id: workspaceId,
+                project_id: args.projectId || deps.getActiveProjectId() || undefined,
+                type: entityType,
+                scope: args.scope || "project",
+                memory_tier: args.tier || undefined,
+                title,
+                content,
+                metadata: args.metadata,
+                confidence: args.confidence !== undefined
+                    ? z.number().min(0).max(1).parse(args.confidence)
+                    : undefined,
+                tags: entityTags.length > 0 ? entityTags : undefined,
+                agent_identifier: "claude-code",
+            });
+            // Fire-and-forget graph expansion: link new entity to semantically similar ones
+            const newEntityIdForGraph = result.entity?.id;
+            if (newEntityIdForGraph) {
+                autoExpandGraph(client, newEntityIdForGraph, title, content, entityTags, workspaceId, args.projectId || deps.getActiveProjectId() || undefined).catch(() => { });
+            }
+            // Semantic contradiction detection (uses hybrid search instead of naive type+tag matching)
+            let potentialContradictions = [];
+            const newEntityId = result.entity?.id;
+            if (newEntityId) {
+                try {
+                    potentialContradictions = await detectContradictions(client, newEntityId, entityType, title, content, entityTags, workspaceId, args.projectId ||
+                        deps.getActiveProjectId() ||
+                        undefined);
+                }
+                catch {
+                    // Don't block creation if contradiction detection fails
+                }
+            }
+            return {
+                success: true,
+                ...result,
+                ...(potentialContradictions.length > 0 && {
+                    potentialContradictions: potentialContradictions.map((c) => ({
+                        id: c.entityId,
+                        title: c.title,
+                        tags: c.tags,
+                    })),
+                    contradictionNote: `Found ${potentialContradictions.length} semantically similar memor${potentialContradictions.length === 1 ? "y" : "ies"} of same type that may contradict. 'contradicts' relations created automatically. Review these to resolve or confirm.`,
+                }),
+            };
+        }
+        case "harmony_recall": {
+            const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
+            if (!workspaceId) {
+                throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
+            }
+            const queryOpts = {
+                workspace_id: workspaceId,
+                project_id: args.projectId || deps.getActiveProjectId() || undefined,
+                type: args.type,
+                scope: args.scope,
+                tags: args.tags,
+                min_confidence: args.minConfidence,
+                q: args.query,
+                limit: args.limit,
+            };
+            // Fetch both markdown (for display) and JSON (for lifecycle evaluation) in parallel
+            const [markdown, { entities }] = await Promise.all([
+                client.listMemoryEntitiesMarkdown(queryOpts),
+                client.listMemoryEntities(queryOpts),
+            ]);
+            // Evaluate lifecycle and auto-promote eligible entities (fire-and-forget)
+            if (entities.length > 0) {
+                Promise.all(entities.map(async (entity) => {
+                    if (!entity.memory_tier || !entity.created_at)
+                        return;
+                    try {
+                        // Touch access count via API (triggers server-side touch_knowledge_entity)
+                        await client.updateMemoryEntity(entity.id, {
+                            metadata: {
+                                ...(entity.metadata || {}),
+                                _last_recall: new Date().toISOString(),
+                            },
+                        });
+                        const lifecycle = evaluateLifecycle({
+                            memory_tier: entity.memory_tier,
+                            confidence: entity.confidence ?? 1.0,
+                            access_count: entity.access_count ?? 0,
+                            last_accessed_at: entity.last_accessed_at,
+                            created_at: entity.created_at,
+                        });
+                        if (lifecycle.promotion.eligible &&
+                            lifecycle.promotion.targetTier) {
+                            await client.updateMemoryEntity(entity.id, {
+                                memory_tier: lifecycle.promotion.targetTier,
+                                metadata: {
+                                    ...(entity.metadata || {}),
+                                    promoted_at: new Date().toISOString(),
+                                    promotion_reason: lifecycle.promotion.reason,
+                                },
+                            });
+                        }
+                    }
+                    catch (_) {
+                        // Non-critical: don't fail recall if promotion check fails
+                    }
+                })).catch(() => { });
+            }
+            return markdown || "No memories found.";
+        }
+        case "harmony_update_memory": {
+            const entityId = z.string().uuid().parse(args.entityId);
+            const updates = {};
+            if (args.title !== undefined)
+                updates.title = z.string().min(1).max(300).parse(args.title);
+            if (args.content !== undefined)
+                updates.content = z.string().max(50000).parse(args.content);
+            if (args.type !== undefined)
+                updates.type = args.type;
+            if (args.scope !== undefined)
+                updates.scope = args.scope;
+            if (args.tags !== undefined)
+                updates.tags = args.tags;
+            if (args.confidence !== undefined)
+                updates.confidence = z.number().min(0).max(1).parse(args.confidence);
+            if (args.metadata !== undefined)
+                updates.metadata = args.metadata;
+            const result = await client.updateMemoryEntity(entityId, updates);
+            return { success: true, ...result };
+        }
+        case "harmony_forget": {
+            const entityId = z.string().uuid().parse(args.entityId);
+            await client.deleteMemoryEntity(entityId);
+            return { success: true };
+        }
+        case "harmony_relate": {
+            const sourceId = z.string().uuid().parse(args.sourceId);
+            const targetId = z.string().uuid().parse(args.targetId);
+            const relationType = z
+                .enum([
+                "learned_from",
+                "resolved_by",
+                "contradicts",
+                "supports",
+                "depends_on",
+                "part_of",
+                "caused_by",
+                "relates_to",
+            ])
+                .parse(args.relationType);
+            const result = await client.createMemoryRelation({
+                source_id: sourceId,
+                target_id: targetId,
+                relation_type: relationType,
+                confidence: args.confidence !== undefined
+                    ? z.number().min(0).max(1).parse(args.confidence)
+                    : undefined,
+            });
+            return { success: true, ...result };
+        }
+        case "harmony_memory_search": {
+            const query = z.string().min(1).max(500).parse(args.query);
+            const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
+            if (!workspaceId) {
+                throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
+            }
+            const markdown = await client.searchMemoryEntitiesMarkdown(workspaceId, query, {
+                project_id: args.projectId ||
+                    deps.getActiveProjectId() ||
+                    undefined,
+                type: args.type,
+                limit: args.limit,
+            });
+            return markdown || "No memories found.";
+        }
+        // Vault index
+        case "harmony_vault_index": {
+            const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
+            if (!workspaceId) {
+                throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
+            }
+            const markdown = await client.getVaultIndexMarkdown({
+                workspace_id: workspaceId,
+                project_id: args.projectId || deps.getActiveProjectId() || undefined,
+                type: args.type,
+                limit: args.limit,
+            });
+            return markdown || "No entities found.";
+        }
+        // Wiki-link resolution
+        case "harmony_resolve_links": {
+            const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
+            if (!workspaceId) {
+                throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
+            }
+            const result = await client.resolveLinks({
+                workspace_id: workspaceId,
+                project_id: args.projectId || deps.getActiveProjectId() || undefined,
+            });
+            return {
+                success: true,
+                ...result,
+                message: `Resolved ${result.resolved} wiki-links, ${result.unresolved} remain unresolved.`,
+            };
+        }
+        // Memory sync
+        case "harmony_sync": {
+            const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
+            if (!workspaceId) {
+                throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
+            }
+            const direction = args.direction || "full";
+            const syncProjectId = args.projectId || deps.getActiveProjectId() || undefined;
+            const memoryDir = deps.getMemoryDir();
+            if (!memoryDir) {
+                return {
+                    success: true,
+                    message: "Memory sync requires local filesystem access. Not available in remote mode.",
+                };
+            }
+            const syncConfig = { memoryDir };
+            let syncResult;
+            switch (direction) {
+                case "pull":
+                    syncResult = await syncPull(client, syncConfig, workspaceId, syncProjectId);
+                    break;
+                case "push":
+                    syncResult = await syncPush(client, syncConfig, workspaceId);
+                    break;
+                default:
+                    syncResult = await syncFull(client, syncConfig, workspaceId, syncProjectId);
+            }
+            const parts = [];
+            if (syncResult.pulled > 0)
+                parts.push(`${syncResult.pulled} pulled`);
+            if (syncResult.pushed > 0)
+                parts.push(`${syncResult.pushed} pushed`);
+            if (syncResult.deleted > 0)
+                parts.push(`${syncResult.deleted} deleted`);
+            if (syncResult.conflicts > 0)
+                parts.push(`${syncResult.conflicts} conflicts (server wins)`);
+            const summary = parts.length > 0 ? parts.join(", ") : "Already in sync";
+            return {
+                success: syncResult.errors.length === 0,
+                ...syncResult,
+                memoryDir: syncConfig.memoryDir,
+                message: summary,
+            };
+        }
+        // Plan operations
+        case "harmony_list_plans": {
+            const projectId = args.projectId || getProjectId();
+            const result = await client.listPlans(projectId, {
+                search: args.search,
+                status: args.status,
+            });
+            return {
+                success: true,
+                plans: result.plans,
+                count: result.plans.length,
+            };
+        }
+        case "harmony_create_plan": {
+            const title = z.string().min(1).max(200).parse(args.title);
+            const projectId = args.projectId || getProjectId();
+            const result = await client.createPlan(projectId, {
+                title,
+                content: args.content,
+                source: args.source || "agent",
+                tasks: args.tasks,
+            });
+            // Build URL for viewing the plan
+            const planUrl = `https://gethmy.com/plans/${result.plan.id}`;
+            return {
+                success: true,
+                planId: result.plan.id,
+                planUrl,
+                plan: result.plan,
+                tasks: result.tasks,
+            };
+        }
+        case "harmony_get_plan": {
+            let result = null;
+            if (args.planId) {
+                const planId = z.string().uuid().parse(args.planId);
+                result = await client.getPlan(planId);
+            }
+            else if (args.cardId) {
+                const cardId = z.string().uuid().parse(args.cardId);
+                result = await client.getPlanByCardId(cardId);
+                if (!result) {
+                    return {
+                        success: true,
+                        plan: null,
+                        tasks: [],
+                        message: "No plan linked to this card",
+                    };
+                }
+            }
+            else {
+                throw new Error("Either planId or cardId must be provided");
+            }
+            return {
+                success: true,
+                plan: result.plan,
+                tasks: result.tasks,
+            };
+        }
+        case "harmony_update_plan": {
+            const planId = z.string().uuid().parse(args.planId);
+            const updates = {};
+            if (args.title !== undefined)
+                updates.title = z.string().min(1).max(200).parse(args.title);
+            if (args.content !== undefined)
+                updates.content = args.content;
+            if (args.status !== undefined) {
+                updates.status = z
+                    .enum(["draft", "active", "archived"])
+                    .parse(args.status);
+            }
+            const result = await client.updatePlan(planId, updates);
+            return { success: true, plan: result.plan };
+        }
+        case "harmony_advance_plan": {
+            // Simplified: just archive the plan
+            const planId = z.string().uuid().parse(args.planId);
+            const summary = args.summary;
+            const planResult = await client.getPlan(planId);
+            const plan = planResult.plan;
+            await client.updatePlan(planId, { status: "archived" });
+            const results = {};
+            const workspaceId = deps.getActiveWorkspaceId() || "";
+            if (summary && workspaceId) {
+                try {
+                    const memResult = await client.createMemoryEntity({
+                        title: `Lesson: ${plan.title}`,
+                        content: summary,
+                        type: "lesson",
+                        scope: "project",
+                        workspaceId,
+                        projectId: plan.project_id,
+                        tags: ["plan", "archived"],
+                        confidence: 0.8,
+                    });
+                    results.memoryEntityId = memResult.entity?.id;
+                    if (results.memoryEntityId) {
+                        const title = `Lesson: ${plan.title}`;
+                        const tags = ["plan", "archived"];
+                        autoExpandGraph(client, results.memoryEntityId, title, summary, tags, workspaceId, plan.project_id).catch(() => { });
+                        detectContradictions(client, results.memoryEntityId, "lesson", title, summary, tags, workspaceId, plan.project_id).catch(() => { });
+                    }
+                }
+                catch (_) {
+                    /* best-effort */
+                }
+            }
+            return {
+                success: true,
+                newStatus: "archived",
+                ...results,
+            };
+        }
+        case "harmony_debug_context": {
+            const entityId = z.string().uuid().parse(args.entityId);
+            const taskContext = z.string().min(1).max(2000).parse(args.taskContext);
+            const cardLabels = args.cardLabels || [];
+            // Fetch the entity
+            const entityResult = await client.getMemoryEntity(entityId);
+            const entity = mapToContextEntity(entityResult.entity);
+            // Compute relevance score
+            const { score, reasons } = computeRelevanceScore(entity, taskContext, cardLabels);
+            // Compute lifecycle status
+            const lifecycle = evaluateLifecycle({
+                memory_tier: entity.memory_tier,
+                confidence: entity.confidence,
+                access_count: entity.access_count,
+                last_accessed_at: entity.last_accessed_at,
+                created_at: entity.updated_at, // using updated_at as proxy
+            });
+            return {
+                success: true,
+                entity: {
+                    id: entity.id,
+                    title: entity.title,
+                    type: entity.type,
+                    tier: entity.memory_tier,
+                    confidence: entity.confidence,
+                    accessCount: entity.access_count,
+                },
+                relevance: {
+                    score: Math.round(score * 1000) / 1000,
+                    reasons,
+                    wouldBeIncluded: score >= 0.1,
+                    threshold: 0.1,
+                },
+                lifecycle: {
+                    decayScore: Math.round(lifecycle.decay.score * 1000) / 1000,
+                    daysSinceAccess: Math.round(lifecycle.decay.daysSinceAccess),
+                    promotionEligible: lifecycle.promotion.eligible,
+                    promotionTarget: lifecycle.promotion.targetTier,
+                    shouldArchive: lifecycle.shouldArchive,
+                    shouldFlagForReview: lifecycle.shouldFlagForReview,
+                },
+                suggestions: [
+                    ...(lifecycle.promotion.eligible
+                        ? [
+                            `Eligible for promotion to ${lifecycle.promotion.targetTier}: ${lifecycle.promotion.reason}`,
+                        ]
+                        : []),
+                    ...(lifecycle.shouldArchive
+                        ? [`Consider archiving: ${lifecycle.archiveReason}`]
+                        : []),
+                    ...(lifecycle.shouldFlagForReview
+                        ? [`Flagged for review: ${lifecycle.reviewReason}`]
+                        : []),
+                    ...(score < 0.1
+                        ? [
+                            "Below relevance threshold - consider adding more specific tags or updating content",
+                        ]
+                        : []),
+                ],
+            };
+        }
+        case "harmony_export_memory_graph": {
+            const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
+            if (!workspaceId) {
+                throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
+            }
+            const projectId = args.projectId || deps.getActiveProjectId() || undefined;
+            const limit = args.limit || 50;
+            // Fetch entities
+            const result = await client.listMemoryEntities({
+                workspace_id: workspaceId,
+                project_id: projectId,
+                limit,
+            });
+            const entities = (result.entities || []);
+            // Build DOT graph
+            const tierColors = {
+                draft: "#FFEB3B", // yellow
+                episode: "#2196F3", // blue
+                reference: "#4CAF50", // green
+            };
+            const typeShapes = {
+                error: "octagon",
+                solution: "diamond",
+                pattern: "hexagon",
+                decision: "house",
+                lesson: "ellipse",
+                preference: "parallelogram",
+            };
+            const lines = [
+                "digraph KnowledgeGraph {",
+                "  rankdir=LR;",
+                "  node [style=filled, fontsize=10];",
+                "",
+            ];
+            // Add nodes
+            for (const entity of entities) {
+                const tier = entity.memory_tier || "reference";
+                const color = tierColors[tier] || "#9E9E9E";
+                const shape = typeShapes[entity.type] || "box";
+                const label = entity.title.length > 40
+                    ? entity.title.slice(0, 37) + "..."
+                    : entity.title;
+                const safeLabel = label.replace(/"/g, '\\"');
+                lines.push(`  "${entity.id.slice(0, 8)}" [label="${safeLabel}\\n(${entity.type}, ${tier})", fillcolor="${color}", shape=${shape}];`);
+            }
+            // Fetch relations for each entity and add edges
+            const entityIds = new Set(entities.map((e) => e.id));
+            const addedEdges = new Set();
+            for (const entity of entities.slice(0, 20)) {
+                // Limit graph API calls
+                try {
+                    const related = await client.getRelatedEntities(entity.id);
+                    // Outgoing relations: { id, relation_type, target: { id, ... } }
+                    for (const raw of related.outgoing || []) {
+                        const rel = raw;
+                        const sourceId = rel.source_id || entity.id;
+                        const targetId = rel.target_id || rel.target?.id;
+                        if (targetId &&
+                            entityIds.has(sourceId) &&
+                            entityIds.has(targetId)) {
+                            const edgeKey = `${sourceId}-${targetId}-${rel.relation_type}`;
+                            if (!addedEdges.has(edgeKey)) {
+                                addedEdges.add(edgeKey);
+                                lines.push(`  "${sourceId.slice(0, 8)}" -> "${targetId.slice(0, 8)}" [label="${rel.relation_type}"];`);
+                            }
+                        }
+                    }
+                    // Incoming relations: { id, relation_type, source: { id, ... } }
+                    for (const raw of related.incoming || []) {
+                        const rel = raw;
+                        const sourceId = rel.source_id || rel.source?.id;
+                        const targetId = rel.target_id || entity.id;
+                        if (sourceId &&
+                            entityIds.has(sourceId) &&
+                            entityIds.has(targetId)) {
+                            const edgeKey = `${sourceId}-${targetId}-${rel.relation_type}`;
+                            if (!addedEdges.has(edgeKey)) {
+                                addedEdges.add(edgeKey);
+                                lines.push(`  "${sourceId.slice(0, 8)}" -> "${targetId.slice(0, 8)}" [label="${rel.relation_type}"];`);
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Relation fetch failed, continue
+                }
+            }
+            lines.push("}");
+            const dotGraph = lines.join("\n");
+            return {
+                success: true,
+                format: "dot",
+                entityCount: entities.length,
+                edgeCount: addedEdges.size,
+                graph: dotGraph,
+                message: `Exported ${entities.length} entities and ${addedEdges.size} relations as DOT graph. Use Graphviz to render: echo '<graph>' | dot -Tpng -o graph.png`,
+            };
+        }
+        case "harmony_prune_draft": {
+            const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
+            if (!workspaceId) {
+                throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
+            }
+            const projectId = args.projectId || deps.getActiveProjectId() || undefined;
+            const dryRun = args.dryRun !== false; // default true
+            const maxAgeDays = args.maxAgeDays || 30;
+            // Fetch draft entities
+            const result = await client.listMemoryEntities({
+                workspace_id: workspaceId,
+                project_id: projectId,
+                limit: 100,
+            });
+            const drafts = (result.entities || []).filter((e) => {
+                const entity = e;
+                return entity.memory_tier === "draft";
+            });
+            const now = Date.now();
+            const stale = [];
+            for (const raw of drafts) {
+                const entity = raw;
+                const ageDays = (now - new Date(entity.created_at).getTime()) / (1000 * 60 * 60 * 24);
+                if (ageDays < maxAgeDays)
+                    continue;
+                const lifecycle = evaluateLifecycle(entity);
+                stale.push({
+                    id: entity.id,
+                    title: entity.title,
+                    ageDays: Math.round(ageDays),
+                    decayScore: Math.round(lifecycle.decay.score * 100) / 100,
+                });
+            }
+            if (!dryRun) {
+                for (const item of stale) {
+                    try {
+                        await client.deleteMemoryEntity(item.id);
+                    }
+                    catch {
+                        // Non-fatal
+                    }
+                }
+            }
+            return {
+                success: true,
+                dryRun,
+                totalDrafts: drafts.length,
+                staleDrafts: stale.length,
+                pruned: dryRun ? 0 : stale.length,
+                items: stale,
+                message: dryRun
+                    ? `Found ${stale.length} stale drafts (>${maxAgeDays} days old). Run with dryRun=false to delete.`
+                    : `Pruned ${stale.length} stale draft memories.`,
+            };
+        }
+        case "harmony_consolidate_memories": {
+            const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
+            if (!workspaceId) {
+                throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
+            }
+            const projectId = args.projectId || deps.getActiveProjectId() || undefined;
+            const dryRun = args.dryRun !== false; // default true
+            const minClusterSize = args.minClusterSize || 2;
+            const consolidationResult = await consolidateMemories(client, workspaceId, projectId, { dryRun, minClusterSize });
+            return {
+                success: true,
+                dryRun,
+                ...consolidationResult,
+                message: dryRun
+                    ? `Found ${consolidationResult.clustersFound} clusters across ${consolidationResult.entitiesProcessed} entities. Run with dryRun=false to consolidate.`
+                    : `Consolidated ${consolidationResult.consolidated} clusters from ${consolidationResult.entitiesProcessed} entities.`,
+            };
+        }
+        case "harmony_get_context_manifest": {
+            const assemblyId = z.string().min(1).max(100).parse(args.assemblyId);
+            const manifest = getCachedManifest(assemblyId);
+            if (!manifest) {
+                throw new Error(`Manifest not found for assembly '${assemblyId}'. Manifests are cached in-memory and expire after server restart.`);
+            }
+            return {
+                success: true,
+                manifest,
+                summary: {
+                    totalIncluded: manifest.included.length,
+                    totalExcluded: manifest.excluded.length,
+                    budgetUsed: `${manifest.budgetUsed}/${manifest.budgetTotal} tokens`,
+                    tierBreakdown: manifest.tierBreakdown,
+                    procedureBreakdown: manifest.procedureBreakdown,
+                },
+            };
+        }
+        case "harmony_promote_memory": {
+            const entityId = z.string().uuid().parse(args.entityId);
+            const targetTier = z
+                .enum(["episode", "reference"])
+                .parse(args.targetTier);
+            const reason = z.string().min(1).max(500).parse(args.reason);
+            // Fetch current entity to validate promotion path
+            const entityResult = await client.getMemoryEntity(entityId);
+            const entity = entityResult.entity;
+            const currentTier = entity.memory_tier || "reference";
+            // Validate promotion path: draft→episode→reference
+            const tierOrder = { draft: 0, episode: 1, reference: 2 };
+            if ((tierOrder[targetTier] || 0) <=
+                (tierOrder[currentTier] || 0)) {
+                throw new Error(`Cannot promote from '${currentTier}' to '${targetTier}'. Must promote to a higher tier.`);
+            }
+            const result = await client.updateMemoryEntity(entityId, {
+                memory_tier: targetTier,
+                metadata: {
+                    promoted_from_tier: currentTier,
+                    promotion_reason: reason,
+                    promoted_at: new Date().toISOString(),
+                },
+            });
+            return {
+                success: true,
+                promoted: {
+                    from: currentTier,
+                    to: targetTier,
+                    reason,
+                },
+                ...result,
+            };
+        }
+        // ============ ONBOARDING TOOLS ============
+        case "harmony_signup": {
+            const email = z.string().email().max(254).parse(args.email);
+            const password = z.string().min(8).max(128).parse(args.password);
+            const fullName = z.string().min(1).max(100).parse(args.fullName);
+            const apiUrl = deps.getApiUrl();
+            const result = await signupUser(apiUrl, {
+                email,
+                password,
+                full_name: fullName,
+            });
+            return {
+                success: true,
+                ...result,
+                message: "Account created. Use the session tokens for authenticated requests, or call harmony_onboard for full setup.",
+            };
+        }
+        case "harmony_create_workspace": {
+            const name = z.string().min(1).max(100).parse(args.name);
+            const result = await client.createWorkspace({
+                name,
+                description: args.description,
+            });
+            return { success: true, ...result };
+        }
+        case "harmony_create_project": {
+            const workspaceId = z.string().uuid().parse(args.workspaceId);
+            const name = z.string().min(1).max(100).parse(args.name);
+            const result = await client.createProject({
+                workspaceId,
+                name,
+                description: args.description,
+                color: args.color,
+                template: args.template,
+            });
+            return { success: true, ...result };
+        }
+        case "harmony_send_invitations": {
+            const workspaceId = z.string().uuid().parse(args.workspaceId);
+            const emails = z
+                .array(z.string().email().max(254))
+                .min(1)
+                .parse(args.emails);
+            const result = await client.sendInvitations({
+                workspaceId,
+                emails,
+                role: args.role,
+                sendEmail: args.sendEmail,
+            });
+            return { success: true, ...result };
+        }
+        case "harmony_generate_api_key": {
+            const name = z.string().min(1).max(100).parse(args.name);
+            const result = await client.generateApiKey(name);
+            return { success: true, ...result };
+        }
+        case "harmony_onboard": {
+            const email = z.string().email().max(254).parse(args.email);
+            const password = z.string().min(8).max(128).parse(args.password);
+            const fullName = z.string().min(1).max(100).parse(args.fullName);
+            const workspaceName = args.workspaceName || `${fullName}'s Workspace`;
+            const projectName = args.projectName || "My First Project";
+            const template = args.template || "kanban";
+            const keyName = args.keyName || "mcp-agent";
+            const apiUrl = deps.getApiUrl();
+            // 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(apiUrl, token, "POST", "/workspaces", {
+                name: workspaceName,
+            });
+            // 3. Create project
+            const projectResult = await requestWithBearer(apiUrl, token, "POST", "/projects", {
+                workspaceId: workspaceResult.workspace.id,
+                name: projectName,
+                template,
+            });
+            // 4. Generate API key
+            const keyResult = await requestWithBearer(apiUrl, token, "POST", "/api-keys", {
+                name: keyName,
+            });
+            // 5. Save config
+            deps.saveConfig({ apiKey: keyResult.rawKey });
+            deps.setActiveWorkspace(workspaceResult.workspace.id);
+            deps.setActiveProject(projectResult.project.id);
+            // 6. Reset client so singleton picks up new key
+            deps.resetClient();
+            return {
+                success: true,
+                user: signupResult.user,
+                workspace: workspaceResult.workspace,
+                project: projectResult.project,
+                columns: projectResult.columns,
+                apiKey: {
+                    rawKey: keyResult.rawKey,
+                    prefix: keyResult.apiKey.prefix,
+                },
+                message: `Onboarding complete! Account created for ${email}. Workspace "${workspaceName}" and project "${projectName}" are ready. API key saved to config.`,
+            };
+        }
+        case "harmony_backfill_embeddings": {
+            const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
+            if (!workspaceId) {
+                throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
+            }
+            const result = await client.backfillEmbeddings(workspaceId, args.batchSize);
+            return {
+                success: true,
+                ...result,
+                message: result.remaining > 0
+                    ? `Processed ${result.processed} entities. ${result.remaining} still need embeddings — run again to continue.`
+                    : `All embeddings up to date. Processed ${result.processed} entities.`,
+            };
+        }
+        case "harmony_backfill_relations": {
+            const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
+            if (!workspaceId) {
+                throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
+            }
+            const projectId = args.projectId || deps.getActiveProjectId() || undefined;
+            const maxRelationsPerEntity = args.maxRelationsPerEntity || 3;
+            // Fetch all entities
+            const { entities: allEntities } = await client.listMemoryEntities({
+                workspace_id: workspaceId,
+                project_id: projectId,
+                limit: 200,
+            });
+            let entitiesProcessed = 0;
+            let relationsCreated = 0;
+            for (const raw of allEntities) {
+                try {
+                    const result = await autoExpandGraph(client, raw.id, raw.title, raw.content || "", raw.tags || [], workspaceId, projectId, maxRelationsPerEntity);
+                    entitiesProcessed++;
+                    relationsCreated += result.relationsCreated;
+                }
+                catch {
+                    // Non-fatal: continue with remaining entities
+                }
+            }
+            return {
+                success: true,
+                entitiesProcessed,
+                relationsCreated,
+                message: `Processed ${entitiesProcessed} entities, created ${relationsCreated} new relations.`,
+            };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+/** Default deps that read from the local config file (for stdio mode). */
+function createConfigDeps() {
+    return {
+        getClient,
+        isConfigured,
+        getActiveProjectId: () => getActiveProjectId(),
+        getActiveWorkspaceId: () => getActiveWorkspaceId(),
+        setActiveProject: (id) => setActiveProject(id),
+        setActiveWorkspace: (id) => setActiveWorkspace(id),
+        getApiUrl,
+        getMemoryDir: () => getMemoryDir(),
+        getUserEmail,
+        saveConfig: (cfg) => saveConfig(cfg),
+        resetClient,
+    };
+}
+export class HarmonyMCPServer {
+    server;
+    constructor() {
+        this.server = new Server({ name: "@gethmy/mcp", version: "2.0.0" }, { capabilities: { tools: {}, resources: {} } });
+        registerHandlers(this.server, createConfigDeps());
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error("Harmony MCP server running on stdio");
+        // Initialize auto-session tracking
+        const configDeps = createConfigDeps();
+        initAutoSession(async (client, cardId, status) => {
+            await runEndSessionPipeline(client, configDeps, cardId, status);
+        }, () => getClient());
+        // Graceful shutdown: end all auto-sessions
+        const handleShutdown = async () => {
+            try {
+                await shutdownAllSessions();
+            }
+            catch {
+                // Best-effort
+            }
+            destroyAutoSession();
+            process.exit(0);
+        };
+        process.on("SIGINT", handleShutdown);
+        process.on("SIGTERM", handleShutdown);
+        // Attempt startup sync (non-blocking, best-effort)
+        try {
+            if (isConfigured()) {
+                const workspaceId = getActiveWorkspaceId();
+                if (workspaceId) {
+                    const client = getClient();
+                    const memoryDir = getMemoryDir();
+                    if (memoryDir) {
+                        const syncConfig = { memoryDir };
+                        const result = await syncPull(client, syncConfig, workspaceId);
+                        console.error(`Startup sync: ${result.pulled} pulled, ${result.deleted} deleted, ${result.errors.length} errors`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.error(`Startup sync failed (non-fatal): ${err}`);
+        }
+    }
+}