@gethmy/mcp 1.0.0 → 2.1.0

package/src/auto-session.ts

@@ -0,0 +1,218 @@
+/**
+ * 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.
+ */
+
+import type { HarmonyApiClient } from "./api-client.js";
+
+export interface TrackedSession {
+  cardId: string;
+  startedAt: number;
+  lastActivityAt: number;
+  /** If true, session was explicitly started via harmony_start_agent_session */
+  isExplicit: boolean;
+  agentIdentifier: string;
+  agentName: string;
+}
+
+export type EndSessionCallback = (
+  client: HarmonyApiClient,
+  cardId: string,
+  status: "completed" | "paused",
+) => Promise<void>;
+
+/** 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<string, TrackedSession>();
+let inactivityTimer: ReturnType<typeof setInterval> | null = null;
+let endCallback: EndSessionCallback | null = null;
+let clientGetter: (() => HarmonyApiClient) | null = null;
+
+/**
+ * Initialize auto-session tracking.
+ * @param callback Called when an auto-session ends (runs the learning pipeline)
+ * @param getClient Function to get the current API client
+ */
+export function initAutoSession(
+  callback: EndSessionCallback,
+  getClient: () => HarmonyApiClient,
+): void {
+  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: string,
+  options?: {
+    autoStart?: boolean;
+    client?: HarmonyApiClient;
+  },
+): Promise<void> {
+  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: string[] = [];
+  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: string): void {
+  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: string): void {
+  activeSessions.delete(cardId);
+}
+
+/**
+ * End all active auto-sessions (called on process shutdown).
+ */
+export async function shutdownAllSessions(): Promise<void> {
+  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(): void {
+  if (inactivityTimer) {
+    clearInterval(inactivityTimer);
+    inactivityTimer = null;
+  }
+  activeSessions.clear();
+  endCallback = null;
+  clientGetter = null;
+}
+
+/**
+ * Get a snapshot of active sessions (for testing/debugging).
+ */
+export function getActiveSessions(): Map<string, TrackedSession> {
+  return activeSessions;
+}
+
+/**
+ * Run inactivity check immediately (exported for testing).
+ * In production, called by the setInterval timer every 60s.
+ */
+export function checkInactivity(): void {
+  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: HarmonyApiClient,
+  cardId: string,
+  status: "completed" | "paused",
+): Promise<void> {
+  activeSessions.delete(cardId);
+  try {
+    await client.endAgentSession(cardId, { status });
+  } catch {
+    // Best-effort end
+  }
+  try {
+    await endCallback?.(client, cardId, status);
+  } catch {
+    // Best-effort pipeline
+  }
+}

package/src/cli.ts

@@ -0,0 +1,166 @@
+#!/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: string): string => {
+      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/src/config.ts

@@ -0,0 +1,285 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface HarmonyConfig {
+  apiKey: string | null;
+  apiUrl: string;
+  activeWorkspaceId: string | null;
+  activeProjectId: string | null;
+  userEmail: string | null;
+  memoryDir: string | null;
+}
+
+/**
+ * Local project-level config (stored in .harmony-mcp.json in project root).
+ * Only contains context IDs - API key stays global for security.
+ */
+export interface LocalConfig {
+  workspaceId: string | null;
+  projectId: string | null;
+}
+
+const DEFAULT_API_URL = "https://gethmy.com/api";
+const LOCAL_CONFIG_FILENAME = ".harmony-mcp.json";
+
+export function getConfigDir(): string {
+  return join(homedir(), ".harmony-mcp");
+}
+
+export function getConfigPath(): string {
+  return join(getConfigDir(), "config.json");
+}
+
+export function getLocalConfigPath(cwd?: string): string {
+  return join(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
+}
+
+export function loadConfig(): HarmonyConfig {
+  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: Partial<HarmonyConfig>): void {
+  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?: string): LocalConfig | null {
+  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: Partial<LocalConfig>,
+  cwd?: string,
+): void {
+  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: Record<string, string> = {};
+  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?: string): boolean {
+  return existsSync(getLocalConfigPath(cwd));
+}
+
+export function getApiKey(): string {
+  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(): string {
+  const config = loadConfig();
+  return config.apiUrl;
+}
+
+export function getUserEmail(): string | null {
+  const config = loadConfig();
+  return config.userEmail;
+}
+
+export function setUserEmail(email: string | null): void {
+  saveConfig({ userEmail: email });
+}
+
+export interface SetContextOptions {
+  local?: boolean;
+  cwd?: string;
+}
+
+export function setActiveWorkspace(
+  workspaceId: string | null,
+  options?: SetContextOptions,
+): void {
+  if (options?.local) {
+    saveLocalConfig({ workspaceId }, options.cwd);
+  } else {
+    saveConfig({ activeWorkspaceId: workspaceId });
+  }
+}
+
+export function setActiveProject(
+  projectId: string | null,
+  options?: SetContextOptions,
+): void {
+  if (options?.local) {
+    saveLocalConfig({ projectId }, options.cwd);
+  } else {
+    saveConfig({ activeProjectId: projectId });
+  }
+}
+
+export function getActiveWorkspaceId(cwd?: string): string | null {
+  // Local config takes precedence over global
+  const localConfig = loadLocalConfig(cwd);
+  if (localConfig?.workspaceId) {
+    return localConfig.workspaceId;
+  }
+  return loadConfig().activeWorkspaceId;
+}
+
+export function getActiveProjectId(cwd?: string): string | null {
+  // Local config takes precedence over global
+  const localConfig = loadLocalConfig(cwd);
+  if (localConfig?.projectId) {
+    return localConfig.projectId;
+  }
+  return loadConfig().activeProjectId;
+}
+
+export function isConfigured(): boolean {
+  const config = loadConfig();
+  return !!config.apiKey;
+}
+
+/**
+ * Check if skills are already installed (globally or locally).
+ * Returns installation status and location.
+ */
+export function areSkillsInstalled(cwd?: string): {
+  installed: boolean;
+  location: "global" | "local" | null;
+  paths: string[];
+} {
+  const home = homedir();
+  const workingDir = cwd || process.cwd();
+  const foundPaths: string[] = [];
+
+  // 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?: string): boolean {
+  const localConfig = loadLocalConfig(cwd);
+  return !!(localConfig?.workspaceId || localConfig?.projectId);
+}
+
+export function getMemoryDir(): string {
+  const config = loadConfig();
+  if (config.memoryDir) return config.memoryDir;
+  return join(homedir(), ".harmony", "memory");
+}