mindgraph-mcp 0.7.1 → 0.9.0

package/README.md

@@ -49,7 +49,7 @@ Or drop this into your Claude Desktop config by hand (`~/Library/Application Sup
 
 ## What You Get
 
-**7 tools** covering the full knowledge-graph workflow:
+**8 tools** covering the full knowledge-graph workflow:
 
 | Tool | Purpose |
 |------|---------|
@@ -60,6 +60,7 @@ Or drop this into your Claude Desktop config by hand (`~/Library/Application Sup
 | `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 |
+| `mindgraph_ontology` | Operational Ontology (Layer 7) — typed domain objects, NL queries with provenance, extraction proposal review (approve/reject), object linking |
 
 **7 prompt templates** for common workflows:
 

package/dist/cli.js

@@ -55,6 +55,8 @@ async function handleTool(client2, name, args) {
         return await handleIngest(client2, args);
       case "mindgraph_synthesize":
         return await handleSynthesize(client2, args);
+      case "mindgraph_ontology":
+        return await handleOntology(client2, args);
       default:
         return err(`Unknown tool: ${name}`);
     }
@@ -443,6 +445,15 @@ async function handleRetrieve(client2, args) {
       return ok(await client2.getPendingApprovals());
     case "unresolved_contradictions":
       return ok(await client2.getContradictions());
+    case "preferences":
+      return ok(
+        await client2.retrieve({
+          action: "preferences",
+          ...query ? { query, k: limit } : {},
+          limit,
+          agent_id
+        })
+      );
     case "layer":
       if (!layer) return err("layer is required for layer retrieval");
       return ok(
@@ -588,6 +599,124 @@ async function handleSynthesize(client2, args) {
       return err(`Unknown synthesize action: ${action}`);
   }
 }
+async function handleOntology(client2, args) {
+  const {
+    action,
+    schema_id,
+    query,
+    object_types,
+    object_type,
+    uid,
+    depth,
+    include_cognitive_context,
+    include_sources,
+    limit,
+    status,
+    proposal_id,
+    feedback,
+    reason,
+    from_uid,
+    to_uid,
+    relation_type,
+    fields,
+    source_uids,
+    agent_id
+  } = args;
+  switch (action) {
+    case "schemas":
+      return ok(await client2.listOntologySchemas());
+    case "schema":
+      if (!schema_id) return err("schema_id is required for action='schema'");
+      return ok(await client2.getOntologySchema(schema_id));
+    case "query": {
+      if (!query) return err("query is required for action='query'");
+      if (!schema_id) {
+        return err(
+          "schema_id is required for action='query' (use action='schemas' to find the active schema)"
+        );
+      }
+      return ok(
+        await client2.queryOntology({
+          query,
+          schema_id,
+          object_types,
+          include_cognitive_context: include_cognitive_context ?? true,
+          include_sources: include_sources ?? true,
+          depth,
+          limit
+        })
+      );
+    }
+    case "search":
+      if (!query) return err("query is required for action='search'");
+      return ok(
+        await client2.searchDomainObjects(query, {
+          schema_id,
+          object_types,
+          limit
+        })
+      );
+    case "objects":
+      if (!schema_id) return err("schema_id is required for action='objects'");
+      return ok(
+        await client2.listDomainObjects({ schema_id, object_type, limit })
+      );
+    case "object":
+      if (!uid) return err("uid is required for action='object'");
+      return ok(await client2.getDomainObject(uid));
+    case "object_context":
+      if (!uid) return err("uid is required for action='object_context'");
+      return ok(await client2.getDomainObjectContext(uid, depth));
+    case "proposals":
+      return ok(
+        await client2.listOntologyProposals({
+          status: status ?? "pending",
+          schema_id,
+          object_type,
+          limit
+        })
+      );
+    case "proposal":
+      if (!proposal_id) return err("proposal_id is required for action='proposal'");
+      return ok(await client2.getOntologyProposal(proposal_id));
+    case "approve":
+      if (!proposal_id) return err("proposal_id is required for action='approve'");
+      return ok(await client2.approveOntologyProposal(proposal_id, { feedback }));
+    case "reject":
+      if (!proposal_id) return err("proposal_id is required for action='reject'");
+      return ok(await client2.rejectOntologyProposal(proposal_id, reason));
+    case "link": {
+      if (!from_uid || !to_uid || !relation_type) {
+        return err(
+          "from_uid, to_uid, and relation_type are required for action='link'"
+        );
+      }
+      return ok(
+        await client2.linkDomainObjects({
+          from_uid,
+          to_uid,
+          relation_type,
+          fields,
+          agent_id
+        })
+      );
+    }
+    case "extract": {
+      if (!schema_id) return err("schema_id is required for action='extract'");
+      if (!source_uids?.length) {
+        return err("source_uids is required for action='extract'");
+      }
+      return ok(
+        await client2.extractOntology({
+          ontology_schema_id: schema_id,
+          source_uids
+        })
+      );
+    }
+    default:
+      return err(`Unknown ontology action: ${action}`);
+  }
+}
 var TOOLS;
 var init_tools = __esm({
   "src/tools.ts"() {
@@ -882,7 +1011,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_retrieve",
-        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.",
+        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. Use 'preferences' for advice or recommendation requests ('suggest a hotel', 'what should I read?') \u2014 it returns the user's stated/learned preferences relevant to the query (pass the topic as 'query'), so your answer reflects what they actually like instead of being generic. Other structured actions ('active_goals', 'open_questions', etc.) only when the user explicitly asks.",
         inputSchema: {
           type: "object",
           properties: {
@@ -898,6 +1027,7 @@ var init_tools = __esm({
                 "weak_claims",
                 "pending_approvals",
                 "unresolved_contradictions",
+                "preferences",
                 "layer",
                 "recent",
                 "chain",
@@ -1068,6 +1198,114 @@ var init_tools = __esm({
           },
           required: ["action"]
         }
+      },
+      {
+        name: "mindgraph_ontology",
+        description: "Work with the Operational Ontology (Layer 7) \u2014 workspace-specific domain objects typed by a user-approved schema (e.g. Client, Contract, Patient, Experiment). Use 'schemas'/'schema' to discover what object and relation types exist before anything else. Use 'query' for natural-language retrieval of typed objects with cognitive context (claims, decisions, risks about them) and source provenance; 'search' for hybrid search over objects; 'objects'/'object'/'object_context' to browse instances. Extraction proposes new objects/relations into a review queue rather than writing directly: use 'proposals'/'proposal' to inspect the queue, and 'approve'/'reject' ONLY when the user explicitly asks \u2014 proposal review is the human-in-the-loop boundary. Use 'link' to relate two existing objects, 'extract' to run schema-typed extraction over already-ingested sources.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            action: {
+              type: "string",
+              enum: [
+                "schemas",
+                "schema",
+                "query",
+                "search",
+                "objects",
+                "object",
+                "object_context",
+                "proposals",
+                "proposal",
+                "approve",
+                "reject",
+                "link",
+                "extract"
+              ],
+              description: "Ontology operation"
+            },
+            schema_id: {
+              type: "string",
+              description: "Ontology schema ID (required for query/objects/extract; optional filter for proposals). Get it from action='schemas'."
+            },
+            query: {
+              type: "string",
+              description: "Natural-language query (for action=query) or search text (for action=search)"
+            },
+            object_types: {
+              type: "array",
+              items: { type: "string" },
+              description: "Restrict to these object type names, e.g. ['Client'] (for query/search)"
+            },
+            object_type: {
+              type: "string",
+              description: "Single object type name filter (for objects/proposals)"
+            },
+            uid: {
+              type: "string",
+              description: "Domain object UID (for object/object_context)"
+            },
+            depth: {
+              type: "number",
+              description: "Traversal depth for context (for query/object_context, default 1)"
+            },
+            include_cognitive_context: {
+              type: "boolean",
+              description: "Include linked cognitive nodes \u2014 claims, decisions, risks (for action=query, default true)"
+            },
+            include_sources: {
+              type: "boolean",
+              description: "Include source provenance entries (for action=query, default true)"
+            },
+            limit: {
+              type: "number",
+              description: "Max results (for query/search/objects/proposals)"
+            },
+            status: {
+              type: "string",
+              enum: ["pending", "approved", "approval_required", "rejected", "applied", "apply_failed"],
+              description: "Review-status filter (for action=proposals, default 'pending')"
+            },
+            proposal_id: {
+              type: "string",
+              description: "Proposal ID (for proposal/approve/reject)"
+            },
+            feedback: {
+              type: "string",
+              description: "Reviewer feedback to record (for action=approve)"
+            },
+            reason: {
+              type: "string",
+              description: "Rejection reason (for action=reject)"
+            },
+            from_uid: {
+              type: "string",
+              description: "Source domain object UID (for action=link)"
+            },
+            to_uid: {
+              type: "string",
+              description: "Target domain object UID (for action=link)"
+            },
+            relation_type: {
+              type: "string",
+              description: "Relation type name from the schema (for action=link)"
+            },
+            fields: {
+              type: "object",
+              description: "Relation field values (for action=link)"
+            },
+            source_uids: {
+              type: "array",
+              items: { type: "string" },
+              description: "Chunk/document UIDs to extract from (for action=extract)"
+            },
+            agent_id: {
+              type: "string",
+              description: "Agent identity"
+            }
+          },
+          required: ["action"]
+        }
       }
     ];
   }
@@ -1155,6 +1393,7 @@ If keyword search returns no results, escalate:
 - 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"
+- User asks for advice or a recommendation ("suggest a hotel", "what should I read?") \u2192 action "preferences", query "topic keywords" \u2014 tailor the answer to what they like
 - Explore around a known node \u2192 action "neighborhood" with start_uid
 - Find connections between nodes \u2192 action "path" with start_uid + end_uid
 

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 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.",
+    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. Use 'preferences' for advice or recommendation requests ('suggest a hotel', 'what should I read?') \u2014 it returns the user's stated/learned preferences relevant to the query (pass the topic as 'query'), so your answer reflects what they actually like instead of being generic. Other structured actions ('active_goals', 'open_questions', etc.) only when the user explicitly asks.",
     inputSchema: {
       type: "object",
       properties: {
@@ -313,6 +313,7 @@ var TOOLS = [
             "weak_claims",
             "pending_approvals",
             "unresolved_contradictions",
+            "preferences",
             "layer",
             "recent",
             "chain",
@@ -483,6 +484,114 @@ var TOOLS = [
       },
       required: ["action"]
     }
+  },
+  {
+    name: "mindgraph_ontology",
+    description: "Work with the Operational Ontology (Layer 7) \u2014 workspace-specific domain objects typed by a user-approved schema (e.g. Client, Contract, Patient, Experiment). Use 'schemas'/'schema' to discover what object and relation types exist before anything else. Use 'query' for natural-language retrieval of typed objects with cognitive context (claims, decisions, risks about them) and source provenance; 'search' for hybrid search over objects; 'objects'/'object'/'object_context' to browse instances. Extraction proposes new objects/relations into a review queue rather than writing directly: use 'proposals'/'proposal' to inspect the queue, and 'approve'/'reject' ONLY when the user explicitly asks \u2014 proposal review is the human-in-the-loop boundary. Use 'link' to relate two existing objects, 'extract' to run schema-typed extraction over already-ingested sources.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: [
+            "schemas",
+            "schema",
+            "query",
+            "search",
+            "objects",
+            "object",
+            "object_context",
+            "proposals",
+            "proposal",
+            "approve",
+            "reject",
+            "link",
+            "extract"
+          ],
+          description: "Ontology operation"
+        },
+        schema_id: {
+          type: "string",
+          description: "Ontology schema ID (required for query/objects/extract; optional filter for proposals). Get it from action='schemas'."
+        },
+        query: {
+          type: "string",
+          description: "Natural-language query (for action=query) or search text (for action=search)"
+        },
+        object_types: {
+          type: "array",
+          items: { type: "string" },
+          description: "Restrict to these object type names, e.g. ['Client'] (for query/search)"
+        },
+        object_type: {
+          type: "string",
+          description: "Single object type name filter (for objects/proposals)"
+        },
+        uid: {
+          type: "string",
+          description: "Domain object UID (for object/object_context)"
+        },
+        depth: {
+          type: "number",
+          description: "Traversal depth for context (for query/object_context, default 1)"
+        },
+        include_cognitive_context: {
+          type: "boolean",
+          description: "Include linked cognitive nodes \u2014 claims, decisions, risks (for action=query, default true)"
+        },
+        include_sources: {
+          type: "boolean",
+          description: "Include source provenance entries (for action=query, default true)"
+        },
+        limit: {
+          type: "number",
+          description: "Max results (for query/search/objects/proposals)"
+        },
+        status: {
+          type: "string",
+          enum: ["pending", "approved", "approval_required", "rejected", "applied", "apply_failed"],
+          description: "Review-status filter (for action=proposals, default 'pending')"
+        },
+        proposal_id: {
+          type: "string",
+          description: "Proposal ID (for proposal/approve/reject)"
+        },
+        feedback: {
+          type: "string",
+          description: "Reviewer feedback to record (for action=approve)"
+        },
+        reason: {
+          type: "string",
+          description: "Rejection reason (for action=reject)"
+        },
+        from_uid: {
+          type: "string",
+          description: "Source domain object UID (for action=link)"
+        },
+        to_uid: {
+          type: "string",
+          description: "Target domain object UID (for action=link)"
+        },
+        relation_type: {
+          type: "string",
+          description: "Relation type name from the schema (for action=link)"
+        },
+        fields: {
+          type: "object",
+          description: "Relation field values (for action=link)"
+        },
+        source_uids: {
+          type: "array",
+          items: { type: "string" },
+          description: "Chunk/document UIDs to extract from (for action=extract)"
+        },
+        agent_id: {
+          type: "string",
+          description: "Agent identity"
+        }
+      },
+      required: ["action"]
+    }
   }
 ];
 function ok(data) {
@@ -513,6 +622,8 @@ async function handleTool(client2, name, args) {
         return await handleIngest(client2, args);
       case "mindgraph_synthesize":
         return await handleSynthesize(client2, args);
+      case "mindgraph_ontology":
+        return await handleOntology(client2, args);
       default:
         return err(`Unknown tool: ${name}`);
     }
@@ -901,6 +1012,15 @@ async function handleRetrieve(client2, args) {
       return ok(await client2.getPendingApprovals());
     case "unresolved_contradictions":
       return ok(await client2.getContradictions());
+    case "preferences":
+      return ok(
+        await client2.retrieve({
+          action: "preferences",
+          ...query ? { query, k: limit } : {},
+          limit,
+          agent_id
+        })
+      );
     case "layer":
       if (!layer) return err("layer is required for layer retrieval");
       return ok(
@@ -1046,6 +1166,124 @@ async function handleSynthesize(client2, args) {
       return err(`Unknown synthesize action: ${action}`);
   }
 }
+async function handleOntology(client2, args) {
+  const {
+    action,
+    schema_id,
+    query,
+    object_types,
+    object_type,
+    uid,
+    depth,
+    include_cognitive_context,
+    include_sources,
+    limit,
+    status,
+    proposal_id,
+    feedback,
+    reason,
+    from_uid,
+    to_uid,
+    relation_type,
+    fields,
+    source_uids,
+    agent_id
+  } = args;
+  switch (action) {
+    case "schemas":
+      return ok(await client2.listOntologySchemas());
+    case "schema":
+      if (!schema_id) return err("schema_id is required for action='schema'");
+      return ok(await client2.getOntologySchema(schema_id));
+    case "query": {
+      if (!query) return err("query is required for action='query'");
+      if (!schema_id) {
+        return err(
+          "schema_id is required for action='query' (use action='schemas' to find the active schema)"
+        );
+      }
+      return ok(
+        await client2.queryOntology({
+          query,
+          schema_id,
+          object_types,
+          include_cognitive_context: include_cognitive_context ?? true,
+          include_sources: include_sources ?? true,
+          depth,
+          limit
+        })
+      );
+    }
+    case "search":
+      if (!query) return err("query is required for action='search'");
+      return ok(
+        await client2.searchDomainObjects(query, {
+          schema_id,
+          object_types,
+          limit
+        })
+      );
+    case "objects":
+      if (!schema_id) return err("schema_id is required for action='objects'");
+      return ok(
+        await client2.listDomainObjects({ schema_id, object_type, limit })
+      );
+    case "object":
+      if (!uid) return err("uid is required for action='object'");
+      return ok(await client2.getDomainObject(uid));
+    case "object_context":
+      if (!uid) return err("uid is required for action='object_context'");
+      return ok(await client2.getDomainObjectContext(uid, depth));
+    case "proposals":
+      return ok(
+        await client2.listOntologyProposals({
+          status: status ?? "pending",
+          schema_id,
+          object_type,
+          limit
+        })
+      );
+    case "proposal":
+      if (!proposal_id) return err("proposal_id is required for action='proposal'");
+      return ok(await client2.getOntologyProposal(proposal_id));
+    case "approve":
+      if (!proposal_id) return err("proposal_id is required for action='approve'");
+      return ok(await client2.approveOntologyProposal(proposal_id, { feedback }));
+    case "reject":
+      if (!proposal_id) return err("proposal_id is required for action='reject'");
+      return ok(await client2.rejectOntologyProposal(proposal_id, reason));
+    case "link": {
+      if (!from_uid || !to_uid || !relation_type) {
+        return err(
+          "from_uid, to_uid, and relation_type are required for action='link'"
+        );
+      }
+      return ok(
+        await client2.linkDomainObjects({
+          from_uid,
+          to_uid,
+          relation_type,
+          fields,
+          agent_id
+        })
+      );
+    }
+    case "extract": {
+      if (!schema_id) return err("schema_id is required for action='extract'");
+      if (!source_uids?.length) {
+        return err("source_uids is required for action='extract'");
+      }
+      return ok(
+        await client2.extractOntology({
+          ontology_schema_id: schema_id,
+          source_uids
+        })
+      );
+    }
+    default:
+      return err(`Unknown ontology action: ${action}`);
+  }
+}
 
 // src/index.ts
 var API_KEY = process.env.MINDGRAPH_API_KEY;
@@ -1112,6 +1350,7 @@ If keyword search returns no results, escalate:
 - 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"
+- User asks for advice or a recommendation ("suggest a hotel", "what should I read?") \u2192 action "preferences", query "topic keywords" \u2014 tailor the answer to what they like
 - Explore around a known node \u2192 action "neighborhood" with start_uid
 - Find connections between nodes \u2192 action "path" with start_uid + end_uid
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindgraph-mcp",
-  "version": "0.7.1",
+  "version": "0.9.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",
@@ -27,7 +27,7 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "mindgraph": "^0.4.0"
+    "mindgraph": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",