@astramindapp/mcp-server 0.21.0 → 0.23.0

package/dist/oauth-connect.js

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * MIND MCP Setup — browser OAuth connect.
+ *
+ * Implements the loopback OAuth 2.1 Authorization Code + PKCE flow against
+ * the MIND backend (backend/routes/mcp_oauth_routes.py):
+ *
+ *   1. Start a local HTTP server on 127.0.0.1 (OS-assigned port), path /callback.
+ *   2. Dynamically register a public client (RFC 7591) at {base}/oauth/mcp/register.
+ *   3. Open {base}/oauth/mcp/authorize in the default browser — the user clicks
+ *      "Connect" on the m-i-n-d.ai consent page.
+ *   4. The browser is redirected back to the loopback server with ?code=...&state=...
+ *   5. Exchange the code at {base}/oauth/mcp/token (PKCE verified) and receive a
+ *      standard `mind_` API key as the access token.
+ *
+ * No dependencies beyond Node built-ins (http, crypto, child_process) and the
+ * global fetch available in Node 18+.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectViaBrowser = connectViaBrowser;
+const http = __importStar(require("http"));
+const crypto = __importStar(require("crypto"));
+const child_process_1 = require("child_process");
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+const CALLBACK_PATH = "/callback";
+const DEFAULT_CLIENT_NAME = "MIND Setup CLI";
+function base64url(buf) {
+    return buf.toString("base64url");
+}
+/** RFC 7636 §4.1 — 43–128 char base64url verifier. 64 random bytes → 86 chars. */
+function generatePkcePair() {
+    const verifier = base64url(crypto.randomBytes(64));
+    const challenge = base64url(crypto.createHash("sha256").update(verifier, "ascii").digest());
+    return { verifier, challenge };
+}
+function openInBrowser(url) {
+    try {
+        let child;
+        if (process.platform === "darwin") {
+            child = (0, child_process_1.spawn)("open", [url], { detached: true, stdio: "ignore" });
+        }
+        else if (process.platform === "win32") {
+            // `start` is a cmd built-in; empty "" is the window title slot.
+            child = (0, child_process_1.spawn)("cmd", ["/c", "start", "", url.replace(/&/g, "^&")], {
+                detached: true,
+                stdio: "ignore",
+            });
+        }
+        else {
+            child = (0, child_process_1.spawn)("xdg-open", [url], { detached: true, stdio: "ignore" });
+        }
+        child.on("error", () => {
+            /* swallow — the URL is printed as a fallback either way */
+        });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function htmlPage(title, heading, body, ok) {
+    const accent = ok ? "#10b981" : "#ef4444";
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<style>
+  body { margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;
+         background: #0b0f19; color: #e5e7eb; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+  .card { text-align: center; padding: 48px 56px; border-radius: 16px; background: #111827;
+          border: 1px solid #1f2937; box-shadow: 0 20px 60px rgba(0,0,0,.5); max-width: 440px; }
+  .badge { font-size: 44px; line-height: 1; margin-bottom: 18px; color: ${accent}; }
+  h1 { font-size: 20px; margin: 0 0 10px; font-weight: 600; }
+  p { margin: 0; color: #9ca3af; font-size: 14px; line-height: 1.6; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <div class="badge">${ok ? "✓" : "✕"}</div>
+    <h1>${heading}</h1>
+    <p>${body}</p>
+  </div>
+</body>
+</html>`;
+}
+const SUCCESS_PAGE = htmlPage("Connected to MIND", "✓ Connected to MIND", "You can close this tab and return to your terminal.", true);
+function errorPage(detail) {
+    return htmlPage("MIND connection failed", "Connection failed", `${detail} — close this tab and retry from your terminal.`, false);
+}
+async function registerClient(base, redirectUri, clientName) {
+    const res = await fetch(`${base}/oauth/mcp/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            redirect_uris: [redirectUri],
+            client_name: clientName,
+        }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`Client registration failed (${res.status}): ${text.slice(0, 300)}`);
+    }
+    const data = (await res.json());
+    if (!data.client_id) {
+        throw new Error("Client registration response did not include a client_id.");
+    }
+    return data.client_id;
+}
+async function exchangeCode(base, code, redirectUri, clientId, verifier) {
+    const res = await fetch(`${base}/oauth/mcp/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: redirectUri,
+            client_id: clientId,
+            code_verifier: verifier,
+        }).toString(),
+    });
+    const data = (await res.json().catch(() => ({})));
+    if (!res.ok || !data.access_token) {
+        const detail = data.error_description || data.error || `HTTP ${res.status}`;
+        throw new Error(`Token exchange failed: ${detail}`);
+    }
+    return data.access_token;
+}
+/**
+ * Run the full browser OAuth flow against a MIND backend and return the
+ * minted `mind_` API key.
+ */
+async function connectViaBrowser(baseUrl, options = {}) {
+    const base = baseUrl.replace(/\/+$/, "");
+    const clientName = options.clientName ?? DEFAULT_CLIENT_NAME;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const shouldOpenBrowser = options.openBrowser ?? process.env.MIND_CONNECT_NO_BROWSER !== "1";
+    const { verifier, challenge } = generatePkcePair();
+    const state = base64url(crypto.randomBytes(24));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        const server = http.createServer();
+        const finish = (err, key) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            // Stop accepting connections; in-flight responses use "Connection: close"
+            // so they flush fully and the server drains on its own.
+            server.close();
+            // Drop any lingering idle keep-alive sockets so the CLI exits promptly
+            // (Node 18.2+). Responses are flushed before this runs because every
+            // handler ends the response before calling finish().
+            setImmediate(() => {
+                server.closeIdleConnections?.();
+            });
+            if (err)
+                reject(err);
+            else
+                resolve(key);
+        };
+        server.on("error", (err) => finish(new Error(`Local callback server error: ${err.message}`)));
+        server.on("request", (req, res) => {
+            void (async () => {
+                const url = new URL(req.url ?? "/", "http://127.0.0.1");
+                if (url.pathname !== CALLBACK_PATH) {
+                    res.writeHead(404, { "Content-Type": "text/plain", Connection: "close" });
+                    res.end("Not found");
+                    return;
+                }
+                const respond = (status, html) => {
+                    res.writeHead(status, {
+                        "Content-Type": "text/html; charset=utf-8",
+                        "Cache-Control": "no-store",
+                        Connection: "close",
+                    });
+                    res.end(html);
+                };
+                const errParam = url.searchParams.get("error");
+                if (errParam) {
+                    const desc = url.searchParams.get("error_description") || errParam;
+                    respond(400, errorPage(desc));
+                    finish(new Error(`Authorization failed: ${desc}`));
+                    return;
+                }
+                const code = url.searchParams.get("code");
+                const returnedState = url.searchParams.get("state");
+                if (!code) {
+                    respond(400, errorPage("No authorization code was returned"));
+                    finish(new Error("Callback did not include an authorization code."));
+                    return;
+                }
+                if (returnedState !== state) {
+                    respond(400, errorPage("State mismatch — possible cross-site request forgery"));
+                    finish(new Error("State mismatch on OAuth callback — aborting (possible CSRF). Retry the connection."));
+                    return;
+                }
+                try {
+                    const accessToken = await exchangeCode(base, code, redirectUri, clientId, verifier);
+                    respond(200, SUCCESS_PAGE);
+                    finish(null, accessToken);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    respond(502, errorPage(message));
+                    finish(new Error(message));
+                }
+            })();
+        });
+        let redirectUri = "";
+        let clientId = "";
+        server.listen(0, "127.0.0.1", () => {
+            void (async () => {
+                try {
+                    const { port } = server.address();
+                    redirectUri = `http://127.0.0.1:${port}${CALLBACK_PATH}`;
+                    clientId = await registerClient(base, redirectUri, clientName);
+                    const authorizeUrl = `${base}/oauth/mcp/authorize?` +
+                        new URLSearchParams({
+                            response_type: "code",
+                            client_id: clientId,
+                            redirect_uri: redirectUri,
+                            state,
+                            code_challenge: challenge,
+                            code_challenge_method: "S256",
+                            scope: "mind:full",
+                        }).toString();
+                    options.onAuthorizeUrl?.(authorizeUrl);
+                    if (shouldOpenBrowser) {
+                        console.log("Opening your browser to connect to MIND...");
+                        openInBrowser(authorizeUrl);
+                        console.log("If the browser didn't open, use this link to connect:");
+                        console.log(`  ${authorizeUrl}`);
+                    }
+                    else {
+                        console.log("Open this link to connect:");
+                        console.log(`  ${authorizeUrl}`);
+                    }
+                    console.log("");
+                    console.log("Waiting for you to click \"Connect\" in the browser...");
+                    timer = setTimeout(() => {
+                        finish(new Error(`Timed out after ${Math.round(timeoutMs / 60000)} minutes waiting for the browser connection. Run the setup again to retry.`));
+                    }, timeoutMs);
+                    // Don't let the timer keep the process alive on its own.
+                    timer.unref?.();
+                }
+                catch (err) {
+                    finish(err instanceof Error ? err : new Error(String(err)));
+                }
+            })();
+        });
+    });
+}
+//# sourceMappingURL=oauth-connect.js.map

package/dist/oauth-connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-connect.js","sourceRoot":"","sources":["../src/oauth-connect.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;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,CA4wJjE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;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,CAo7JjE"}

package/dist/server.js

@@ -48,7 +48,7 @@ const integration_guide_js_1 = require("./integration-guide.js");
 function createMindMcpServer(client) {
     const server = new mcp_js_1.McpServer({
         name: "mind",
-        version: "0.17.0",
+        version: "0.23.0",
     }, {
         // Returned to every client in the MCP `initialize` response — the first
         // thing any connecting agent sees about how to integrate with MIND.
@@ -1392,6 +1392,155 @@ function createMindMcpServer(client) {
             };
         }
     });
+    // ─── mind_checklists ────────────────────────────────────
+    // The granular level beneath a Task. Shape: Template → Sections[phase] →
+    // Items. Templates (yours + flagship) instantiate into runs attached to a
+    // task or life item; items are toggled and runs completed (which mirrors the
+    // finished checklist into the knowledge graph).
+    server.tool("mind_checklists", "Manage checklists in MIND — the granular level beneath a Task in the Focus→Project→Outcome→Task→Checklist hierarchy. A checklist attaches to a task (parent_type=task) or a Life item (parent_type=life_item) and groups checkable steps into phase-bucketed sections (pre/run/post). Use list_templates/get_template/create_template for reusable blueprints (including global flagship templates), then create a run from a template_id or inline sections_json, toggle_item to check steps, and complete to finish + mirror it into the knowledge graph.", {
+        action: zod_1.z
+            .enum([
+            "list_templates", "get_template", "create_template",
+            "list", "create", "get", "toggle_item", "complete", "delete",
+        ])
+            .describe("What to do: list_templates/get_template/create_template (blueprints); list/create/get/toggle_item/complete/delete (runs)"),
+        template_id: zod_1.z.string().optional().describe("Template ID — required for get_template; optional on create (instantiate from a template)"),
+        checklist_id: zod_1.z.string().optional().describe("Checklist run ID — required for get/toggle_item/complete/delete"),
+        item_id: zod_1.z.string().optional().describe("Checklist item ID — required for toggle_item"),
+        title: zod_1.z.string().optional().describe("Title (required for create_template; optional for create run)"),
+        description: zod_1.z.string().optional().describe("Template description (create_template)"),
+        parent_type: zod_1.z.string().optional().describe("Attach a run to: task or life_item (required for create + list filter)"),
+        parent_id: zod_1.z.string().optional().describe("ID of the parent task / life item (required for create)"),
+        parent_label: zod_1.z.string().optional().describe("Optional human label for the parent"),
+        sections_json: zod_1.z.string().optional().describe('Inline sections as JSON, e.g. [{"title":"Setup","phase":"pre","items":[{"label":"do x"}]}] — for create_template or an inline create run'),
+    }, async ({ action, template_id, checklist_id, item_id, title, description, parent_type, parent_id, parent_label, sections_json }) => {
+        try {
+            const parseSections = () => {
+                if (!sections_json)
+                    return undefined;
+                const parsed = JSON.parse(sections_json);
+                if (!Array.isArray(parsed))
+                    throw new Error("sections_json must be a JSON array of sections");
+                return parsed;
+            };
+            const fmtTemplate = (t) => {
+                const secCount = (t.sections ?? []).length;
+                const itemCount = (t.sections ?? []).reduce((n, s) => n + (s.items?.length ?? 0), 0);
+                return `• ${t.title}${t.origin === "flagship" ? " ⭐ flagship" : ""} — ${secCount} section(s), ${itemCount} item(s) — id: ${t.template_id}`;
+            };
+            const fmtSections = (sections) => (sections ?? [])
+                .map((s) => {
+                const head = `  [${s.phase}] ${s.title}`;
+                const items = (s.items ?? [])
+                    .map((it) => `    ${it.checked ? "[x]" : "[ ]"} ${it.label} — id: ${it.item_id}`)
+                    .join("\n");
+                return items ? `${head}\n${items}` : head;
+            })
+                .join("\n");
+            const fmtChecklist = (c, withItems = false) => {
+                const p = c.progress ?? { done: 0, total: 0, pct: 0 };
+                const head = `• ${c.title} (${p.done}/${p.total}, ${p.pct}%)` +
+                    `${c.completed_at ? " ✅ complete" : ""}` +
+                    `${c.parent_label ? `, on ${c.parent_label}` : ""} — id: ${c.checklist_id}`;
+                return withItems ? `${head}\n${fmtSections(c.sections ?? [])}` : head;
+            };
+            switch (action) {
+                case "list_templates": {
+                    const result = await client.listChecklistTemplates();
+                    const templates = result.templates ?? [];
+                    if (templates.length === 0) {
+                        return { content: [{ type: "text", text: "No checklist templates found." }] };
+                    }
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `${result.total} template(s):\n` + templates.map(fmtTemplate).join("\n"),
+                            }],
+                    };
+                }
+                case "get_template": {
+                    if (!template_id) {
+                        return { content: [{ type: "text", text: "Error: template_id is required for get_template" }], isError: true };
+                    }
+                    const t = await client.getChecklistTemplate(template_id);
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `${fmtTemplate(t)}${t.description ? `\n${t.description}` : ""}\n${fmtSections(t.sections ?? [])}`,
+                            }],
+                    };
+                }
+                case "create_template": {
+                    if (!title) {
+                        return { content: [{ type: "text", text: "Error: title is required to create a template" }], isError: true };
+                    }
+                    const t = await client.createChecklistTemplate({
+                        title, description, sections: parseSections(),
+                    });
+                    return { content: [{ type: "text", text: `✅ Created template: ${fmtTemplate(t)}` }] };
+                }
+                case "list": {
+                    const result = await client.listChecklists(parent_type, parent_id);
+                    const checklists = result.checklists ?? [];
+                    if (checklists.length === 0) {
+                        return { content: [{ type: "text", text: "No checklists found." }] };
+                    }
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `${result.total} checklist(s):\n` + checklists.map((c) => fmtChecklist(c)).join("\n"),
+                            }],
+                    };
+                }
+                case "create": {
+                    if (!parent_type || !parent_id) {
+                        return { content: [{ type: "text", text: "Error: parent_type and parent_id are required to create a checklist run" }], isError: true };
+                    }
+                    const c = await client.createChecklist({
+                        parent_type, parent_id, parent_label, title,
+                        template_id, sections: parseSections(),
+                    });
+                    return { content: [{ type: "text", text: `✅ Created checklist:\n${fmtChecklist(c, true)}` }] };
+                }
+                case "get": {
+                    if (!checklist_id) {
+                        return { content: [{ type: "text", text: "Error: checklist_id is required for get" }], isError: true };
+                    }
+                    const c = await client.getChecklist(checklist_id);
+                    return { content: [{ type: "text", text: fmtChecklist(c, true) }] };
+                }
+                case "toggle_item": {
+                    if (!checklist_id || !item_id) {
+                        return { content: [{ type: "text", text: "Error: checklist_id and item_id are required for toggle_item" }], isError: true };
+                    }
+                    const c = await client.toggleChecklistItem(checklist_id, item_id);
+                    return { content: [{ type: "text", text: `✅ Toggled item:\n${fmtChecklist(c, true)}` }] };
+                }
+                case "complete": {
+                    if (!checklist_id) {
+                        return { content: [{ type: "text", text: "Error: checklist_id is required for complete" }], isError: true };
+                    }
+                    const c = await client.completeChecklist(checklist_id);
+                    return { content: [{ type: "text", text: `✅ Completed checklist "${c.title}" — mirrored to the knowledge graph.` }] };
+                }
+                case "delete": {
+                    if (!checklist_id) {
+                        return { content: [{ type: "text", text: "Error: checklist_id is required for delete" }], isError: true };
+                    }
+                    await client.deleteChecklist(checklist_id);
+                    return { content: [{ type: "text", text: `🗑️ Deleted checklist ${checklist_id}` }] };
+                }
+                default:
+                    return { content: [{ type: "text", text: `Unknown action: ${action}` }], isError: true };
+            }
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `mind_checklists error: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
     // ─── mind_crm ───────────────────────────────────────────
     // Read/write contacts, interactions, and activities.
     // Enhanced: delete, get, log_activity, list_activities.