mindgraph-mcp 0.4.0 → 0.6.0

package/dist/cli.js

@@ -387,10 +387,10 @@ async function handleRetrieve(client2, args) {
       return ok(
         await client2.retrieveContext({
           query,
-          k: limit,
+          node_limit: limit,
           node_types,
           layer,
-          include_chunks,
+          chunk_limit: include_chunks ? limit ?? 5 : 0,
           include_graph
         })
       );
@@ -462,6 +462,14 @@ async function handleRetrieve(client2, args) {
           agent_id
         })
       );
+    // Document inventory
+    case "document_index":
+      return ok(
+        await client2.getNodes({
+          node_type: "Document",
+          limit: limit ?? 100
+        })
+      );
     // Graph traversal
     case "chain":
       if (!start_uid) return err("start_uid is required for chain traversal");
@@ -852,7 +860,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_retrieve",
-        description: "Search and explore the knowledge graph. Use 'context' (default) for BM25 keyword retrieval \u2014 pass 1-3 discriminating keywords (proper nouns, technical terms), not sentences. GOOD: 'Kissinger NATO'. BAD: 'What is Kissinger\\'s view on NATO?'. Use 'semantic' when keywords return nothing \u2014 good for conceptual/fuzzy queries where user words differ from stored labels. Use 'hybrid' to combine keyword + semantic. Use 'text' for fast keyword-only lookup. Use 'neighborhood' to explore around a known node, 'chain' for reasoning chains, 'path' between two nodes, 'subgraph' for connected components. Other actions ('active_goals', 'open_questions', etc.) only when the user explicitly asks.",
+        description: "Search and explore the knowledge graph. Use 'context' (default) for BM25 keyword retrieval \u2014 returns graph nodes only by default (labels, summaries, types, confidence); set include_chunks=true to also get full source text. Pass 1-3 discriminating keywords, not sentences. GOOD: 'Kissinger NATO'. BAD: 'What is Kissinger\\'s view on NATO?'. Use 'document_index' to list all ingested documents (titles, dates, UIDs) for orientation. Use 'semantic' when keywords return nothing \u2014 conceptual/fuzzy queries. Use 'hybrid' for keyword + semantic. Use 'text' for fast keyword-only. Use 'neighborhood'/'chain'/'path'/'subgraph' for graph traversal. Other actions ('active_goals', 'open_questions', etc.) only when the user explicitly asks.",
         inputSchema: {
           type: "object",
           properties: {
@@ -873,7 +881,8 @@ var init_tools = __esm({
                 "chain",
                 "neighborhood",
                 "path",
-                "subgraph"
+                "subgraph",
+                "document_index"
               ],
               description: "Retrieval or traversal strategy"
             },
@@ -919,7 +928,7 @@ var init_tools = __esm({
             },
             include_chunks: {
               type: "boolean",
-              description: "Include source document chunks in context results (default: true)"
+              description: "Include source document chunks in context results (default: false \u2014 set true to fetch full chunk text for citations or deep reading)"
             },
             include_graph: {
               type: "boolean",
@@ -1013,7 +1022,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.4.0 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v0.5.0 running on stdio (${BASE_URL})`
   );
 }
 var import_server, import_stdio, import_types, import_mindgraph, API_KEY, BASE_URL, AGENT_ID, client, INSTRUCTIONS, server, PROMPTS;
@@ -1056,6 +1065,17 @@ There is no session to open. There is no context to pre-load. Just search for wh
 \u2717 WRONG: First retrieve active_goals, then open_questions, then search
 \u2717 WRONG: \`mindgraph_retrieve({action: "context", query: "Tell me about Indian philosophy and Taoism"})\` \u2014 natural language won't match BM25
 
+## Two-phase retrieval protocol
+
+**Phase 1 \u2014 Orient (default, fast, lightweight):**
+Use \`action: "context"\` with keywords. By default this returns only graph nodes \u2014 structured knowledge with labels, summaries, types, confidence scores, and edges. This is usually sufficient and keeps results compact.
+
+**Phase 2 \u2014 Fetch source text (only when needed):**
+If you need the original source text behind a node (for verbatim quotes, citations, or when graph summaries lack detail), use \`action: "context"\` with \`include_chunks: true\`. This adds full document chunks (400-800 words each) to the response.
+
+**Orientation shortcut:**
+- \`action: "document_index"\` \u2014 list all ingested documents (titles, dates, UIDs) to see what's in the graph
+
 ## Search strategy \u2014 keyword first, semantic as fallback
 
 The default search uses BM25 keyword matching. Query with 1\u20133 discriminating terms (proper nouns, technical terms). Drop filler words.
@@ -1073,6 +1093,7 @@ If keyword search returns no results, escalate:
 ## When to READ
 
 - User asks about topic X \u2192 \`mindgraph_retrieve\` action "context", query "X keywords"
+- User asks "what documents are in my graph?" \u2192 action "document_index"
 - User explicitly asks "what are my goals?" \u2192 action "active_goals"
 - User explicitly asks about open questions \u2192 action "open_questions"
 - Explore around a known node \u2192 action "neighborhood" with start_uid
@@ -1094,6 +1115,7 @@ Capture knowledge when the user shares something worth remembering:
 
 - \`capture\`: "entity"/"observation" for facts, "journal" for personal/informal
 - \`reason\`: "claim" when evidence exists, "open_question"/"hypothesis" otherwise
+- \`retrieve\`: "context" returns graph nodes only by default \u2014 set include_chunks=true for source text
 - \`retrieve\`: "context" (FTS default) \u2192 "semantic" (conceptual fallback) \u2192 "hybrid" (both)
 - \`retrieve\`: "neighborhood"/"chain"/"path"/"subgraph" for graph exploration
 - Confidence: 0.9+ for facts, 0.5-0.8 for uncertain, <0.5 for speculation
@@ -1101,7 +1123,7 @@ Capture knowledge when the user shares something worth remembering:
     server = new import_server.Server(
       {
         name: "mindgraph",
-        version: "0.4.0"
+        version: "0.5.0"
       },
       {
         capabilities: {

package/dist/index.js

@@ -297,7 +297,7 @@ var TOOLS = [
   },
   {
     name: "mindgraph_retrieve",
-    description: "Search and explore the knowledge graph. Use 'context' (default) for BM25 keyword retrieval \u2014 pass 1-3 discriminating keywords (proper nouns, technical terms), not sentences. GOOD: 'Kissinger NATO'. BAD: 'What is Kissinger\\'s view on NATO?'. Use 'semantic' when keywords return nothing \u2014 good for conceptual/fuzzy queries where user words differ from stored labels. Use 'hybrid' to combine keyword + semantic. Use 'text' for fast keyword-only lookup. Use 'neighborhood' to explore around a known node, 'chain' for reasoning chains, 'path' between two nodes, 'subgraph' for connected components. Other actions ('active_goals', 'open_questions', etc.) only when the user explicitly asks.",
+    description: "Search and explore the knowledge graph. Use 'context' (default) for BM25 keyword retrieval \u2014 returns graph nodes only by default (labels, summaries, types, confidence); set include_chunks=true to also get full source text. Pass 1-3 discriminating keywords, not sentences. GOOD: 'Kissinger NATO'. BAD: 'What is Kissinger\\'s view on NATO?'. Use 'document_index' to list all ingested documents (titles, dates, UIDs) for orientation. Use 'semantic' when keywords return nothing \u2014 conceptual/fuzzy queries. Use 'hybrid' for keyword + semantic. Use 'text' for fast keyword-only. Use 'neighborhood'/'chain'/'path'/'subgraph' for graph traversal. Other actions ('active_goals', 'open_questions', etc.) only when the user explicitly asks.",
     inputSchema: {
       type: "object",
       properties: {
@@ -318,7 +318,8 @@ var TOOLS = [
             "chain",
             "neighborhood",
             "path",
-            "subgraph"
+            "subgraph",
+            "document_index"
           ],
           description: "Retrieval or traversal strategy"
         },
@@ -364,7 +365,7 @@ var TOOLS = [
         },
         include_chunks: {
           type: "boolean",
-          description: "Include source document chunks in context results (default: true)"
+          description: "Include source document chunks in context results (default: false \u2014 set true to fetch full chunk text for citations or deep reading)"
         },
         include_graph: {
           type: "boolean",
@@ -809,10 +810,10 @@ async function handleRetrieve(client2, args) {
       return ok(
         await client2.retrieveContext({
           query,
-          k: limit,
+          node_limit: limit,
           node_types,
           layer,
-          include_chunks,
+          chunk_limit: include_chunks ? limit ?? 5 : 0,
           include_graph
         })
       );
@@ -884,6 +885,14 @@ async function handleRetrieve(client2, args) {
           agent_id
         })
       );
+    // Document inventory
+    case "document_index":
+      return ok(
+        await client2.getNodes({
+          node_type: "Document",
+          limit: limit ?? 100
+        })
+      );
     // Graph traversal
     case "chain":
       if (!start_uid) return err("start_uid is required for chain traversal");
@@ -1013,6 +1022,17 @@ There is no session to open. There is no context to pre-load. Just search for wh
 \u2717 WRONG: First retrieve active_goals, then open_questions, then search
 \u2717 WRONG: \`mindgraph_retrieve({action: "context", query: "Tell me about Indian philosophy and Taoism"})\` \u2014 natural language won't match BM25
 
+## Two-phase retrieval protocol
+
+**Phase 1 \u2014 Orient (default, fast, lightweight):**
+Use \`action: "context"\` with keywords. By default this returns only graph nodes \u2014 structured knowledge with labels, summaries, types, confidence scores, and edges. This is usually sufficient and keeps results compact.
+
+**Phase 2 \u2014 Fetch source text (only when needed):**
+If you need the original source text behind a node (for verbatim quotes, citations, or when graph summaries lack detail), use \`action: "context"\` with \`include_chunks: true\`. This adds full document chunks (400-800 words each) to the response.
+
+**Orientation shortcut:**
+- \`action: "document_index"\` \u2014 list all ingested documents (titles, dates, UIDs) to see what's in the graph
+
 ## Search strategy \u2014 keyword first, semantic as fallback
 
 The default search uses BM25 keyword matching. Query with 1\u20133 discriminating terms (proper nouns, technical terms). Drop filler words.
@@ -1030,6 +1050,7 @@ If keyword search returns no results, escalate:
 ## When to READ
 
 - User asks about topic X \u2192 \`mindgraph_retrieve\` action "context", query "X keywords"
+- User asks "what documents are in my graph?" \u2192 action "document_index"
 - User explicitly asks "what are my goals?" \u2192 action "active_goals"
 - User explicitly asks about open questions \u2192 action "open_questions"
 - Explore around a known node \u2192 action "neighborhood" with start_uid
@@ -1051,6 +1072,7 @@ Capture knowledge when the user shares something worth remembering:
 
 - \`capture\`: "entity"/"observation" for facts, "journal" for personal/informal
 - \`reason\`: "claim" when evidence exists, "open_question"/"hypothesis" otherwise
+- \`retrieve\`: "context" returns graph nodes only by default \u2014 set include_chunks=true for source text
 - \`retrieve\`: "context" (FTS default) \u2192 "semantic" (conceptual fallback) \u2192 "hybrid" (both)
 - \`retrieve\`: "neighborhood"/"chain"/"path"/"subgraph" for graph exploration
 - Confidence: 0.9+ for facts, 0.5-0.8 for uncertain, <0.5 for speculation
@@ -1058,7 +1080,7 @@ Capture knowledge when the user shares something worth remembering:
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.4.0"
+    version: "0.5.0"
   },
   {
     capabilities: {
@@ -1414,7 +1436,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.4.0 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v0.5.0 running on stdio (${BASE_URL})`
   );
 }
 main().catch((error) => {

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "mindgraph-mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "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",
   "bin": {
     "mindgraph-mcp": "dist/cli.js"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsup",
     "lint": "tsc --noEmit",
@@ -25,7 +27,7 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "mindgraph": "^0.2.1"
+    "mindgraph": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",