@gethmy/mcp 1.0.0 → 2.1.0

package/dist/lib/auto-session.js

@@ -0,0 +1,173 @@
+/**
+ * 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.
+ */
+/** 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;
+/**
+ * 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
+ */
+export function initAutoSession(callback, getClient) {
+    endCallback = callback;
+    clientGetter = getClient;
+    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");
+    }
+    // Start a new auto-session
+    try {
+        await client.startAgentSession(cardId, {
+            agentIdentifier: "auto",
+            agentName: "Auto-detected Agent",
+            status: "working",
+        });
+    }
+    catch {
+        // Session start failed (might already have one), still track locally
+    }
+    activeSessions.set(cardId, {
+        cardId,
+        startedAt: now,
+        lastActivityAt: now,
+        isExplicit: false,
+        agentIdentifier: "auto",
+        agentName: "Auto-detected Agent",
+    });
+}
+/**
+ * Mark a session as explicitly started (won't be auto-ended by card switching or inactivity).
+ */
+export function markExplicit(cardId) {
+    const existing = activeSessions.get(cardId);
+    if (existing) {
+        existing.isExplicit = true;
+    }
+    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: "explicit",
+            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;
+}
+/**
+ * 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

@@ -0,0 +1,127 @@
+#!/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 { 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 () => {
+    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://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")
+    .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,
+    });
+});
+program.parse();

package/dist/lib/config.js

@@ -0,0 +1,205 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const DEFAULT_API_URL = "https://gethmy.com/api";
+const LOCAL_CONFIG_FILENAME = ".harmony-mcp.json";
+export function getConfigDir() {
+    return join(homedir(), ".harmony-mcp");
+}
+export function getConfigPath() {
+    return join(getConfigDir(), "config.json");
+}
+export function getLocalConfigPath(cwd) {
+    return join(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
+}
+export function loadConfig() {
+    const configPath = getConfigPath();
+    if (!existsSync(configPath)) {
+        return {
+            apiKey: null,
+            apiUrl: DEFAULT_API_URL,
+            activeWorkspaceId: null,
+            activeProjectId: null,
+            userEmail: null,
+            memoryDir: null,
+        };
+    }
+    try {
+        const data = readFileSync(configPath, "utf-8");
+        const config = JSON.parse(data);
+        return {
+            apiKey: config.apiKey || null,
+            apiUrl: config.apiUrl || DEFAULT_API_URL,
+            activeWorkspaceId: config.activeWorkspaceId || null,
+            activeProjectId: config.activeProjectId || null,
+            userEmail: config.userEmail || null,
+            memoryDir: config.memoryDir || null,
+        };
+    }
+    catch {
+        return {
+            apiKey: null,
+            apiUrl: DEFAULT_API_URL,
+            activeWorkspaceId: null,
+            activeProjectId: null,
+            userEmail: null,
+            memoryDir: null,
+        };
+    }
+}
+export function saveConfig(config) {
+    const configDir = getConfigDir();
+    const configPath = getConfigPath();
+    if (!existsSync(configDir)) {
+        mkdirSync(configDir, { recursive: true, mode: 0o700 });
+    }
+    const existingConfig = loadConfig();
+    const newConfig = { ...existingConfig, ...config };
+    writeFileSync(configPath, JSON.stringify(newConfig, null, 2), {
+        mode: 0o600,
+    });
+}
+export function loadLocalConfig(cwd) {
+    const localConfigPath = getLocalConfigPath(cwd);
+    if (!existsSync(localConfigPath)) {
+        return null;
+    }
+    try {
+        const data = readFileSync(localConfigPath, "utf-8");
+        const config = JSON.parse(data);
+        return {
+            workspaceId: config.workspaceId || null,
+            projectId: config.projectId || null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function saveLocalConfig(config, cwd) {
+    const localConfigPath = getLocalConfigPath(cwd);
+    const existingConfig = loadLocalConfig(cwd) || {
+        workspaceId: null,
+        projectId: null,
+    };
+    const newConfig = { ...existingConfig, ...config };
+    // Remove null values from the saved config for cleaner output
+    const cleanConfig = {};
+    if (newConfig.workspaceId)
+        cleanConfig.workspaceId = newConfig.workspaceId;
+    if (newConfig.projectId)
+        cleanConfig.projectId = newConfig.projectId;
+    writeFileSync(localConfigPath, JSON.stringify(cleanConfig, null, 2));
+}
+export function hasLocalConfig(cwd) {
+    return existsSync(getLocalConfigPath(cwd));
+}
+export function getApiKey() {
+    const config = loadConfig();
+    if (!config.apiKey) {
+        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.");
+    }
+    return config.apiKey;
+}
+export function getApiUrl() {
+    const config = loadConfig();
+    return config.apiUrl;
+}
+export function getUserEmail() {
+    const config = loadConfig();
+    return config.userEmail;
+}
+export function setUserEmail(email) {
+    saveConfig({ userEmail: email });
+}
+export function setActiveWorkspace(workspaceId, options) {
+    if (options?.local) {
+        saveLocalConfig({ workspaceId }, options.cwd);
+    }
+    else {
+        saveConfig({ activeWorkspaceId: workspaceId });
+    }
+}
+export function setActiveProject(projectId, options) {
+    if (options?.local) {
+        saveLocalConfig({ projectId }, options.cwd);
+    }
+    else {
+        saveConfig({ activeProjectId: projectId });
+    }
+}
+export function getActiveWorkspaceId(cwd) {
+    // Local config takes precedence over global
+    const localConfig = loadLocalConfig(cwd);
+    if (localConfig?.workspaceId) {
+        return localConfig.workspaceId;
+    }
+    return loadConfig().activeWorkspaceId;
+}
+export function getActiveProjectId(cwd) {
+    // Local config takes precedence over global
+    const localConfig = loadLocalConfig(cwd);
+    if (localConfig?.projectId) {
+        return localConfig.projectId;
+    }
+    return loadConfig().activeProjectId;
+}
+export function isConfigured() {
+    const config = loadConfig();
+    return !!config.apiKey;
+}
+/**
+ * Check if skills are already installed (globally or locally).
+ * Returns installation status and location.
+ */
+export function areSkillsInstalled(cwd) {
+    const home = homedir();
+    const workingDir = cwd || process.cwd();
+    const foundPaths = [];
+    // Check global skills directory
+    const globalSkillsDir = join(home, ".agents", "skills");
+    const globalSkillPath = join(globalSkillsDir, "hmy", "SKILL.md");
+    if (existsSync(globalSkillPath)) {
+        foundPaths.push(globalSkillPath);
+        return { installed: true, location: "global", paths: foundPaths };
+    }
+    // Check Claude global skills (symlinked from global skills)
+    const claudeGlobalSkill = join(home, ".claude", "skills", "hmy.md");
+    if (existsSync(claudeGlobalSkill)) {
+        foundPaths.push(claudeGlobalSkill);
+        return { installed: true, location: "global", paths: foundPaths };
+    }
+    // Check Claude global skills (alternate SKILL.md format)
+    const claudeGlobalSkillAlt = join(home, ".claude", "skills", "hmy", "SKILL.md");
+    if (existsSync(claudeGlobalSkillAlt)) {
+        foundPaths.push(claudeGlobalSkillAlt);
+        return { installed: true, location: "global", paths: foundPaths };
+    }
+    // Check local skills in project directory
+    const localSkillPath = join(workingDir, ".claude", "skills", "hmy.md");
+    if (existsSync(localSkillPath)) {
+        foundPaths.push(localSkillPath);
+        return { installed: true, location: "local", paths: foundPaths };
+    }
+    // Check local skills in project directory (alternate SKILL.md format)
+    const localSkillPathAlt = join(workingDir, ".claude", "skills", "hmy", "SKILL.md");
+    if (existsSync(localSkillPathAlt)) {
+        foundPaths.push(localSkillPathAlt);
+        return { installed: true, location: "local", paths: foundPaths };
+    }
+    return { installed: false, location: null, paths: [] };
+}
+/**
+ * Check if project context is configured in the local directory.
+ */
+export function hasProjectContext(cwd) {
+    const localConfig = loadLocalConfig(cwd);
+    return !!(localConfig?.workspaceId || localConfig?.projectId);
+}
+export function getMemoryDir() {
+    const config = loadConfig();
+    if (config.memoryDir)
+        return config.memoryDir;
+    return join(homedir(), ".harmony", "memory");
+}