@gethmy/mcp 1.0.0 → 2.1.0

package/src/graph-expansion.ts

@@ -0,0 +1,234 @@
+/**
+ * Auto Knowledge Graph Expansion
+ *
+ * When a new entity is created, find semantically similar existing entities
+ * and automatically create `relates_to` relations between them.
+ */
+
+import type { HarmonyApiClient } from "./api-client.js";
+
+/**
+ * Automatically expand the knowledge graph by linking a newly-created entity
+ * to semantically similar existing entities via `relates_to` relations.
+ *
+ * Non-fatal: errors are caught and silently ignored so callers are never blocked.
+ */
+export async function autoExpandGraph(
+  client: HarmonyApiClient,
+  entityId: string,
+  title: string,
+  content: string,
+  _tags: string[],
+  workspaceId: string,
+  projectId?: string,
+  maxRelations: number = 5,
+): Promise<{ relationsCreated: number }> {
+  try {
+    // Build a search query from the title + first 200 chars of content
+    const contentSnippet = content.slice(0, 200).trim();
+    const query = [title, contentSnippet].filter(Boolean).join(" ");
+
+    let candidates: Array<{ id: string }> = [];
+
+    // First attempt
+    const { entities } = await client.searchMemoryEntities(workspaceId, query, {
+      project_id: projectId,
+      limit: 20,
+    });
+
+    candidates = (entities as Array<{ id: string }>)
+      .filter((e) => e.id !== entityId)
+      .slice(0, maxRelations);
+
+    // Retry once after 2s if no candidates found (handles embedding generation race)
+    if (candidates.length === 0) {
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      const retry = await client.searchMemoryEntities(workspaceId, query, {
+        project_id: projectId,
+        limit: 20,
+      });
+      candidates = (retry.entities as Array<{ id: string }>)
+        .filter((e) => e.id !== entityId)
+        .slice(0, maxRelations);
+    }
+
+    let relationsCreated = 0;
+    for (const candidate of candidates) {
+      try {
+        await client.createMemoryRelation({
+          source_id: entityId,
+          target_id: candidate.id,
+          relation_type: "relates_to",
+          confidence: 0.6,
+        });
+        relationsCreated++;
+      } catch (err: unknown) {
+        // Silently skip 409 Conflict (relation already exists) and other errors
+        const status = (err as { status?: number })?.status;
+        if (status !== 409) {
+          // Non-409 errors are still non-fatal; just skip
+        }
+      }
+    }
+
+    return { relationsCreated };
+  } catch {
+    // Never block callers due to graph expansion failures
+    return { relationsCreated: 0 };
+  }
+}
+
+export interface SimilarEntity {
+  id: string;
+  type: string;
+  title: string;
+  content: string;
+  confidence: number;
+  rrf_score?: number;
+  tags?: string[];
+}
+
+/**
+ * Find entities semantically similar to the given title+content using
+ * hybrid FTS+vector search. Returns entities sorted by relevance.
+ */
+export async function findSimilarEntities(
+  client: HarmonyApiClient,
+  title: string,
+  content: string,
+  workspaceId: string,
+  options?: {
+    projectId?: string;
+    limit?: number;
+    minRrfScore?: number;
+    excludeIds?: string[];
+    type?: string;
+  },
+): Promise<SimilarEntity[]> {
+  const contentSnippet = content.slice(0, 200).trim();
+  const query = [title, contentSnippet].filter(Boolean).join(" ");
+
+  try {
+    const { entities } = await client.searchMemoryEntities(workspaceId, query, {
+      project_id: options?.projectId,
+      limit: options?.limit ?? 20,
+      type: options?.type,
+    });
+
+    const minScore = options?.minRrfScore ?? 0;
+    const excludeSet = new Set(options?.excludeIds || []);
+
+    return (
+      entities as Array<{
+        id: string;
+        type: string;
+        title: string;
+        content: string;
+        confidence: number;
+        rrf_score?: number;
+        tags?: string[];
+      }>
+    ).filter((e) => {
+      if (excludeSet.has(e.id)) return false;
+      if (minScore > 0 && (e.rrf_score ?? 0) < minScore) return false;
+      return true;
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Causal lookup table: maps an entity type to the target types it should
+ * be linked to, along with the relation type and direction.
+ *
+ * "forward" means source=newEntity → target=match.
+ * "reverse" means source=match → target=newEntity.
+ */
+const CAUSAL_LOOKUP: Array<{
+  sourceType: string;
+  targetType: string;
+  relation: string;
+  direction: "forward" | "reverse";
+}> = [
+  {
+    sourceType: "error",
+    targetType: "solution",
+    relation: "resolved_by",
+    direction: "forward",
+  },
+  {
+    sourceType: "solution",
+    targetType: "error",
+    relation: "resolved_by",
+    direction: "reverse",
+  },
+  {
+    sourceType: "lesson",
+    targetType: "error",
+    relation: "learned_from",
+    direction: "forward",
+  },
+];
+
+/**
+ * Link a newly created entity to causally-related entities of *other* types.
+ *
+ * For example, a new `error` entity gets linked to similar `solution` entities
+ * via `resolved_by`, enabling agents to discover "what solved similar problems."
+ *
+ * Non-fatal: all errors are caught silently.
+ */
+export async function linkCrossTypeNeighbors(
+  client: HarmonyApiClient,
+  entityId: string,
+  entityType: string,
+  title: string,
+  content: string,
+  workspaceId: string,
+  projectId?: string,
+): Promise<{ relationsCreated: number }> {
+  const rules = CAUSAL_LOOKUP.filter((r) => r.sourceType === entityType);
+  if (rules.length === 0) return { relationsCreated: 0 };
+
+  let relationsCreated = 0;
+
+  for (const rule of rules) {
+    try {
+      const matches = await findSimilarEntities(
+        client,
+        title,
+        content,
+        workspaceId,
+        {
+          projectId,
+          limit: 10,
+          minRrfScore: 0.04,
+          excludeIds: [entityId],
+          type: rule.targetType,
+        },
+      );
+
+      // Cap at 3 matches per target type
+      for (const match of matches.slice(0, 3)) {
+        const sourceId = rule.direction === "forward" ? entityId : match.id;
+        const targetId = rule.direction === "forward" ? match.id : entityId;
+        try {
+          await client.createMemoryRelation({
+            source_id: sourceId,
+            target_id: targetId,
+            relation_type: rule.relation,
+            confidence: 0.65,
+          });
+          relationsCreated++;
+        } catch {
+          // Skip duplicate/failed relations silently
+        }
+      }
+    } catch {
+      // Non-fatal: search failure for one rule shouldn't block others
+    }
+  }
+
+  return { relationsCreated };
+}

package/src/http.ts

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+
+/**
+ * HTTP REST Adapter for Harmony MCP
+ *
+ * This provides a REST API that forwards requests to the Harmony API.
+ * It accepts Bearer tokens (JWT) or X-API-Key headers for authentication.
+ *
+ * This adapter is useful for non-MCP clients that want to interact with
+ * Harmony via HTTP instead of the MCP stdio protocol.
+ */
+
+import { serve } from "bun";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { loadConfig } from "./config.js";
+
+const app = new Hono();
+
+// CORS configuration
+app.use(
+  "/*",
+  cors({
+    origin: [
+      "https://gethmy.com",
+      "http://localhost:8080",
+      "http://localhost:3000",
+    ],
+    allowMethods: ["GET", "POST", "PATCH", "DELETE", "OPTIONS"],
+    allowHeaders: ["Content-Type", "Authorization", "X-API-Key"],
+  }),
+);
+
+// Get API URL from config or use default
+function getApiUrl(): string {
+  const config = loadConfig();
+  return config.apiUrl;
+}
+
+// Forward request to Harmony API
+async function forwardToApi(
+  method: string,
+  path: string,
+  authHeader: string | undefined,
+  apiKey: string | undefined,
+  body?: unknown,
+): Promise<{ data: unknown; status: number }> {
+  const apiUrl = getApiUrl();
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+
+  // Use API key if provided, otherwise forward the Authorization header
+  if (apiKey) {
+    headers["X-API-Key"] = apiKey;
+  } else if (authHeader) {
+    headers.Authorization = authHeader;
+  } else {
+    throw new Error("Unauthorized: Missing API key or Authorization header");
+  }
+
+  const response = await fetch(`${apiUrl}${path}`, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  const data = await response.json();
+  return { data, status: response.status };
+}
+
+// Health check
+app.get("/health", (c) =>
+  c.json({ status: "ok", service: "harmony-mcp-http" }),
+);
+
+// List available endpoints
+app.get("/", (c) =>
+  c.json({
+    service: "Harmony MCP HTTP Adapter",
+    endpoints: {
+      workspaces: {
+        list: "GET /workspaces",
+        members: "GET /workspaces/:id/members",
+        projects: "GET /workspaces/:id/projects",
+      },
+      board: {
+        get: "GET /board/:projectId",
+      },
+      cards: {
+        create: "POST /cards",
+        get: "GET /cards/:id",
+        getByShortId: "GET /projects/:projectId/cards/:shortId",
+        update: "PATCH /cards/:id",
+        delete: "DELETE /cards/:id",
+        move: "POST /cards/:id/move",
+        search: "GET /search?q=query",
+      },
+      columns: {
+        create: "POST /columns",
+        update: "PATCH /columns/:id",
+        delete: "DELETE /columns/:id",
+      },
+      labels: {
+        create: "POST /labels",
+        addToCard: "POST /cards/:id/labels",
+        removeFromCard: "DELETE /cards/:id/labels/:labelId",
+      },
+      subtasks: {
+        create: "POST /subtasks",
+        toggle: "POST /subtasks/:id/toggle",
+        delete: "DELETE /subtasks/:id",
+      },
+      nlu: {
+        process: "POST /nlu",
+      },
+    },
+    authentication: "Include X-API-Key header or Authorization: Bearer <token>",
+  }),
+);
+
+// Generic proxy handler
+async function handleRequest(
+  c: {
+    req: {
+      method: string;
+      url: string;
+      header: (name: string) => string | undefined;
+    };
+    json: () => Promise<unknown>;
+  },
+  method: string,
+  path: string,
+) {
+  try {
+    const authHeader = c.req.header("Authorization");
+    const apiKey = c.req.header("X-API-Key");
+
+    let body: unknown;
+    if (["POST", "PATCH", "PUT"].includes(method)) {
+      try {
+        body = await c.json();
+      } catch {
+        // No body or invalid JSON
+      }
+    }
+
+    const { data, status } = await forwardToApi(
+      method,
+      path,
+      authHeader,
+      apiKey,
+      body,
+    );
+    return new Response(JSON.stringify(data), {
+      status,
+      headers: { "Content-Type": "application/json" },
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const status = message.includes("Unauthorized") ? 401 : 500;
+    return new Response(JSON.stringify({ error: message }), {
+      status,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+}
+
+// Workspaces
+app.get("/workspaces", (c) => handleRequest(c, "GET", "/workspaces"));
+app.get("/workspaces/:id/members", (c) =>
+  handleRequest(c, "GET", `/workspaces/${c.req.param("id")}/members`),
+);
+app.get("/workspaces/:id/projects", (c) =>
+  handleRequest(c, "GET", `/workspaces/${c.req.param("id")}/projects`),
+);
+
+// Projects
+app.get("/projects", (c) => {
+  const workspaceId = new URL(c.req.url).searchParams.get("workspace_id");
+  return handleRequest(c, "GET", `/projects?workspace_id=${workspaceId}`);
+});
+
+// Get card by short ID: GET /projects/:projectId/cards/:shortId
+app.get("/projects/:projectId/cards/:shortId", (c) =>
+  handleRequest(
+    c,
+    "GET",
+    `/projects/${c.req.param("projectId")}/cards/${c.req.param("shortId")}`,
+  ),
+);
+
+// Board
+app.get("/board/:projectId", (c) =>
+  handleRequest(c, "GET", `/board/${c.req.param("projectId")}`),
+);
+
+// Cards
+app.get("/cards/:id", (c) =>
+  handleRequest(c, "GET", `/cards/${c.req.param("id")}`),
+);
+app.post("/cards", (c) => handleRequest(c, "POST", "/cards"));
+app.patch("/cards/:id", (c) =>
+  handleRequest(c, "PATCH", `/cards/${c.req.param("id")}`),
+);
+app.delete("/cards/:id", (c) =>
+  handleRequest(c, "DELETE", `/cards/${c.req.param("id")}`),
+);
+app.post("/cards/:id/move", (c) =>
+  handleRequest(c, "POST", `/cards/${c.req.param("id")}/move`),
+);
+app.post("/cards/:id/labels", (c) =>
+  handleRequest(c, "POST", `/cards/${c.req.param("id")}/labels`),
+);
+app.delete("/cards/:id/labels/:labelId", (c) =>
+  handleRequest(
+    c,
+    "DELETE",
+    `/cards/${c.req.param("id")}/labels/${c.req.param("labelId")}`,
+  ),
+);
+
+// Search
+app.get("/search", (c) => {
+  const params = new URL(c.req.url).searchParams;
+  return handleRequest(c, "GET", `/search?${params.toString()}`);
+});
+
+// Columns
+app.post("/columns", (c) => handleRequest(c, "POST", "/columns"));
+app.patch("/columns/:id", (c) =>
+  handleRequest(c, "PATCH", `/columns/${c.req.param("id")}`),
+);
+app.delete("/columns/:id", (c) =>
+  handleRequest(c, "DELETE", `/columns/${c.req.param("id")}`),
+);
+
+// Labels
+app.post("/labels", (c) => handleRequest(c, "POST", "/labels"));
+
+// Subtasks
+app.post("/subtasks", (c) => handleRequest(c, "POST", "/subtasks"));
+app.post("/subtasks/:id/toggle", (c) =>
+  handleRequest(c, "POST", `/subtasks/${c.req.param("id")}/toggle`),
+);
+app.delete("/subtasks/:id", (c) =>
+  handleRequest(c, "DELETE", `/subtasks/${c.req.param("id")}`),
+);
+
+// NLU
+app.post("/nlu", (c) => handleRequest(c, "POST", "/nlu"));
+app.post("/nlu/process", (c) => handleRequest(c, "POST", "/nlu"));
+
+// Start server
+const port = parseInt(process.env.PORT || "3001", 10);
+
+console.log(`Starting Harmony MCP HTTP adapter on port ${port}...`);
+
+serve({
+  fetch: app.fetch,
+  port,
+});
+
+console.log(`Harmony MCP HTTP adapter running at http://localhost:${port}`);

package/src/index.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { HarmonyMCPServer } from "./server.js";
+
+const server = new HarmonyMCPServer();
+server.run().catch((error) => {
+  console.error("Failed to start MCP server:", error);
+  process.exit(1);
+});

package/src/lifecycle-maintenance.ts

@@ -0,0 +1,120 @@
+/**
+ * Automatic Memory Lifecycle Maintenance
+ *
+ * Runs at session end to enforce decay/archival rules:
+ * - Archive entities with confidence < 0.3
+ * - Delete stale drafts (>30 days old with low decay score)
+ * - Auto-promote eligible entities (draft→episode, episode→reference)
+ *
+ * All operations are non-fatal — failures are logged but never block session end.
+ */
+
+import { evaluateLifecycle } from "@harmony/memory";
+import type { HarmonyApiClient } from "./api-client.js";
+
+interface MemoryEntity {
+  id: string;
+  title: string;
+  memory_tier: "draft" | "episode" | "reference";
+  confidence: number;
+  access_count: number;
+  last_accessed_at: string | null;
+  created_at: string;
+}
+
+export interface MaintenanceResult {
+  archived: number;
+  pruned: number;
+  promoted: number;
+  reviewed: number;
+  errors: number;
+}
+
+/**
+ * Run lifecycle maintenance for a workspace.
+ * Called automatically at session end alongside consolidation.
+ */
+export async function runLifecycleMaintenance(
+  client: HarmonyApiClient,
+  workspaceId: string,
+  projectId?: string,
+): Promise<MaintenanceResult> {
+  const result: MaintenanceResult = {
+    archived: 0,
+    pruned: 0,
+    promoted: 0,
+    reviewed: 0,
+    errors: 0,
+  };
+
+  let entities: MemoryEntity[];
+  try {
+    const listResult = await client.listMemoryEntities({
+      workspace_id: workspaceId,
+      project_id: projectId,
+      limit: 200,
+    });
+    entities = (listResult.entities || []) as MemoryEntity[];
+  } catch {
+    return result;
+  }
+
+  if (entities.length === 0) return result;
+
+  const now = Date.now();
+  const STALE_DRAFT_MAX_AGE_DAYS = 30;
+
+  for (const entity of entities) {
+    try {
+      const lifecycle = evaluateLifecycle(entity);
+
+      // 1. Archive low-confidence entities (confidence < 0.3)
+      if (lifecycle.shouldArchive) {
+        await client.deleteMemoryEntity(entity.id);
+        result.archived++;
+        continue;
+      }
+
+      // 2. Prune stale drafts (>30 days old with low decay score)
+      if (entity.memory_tier === "draft") {
+        const ageDays =
+          (now - new Date(entity.created_at).getTime()) / (1000 * 60 * 60 * 24);
+        if (ageDays > STALE_DRAFT_MAX_AGE_DAYS && lifecycle.decay.score < 0.3) {
+          await client.deleteMemoryEntity(entity.id);
+          result.pruned++;
+          continue;
+        }
+      }
+
+      // 3. Auto-promote eligible entities
+      if (lifecycle.promotion.eligible && lifecycle.promotion.targetTier) {
+        await client.updateMemoryEntity(entity.id, {
+          memory_tier: lifecycle.promotion.targetTier,
+          metadata: {
+            promoted_at: new Date().toISOString(),
+            promotion_reason: lifecycle.promotion.reason,
+            promoted_from: entity.memory_tier,
+          },
+        });
+        result.promoted++;
+        continue;
+      }
+
+      // 4. Flag stale entities for review (>90 days, <3 accesses)
+      if (lifecycle.shouldFlagForReview) {
+        await client.updateMemoryEntity(entity.id, {
+          metadata: {
+            needs_review: true,
+            review_reason: lifecycle.reviewReason,
+            flagged_at: new Date().toISOString(),
+          },
+        });
+        result.reviewed++;
+      }
+    } catch {
+      result.errors++;
+    }
+  }
+
+  return result;
+}