hunchful-mcp 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# Hunchful MCP server
+
+Connect your AI assistant directly to a [Hunchful](https://hunchful.io) model, so
+it can **read** your collaboration model and **refine** it as it learns — instead
+of you copy-pasting links or payloads.
+
+It's a thin wrapper over Hunchful's public HTTP endpoints; no data is stored by
+the server, and it honours the same provenance-pointer contract (no transcripts,
+quotes, or third-party names).
+
+## Tools
+
+| Tool | What it does | Auth |
+| --- | --- | --- |
+| `read_model` | Read the model: hunches, confidence, refinable axis ids | none (public) |
+| `propose_refinement` | Propose changes → land in the owner's confirm queue | contribution token |
+| `apply_refinement` | Apply changes directly as one logged revision | edit token |
+
+`propose_refinement` is the safe default: the owner confirms each change. Use
+`apply_refinement` only when the owner has handed you their edit key.
+
+## Configure
+
+Set these environment variables (in your MCP client config):
+
+- `HUNCHFUL_MODEL_ID` — your model id (from `hunchful.io/m/<id>`), so tools can omit it
+- `HUNCHFUL_CONTRIBUTION_TOKEN` — scoped, propose-only key. Generate it on your model's
+  Edit page → **"let an agent contribute"**. It can only *propose*.
+- `HUNCHFUL_EDIT_TOKEN` — the model's edit key. Enables **direct** apply. Optional and
+  powerful — only set it if you want the AI to write without a confirm step. You can
+  regenerate the key anytime to revoke access.
+- `HUNCHFUL_BASE` — override the site origin (default `https://hunchful.io`).
+
+### Claude Desktop / Claude Code (`claude_desktop_config.json` or `.mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "hunchful": {
+      "command": "npx",
+      "args": ["-y", "hunchful-mcp"],
+      "env": {
+        "HUNCHFUL_MODEL_ID": "your-model-id",
+        "HUNCHFUL_CONTRIBUTION_TOKEN": "ctb_…"
+      }
+    }
+  }
+}
+```
+
+To run it from a local checkout instead of npx:
+
+```json
+{
+  "mcpServers": {
+    "hunchful": {
+      "command": "node",
+      "args": ["/absolute/path/to/hunchful/mcp-server/index.mjs"],
+      "env": { "HUNCHFUL_MODEL_ID": "your-model-id", "HUNCHFUL_CONTRIBUTION_TOKEN": "ctb_…" }
+    }
+  }
+}
+```
+
+## Install (local)
+
+```bash
+cd mcp-server
+npm install
+```
+
+## Safety
+
+- The owner stays in control: `propose_refinement` never changes anything until the
+  owner confirms; a shared edit key can be regenerated to revoke access instantly.
+- Provenance pointers only. The server rejects anything but `{patternId, direction,
+  observedAt, source}` — no free text.
+- Every applied change is recorded in the model's revision history.

package/index.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * Hunchful MCP server.
+ *
+ * Lets an AI assistant connect directly to a Hunchful model — read it, and
+ * refine it — instead of the person copy-pasting links or payloads. It's a thin,
+ * dependency-light wrapper over Hunchful's public HTTP endpoints:
+ *
+ *   read_model         GET  /m/{id}/cmp.json           (open)
+ *   propose_refinement POST /api/contribute            (contribution token → owner confirms)
+ *   apply_refinement   POST /api/apply                 (edit token → direct, one logged revision)
+ *
+ * Configure with environment variables (in your MCP client config):
+ *   HUNCHFUL_MODEL_ID            default model id, so tools can omit it
+ *   HUNCHFUL_CONTRIBUTION_TOKEN  scoped, propose-only key (Edit page → "let an agent contribute")
+ *   HUNCHFUL_EDIT_TOKEN          the model's edit key — enables direct apply (powerful; optional)
+ *   HUNCHFUL_BASE                override the site origin (default https://hunchful.io)
+ *
+ * Provenance-pointer contract only: no transcripts, quotes, or third-party names.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const BASE = (process.env.HUNCHFUL_BASE || "https://hunchful.io").replace(/\/+$/, "");
+const DEFAULT_MODEL = process.env.HUNCHFUL_MODEL_ID || "";
+const EDIT_TOKEN = process.env.HUNCHFUL_EDIT_TOKEN || "";
+const CONTRIB_TOKEN = process.env.HUNCHFUL_CONTRIBUTION_TOKEN || "";
+
+function modelIdOr(given) {
+  const id = (given || DEFAULT_MODEL || "").trim();
+  if (!id) throw new Error("No modelId given and HUNCHFUL_MODEL_ID is not set.");
+  return id;
+}
+function ok(obj) {
+  return { content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }] };
+}
+function fail(msg) {
+  return { content: [{ type: "text", text: String(msg) }], isError: true };
+}
+
+async function fetchCmp(modelId) {
+  const r = await fetch(`${BASE}/m/${encodeURIComponent(modelId)}/cmp.json`, { headers: { accept: "application/json" } });
+  if (!r.ok) throw new Error(`Couldn't read model ${modelId} (HTTP ${r.status}).`);
+  return r.json();
+}
+function normalizeItems(items) {
+  const now = new Date().toISOString();
+  return items.map((it) => ({
+    patternId: it.patternId,
+    direction: it.direction,
+    observedAt: it.observedAt || now,
+    source: it.source || "agent:mcp",
+  }));
+}
+
+const itemShape = {
+  patternId: z.string().describe("One of the model's refinable axis ids (see read_model → refinablePatternIds)."),
+  direction: z.enum(["strengthens", "weakens"]).describe("Does the evidence strengthen or weaken this hunch?"),
+  observedAt: z.string().optional().describe("ISO date the evidence was observed (defaults to now)."),
+  source: z.string().optional().describe('Provenance pointer only, e.g. "agent:claude". No free text, no names.'),
+};
+
+const server = new McpServer({ name: "hunchful", version: "1.0.0" });
+
+server.tool(
+  "read_model",
+  "Read a Hunchful collaboration model: its hunches (axis, pole, confidence), the axis ids you can refine, and how to write back. Start here.",
+  { modelId: z.string().optional().describe("Model id. Defaults to HUNCHFUL_MODEL_ID.") },
+  async ({ modelId }) => {
+    try {
+      const id = modelIdOr(modelId);
+      const doc = await fetchCmp(id);
+      return ok({
+        modelId: id,
+        libraryVersion: doc.libraryVersion,
+        hunches: (doc.hypotheses || []).map((h) => ({ patternId: h.patternId, pole: h.pole, statement: h.statement, confidence: h.confidence })),
+        refinablePatternIds: doc.contribution?.patternIds ?? (doc.hypotheses || []).map((h) => h.patternId),
+        constraints: doc.contribution?.constraints,
+        canApplyDirectly: !!EDIT_TOKEN,
+        canPropose: !!CONTRIB_TOKEN,
+      });
+    } catch (e) {
+      return fail(e.message || e);
+    }
+  }
+);
+
+server.tool(
+  "propose_refinement",
+  "Propose a refinement (provenance pointers only). It lands in the owner's queue for them to confirm — nothing changes until they do. Needs HUNCHFUL_CONTRIBUTION_TOKEN.",
+  {
+    modelId: z.string().optional(),
+    items: z.array(z.object(itemShape)).min(1).describe("Which axes to strengthen/weaken, based on what you learned."),
+  },
+  async ({ modelId, items }) => {
+    try {
+      if (!CONTRIB_TOKEN) return fail("No HUNCHFUL_CONTRIBUTION_TOKEN set. Ask the owner to generate one (their model's Edit page → \"let an agent contribute\"), or use apply_refinement with an edit token.");
+      const id = modelIdOr(modelId);
+      const doc = await fetchCmp(id).catch(() => ({}));
+      const body = { type: "hunchful.refinement", modelId: id, libraryVersion: doc.libraryVersion || "v1", contributionToken: CONTRIB_TOKEN, items: normalizeItems(items) };
+      const r = await fetch(`${BASE}/api/contribute`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+      const j = await r.json().catch(() => ({}));
+      if (!r.ok) return fail(j.debugMessage || j.error || `HTTP ${r.status}`);
+      return ok({ status: "pending", ...j, note: "The owner confirms this in their refine page before it applies." });
+    } catch (e) {
+      return fail(e.message || e);
+    }
+  }
+);
+
+server.tool(
+  "apply_refinement",
+  "Apply a refinement directly as one logged revision (append evidence, nudge confidence). Needs HUNCHFUL_EDIT_TOKEN — the owner's key. Prefer propose_refinement unless the owner asked you to write directly.",
+  {
+    modelId: z.string().optional(),
+    items: z.array(z.object(itemShape)).min(1),
+  },
+  async ({ modelId, items }) => {
+    try {
+      if (!EDIT_TOKEN) return fail("No HUNCHFUL_EDIT_TOKEN set. Direct apply needs the owner's edit key. Use propose_refinement instead (with a contribution token).");
+      const id = modelIdOr(modelId);
+      const doc = await fetchCmp(id).catch(() => ({}));
+      const body = { type: "hunchful.refinement", modelId: id, libraryVersion: doc.libraryVersion || "v1", items: normalizeItems(items), editToken: EDIT_TOKEN };
+      const r = await fetch(`${BASE}/api/apply`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+      const j = await r.json().catch(() => ({}));
+      if (!r.ok) return fail(j.debugMessage || j.error || `HTTP ${r.status}`);
+      return ok(j);
+    } catch (e) {
+      return fail(e.message || e);
+    }
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "hunchful-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Hunchful — let an AI read and refine a Hunchful collaboration model directly, instead of copy-pasting links.",
+  "type": "module",
+  "bin": {
+    "hunchful-mcp": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "zod": "^3.23.8"
+  },
+  "license": "MIT",
+  "author": "Filip Nilsson",
+  "repository": "github:filinils/cognitive-model-protocol"
+}