mindgraph-mcp 0.7.0 → 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

@@ -1079,7 +1079,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.7.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, ORG_ID, client, INSTRUCTIONS, server, PROMPTS;
@@ -1183,7 +1183,7 @@ Capture knowledge when the user shares something worth remembering:
     server = new import_server.Server(
       {
         name: "mindgraph",
-        version: "0.7.0"
+        version: "0.7.1"
       },
       {
         capabilities: {

package/dist/index.js

@@ -1140,7 +1140,7 @@ Capture knowledge when the user shares something worth remembering:
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.7.0"
+    version: "0.7.1"
   },
   {
     capabilities: {
@@ -1496,7 +1496,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.7.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.7.0",
+  "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",