@astramindapp/mcp-server 0.8.2 → 0.9.0

package/dist/server.d.ts

@@ -4,26 +4,38 @@
  * Exposes the MIND knowledge graph as MCP tools that any LLM agent can use.
  * This is the universal AI memory layer.
  *
- * Tools (17):
- *   mind_query     — Semantic search across the knowledge graph
- *   mind_remember  — Store/manage content in the graph (auto-categorized)
- *   mind_context   — Get structured always-loaded context (soul/user/rules)
- *   mind_life      — Read/write goals, projects, tasks, calendar events, stats
- *   mind_crm       — Read/write contacts, interactions, and activities
- *   mind_graph     — Get graph statistics, diagnostics, and labels
- *   mind_admin     — Admin-only user and featured mind management
- *   mind_sense     — MINDsense emotional intelligence layer
- *   mind_research  — Deep research agent jobs
- *   mind_train     — Self-training and chat-to-KG sessions
- *   mind_social    — Thoughts, communities, and feed
- *   mind_profile   — Profile, prompts, and model preferences
- *   mind_insights  — ALE insights and analytics
- *   mind_automate  — Automations and triggers
- *   mind_notify    — Notifications management
- *   mind_agents    — Admin-only Agent Command Center (registry, heartbeat,
- *                    probe, status — for Anthony's agent fleet)
- *   mind_accounts  — Multi-MIND accounts: discover/create MINDs, manage
- *                    owners and viewers, send invitations
+ * The server is self-describing: every connecting client receives
+ * SERVER_INSTRUCTIONS (from ./integration-guide) in the MCP `initialize`
+ * response, and can read the full playbook from the `mind://integration-guide`
+ * resource. Any agent that connects therefore knows what MIND is, which
+ * integration path to use for its runtime, how to authenticate, and the
+ * session protocol — without having to be told.
+ *
+ * Tools (23):
+ *   mind_query        — Semantic search across the knowledge graph
+ *   mind_remember     — Store/manage content in the graph (auto-categorized)
+ *   mind_folders      — Organize documents into folders (list/create/rename/
+ *                       move/delete/move_documents)
+ *   mind_context      — Get structured always-loaded context (soul/user/rules)
+ *   mind_life         — Goals, projects, tasks, calendar (incl. bulk_delete)
+ *   mind_tasks        — Site-wide assignable, reportable work items
+ *   mind_crm          — Read/write contacts, interactions, and activities
+ *   mind_graph        — Get graph statistics, diagnostics, and labels
+ *   mind_admin        — Admin-only user and featured mind management
+ *   mind_sense        — MINDsense emotional intelligence layer
+ *   mind_research     — Deep research agent jobs
+ *   mind_train        — Self-training and chat-to-KG sessions
+ *   mind_social       — Thoughts, communities, and feed
+ *   mind_profile      — Profile, prompts, and model preferences
+ *   mind_insights     — ALE insights and analytics
+ *   mind_automate     — Automations and triggers
+ *   mind_notify       — Notifications management
+ *   mind_agents       — Admin-only Agent Command Center (registry, heartbeat,
+ *                       probe, status — for the agent fleet)
+ *   mind_accounts     — Multi-MIND accounts: discover/create MINDs, manage
+ *                       owners and viewers, send invitations
+ *   mind_list_templates / mind_get_template / mind_save_typed /
+ *   mind_bootstrap_templates — the 16 Front Layer typed-document templates
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { MindClient } from "./mind-client.js";

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAi/FjE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAkpGjE"}

package/dist/server.js

@@ -5,36 +5,68 @@
  * Exposes the MIND knowledge graph as MCP tools that any LLM agent can use.
  * This is the universal AI memory layer.
  *
- * Tools (17):
- *   mind_query     — Semantic search across the knowledge graph
- *   mind_remember  — Store/manage content in the graph (auto-categorized)
- *   mind_context   — Get structured always-loaded context (soul/user/rules)
- *   mind_life      — Read/write goals, projects, tasks, calendar events, stats
- *   mind_crm       — Read/write contacts, interactions, and activities
- *   mind_graph     — Get graph statistics, diagnostics, and labels
- *   mind_admin     — Admin-only user and featured mind management
- *   mind_sense     — MINDsense emotional intelligence layer
- *   mind_research  — Deep research agent jobs
- *   mind_train     — Self-training and chat-to-KG sessions
- *   mind_social    — Thoughts, communities, and feed
- *   mind_profile   — Profile, prompts, and model preferences
- *   mind_insights  — ALE insights and analytics
- *   mind_automate  — Automations and triggers
- *   mind_notify    — Notifications management
- *   mind_agents    — Admin-only Agent Command Center (registry, heartbeat,
- *                    probe, status — for Anthony's agent fleet)
- *   mind_accounts  — Multi-MIND accounts: discover/create MINDs, manage
- *                    owners and viewers, send invitations
+ * The server is self-describing: every connecting client receives
+ * SERVER_INSTRUCTIONS (from ./integration-guide) in the MCP `initialize`
+ * response, and can read the full playbook from the `mind://integration-guide`
+ * resource. Any agent that connects therefore knows what MIND is, which
+ * integration path to use for its runtime, how to authenticate, and the
+ * session protocol — without having to be told.
+ *
+ * Tools (23):
+ *   mind_query        — Semantic search across the knowledge graph
+ *   mind_remember     — Store/manage content in the graph (auto-categorized)
+ *   mind_folders      — Organize documents into folders (list/create/rename/
+ *                       move/delete/move_documents)
+ *   mind_context      — Get structured always-loaded context (soul/user/rules)
+ *   mind_life         — Goals, projects, tasks, calendar (incl. bulk_delete)
+ *   mind_tasks        — Site-wide assignable, reportable work items
+ *   mind_crm          — Read/write contacts, interactions, and activities
+ *   mind_graph        — Get graph statistics, diagnostics, and labels
+ *   mind_admin        — Admin-only user and featured mind management
+ *   mind_sense        — MINDsense emotional intelligence layer
+ *   mind_research     — Deep research agent jobs
+ *   mind_train        — Self-training and chat-to-KG sessions
+ *   mind_social       — Thoughts, communities, and feed
+ *   mind_profile      — Profile, prompts, and model preferences
+ *   mind_insights     — ALE insights and analytics
+ *   mind_automate     — Automations and triggers
+ *   mind_notify       — Notifications management
+ *   mind_agents       — Admin-only Agent Command Center (registry, heartbeat,
+ *                       probe, status — for the agent fleet)
+ *   mind_accounts     — Multi-MIND accounts: discover/create MINDs, manage
+ *                       owners and viewers, send invitations
+ *   mind_list_templates / mind_get_template / mind_save_typed /
+ *   mind_bootstrap_templates — the 16 Front Layer typed-document templates
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMindMcpServer = createMindMcpServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const zod_1 = require("zod");
+const integration_guide_js_1 = require("./integration-guide.js");
 function createMindMcpServer(client) {
     const server = new mcp_js_1.McpServer({
         name: "mind",
-        version: "0.2.0",
+        version: "0.9.0",
+    }, {
+        // Returned to every client in the MCP `initialize` response — the first
+        // thing any connecting agent sees about how to integrate with MIND.
+        instructions: integration_guide_js_1.SERVER_INSTRUCTIONS,
     });
+    // ─── mind://integration-guide ───────────────────────────
+    // The full integration playbook, readable on demand by any MCP client.
+    server.registerResource("integration-guide", "mind://integration-guide", {
+        title: "MIND Integration Guide",
+        description: "Complete playbook for integrating any AI agent with MIND — the three integration paths (MCP server, OpenClaw plugin, REST API), authentication, the session protocol, all 22 tools, REST endpoint mapping, and common recipes.",
+        mimeType: "text/markdown",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "text/markdown",
+                text: integration_guide_js_1.INTEGRATION_GUIDE,
+            },
+        ],
+    }));
     // ─── mind_query ─────────────────────────────────────────
     // Semantic search across the user's knowledge graph.
     // Replaces flat MEMORY.md — returns only relevant memories.
@@ -253,6 +285,131 @@ function createMindMcpServer(client) {
             };
         }
     });
+    // ─── mind_folders ───────────────────────────────────────
+    // Organize documents into folders. Folders are a presentation layer — the
+    // knowledge graph still indexes every document regardless of folder.
+    server.tool("mind_folders", "Organize your MIND documents into folders. Folders are a presentation layer — the knowledge graph still indexes and retrieves across every document regardless of folder. Use mind_remember to create a document, then mind_folders move_documents to file it. Actions: list, create, rename, move, delete, move_documents.", {
+        action: zod_1.z
+            .enum(["list", "create", "rename", "move", "delete", "move_documents"])
+            .describe("list (all folders + counts), create (new folder), rename (change a folder's name), move (re-nest a folder), delete (remove a folder — its documents and subfolders move up a level, nothing is deleted), move_documents (file documents into a folder)"),
+        name: zod_1.z.string().optional().describe("Folder name — required for create and rename"),
+        folder_id: zod_1.z
+            .string()
+            .optional()
+            .describe("Folder id — the folder to rename/move/delete, or the destination for move_documents (omit or pass 'root' to file documents at the top level)"),
+        parent_id: zod_1.z
+            .string()
+            .optional()
+            .describe("Parent folder id for create and move. Omit or pass 'root' for the top level"),
+        doc_ids: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("Document ids to file — required for move_documents"),
+    }, async ({ action, name, folder_id, parent_id, doc_ids }) => {
+        try {
+            switch (action) {
+                case "list": {
+                    const res = await client.listFolders();
+                    if (!res.folders.length) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `No folders yet. ${res.unfiled_count} document(s), all at the top level. Create one with action 'create'.`,
+                                },
+                            ],
+                        };
+                    }
+                    const byId = new Map(res.folders.map((f) => [f.id, f]));
+                    const lines = res.folders.map((f) => {
+                        const parent = f.parent_id ? byId.get(f.parent_id)?.name ?? "?" : "(top level)";
+                        return `• ${f.name} — ${f.document_count ?? 0} doc(s) · id: ${f.id} · parent: ${parent}`;
+                    });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: [
+                                    `${res.folders.length} folder(s) · ${res.unfiled_count} unfiled · ${res.total_count} total documents`,
+                                    "",
+                                    ...lines,
+                                ].join("\n"),
+                            },
+                        ],
+                    };
+                }
+                case "create": {
+                    if (!name)
+                        throw new Error("'name' is required to create a folder");
+                    const res = await client.createFolder(name, parent_id ?? null);
+                    return {
+                        content: [
+                            { type: "text", text: `Created folder "${res.folder.name}" (id: ${res.folder.id})` },
+                        ],
+                    };
+                }
+                case "rename": {
+                    if (!folder_id)
+                        throw new Error("'folder_id' is required to rename a folder");
+                    if (!name)
+                        throw new Error("'name' is required to rename a folder");
+                    const res = await client.updateFolder(folder_id, { name });
+                    return {
+                        content: [{ type: "text", text: `Renamed folder to "${res.folder.name}"` }],
+                    };
+                }
+                case "move": {
+                    if (!folder_id)
+                        throw new Error("'folder_id' is required to move a folder");
+                    // Always send parent_id explicitly (id or null) so the move applies.
+                    const res = await client.updateFolder(folder_id, { parent_id: parent_id ?? null });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Moved folder "${res.folder.name}" ${res.folder.parent_id ? "into another folder" : "to the top level"}`,
+                            },
+                        ],
+                    };
+                }
+                case "delete": {
+                    if (!folder_id)
+                        throw new Error("'folder_id' is required to delete a folder");
+                    const res = await client.deleteFolder(folder_id);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Deleted folder. ${res.documents_reparented} document(s) moved up a level — no documents were deleted.`,
+                            },
+                        ],
+                    };
+                }
+                case "move_documents": {
+                    if (!doc_ids || !doc_ids.length)
+                        throw new Error("'doc_ids' is required for move_documents");
+                    const dest = !folder_id || folder_id === "root" ? null : folder_id;
+                    const res = await client.moveDocuments(doc_ids, dest);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Moved ${res.moved} document(s) ${dest ? "into the folder" : "to the top level"}`,
+                            },
+                        ],
+                    };
+                }
+                default:
+                    throw new Error(`Unknown action: ${action}`);
+            }
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error managing folders: ${err}` }],
+                isError: true,
+            };
+        }
+    });
     // ─── mind_context ───────────────────────────────────────
     // Get structured always-loaded context.
     // Equivalent to OpenClaw's SOUL.md + USER.md + AGENTS.md bootstrap injection,