mindgraph-mcp 0.6.1 → 0.7.1

package/README.md

@@ -0,0 +1,128 @@
+# mindgraph-mcp
+
+[![npm](https://img.shields.io/npm/v/mindgraph-mcp)](https://www.npmjs.com/package/mindgraph-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Model Context Protocol server for [MindGraph](https://mindgraph.cloud) — plug your persistent, structured knowledge graph into Claude Desktop, Claude Code, and any MCP-compatible client.
+
+## Install
+
+The fastest way to install is the interactive setup:
+
+```bash
+npx mindgraph-mcp init
+```
+
+This walks you through:
+
+1. Sign in via browser (or paste an existing API key).
+2. Pick your client — Claude Desktop, Claude Code, or both.
+3. The server is wired up automatically; restart your client to activate.
+
+Don't have a MindGraph account yet? Sign up at [mindgraph.cloud](https://mindgraph.cloud) first.
+
+### Manual install
+
+```bash
+# Claude Desktop
+npx mindgraph-mcp install --api-key mg_your_key_here
+
+# Claude Code
+npx mindgraph-mcp install-code --api-key mg_your_key_here
+```
+
+Or drop this into your Claude Desktop config by hand (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "mindgraph": {
+      "command": "npx",
+      "args": ["-y", "mindgraph-mcp@latest"],
+      "env": {
+        "MINDGRAPH_API_KEY": "mg_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## What You Get
+
+**7 tools** covering the full knowledge-graph workflow:
+
+| Tool | Purpose |
+|------|---------|
+| `mindgraph_capture` | Entities, observations, sources, snippets, concepts, journal entries |
+| `mindgraph_reason` | Claims with evidence, open questions, hypotheses, theories, anomalies |
+| `mindgraph_commit` | Goals, projects, decisions, options, milestones |
+| `mindgraph_plan` | Plans, tasks, procedures, governance policies, risk assessments, executions |
+| `mindgraph_retrieve` | BM25 / semantic / hybrid search, traversal (chain, neighborhood, path, subgraph), document index |
+| `mindgraph_ingest` | Chunk / document / session ingestion with LLM-powered extraction |
+| `mindgraph_synthesize` | Project-scoped cross-document synthesis — mine signals, spawn Article-generation jobs |
+
+**7 prompt templates** for common workflows:
+
+`graph-summary`, `active-goals`, `open-questions`, `review-contradictions`, `knowledge-about`, `daily-briefing`, `capture-conversation`.
+
+**Resources** (static + dynamic URIs):
+
+- `mindgraph://stats`, `mindgraph://goals`, `mindgraph://questions`, `mindgraph://contradictions`, `mindgraph://decisions`
+- `mindgraph://node/{uid}` — a node with all its outgoing and incoming edges
+- `mindgraph://search/{query}` — BM25 search results
+- `mindgraph://layer/{layer}` — all nodes in a cognitive layer (reality, epistemic, intent, action, memory, agent)
+
+## CLI
+
+```text
+mindgraph-mcp                  Start the MCP server (stdio transport)
+mindgraph-mcp init             Interactive setup
+mindgraph-mcp install          Install into Claude Desktop config
+mindgraph-mcp install-code     Install into Claude Code
+mindgraph-mcp uninstall        Remove from Claude Desktop config
+mindgraph-mcp uninstall-code   Remove from Claude Code
+mindgraph-mcp status           Show installation status
+```
+
+Options: `--api-key <key>`, `--base-url <url>`, `--help`.
+
+## Environment
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MINDGRAPH_API_KEY` | *(required)* | Your MindGraph API key (`mg_…`) |
+| `MINDGRAPH_BASE_URL` | `https://api.mindgraph.cloud` | Override for self-hosted deployments |
+| `MINDGRAPH_AGENT_ID` | `mcp` | Stamped onto every node/edge written by the MCP — useful for provenance across multiple agents |
+| `MINDGRAPH_ORG_ID` | *(unset)* | Pin operations to a specific organization when a key has access to more than one |
+
+## Usage in Claude
+
+Once installed, start asking Claude about your knowledge graph naturally:
+
+> "What did I capture about climate policy last week?"
+> "Summarize my active goals and open decisions."
+> "Ingest this PDF and extract the main claims."
+> "Find entities mentioned across multiple project documents, then spin up a synthesis."
+
+The server auto-injects `agent_id: "mcp"` on every write so you always know which nodes came from your MCP sessions.
+
+## Architecture
+
+This MCP server is a thin wrapper over the [mindgraph](https://www.npmjs.com/package/mindgraph) TypeScript SDK. It exposes cognitive-layer abstractions (Reality, Epistemic, Intent, Action, Memory, Agent) as consolidated tools rather than one-tool-per-endpoint, which keeps the tool surface compact enough for high-quality tool selection by the model.
+
+Search strategy is **keyword-first**: `mindgraph_retrieve` defaults to `action: "context"` which uses BM25. Escalate to `semantic` or `hybrid` only when keywords fail.
+
+## Development
+
+```bash
+git clone https://github.com/shuruheel/mindgraph-mcp
+cd mindgraph-mcp
+npm install
+npm run build            # build with tsup (CJS + .d.ts)
+npm run lint             # tsc --noEmit
+npm run dev              # tsup --watch
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -53,6 +53,8 @@ async function handleTool(client2, name, args) {
         return await handleRetrieve(client2, args);
       case "mindgraph_ingest":
         return await handleIngest(client2, args);
+      case "mindgraph_synthesize":
+        return await handleSynthesize(client2, args);
       default:
         return err(`Unknown tool: ${name}`);
     }
@@ -566,6 +568,26 @@ async function handleIngest(client2, args) {
       return err(`Unknown ingest action: ${action}`);
   }
 }
+async function handleSynthesize(client2, args) {
+  const { action, project_uid, signals, target_types, job_id } = args;
+  switch (action) {
+    case "signals":
+      if (!project_uid)
+        return err("project_uid is required for action='signals'");
+      return ok(
+        await client2.signals(project_uid, { signals, target_types })
+      );
+    case "run":
+      if (!project_uid)
+        return err("project_uid is required for action='run'");
+      return ok(await client2.runSynthesis(project_uid));
+    case "job_status":
+      if (!job_id) return err("job_id is required for action='job_status'");
+      return ok(await client2.getJob(job_id));
+    default:
+      return err(`Unknown synthesize action: ${action}`);
+  }
+}
 var TOOLS;
 var init_tools = __esm({
   "src/tools.ts"() {
@@ -1011,6 +1033,41 @@ var init_tools = __esm({
           },
           required: ["action"]
         }
+      },
+      {
+        name: "mindgraph_synthesize",
+        description: "Work with Projects \u2014 scoped document corpora \u2014 and run cross-document synthesis over them. Use 'signals' to mine structural signals (entity bridges, claim hubs, theory support gaps, concept clusters, analogy candidates, dialectical pairs) without any LLM calls; useful for orientation before a full synthesis. Use 'run' to spawn a background synthesis job that turns the top idea clusters into Article nodes linked via Covers edges. Both operate on a Project's corpus, where documents are linked to the Project via PartOfProject edges (create the project with mindgraph_commit action 'project', then link docs via the ingest flow or add_link). Use 'job_status' to poll a synthesis job.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            action: {
+              type: "string",
+              enum: ["signals", "run", "job_status"],
+              description: "Synthesis action"
+            },
+            project_uid: {
+              type: "string",
+              description: "UID of the Project node (required for signals/run)"
+            },
+            signals: {
+              type: "string",
+              description: "Comma-separated subset of signal names to compute, e.g. 'clustered_claim_hubs,dialectical_pairs'. If omitted, all signals run. (Only for action='signals'.)"
+            },
+            target_types: {
+              type: "string",
+              description: "Comma-separated node types used to filter entity_bridges and claim_hubs (e.g. 'Person,Organization,Theory'). (Only for action='signals'.)"
+            },
+            job_id: {
+              type: "string",
+              description: "Job ID to poll (for action='job_status')"
+            },
+            agent_id: {
+              type: "string",
+              description: "Agent identity"
+            }
+          },
+          required: ["action"]
+        }
       }
     ];
   }
@@ -1022,10 +1079,10 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.5.0 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v0.7.1 running on stdio (${BASE_URL})`
   );
 }
-var import_server, import_stdio, import_types, import_mindgraph, API_KEY, BASE_URL, AGENT_ID, client, INSTRUCTIONS, server, PROMPTS;
+var import_server, import_stdio, import_types, import_mindgraph, API_KEY, BASE_URL, AGENT_ID, ORG_ID, client, INSTRUCTIONS, server, PROMPTS;
 var init_src = __esm({
   "src/index.ts"() {
     "use strict";
@@ -1037,6 +1094,7 @@ var init_src = __esm({
     API_KEY = process.env.MINDGRAPH_API_KEY;
     BASE_URL = process.env.MINDGRAPH_BASE_URL || "https://api.mindgraph.cloud";
     AGENT_ID = process.env.MINDGRAPH_AGENT_ID || "mcp";
+    ORG_ID = process.env.MINDGRAPH_ORG_ID;
     if (!API_KEY) {
       console.error(
         "Error: MINDGRAPH_API_KEY environment variable is required.\nGet your API key at https://mindgraph.cloud/dashboard/keys\nOr run: npx mindgraph-mcp init"
@@ -1045,9 +1103,10 @@ var init_src = __esm({
     }
     client = new import_mindgraph.MindGraph({
       baseUrl: BASE_URL,
-      apiKey: API_KEY
+      apiKey: API_KEY,
+      orgId: ORG_ID
     });
-    INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph (6 tools).
+    INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph (7 tools).
 
 ## #1 RULE: Go straight to the user's topic
 
@@ -1110,6 +1169,7 @@ Capture knowledge when the user shares something worth remembering:
 - Goals or projects \u2192 \`mindgraph_commit\` action "goal"/"project"
 - Decisions \u2192 \`mindgraph_commit\` action "open_decision"
 - Long-form content \u2192 \`mindgraph_ingest\`
+- Cross-document synthesis over a project corpus \u2192 \`mindgraph_synthesize\` (action "signals" for structural signals; action "run" to spawn a synthesis job that writes Article nodes)
 
 ## Tool tips
 
@@ -1123,7 +1183,7 @@ Capture knowledge when the user shares something worth remembering:
     server = new import_server.Server(
       {
         name: "mindgraph",
-        version: "0.5.0"
+        version: "0.7.1"
       },
       {
         capabilities: {

package/dist/index.js

@@ -448,6 +448,41 @@ var TOOLS = [
       },
       required: ["action"]
     }
+  },
+  {
+    name: "mindgraph_synthesize",
+    description: "Work with Projects \u2014 scoped document corpora \u2014 and run cross-document synthesis over them. Use 'signals' to mine structural signals (entity bridges, claim hubs, theory support gaps, concept clusters, analogy candidates, dialectical pairs) without any LLM calls; useful for orientation before a full synthesis. Use 'run' to spawn a background synthesis job that turns the top idea clusters into Article nodes linked via Covers edges. Both operate on a Project's corpus, where documents are linked to the Project via PartOfProject edges (create the project with mindgraph_commit action 'project', then link docs via the ingest flow or add_link). Use 'job_status' to poll a synthesis job.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["signals", "run", "job_status"],
+          description: "Synthesis action"
+        },
+        project_uid: {
+          type: "string",
+          description: "UID of the Project node (required for signals/run)"
+        },
+        signals: {
+          type: "string",
+          description: "Comma-separated subset of signal names to compute, e.g. 'clustered_claim_hubs,dialectical_pairs'. If omitted, all signals run. (Only for action='signals'.)"
+        },
+        target_types: {
+          type: "string",
+          description: "Comma-separated node types used to filter entity_bridges and claim_hubs (e.g. 'Person,Organization,Theory'). (Only for action='signals'.)"
+        },
+        job_id: {
+          type: "string",
+          description: "Job ID to poll (for action='job_status')"
+        },
+        agent_id: {
+          type: "string",
+          description: "Agent identity"
+        }
+      },
+      required: ["action"]
+    }
   }
 ];
 function ok(data) {
@@ -476,6 +511,8 @@ async function handleTool(client2, name, args) {
         return await handleRetrieve(client2, args);
       case "mindgraph_ingest":
         return await handleIngest(client2, args);
+      case "mindgraph_synthesize":
+        return await handleSynthesize(client2, args);
       default:
         return err(`Unknown tool: ${name}`);
     }
@@ -989,11 +1026,32 @@ async function handleIngest(client2, args) {
       return err(`Unknown ingest action: ${action}`);
   }
 }
+async function handleSynthesize(client2, args) {
+  const { action, project_uid, signals, target_types, job_id } = args;
+  switch (action) {
+    case "signals":
+      if (!project_uid)
+        return err("project_uid is required for action='signals'");
+      return ok(
+        await client2.signals(project_uid, { signals, target_types })
+      );
+    case "run":
+      if (!project_uid)
+        return err("project_uid is required for action='run'");
+      return ok(await client2.runSynthesis(project_uid));
+    case "job_status":
+      if (!job_id) return err("job_id is required for action='job_status'");
+      return ok(await client2.getJob(job_id));
+    default:
+      return err(`Unknown synthesize action: ${action}`);
+  }
+}
 
 // src/index.ts
 var API_KEY = process.env.MINDGRAPH_API_KEY;
 var BASE_URL = process.env.MINDGRAPH_BASE_URL || "https://api.mindgraph.cloud";
 var AGENT_ID = process.env.MINDGRAPH_AGENT_ID || "mcp";
+var ORG_ID = process.env.MINDGRAPH_ORG_ID;
 if (!API_KEY) {
   console.error(
     "Error: MINDGRAPH_API_KEY environment variable is required.\nGet your API key at https://mindgraph.cloud/dashboard/keys\nOr run: npx mindgraph-mcp init"
@@ -1002,9 +1060,10 @@ if (!API_KEY) {
 }
 var client = new import_mindgraph.MindGraph({
   baseUrl: BASE_URL,
-  apiKey: API_KEY
+  apiKey: API_KEY,
+  orgId: ORG_ID
 });
-var INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph (6 tools).
+var INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph (7 tools).
 
 ## #1 RULE: Go straight to the user's topic
 
@@ -1067,6 +1126,7 @@ Capture knowledge when the user shares something worth remembering:
 - Goals or projects \u2192 \`mindgraph_commit\` action "goal"/"project"
 - Decisions \u2192 \`mindgraph_commit\` action "open_decision"
 - Long-form content \u2192 \`mindgraph_ingest\`
+- Cross-document synthesis over a project corpus \u2192 \`mindgraph_synthesize\` (action "signals" for structural signals; action "run" to spawn a synthesis job that writes Article nodes)
 
 ## Tool tips
 
@@ -1080,7 +1140,7 @@ Capture knowledge when the user shares something worth remembering:
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.5.0"
+    version: "0.7.1"
   },
   {
     capabilities: {
@@ -1436,7 +1496,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.5.0 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v0.7.1 running on stdio (${BASE_URL})`
   );
 }
 main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph-mcp",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "MCP server for MindGraph — connect Claude Desktop, Claude Code, and any MCP client to your knowledge graph",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,7 +27,7 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "mindgraph": "^0.3.0"
+    "mindgraph": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",