@gethmy/mcp 1.0.0 → 2.1.0

package/dist/lib/graph-expansion.js

@@ -0,0 +1,163 @@
+/**
+ * Auto Knowledge Graph Expansion
+ *
+ * When a new entity is created, find semantically similar existing entities
+ * and automatically create `relates_to` relations between them.
+ */
+/**
+ * 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, entityId, title, content, _tags, workspaceId, projectId, maxRelations = 5) {
+    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 = [];
+        // First attempt
+        const { entities } = await client.searchMemoryEntities(workspaceId, query, {
+            project_id: projectId,
+            limit: 20,
+        });
+        candidates = entities
+            .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
+                .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) {
+                // Silently skip 409 Conflict (relation already exists) and other errors
+                const status = err?.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 };
+    }
+}
+/**
+ * Find entities semantically similar to the given title+content using
+ * hybrid FTS+vector search. Returns entities sorted by relevance.
+ */
+export async function findSimilarEntities(client, title, content, workspaceId, options) {
+    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.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 = [
+    {
+        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, entityId, entityType, title, content, workspaceId, projectId) {
+    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/dist/lib/http.js

@@ -0,0 +1,174 @@
+#!/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() {
+    const config = loadConfig();
+    return config.apiUrl;
+}
+// Forward request to Harmony API
+async function forwardToApi(method, path, authHeader, apiKey, body) {
+    const apiUrl = getApiUrl();
+    const headers = {
+        "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, method, path) {
+    try {
+        const authHeader = c.req.header("Authorization");
+        const apiKey = c.req.header("X-API-Key");
+        let body;
+        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/dist/lib/index.js

@@ -0,0 +1,7 @@
+#!/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/dist/lib/lifecycle-maintenance.js

@@ -0,0 +1,88 @@
+/**
+ * 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";
+/**
+ * Run lifecycle maintenance for a workspace.
+ * Called automatically at session end alongside consolidation.
+ */
+export async function runLifecycleMaintenance(client, workspaceId, projectId) {
+    const result = {
+        archived: 0,
+        pruned: 0,
+        promoted: 0,
+        reviewed: 0,
+        errors: 0,
+    };
+    let entities;
+    try {
+        const listResult = await client.listMemoryEntities({
+            workspace_id: workspaceId,
+            project_id: projectId,
+            limit: 200,
+        });
+        entities = (listResult.entities || []);
+    }
+    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;
+}