@neuctra/notlix-mcp 1.0.0 → 2.0.1

package/src/content.js

@@ -0,0 +1,263 @@
+import { documentToReadable, editDocument, markdownToDocument } from "./documents.js";
+import { editDiagram, editKnowledge, editNote, editPresentation } from "./shared/aiEdits.js";
+import { DIAGRAM_SHAPES, boundsOf, createEdge, createNode, diagramText, normalizeDiagram } from "./shared/diagrams.js";
+import { markdownToSlides, normalizeSlides, slidesText } from "./shared/presentations.js";
+
+// The five content types an AI can manage, and how each is read, created and
+// edited. Records are shaped exactly as the Notlix services write them
+// (neuctra-notlix-client/services/*.service.js). None of these are encrypted;
+// the vault (passwords, secure notes, API keys, files) is never touched.
+
+export const TYPES = ["note", "knowledge", "document", "presentation", "diagram"];
+
+export const TYPE_LABELS = {
+  note: "Notes",
+  knowledge: "Knowledge",
+  document: "Documents",
+  presentation: "Presentations",
+  diagram: "Diagrams",
+};
+
+// From NOTE_CATEGORIES and DOCUMENT_CATEGORIES in the client services.
+export const NOTE_CATEGORIES = ["general", "work", "personal", "learning", "ideas", "project", "meeting", "research", "journal"];
+export const DOCUMENT_CATEGORIES = ["general", "work", "personal", "project", "meeting", "research"];
+
+export const DIAGRAM_SHAPE_IDS = DIAGRAM_SHAPES.map((shape) => shape.id);
+
+// Authix refuses saves over about 100 KB.
+export const MAX_RECORD_BYTES = 100_000;
+
+export class ContentError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContentError";
+  }
+}
+
+const now = () => new Date().toISOString();
+
+// ---- Reading -----------------------------------------------------------------
+
+function noteText(record) {
+  if (typeof record.content === "string") return record.content;
+  return (Array.isArray(record.content) ? record.content : [])
+    .map((block) => (typeof block?.content === "string" ? block.content : ""))
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+function slidesToReadable(slides) {
+  return normalizeSlides(slides)
+    .map((slide, index) => {
+      const lines = [`<!-- slide ${index + 1} -->`];
+      for (const element of slide.elements) {
+        if (element.rows) lines.push(...element.rows.map((row) => `| ${row.join(" | ")} |`));
+        else if (typeof element.text === "string" && element.text.trim()) {
+          if (element.role === "title") lines.push(`# ${element.text}`);
+          else if (element.bullets) lines.push(...element.text.split("\n").map((line) => `- ${line}`));
+          else lines.push(element.text);
+        }
+      }
+      if (slide.notes) lines.push(`Notes: ${slide.notes}`);
+      return lines.join("\n");
+    })
+    .join("\n\n---\n\n");
+}
+
+function diagramToReadable(record) {
+  const { nodes, edges } = normalizeDiagram(record);
+  const textOf = new Map(nodes.map((node) => [node.id, node.text || "(no text)"]));
+  const lines = ["Nodes:"];
+  for (const node of nodes) lines.push(`- [${node.id}] ${node.text || "(no text)"} (${node.shape})`);
+  lines.push("", "Connectors:");
+  for (const edge of edges) {
+    const label = edge.label ? `: ${edge.label}` : "";
+    lines.push(`- [${edge.from}] ${textOf.get(edge.from) ?? "?"} -> [${edge.to}] ${textOf.get(edge.to) ?? "?"}${label}`);
+  }
+  return lines.join("\n");
+}
+
+/** The item's content as text an AI can read. */
+export function readableContent(type, record) {
+  switch (type) {
+    case "note":
+      return noteText(record);
+    case "knowledge":
+      return typeof record.content === "string" ? record.content : "";
+    case "document":
+      return documentToReadable(record.html);
+    case "presentation":
+      return slidesToReadable(record.slides);
+    case "diagram":
+      return diagramToReadable(record);
+    default:
+      return "";
+  }
+}
+
+/** Text to search in: the title plus whatever the item says. */
+export function searchableText(type, record) {
+  const body =
+    type === "note" ? noteText(record) : type === "knowledge" ? record.content : record.text;
+  return `${record.title || ""} ${typeof body === "string" ? body : ""}`.toLowerCase();
+}
+
+// ---- Diagrams from a simple description -------------------------------------
+
+const GAP_X = 220;
+const GAP_Y = 160;
+
+/**
+ * Lays nodes out in rows, top to bottom, following the connectors. `nodes` use
+ * the AI's own keys; edges name those keys (or existing node ids). Returns the
+ * created nodes and edges, with keys mapped to real ids.
+ */
+function layOut(newNodes, newEdges, { existing = [], top = 0 } = {}) {
+  const keys = newNodes.map((node) => String(node.id));
+  if (new Set(keys).size !== keys.length) throw new ContentError("Each node needs its own id.");
+
+  const existingIds = new Set(existing.map((node) => node.id));
+  const isNew = new Set(keys);
+  for (const edge of newEdges) {
+    for (const end of [edge.from, edge.to]) {
+      if (!isNew.has(String(end)) && !existingIds.has(String(end))) {
+        throw new ContentError(`A connector names "${end}", which isn't a node id.`);
+      }
+    }
+  }
+
+  // Each new node's row is one below the deepest new node pointing at it.
+  const level = new Map(keys.map((key) => [key, 0]));
+  for (let pass = 0; pass < keys.length; pass += 1) {
+    let changed = false;
+    for (const { from, to } of newEdges) {
+      const a = String(from);
+      const b = String(to);
+      if (isNew.has(a) && isNew.has(b) && level.get(b) < level.get(a) + 1 && level.get(a) + 1 < keys.length) {
+        level.set(b, level.get(a) + 1);
+        changed = true;
+      }
+    }
+    if (!changed) break;
+  }
+
+  const rows = [];
+  for (const node of newNodes) {
+    const row = level.get(String(node.id));
+    (rows[row] ||= []).push(node);
+  }
+
+  const ids = new Map();
+  const nodes = [];
+  rows.filter(Boolean).forEach((row, rowIndex) => {
+    row.forEach((node, index) => {
+      const x = (index - (row.length - 1) / 2) * GAP_X;
+      const created = createNode(node.shape || "rect", x, top + rowIndex * GAP_Y, { text: String(node.text || "") });
+      ids.set(String(node.id), created.id);
+      nodes.push(created);
+    });
+  });
+
+  const edges = newEdges.map((edge) =>
+    createEdge(ids.get(String(edge.from)) ?? String(edge.from), ids.get(String(edge.to)) ?? String(edge.to), {
+      label: String(edge.label || ""),
+    }),
+  );
+  return { nodes, edges };
+}
+
+// ---- Creating ----------------------------------------------------------------
+
+/** The record to save for a new item. */
+export function newRecord(type, { title, content = "", category, diagram }) {
+  const created = now();
+  const base = { title: title.trim(), isPinned: false, createdAt: created, updatedAt: created };
+
+  switch (type) {
+    case "note":
+      return {
+        ...base,
+        content: content.trim() ? [{ id: `blk_${Date.now()}`, type: "text", content: content.trim() }] : [],
+        category: NOTE_CATEGORIES.includes(category) ? category : "general",
+      };
+    case "knowledge":
+      return { ...base, content };
+    case "document":
+      return {
+        ...base,
+        ...markdownToDocument(content),
+        category: DOCUMENT_CATEGORIES.includes(category) ? category : "general",
+      };
+    case "presentation": {
+      const slides = markdownToSlides(content || `# ${title}`);
+      return { ...base, themeId: "paper", slides, text: slidesText(slides) };
+    }
+    case "diagram": {
+      if (!diagram?.nodes?.length) throw new ContentError("A diagram needs at least one node in diagram.nodes.");
+      const { nodes, edges } = layOut(diagram.nodes, diagram.edges || []);
+      return { ...base, themeId: "paper", nodes, edges, text: diagramText({ nodes, edges }) };
+    }
+    default:
+      throw new ContentError(`Unknown type "${type}".`);
+  }
+}
+
+// ---- Editing -----------------------------------------------------------------
+
+/**
+ * The fields to change on an existing item. `edits` are find-and-replace pairs
+ * on its text, `append` is added at the end, `diagram` adds nodes and
+ * connectors. Returns `{ changes, missed }`; missed lists finds that didn't match.
+ */
+export function editRecord(type, record, { title, edits = [], append = "", diagram }) {
+  const request = { edits, append: String(append || "") };
+  let result;
+
+  switch (type) {
+    case "note":
+      result = editNote(record, request);
+      break;
+    case "knowledge":
+      result = editKnowledge(record, request);
+      break;
+    case "document":
+      result = editDocument(record, request);
+      break;
+    case "presentation":
+      result = editPresentation(record, request);
+      result.changes.text = slidesText(result.changes.slides);
+      break;
+    case "diagram": {
+      if (request.append.trim()) {
+        throw new ContentError("Diagrams can't take appended text. Use diagram.nodes and diagram.edges to add to one.");
+      }
+      result = editDiagram(record, request);
+      if (diagram?.nodes?.length || diagram?.edges?.length) {
+        const { nodes, edges } = result.changes;
+        const bounds = boundsOf(nodes);
+        const top = nodes.length ? bounds.y + bounds.h + GAP_Y : 0;
+        const added = layOut(diagram.nodes || [], diagram.edges || [], { existing: nodes, top });
+        result.changes.nodes = [...nodes, ...added.nodes];
+        result.changes.edges = [...edges, ...added.edges];
+      }
+      result.changes.text = diagramText(result.changes);
+      break;
+    }
+    default:
+      throw new ContentError(`Unknown type "${type}".`);
+  }
+
+  if (title !== undefined) result.changes.title = title.trim();
+  result.changes.updatedAt = now();
+  return result;
+}
+
+/** Throws when a record is too big for Authix to accept. */
+export function checkSize(record) {
+  const bytes = new TextEncoder().encode(JSON.stringify(record)).length;
+  if (bytes > MAX_RECORD_BYTES) {
+    throw new ContentError(
+      `That's too big for one Notlix item (${Math.round(bytes / 1000)} KB, the limit is about 100 KB). Split it into smaller items.`,
+    );
+  }
+}

package/src/defaults.js

@@ -0,0 +1,8 @@
+// Written by scripts/sync.mjs from the website's public settings.
+
+export default {
+  "authixUrl": "https://server.authix.neuctra.com/api",
+  "publishableKey": "pk_live_d992acbc_94a61ccb2354550f205674733b5e77bb7e3e51774d4544fd",
+  "appId": "7870561b328f8fb3a5beec64fbb81443",
+  "origin": "https://notlix.neuctra.com"
+};

package/src/documents.js

@@ -0,0 +1,133 @@
+import { Marked } from "marked";
+import { parseHTML } from "linkedom";
+
+// Documents are stored as HTML for the Notlix document editor. The website
+// converts AI markdown in the browser (cms-core + DOMPurify); there is no DOM
+// here, so this builds the HTML itself and never lets raw HTML through: tags an
+// AI writes are shown as text, and only http(s) and mailto links are kept.
+
+const escapeHtml = (text) =>
+  String(text).replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char]);
+
+const SAFE_URL = /^(https?:|mailto:)/i;
+
+const marked = new Marked({
+  gfm: true,
+  renderer: {
+    html({ text }) {
+      return escapeHtml(text);
+    },
+    link({ href, title, tokens }) {
+      const label = this.parser.parseInline(tokens);
+      if (!SAFE_URL.test(String(href).trim())) return label;
+      const titleAttr = title ? ` title="${escapeHtml(title)}"` : "";
+      return `<a href="${escapeHtml(href)}"${titleAttr} target="_blank" rel="noopener noreferrer">${label}</a>`;
+    },
+    image({ href, text }) {
+      if (!/^https?:/i.test(String(href).trim())) return escapeHtml(text || "");
+      return `<img src="${escapeHtml(href)}" alt="${escapeHtml(text || "")}">`;
+    },
+  },
+});
+
+function bodyOf(html) {
+  return parseHTML(`<!doctype html><html><body>${html}</body></html>`).document.body;
+}
+
+/** Plain text of some HTML, for card previews and search. */
+export function htmlToText(html) {
+  return bodyOf(String(html || "")).textContent || "";
+}
+
+/** `{ html, text }` for a document, from markdown. */
+export function markdownToDocument(markdown) {
+  const html = marked.parse(String(markdown || ""), { async: false });
+  return { html, text: htmlToText(html) };
+}
+
+const BLOCKS = new Set(["P", "DIV", "SECTION", "ARTICLE", "HEADER", "FOOTER", "FIGURE", "FIGCAPTION", "UL", "OL", "TABLE", "HR"]);
+
+/**
+ * A readable, markdown-like view of a document for an AI. Headings get #,
+ * list items get -, tables become rows of |. Bold and links are left as plain
+ * words, which is also how a find must be written to match.
+ */
+export function documentToReadable(html) {
+  const out = [];
+  const walk = (node, listIndex = null) => {
+    if (node.nodeType === 3) {
+      out.push(node.nodeValue.replace(/\s+/g, " "));
+      return;
+    }
+    if (node.nodeType !== 1) return;
+    const tag = node.tagName;
+    const children = (index) => node.childNodes.forEach((child) => walk(child, index));
+
+    if (/^H[1-6]$/.test(tag)) {
+      out.push(`\n\n${"#".repeat(Number(tag[1]))} `);
+      children();
+      out.push("\n\n");
+    } else if (tag === "BR") out.push("\n");
+    else if (tag === "LI") {
+      out.push(listIndex === null ? "\n- " : `\n${listIndex}. `);
+      children();
+    } else if (tag === "OL") {
+      out.push("\n");
+      let index = 0;
+      node.childNodes.forEach((child) => walk(child, child.tagName === "LI" ? (index += 1) : null));
+      out.push("\n");
+    } else if (tag === "PRE") out.push(`\n\n\`\`\`\n${node.textContent}\n\`\`\`\n\n`);
+    else if (tag === "BLOCKQUOTE") out.push(`\n\n> ${node.textContent.trim().replace(/\n+/g, "\n> ")}\n\n`);
+    else if (tag === "TR") {
+      out.push("\n|");
+      node.childNodes.forEach((cell) => {
+        if (cell.nodeType === 1) out.push(` ${cell.textContent.trim()} |`);
+      });
+    } else if (tag === "IMG") out.push(`[image${node.getAttribute("alt") ? `: ${node.getAttribute("alt")}` : ""}]`);
+    else if (tag === "HR") out.push("\n\n---\n\n");
+    else if (BLOCKS.has(tag)) {
+      out.push("\n\n");
+      children();
+      out.push("\n\n");
+    } else children();
+  };
+  bodyOf(String(html || "")).childNodes.forEach((node) => walk(node));
+  return out
+    .join("")
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+const replaceAll = (text, find, replace) => text.split(find).join(replace);
+
+/**
+ * Applies find-and-replace edits to a document's text nodes only, so edits
+ * can't add markup, and appends markdown at the end. Returns
+ * `{ changes: { html, text }, missed }`, like the website's editDocument.
+ */
+export function editDocument(record, { edits = [], append = "" }) {
+  const body = bodyOf(String(record.html || ""));
+  const textNodes = [];
+  const collect = (node) => {
+    if (node.nodeType === 3) textNodes.push(node);
+    node.childNodes?.forEach(collect);
+  };
+  collect(body);
+
+  const missed = [];
+  for (const { find, replace } of edits) {
+    let found = false;
+    for (const node of textNodes) {
+      if (node.nodeValue.includes(find)) {
+        node.nodeValue = replaceAll(node.nodeValue, find, replace);
+        found = true;
+      }
+    }
+    if (!found) missed.push(find);
+  }
+
+  let html = body.innerHTML;
+  if (String(append).trim()) html += markdownToDocument(append).html;
+  return { changes: { html, text: htmlToText(html) }, missed };
+}

package/src/http.js

@@ -1,43 +1,14 @@
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 
-import { parseConnection } from "./connection.js";
-import { InboxError, createInboxClient } from "./inbox.js";
 import { createNotlixServer } from "./server.js";
 
-// Remote MCP over Streamable HTTP, with web-standard Request/Response so it runs
-// on Cloudflare Workers (neuctra-notlix-mcp-http). The token is part of the URL,
-// /mcp/<id>.<secret>, because a URL is the one thing every MCP client can be given.
+// Remote MCP over Streamable HTTP with web-standard Request/Response, for
+// Cloudflare Workers (neuctra-notlix-mcp-http). Signing the user in is the
+// caller's job: pass an AuthixClient that already holds their session.
 
-const json = (status, body) =>
-  new Response(JSON.stringify(body), {
-    status,
-    headers: { "Content-Type": "application/json", "X-Content-Type-Options": "nosniff" },
-  });
-
-const invalid = () =>
-  json(401, { error: { code: "INVALID_TOKEN", message: "This connection isn't valid. Reconnect from Notlix." } });
-
-/**
- * Answers one MCP request for `token`. Stateless: a new server and transport
- * each time. `apiUrl` is the Notlix server; `fetch` is optional (a service binding).
- */
-export async function handleMcpRequest(request, { token, apiUrl, fetch }) {
-  const connection = parseConnection(token);
-  if (!connection) return invalid();
-
-  const inbox = createInboxClient({ apiUrl, ...connection, fetch });
-  try {
-    // Checks the token, so a wrong URL fails when it's added, not on first save.
-    await inbox.getPublicKey();
-  } catch (err) {
-    if (err instanceof InboxError && err.status === 401) return invalid();
-    if (err instanceof InboxError && err.status === 429) {
-      return json(429, { error: { code: "RATE_LIMITED", message: err.message } });
-    }
-    return json(502, { error: { code: "UPSTREAM", message: err.message } });
-  }
-
-  const server = createNotlixServer(inbox);
+/** Answers one MCP request. Stateless: a new server and transport each time. */
+export async function handleMcpRequest(request, { authix }) {
+  const server = createNotlixServer(authix);
   const transport = new WebStandardStreamableHTTPServerTransport({
     sessionIdGenerator: undefined,
     enableJsonResponse: true,

package/src/index.js

@@ -1,4 +1,8 @@
-export { DEFAULT_API_URL, parseConnection } from "./connection.js";
-export { InboxError, createInboxClient } from "./inbox.js";
-export { seal } from "./seal.js";
+// Works in Node and on Cloudflare Workers. The sign-in commands and session
+// file are Node-only and live in src/cli/.
+
+export { AuthixClient, AuthixError, SESSION_COOKIE, authixConfig } from "./authix.js";
+export { ContentError, TYPES, TYPE_LABELS } from "./content.js";
+export { markdownToDocument, documentToReadable } from "./documents.js";
 export { VERSION, createNotlixServer } from "./server.js";
+export { SHARE_TOKEN, sharedItemText } from "./sharedText.js";