@gethmy/mcp 2.3.1 → 2.3.3

package/dist/lib/auto-session.js

@@ -1,214 +0,0 @@
-/**
- * Auto-Session Tracking
- *
- * Automatically detects agent session boundaries by monitoring tool calls.
- * Sessions auto-start when card-mutating tools are called, and auto-end
- * after 10 minutes of inactivity or when a different card is worked on.
- *
- * Agent identity is resolved from the MCP client's `initialize` handshake
- * (clientInfo.name), so "Claude Code", "Cursor", "Codex", etc. are
- * detected automatically — no hardcoded fallback needed.
- */
-/** Well-known MCP client names → human-friendly display names */
-const CLIENT_DISPLAY_NAMES = {
-    "claude-code": "Claude Code",
-    "claude-desktop": "Claude Desktop",
-    cursor: "Cursor",
-    windsurf: "Windsurf",
-    cline: "Cline",
-    continue: "Continue",
-    "codex-cli": "OpenAI Codex",
-    zed: "Zed",
-    "gemini-cli": "Gemini CLI",
-};
-/** Derive a slug-style identifier from a client name */
-function toIdentifier(name) {
-    return name.toLowerCase().replace(/\s+/g, "-");
-}
-/** Resolve agent identity from MCP client info */
-export function resolveAgentIdentity(info) {
-    if (!info?.name) {
-        return { agentIdentifier: "unknown", agentName: "Unknown Agent" };
-    }
-    const key = toIdentifier(info.name);
-    const displayName = CLIENT_DISPLAY_NAMES[key] ?? info.name; // use raw name if not in map
-    return { agentIdentifier: key, agentName: displayName };
-}
-/** Tools that trigger auto-start of a session */
-export const AUTO_START_TRIGGERS = new Set([
-    "harmony_generate_prompt",
-    "harmony_update_card",
-    "harmony_move_card",
-    "harmony_create_subtask",
-    "harmony_toggle_subtask",
-    "harmony_add_label_to_card",
-    "harmony_remove_label_from_card",
-]);
-export const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
-const CHECK_INTERVAL_MS = 60 * 1000; // 60 seconds
-const activeSessions = new Map();
-let inactivityTimer = null;
-let endCallback = null;
-let clientGetter = null;
-let clientInfoGetter = null;
-/**
- * Initialize auto-session tracking.
- * @param callback Called when an auto-session ends (runs the learning pipeline)
- * @param getClient Function to get the current API client
- * @param getClientInfo Function to get MCP client identity from the initialize handshake
- */
-export function initAutoSession(callback, getClient, getClientInfo) {
-    endCallback = callback;
-    clientGetter = getClient;
-    clientInfoGetter = getClientInfo ?? null;
-    if (inactivityTimer)
-        clearInterval(inactivityTimer);
-    inactivityTimer = setInterval(checkInactivity, CHECK_INTERVAL_MS);
-}
-/**
- * Track activity on a card. Auto-starts a session if needed.
- */
-export async function trackActivity(cardId, options) {
-    const now = Date.now();
-    const existing = activeSessions.get(cardId);
-    if (existing) {
-        // Update last activity timestamp
-        existing.lastActivityAt = now;
-        return;
-    }
-    // Only auto-start if the tool is a trigger
-    if (!options?.autoStart)
-        return;
-    const client = options?.client ?? clientGetter?.();
-    if (!client)
-        return;
-    // Collect auto-sessions on other cards to end (avoid mutating map during iteration)
-    const toEnd = [];
-    for (const [otherCardId, session] of activeSessions) {
-        if (otherCardId !== cardId && !session.isExplicit) {
-            toEnd.push(otherCardId);
-        }
-    }
-    for (const otherCardId of toEnd) {
-        await autoEndSession(client, otherCardId, "completed");
-    }
-    // Resolve agent identity from MCP client info
-    const info = clientInfoGetter?.() ?? null;
-    const { agentIdentifier, agentName } = resolveAgentIdentity(info);
-    // Start a new auto-session
-    try {
-        await client.startAgentSession(cardId, {
-            agentIdentifier,
-            agentName,
-            status: "working",
-        });
-    }
-    catch {
-        // Session start failed (might already have one), still track locally
-    }
-    activeSessions.set(cardId, {
-        cardId,
-        startedAt: now,
-        lastActivityAt: now,
-        isExplicit: false,
-        agentIdentifier,
-        agentName,
-    });
-}
-/**
- * Mark a session as explicitly started (won't be auto-ended by card switching or inactivity).
- * Optionally accepts the real agent identifier/name to store in the session.
- */
-export function markExplicit(cardId, options) {
-    const existing = activeSessions.get(cardId);
-    if (existing) {
-        existing.isExplicit = true;
-        if (options?.agentIdentifier)
-            existing.agentIdentifier = options.agentIdentifier;
-        if (options?.agentName)
-            existing.agentName = options.agentName;
-    }
-    else {
-        // Track the explicit session even if we didn't auto-start it
-        activeSessions.set(cardId, {
-            cardId,
-            startedAt: Date.now(),
-            lastActivityAt: Date.now(),
-            isExplicit: true,
-            agentIdentifier: options?.agentIdentifier ?? "explicit",
-            agentName: options?.agentName ?? "Explicit Agent",
-        });
-    }
-}
-/**
- * Remove a session from tracking (called when session is explicitly ended).
- */
-export function untrack(cardId) {
-    activeSessions.delete(cardId);
-}
-/**
- * End all active auto-sessions (called on process shutdown).
- */
-export async function shutdownAllSessions() {
-    const client = clientGetter?.();
-    if (!client)
-        return;
-    // Snapshot keys to avoid mutating map during iteration
-    const cardIds = [...activeSessions.keys()];
-    const promises = cardIds.map((cardId) => autoEndSession(client, cardId, "paused"));
-    await Promise.allSettled(promises);
-}
-/**
- * Clean up the interval timer (for tests).
- */
-export function destroyAutoSession() {
-    if (inactivityTimer) {
-        clearInterval(inactivityTimer);
-        inactivityTimer = null;
-    }
-    activeSessions.clear();
-    endCallback = null;
-    clientGetter = null;
-    clientInfoGetter = null;
-}
-/**
- * Get a snapshot of active sessions (for testing/debugging).
- */
-export function getActiveSessions() {
-    return activeSessions;
-}
-/**
- * Run inactivity check immediately (exported for testing).
- * In production, called by the setInterval timer every 60s.
- */
-export function checkInactivity() {
-    const now = Date.now();
-    const client = clientGetter?.();
-    if (!client)
-        return;
-    // Snapshot keys to avoid mutating map during iteration
-    const entries = [...activeSessions.entries()];
-    for (const [cardId, session] of entries) {
-        if (session.isExplicit)
-            continue;
-        if (now - session.lastActivityAt > INACTIVITY_TIMEOUT_MS) {
-            autoEndSession(client, cardId, "completed").catch(() => { });
-        }
-    }
-}
-// --- Internal ---
-async function autoEndSession(client, cardId, status) {
-    activeSessions.delete(cardId);
-    try {
-        await client.endAgentSession(cardId, { status });
-    }
-    catch {
-        // Best-effort end
-    }
-    try {
-        await endCallback?.(client, cardId, status);
-    }
-    catch {
-        // Best-effort pipeline
-    }
-}

package/dist/lib/cli.js

@@ -1,138 +0,0 @@
-#!/usr/bin/env node
-import { createRequire } from "node:module";
-import { program } from "commander";
-import { areSkillsInstalled, getActiveProjectId, getActiveWorkspaceId, getConfigPath, getLocalConfigPath, hasLocalConfig, isConfigured, loadConfig, loadLocalConfig, saveConfig, } from "./config.js";
-import { HarmonyMCPServer } from "./server.js";
-import { refreshSkills } from "./skills.js";
-import { runSetup } from "./tui/setup.js";
-const require = createRequire(import.meta.url);
-const { version } = require("../package.json");
-program
-    .name("@gethmy/mcp")
-    .description("MCP server for Harmony Kanban board")
-    .version(version);
-program
-    .command("serve")
-    .description("Start the MCP server (stdio transport)")
-    .action(async () => {
-    if (!isConfigured()) {
-        console.error("No API key configured.");
-        console.error("Run: npx @gethmy/mcp setup");
-        process.exit(1);
-    }
-    await refreshSkills();
-    const server = new HarmonyMCPServer();
-    await server.run();
-});
-program
-    .command("status")
-    .description("Show configuration status")
-    .action(() => {
-    const globalConfig = loadConfig();
-    const localConfig = loadLocalConfig();
-    const hasLocal = hasLocalConfig();
-    const skillsStatus = areSkillsInstalled();
-    // Helper to mask email for privacy (u***@example.com)
-    const maskEmail = (email) => {
-        const [local, domain] = email.split("@");
-        if (!domain)
-            return email;
-        return `${local[0]}***@${domain}`;
-    };
-    if (isConfigured()) {
-        console.log("Status: Configured\n");
-        console.log("API:");
-        console.log(`  Key: ${globalConfig.apiKey?.slice(0, 8)}...`);
-        console.log(`  URL: ${globalConfig.apiUrl}`);
-        console.log(`  Email: ${globalConfig.userEmail ? maskEmail(globalConfig.userEmail) : "(not set)"}`);
-        console.log("\nSkills:");
-        if (skillsStatus.installed) {
-            console.log(`  Installed: Yes (${skillsStatus.location})`);
-            for (const path of skillsStatus.paths) {
-                console.log(`    ${path}`);
-            }
-        }
-        else {
-            console.log("  Installed: No");
-            console.log("  Run: npx @gethmy/mcp setup");
-        }
-        console.log("\nContext:");
-        if (hasLocal) {
-            console.log(`  Local config: ${getLocalConfigPath()}`);
-            console.log(`    Workspace: ${localConfig?.workspaceId || "(not set)"}`);
-            console.log(`    Project: ${localConfig?.projectId || "(not set)"}`);
-        }
-        console.log(`  Global config: ${getConfigPath()}`);
-        console.log(`    Workspace: ${globalConfig.activeWorkspaceId || "(not set)"}`);
-        console.log(`    Project: ${globalConfig.activeProjectId || "(not set)"}`);
-        // Show effective (active) context
-        const effectiveWorkspace = getActiveWorkspaceId();
-        const effectiveProject = getActiveProjectId();
-        const wsSource = localConfig?.workspaceId
-            ? "local"
-            : globalConfig.activeWorkspaceId
-                ? "global"
-                : "";
-        const projSource = localConfig?.projectId
-            ? "local"
-            : globalConfig.activeProjectId
-                ? "global"
-                : "";
-        console.log("\n  Active (effective):");
-        console.log(`    Workspace: ${effectiveWorkspace || "(not set)"}${wsSource ? ` ← ${wsSource}` : ""}`);
-        console.log(`    Project: ${effectiveProject || "(not set)"}${projSource ? ` ← ${projSource}` : ""}`);
-    }
-    else {
-        console.log("Status: Not configured\n");
-        console.log("Run: npx @gethmy/mcp setup");
-        console.log("Get an API key at: https://app.gethmy.com/user/keys");
-    }
-});
-program
-    .command("reset")
-    .description("Remove stored configuration")
-    .action(() => {
-    saveConfig({
-        apiKey: null,
-        activeWorkspaceId: null,
-        activeProjectId: null,
-        userEmail: null,
-    });
-    console.log("Configuration reset successfully");
-    console.log("\nTo reconfigure, run: npx @gethmy/mcp setup");
-});
-program
-    .command("setup")
-    .description("Smart setup wizard for Harmony MCP (recommended)")
-    .option("-f, --force", "Overwrite existing configuration files")
-    .option("-k, --api-key <key>", "API key (skips prompt)")
-    .option("-e, --email <email>", "Your email for auto-assignment")
-    .option("-a, --agents <agents...>", "Agents to configure: claude, codex, cursor, windsurf")
-    .option("-l, --local", "Install skills locally in project directory")
-    .option("-g, --global", "Install skills globally (recommended)")
-    .option("-w, --workspace <id>", "Set workspace context")
-    .option("-p, --project <id>", "Set project context")
-    .option("--skip-context", "Skip workspace/project selection")
-    .option("--skip-docs", "Skip project docs scaffold/verification")
-    .option("--new", "Create a new account (skip the choice prompt)")
-    .option("-n, --name <name>", "Full name (for account creation)")
-    .action(async (options) => {
-    await runSetup({
-        force: options.force,
-        apiKey: options.apiKey,
-        userEmail: options.email,
-        agents: options.agents,
-        installMode: options.global
-            ? "global"
-            : options.local
-                ? "local"
-                : undefined,
-        workspaceId: options.workspace,
-        projectId: options.project,
-        skipContext: options.skipContext,
-        skipDocs: options.skipDocs,
-        newAccount: options.new,
-        name: options.name,
-    });
-});
-program.parse();

package/dist/lib/consolidation.js

@@ -1,303 +0,0 @@
-/**
- * Smart Memory Consolidation
- *
- * Clusters similar draft/episode memories and merges them into
- * consolidated reference entities to reduce noise and improve retrieval.
- */
-import { findSimilarEntities } from "./graph-expansion.js";
-/**
- * Consolidate similar draft/episode memories into reference entities.
- *
- * 1. Lists all draft and episode tier entities in scope
- * 2. Groups by entity type
- * 3. For each type group, finds clusters via embedding similarity
- * 4. Merges clusters into new reference entities with part_of relations
- */
-export async function consolidateMemories(client, workspaceId, projectId, options) {
-    const dryRun = options?.dryRun !== false; // default true
-    const minClusterSize = options?.minClusterSize ?? 3; // raised from 2 to reduce noise
-    const result = {
-        consolidated: 0,
-        clustersFound: 0,
-        entitiesProcessed: 0,
-        details: [],
-    };
-    // Step 1: Fetch all draft and episode entities
-    const listResult = await client.listMemoryEntities({
-        workspace_id: workspaceId,
-        project_id: projectId,
-        limit: 100,
-    });
-    const allEntities = (listResult.entities || []).filter((e) => e.memory_tier === "draft" || e.memory_tier === "episode");
-    result.entitiesProcessed = allEntities.length;
-    if (allEntities.length < minClusterSize)
-        return result;
-    // Step 2: Group by type
-    const typeGroups = new Map();
-    for (const entity of allEntities) {
-        const group = typeGroups.get(entity.type) || [];
-        group.push(entity);
-        typeGroups.set(entity.type, group);
-    }
-    // Step 3: Find clusters within each type group
-    for (const [type, entities] of typeGroups) {
-        if (entities.length < minClusterSize)
-            continue;
-        const clustered = new Set();
-        const clusters = [];
-        for (const entity of entities) {
-            if (clustered.has(entity.id))
-                continue;
-            // Search for similar entities using embedding-based search
-            const similar = await findSimilarEntities(client, entity.title, entity.content, workspaceId, {
-                projectId,
-                limit: 20,
-                minRrfScore: 0.01,
-                excludeIds: [...clustered],
-            });
-            // Filter to only entities in our current type group that aren't yet clustered
-            const entityIdSet = new Set(entities.map((e) => e.id));
-            const clusterMembers = similar.filter((s) => entityIdSet.has(s.id) &&
-                !clustered.has(s.id) &&
-                s.id !== entity.id &&
-                s.type === type);
-            if (clusterMembers.length >= minClusterSize - 1) {
-                const cluster = [
-                    entity,
-                    ...clusterMembers.slice(0, 5).map((s) => {
-                        // Map back to full entity from our list
-                        return entities.find((e) => e.id === s.id) || entity;
-                    }),
-                ];
-                // Deduplicate by id
-                const uniqueCluster = [];
-                const seen = new Set();
-                for (const member of cluster) {
-                    if (!seen.has(member.id)) {
-                        seen.add(member.id);
-                        uniqueCluster.push(member);
-                    }
-                }
-                if (uniqueCluster.length >= minClusterSize) {
-                    clusters.push(uniqueCluster);
-                    for (const member of uniqueCluster) {
-                        clustered.add(member.id);
-                    }
-                }
-            }
-        }
-        // Step 4: Create consolidated entities for each cluster
-        for (const cluster of clusters) {
-            result.clustersFound++;
-            // Derive title from most common words across cluster titles
-            const mergedTitle = deriveClusterTitle(cluster, type);
-            const memberTitles = cluster.map((e) => e.title);
-            // Synthesize content: extract unique knowledge from each member,
-            // not just a bullet list of titles. Each member's content is trimmed
-            // to its first meaningful paragraph (skipping headers and metadata).
-            const mergedContent = synthesizeClusterContent(cluster, type);
-            // Max confidence from cluster members
-            const maxConfidence = Math.max(...cluster.map((e) => e.confidence));
-            // Union of all tags (deduped)
-            const allTags = [...new Set(cluster.flatMap((e) => e.tags || []))];
-            const detail = {
-                clusterSize: cluster.length,
-                mergedTitle,
-                memberTitles,
-            };
-            if (!dryRun) {
-                try {
-                    // Create consolidated reference entity
-                    const createResult = await client.createMemoryEntity({
-                        workspace_id: workspaceId,
-                        project_id: projectId,
-                        type,
-                        scope: "project",
-                        memory_tier: "reference",
-                        title: mergedTitle,
-                        content: mergedContent,
-                        confidence: maxConfidence,
-                        tags: [...allTags.slice(0, 15), "consolidated"],
-                        metadata: {
-                            source: "consolidation",
-                            member_ids: cluster.map((e) => e.id),
-                            consolidated_at: new Date().toISOString(),
-                        },
-                    });
-                    const newEntity = createResult.entity;
-                    if (newEntity?.id) {
-                        detail.entityId = newEntity.id;
-                        // Create part_of relations from members → consolidated entity
-                        for (const member of cluster) {
-                            try {
-                                await client.createMemoryRelation({
-                                    source_id: member.id,
-                                    target_id: newEntity.id,
-                                    relation_type: "part_of",
-                                    confidence: 0.8,
-                                });
-                            }
-                            catch {
-                                // Skip duplicate relations
-                            }
-                        }
-                        // Downgrade member confidence by 0.3 (min 0.1)
-                        for (const member of cluster) {
-                            try {
-                                const newConf = Math.max(member.confidence - 0.3, 0.1);
-                                await client.updateMemoryEntity(member.id, {
-                                    confidence: newConf,
-                                    metadata: {
-                                        consolidated_into: newEntity.id,
-                                        original_confidence: member.confidence,
-                                    },
-                                });
-                            }
-                            catch {
-                                // Non-fatal
-                            }
-                        }
-                        result.consolidated++;
-                    }
-                }
-                catch {
-                    // Non-fatal: consolidation failure for one cluster shouldn't block others
-                }
-            }
-            else {
-                result.consolidated++;
-            }
-            result.details.push(detail);
-        }
-    }
-    return result;
-}
-/**
- * Synthesize cluster content by extracting unique, actionable knowledge
- * from each member entity. Skips boilerplate (headers, metadata, agent names)
- * and deduplicates similar lines across members.
- */
-function synthesizeClusterContent(cluster, type) {
-    // Lines to skip: headers, agent metadata, timestamps, progress percentages
-    const SKIP_PATTERNS = [
-        /^##\s/,
-        /^Agent:/,
-        /^Duration:/,
-        /^Labels:/,
-        /^Progress:/,
-        /^Session status:/,
-        /^Completed at/,
-        /^Final state:/,
-        /^Related:/,
-        /^When working on:/,
-        /^\d+\.\s+.+\(\d+%,\s*\+\d+%\)/, // procedure step with progress percentages
-        /^Last updated:/,
-        /^Recurring pattern:/,
-        /^Consolidated from/,
-    ];
-    const seenLines = new Set();
-    const knowledgeLines = [];
-    for (const entity of cluster) {
-        const lines = entity.content.split("\n").map((l) => l.trim());
-        for (const line of lines) {
-            if (!line || line.length < 20)
-                continue;
-            if (SKIP_PATTERNS.some((p) => p.test(line)))
-                continue;
-            // Normalize for dedup: lowercase, strip markdown formatting
-            const normalized = line
-                .toLowerCase()
-                .replace(/[*_`#[\]]/g, "")
-                .trim();
-            if (seenLines.has(normalized))
-                continue;
-            seenLines.add(normalized);
-            knowledgeLines.push(line);
-        }
-    }
-    if (knowledgeLines.length === 0) {
-        // Fallback: if no knowledge was extractable, use a compact summary
-        return `${cluster.length} related ${type} entities consolidated. Original titles:\n${cluster.map((e) => `- ${e.title}`).join("\n")}`;
-    }
-    // Cap at ~400 tokens worth of content (1600 chars)
-    const MAX_CHARS = 1600;
-    const result = [
-        `Consolidated knowledge from ${cluster.length} ${type} entities:\n`,
-    ];
-    let charCount = result[0].length;
-    for (const line of knowledgeLines) {
-        if (charCount + line.length + 3 > MAX_CHARS)
-            break;
-        result.push(`- ${line}`);
-        charCount += line.length + 3;
-    }
-    return result.join("\n");
-}
-/**
- * Derive a cluster title from the most common meaningful words across member titles.
- */
-function deriveClusterTitle(cluster, type) {
-    const stopWords = new Set([
-        "the",
-        "a",
-        "an",
-        "is",
-        "are",
-        "was",
-        "were",
-        "be",
-        "been",
-        "being",
-        "have",
-        "has",
-        "had",
-        "do",
-        "does",
-        "did",
-        "will",
-        "shall",
-        "would",
-        "should",
-        "may",
-        "might",
-        "can",
-        "could",
-        "of",
-        "in",
-        "to",
-        "for",
-        "with",
-        "on",
-        "at",
-        "from",
-        "by",
-        "and",
-        "or",
-        "but",
-        "not",
-        "session",
-        "blocker",
-        "pattern",
-        "solution",
-        "error",
-        "task",
-        "mid-session",
-    ]);
-    const wordCounts = new Map();
-    for (const entity of cluster) {
-        const words = entity.title
-            .toLowerCase()
-            .split(/\W+/)
-            .filter((w) => w.length > 2 && !stopWords.has(w));
-        for (const word of words) {
-            wordCounts.set(word, (wordCounts.get(word) || 0) + 1);
-        }
-    }
-    // Sort by frequency, take top 4 for more descriptive titles
-    const topWords = [...wordCounts.entries()]
-        .sort((a, b) => b[1] - a[1])
-        .slice(0, 4)
-        .map(([word]) => word[0].toUpperCase() + word.slice(1));
-    const suffix = topWords.length > 0 ? topWords.join(" / ") : "Various";
-    return `${type[0].toUpperCase() + type.slice(1)}: ${suffix}`;
-}