@gethmy/mcp 2.5.1 → 2.5.4

package/dist/index.js

@@ -1311,6 +1311,17 @@ class HarmonyApiClient {
     }
     throw lastError || new Error("Request failed after retries");
   }
+  async fetchSkillsVersion() {
+    return this.request("GET", "/skills/version");
+  }
+  async fetchSkill(name) {
+    return this.request("GET", `/skills/${encodeURIComponent(name)}`);
+  }
+  async recordSkillInvocation(name) {
+    try {
+      await this.request("POST", "/skills/telemetry", { name });
+    } catch {}
+  }
   async listWorkspaces() {
     return this.request("GET", "/workspaces");
   }
@@ -3542,6 +3553,22 @@ var RESOURCES = [
     mimeType: "application/json"
   }
 ];
+async function listResourcesDynamic(deps) {
+  if (!deps.isConfigured())
+    return RESOURCES;
+  try {
+    const versionInfo = await deps.getClient().fetchSkillsVersion();
+    const skillResources = versionInfo.skills.filter((name) => name !== "hmy-update-check").map((name) => ({
+      uri: `harmony://skills/${name}`,
+      name: `Skill: ${name}`,
+      description: `Harmony skill (SKILL.md) — version ${versionInfo.version}`,
+      mimeType: "text/markdown"
+    }));
+    return [...RESOURCES, ...skillResources];
+  } catch {
+    return RESOURCES;
+  }
+}
 async function runEndSessionPipeline(client3, _deps, cardId, sessionStatus) {
   try {
     const { card } = await client3.getCard(cardId);
@@ -3609,7 +3636,7 @@ function registerHandlers(server, deps) {
     }
   });
   server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-    resources: RESOURCES
+    resources: await listResourcesDynamic(deps)
   }));
   server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     const { uri } = request.params;
@@ -3628,6 +3655,26 @@ function registerHandlers(server, deps) {
         ]
       };
     }
+    const SKILL_URI_RE = /^harmony:\/\/skills\/([a-z0-9][a-z0-9-]*[a-z0-9])$/;
+    const skillMatch = uri.match(SKILL_URI_RE);
+    if (skillMatch) {
+      const name = skillMatch[1];
+      if (!deps.isConfigured()) {
+        throw new Error(`Cannot read skill "${name}": Harmony MCP server is not configured. Run \`hmy-mcp setup\`.`);
+      }
+      const client3 = deps.getClient();
+      client3.recordSkillInvocation(name);
+      const fetched = await client3.fetchSkill(name);
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "text/markdown",
+            text: fetched.content
+          }
+        ]
+      };
+    }
     throw new Error(`Unknown resource: ${uri}`);
   });
 }

package/dist/lib/api-client.js

@@ -918,6 +918,17 @@ class HarmonyApiClient {
     }
     throw lastError || new Error("Request failed after retries");
   }
+  async fetchSkillsVersion() {
+    return this.request("GET", "/skills/version");
+  }
+  async fetchSkill(name) {
+    return this.request("GET", `/skills/${encodeURIComponent(name)}`);
+  }
+  async recordSkillInvocation(name) {
+    try {
+      await this.request("POST", "/skills/telemetry", { name });
+    } catch {}
+  }
   async listWorkspaces() {
     return this.request("GET", "/workspaces");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.5.1",
+  "version": "2.5.4",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"

package/src/api-client.ts

@@ -323,6 +323,62 @@ export class HarmonyApiClient {
     throw lastError || new Error("Request failed after retries");
   }
 
+  // ============ SKILLS OPERATIONS ============
+
+  /**
+   * GET /v1/skills/version — unauthenticated discovery endpoint.
+   * Returns aggregate version, the list of skill names, sha256 integrity
+   * hashes, and the ed25519 public key for signature verification.
+   */
+  async fetchSkillsVersion(): Promise<{
+    version: string;
+    skills: string[];
+    integrity: Record<string, string>;
+    publicKey: string;
+  }> {
+    return this.request("GET", "/skills/version");
+  }
+
+  /**
+   * GET /v1/skills/{name} — authenticated content fetch.
+   * Returns rendered SKILL.md (frontmatter + body) ready to install.
+   *
+   * Phase 3b: `skillVersion` (per-skill integer) is returned alongside the
+   * legacy aggregate `version` string so refreshSkills can compare per-skill
+   * instead of treating any global bump as "everything stale."
+   */
+  async fetchSkill(name: string): Promise<{
+    name: string;
+    version: string;
+    skillVersion?: number;
+    content: string;
+    sha256: string;
+    signature: string;
+  }> {
+    return this.request("GET", `/skills/${encodeURIComponent(name)}`);
+  }
+
+  /**
+   * POST /v1/skills/telemetry — fire-and-forget activation signal.
+   * Called from the ReadResourceRequest handler when an agent reads
+   * a harmony://skills/<name> resource. Increments invocation_count +
+   * sets last_used = now() on the matching skill_resource row.
+   *
+   * Best-effort: returns void; never throws. If the endpoint doesn't
+   * exist yet (pre-Phase-2 backend), or the network is flaky, the
+   * activation is dropped silently. The skill content read itself
+   * is NOT gated on this call succeeding.
+   */
+  async recordSkillInvocation(name: string): Promise<void> {
+    try {
+      await this.request("POST", "/skills/telemetry", { name });
+    } catch {
+      // Fire-and-forget: any failure (404 if endpoint not deployed yet,
+      // 401 if API key rotated, network timeout) is swallowed so the
+      // caller can proceed with serving content.
+    }
+  }
+
   // ============ WORKSPACE OPERATIONS ============
 
   async listWorkspaces(): Promise<{ workspaces: unknown[] }> {

package/src/server.ts

@@ -1530,6 +1530,38 @@ export const RESOURCES = [
   },
 ];
 
+/**
+ * Build the dynamic resource list. Skill resources (harmony://skills/<name>)
+ * are derived at request time from /v1/skills/version so the list always
+ * matches what the agent will get on read. Phase 1 of card #162 — the
+ * ReadResourceRequest on harmony://skills/<name> is the activation signal
+ * for skill telemetry.
+ *
+ * Offline / unauthenticated → returns just the static RESOURCES. Agents
+ * that can't reach the API still see the context resource and any error
+ * surfaces on read rather than list (matches the existing offline-safe
+ * posture of refreshSkills()).
+ */
+async function listResourcesDynamic(deps: ToolDeps): Promise<typeof RESOURCES> {
+  if (!deps.isConfigured()) return RESOURCES;
+  try {
+    const versionInfo = await deps.getClient().fetchSkillsVersion();
+    // hmy-update-check is a shell script served on the same URL but is
+    // not an installable SKILL.md; don't surface it as an MCP resource.
+    const skillResources = versionInfo.skills
+      .filter((name) => name !== "hmy-update-check")
+      .map((name) => ({
+        uri: `harmony://skills/${name}`,
+        name: `Skill: ${name}`,
+        description: `Harmony skill (SKILL.md) — version ${versionInfo.version}`,
+        mimeType: "text/markdown",
+      }));
+    return [...RESOURCES, ...skillResources];
+  } catch {
+    return RESOURCES;
+  }
+}
+
 /**
  * Reusable end-session pipeline.
  * Called by both explicit harmony_end_agent_session and auto-session timeout/card-switch.
@@ -1654,9 +1686,10 @@ export function registerHandlers(server: Server, deps: ToolDeps): void {
     }
   });
 
-  // List resources
+  // List resources — dynamic so harmony://skills/<name> entries reflect
+  // the live /v1/skills/version payload at request time.
   server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-    resources: RESOURCES,
+    resources: await listResourcesDynamic(deps),
   }));
 
   // Read resource
@@ -1683,6 +1716,37 @@ export function registerHandlers(server: Server, deps: ToolDeps): void {
       };
     }
 
+    // harmony://skills/<name> — Phase 1 of card #162. This read IS the
+    // activation event: agent matched the skill's description, harness
+    // calls ReadResource, we fire fire-and-forget telemetry before
+    // returning the body. recordSkillInvocation() swallows all errors
+    // so a telemetry outage never blocks skill delivery.
+    const SKILL_URI_RE = /^harmony:\/\/skills\/([a-z0-9][a-z0-9-]*[a-z0-9])$/;
+    const skillMatch = uri.match(SKILL_URI_RE);
+    if (skillMatch) {
+      const name = skillMatch[1];
+      if (!deps.isConfigured()) {
+        throw new Error(
+          `Cannot read skill "${name}": Harmony MCP server is not configured. Run \`hmy-mcp setup\`.`,
+        );
+      }
+      const client = deps.getClient();
+      // Fire-and-forget BEFORE awaiting the content fetch so a slow
+      // telemetry endpoint never delays skill delivery. The promise
+      // is intentionally dropped (caught inside recordSkillInvocation).
+      void client.recordSkillInvocation(name);
+      const fetched = await client.fetchSkill(name);
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "text/markdown",
+            text: fetched.content,
+          },
+        ],
+      };
+    }
+
     throw new Error(`Unknown resource: ${uri}`);
   });
 }