@neuctra/notlix-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# @neuctra/notlix-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local MCP server for Neuctra Notlix. It lets Claude Code, Claude Desktop, Cursor and other MCP tools
+save to a Notlix account. It runs over stdio on the user's computer.
+
+Two tools:
+
+- `save_to_notlix`: adds a Knowledge item, Document, Presentation or Note.
+- `edit_in_notlix`: queues find-and-replace edits or appended text for one item the user turned
+  **Edit with AI** on for, addressed by a reference such as `ntx-doc-<16 hex>`.
+
+Each item is encrypted here, to the user's public key, before it is sent. The Notlix server only
+stores ciphertext, and only the user's browser can open it. The token is write-only: it can't read,
+search or delete anything.
+
+## Setup
+
+In Notlix, open **Connect AI** and copy the connection token (`<id>.<secret>`).
+
+Claude Code:
+
+```bash
+claude mcp add notlix -e NOTLIX_TOKEN=<token> -- npx -y @neuctra/notlix-mcp
+```
+
+Claude Desktop, Cursor and others (`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "notlix": {
+      "command": "npx",
+      "args": ["-y", "@neuctra/notlix-mcp"],
+      "env": { "NOTLIX_TOKEN": "<token>" }
+    }
+  }
+}
+```
+
+| Variable | |
+|---|---|
+| `NOTLIX_TOKEN` | Required. The connection token. An old URL ending in `/mcp/<id>.<secret>` works too. |
+| `NOTLIX_API_URL` | Optional. The Notlix server. Defaults to `https://server.notlix.neuctra.com`. |
+
+Requires Node.js 20 or later.
+
+## As a library
+
+The remote Worker (`neuctra-notlix-mcp-http`) uses this package, so the tools exist in one place:
+
+```js
+import { createInboxClient, createNotlixServer, parseConnection } from "@neuctra/notlix-mcp";
+import { handleMcpRequest } from "@neuctra/notlix-mcp/http"; // Streamable HTTP, web-standard Request/Response
+```
+
+## Development
+
+```bash
+npm install
+npm test   # runs the tools against the real neuctra-notlix-server app with fake bindings
+```
+
+The tests import `../neuctra-notlix-server` and `../neuctra-notlix-client`, so run `npm install` in
+the server folder first.

package/bin/notlix-mcp.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Local MCP server for Notlix over stdio. Configure it with:
+//   NOTLIX_TOKEN    the connection token from Notlix, Connect AI (required)
+//   NOTLIX_API_URL  the Notlix server (optional, defaults to production)
+// The token can also be passed as the first argument.
+// stdout carries the MCP protocol, so messages go to stderr.
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { DEFAULT_API_URL, createInboxClient, createNotlixServer, parseConnection } from "../src/index.js";
+
+const token = process.env.NOTLIX_TOKEN || process.argv[2];
+const connection = parseConnection(token);
+if (!connection) {
+  console.error(
+    token
+      ? "notlix-mcp: NOTLIX_TOKEN isn't a Notlix connection token. Copy it again from Notlix, Connect AI."
+      : "notlix-mcp: set NOTLIX_TOKEN to the connection token from Notlix, Connect AI.",
+  );
+  process.exit(1);
+}
+
+const apiUrl = process.env.NOTLIX_API_URL || DEFAULT_API_URL;
+const inbox = createInboxClient({ apiUrl, ...connection });
+const server = createNotlixServer(inbox);
+await server.connect(new StdioServerTransport());
+
+// A bad token shouldn't stop the tools from listing, but say so early.
+inbox.getPublicKey().catch((err) => console.error(`notlix-mcp: ${err.message}`));

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@neuctra/notlix-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "MCP server for Neuctra Notlix: lets Claude Code, Claude Desktop, Cursor and other MCP tools save to Notlix. Encrypts on your machine.",
+  "type": "module",
+  "bin": {
+    "notlix-mcp": "bin/notlix-mcp.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./http": "./src/http.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/notlix-mcp.js",
+    "test": "node --test \"test/*.test.js\""
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.6.7"
+  },
+  "license": "UNLICENSED"
+}

package/src/connection.js

@@ -0,0 +1,15 @@
+// The connection token the Notlix dashboard gives out under Connect AI:
+// `<inbox id>.<write secret>`. Older connections handed out a full URL ending
+// in /mcp/<id>.<secret>; that works too.
+
+export const DEFAULT_API_URL = "https://server.notlix.neuctra.com";
+
+const TOKEN = /^([0-9a-f]{32})\.([0-9a-f]{64})$/;
+
+/** `{ id, secret }` from a token or an old MCP URL, or null when it isn't one. */
+export function parseConnection(value) {
+  const text = String(value || "").trim();
+  const token = text.includes("/mcp/") ? text.split("/mcp/").pop().split(/[/?#]/)[0] : text;
+  const match = TOKEN.exec(token);
+  return match ? { id: match[1], secret: match[2] } : null;
+}

package/src/http.js

@@ -0,0 +1,53 @@
+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.
+
+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);
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+    enableJsonResponse: true,
+  });
+  await server.connect(transport);
+  try {
+    return await transport.handleRequest(request);
+  } finally {
+    // JSON responses are complete once returned.
+    transport.close();
+    server.close();
+  }
+}

package/src/inbox.js

@@ -0,0 +1,60 @@
+import { seal } from "./seal.js";
+
+// Talks to the Notlix server's inbox API with the write token. It can fetch the
+// inbox's public key and add encrypted items. It can't read anything.
+
+/** An error whose message is safe to show the AI and the user. */
+export class InboxError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "InboxError";
+    this.status = status;
+  }
+}
+
+const UNREACHABLE = "Couldn't reach Notlix. Check the connection and try again.";
+
+/**
+ * `apiUrl`: the Notlix server. `fetch`: optional, for a Cloudflare service
+ * binding or tests. The public key is fetched once and kept.
+ */
+export function createInboxClient({ apiUrl, id, secret, fetch: doFetch = globalThis.fetch }) {
+  const base = String(apiUrl).replace(/\/+$/, "");
+  const headers = { Authorization: `Bearer ${secret}` };
+  let publicKey = null;
+
+  async function call(path, init = {}) {
+    let res;
+    try {
+      res = await doFetch(`${base}/v1/inboxes/${id}${path}`, {
+        ...init,
+        headers: { ...headers, ...init.headers },
+      });
+    } catch {
+      throw new InboxError(UNREACHABLE, 0);
+    }
+    if (res.ok) return res.json();
+    const body = await res.json().catch(() => null);
+    if (res.status === 401) publicKey = null;
+    throw new InboxError(body?.error?.message || UNREACHABLE, res.status);
+  }
+
+  async function getPublicKey() {
+    if (!publicKey) publicKey = (await call("/key")).publicKey;
+    return publicKey;
+  }
+
+  return {
+    getPublicKey,
+    /** Encrypts `item` here and adds it to the inbox. Returns the item id. */
+    async add(item) {
+      const sealed = await seal(await getPublicKey(), item);
+      const { id: itemId } = await call("/items", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(sealed),
+      });
+      return itemId;
+    },
+  };
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { DEFAULT_API_URL, parseConnection } from "./connection.js";
+export { InboxError, createInboxClient } from "./inbox.js";
+export { seal } from "./seal.js";
+export { VERSION, createNotlixServer } from "./server.js";

package/src/seal.js

@@ -0,0 +1,32 @@
+// Encrypts an item to the inbox's public key (ECDH P-256 + AES-GCM, a new key
+// pair per item). Only the user's browser holds the private key; it opens
+// items with openInboxItem in the Notlix client (lib/security/inboxCrypto.js).
+
+const EC = { name: "ECDH", namedCurve: "P-256" };
+
+function toBase64(bytes) {
+  let binary = "";
+  for (const byte of new Uint8Array(bytes)) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+/** Returns `{ x, y, iv, cipher }`, the shape the Notlix server stores. */
+export async function seal(publicKey, item) {
+  const recipient = await crypto.subtle.importKey("jwk", publicKey, EC, false, []);
+  const ephemeral = await crypto.subtle.generateKey(EC, true, ["deriveKey"]);
+  const key = await crypto.subtle.deriveKey(
+    { name: "ECDH", public: recipient },
+    ephemeral.privateKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt"],
+  );
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const cipher = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    key,
+    new TextEncoder().encode(JSON.stringify(item)),
+  );
+  const { x, y } = await crypto.subtle.exportKey("jwk", ephemeral.publicKey);
+  return { x, y, iv: toBase64(iv), cipher: toBase64(cipher) };
+}

package/src/server.js

@@ -0,0 +1,141 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { InboxError } from "./inbox.js";
+
+// The Notlix MCP tools. Used by the local stdio command (bin/notlix-mcp.js) and
+// by the remote Worker (neuctra-notlix-mcp-http). Items are encrypted here,
+// before they leave, so the Notlix server never sees the text. The write token
+// can add items and queue text edits for items the user turned AI editing on
+// for. It can't read anything.
+
+export const VERSION = "1.0.0";
+
+const TOOL_DESCRIPTION = `Save something to the user's Neuctra Notlix account so it isn't lost when this chat ends.
+
+Use this when the user asks you to save, remember or store something in Notlix. Write a clear title and a self-contained document that makes sense without this chat. Use type "knowledge" (markdown) for reference material, decisions and project context, type "document" (markdown) for finished, formatted writing the user will read, edit or export, such as reports, proposals and letters, type "presentation" for slide decks, and type "note" (plain text) for quick notes.
+
+For a presentation, write markdown with --- on its own line between slides. Start each slide with a # heading, follow it with short - bullets, and add a line starting with Notes: at the end of a slide for speaker notes. Keep each slide to about six short bullets. Images are not supported.
+
+Never save passwords, API keys, tokens or other secrets: Knowledge, Documents, Presentations and Notes are not encrypted in the account. This tool can only add new items. To change an item that already exists, use edit_in_notlix with the reference the user gives you. Nothing here can read or search Notlix.`;
+
+const EDIT_DESCRIPTION = `Edit an item in the user's Neuctra Notlix account that the user chose to share with you: fix typos, reword, or add more content at the end, such as new research.
+
+You can only edit an item the user gave you a Notlix reference for. It looks like ntx-doc-3f9a1c2b7d4e5f60, and the user copies it from Notlix together with the item's current text. Without a reference, ask the user to open the item in Notlix, choose "Edit with AI" and paste what it copies. Never make up a reference: edits with any other reference are refused.
+
+- edits: each find is copied exactly from the item's current text and replaced with replace. Every occurrence is replaced, so include enough surrounding words to match only the place you mean. For documents, copy the words as they read, without markdown symbols such as ** or #, and keep each find inside one paragraph and one style (a find can't cross bold or a link). For presentations and diagrams, keep each find inside one bullet, table cell, notes field, shape or connector label. replace is plain text.
+- append: new content added at the end. Markdown for knowledge (ntx-kn) and documents (ntx-doc), plain text for notes (ntx-note), and for presentations (ntx-ppt) new slides written as markdown with --- between slides, a # title and - bullets. Diagrams (ntx-dgm) can't take appended content.
+
+You can't delete items, rename them, or edit the encrypted vault. Edits are applied the next time the user opens Notlix. If a find doesn't match, that edit is skipped and the user is told, so you won't see an error here.`;
+
+// Matches newAiEditRef in the client. The prefix says what kind of item it is.
+const EDIT_REF = /^ntx-(kn|doc|ppt|dgm|note)-[0-9a-f]{16}$/;
+
+const DESTINATIONS = {
+  knowledge: "Knowledge",
+  document: "Documents",
+  presentation: "Presentations",
+  note: "Notes",
+};
+
+/** Sends an item. Returns a tool error result when it couldn't, or null. */
+async function send(inbox, item) {
+  try {
+    await inbox.add(item);
+    return null;
+  } catch (err) {
+    if (!(err instanceof InboxError)) throw err;
+    return { isError: true, content: [{ type: "text", text: err.message }] };
+  }
+}
+
+/** An MCP server with save_to_notlix and edit_in_notlix. `inbox` comes from createInboxClient. */
+export function createNotlixServer(inbox) {
+  const server = new McpServer({ name: "neuctra-notlix", version: VERSION });
+
+  server.registerTool(
+    "save_to_notlix",
+    {
+      title: "Save to Notlix",
+      description: TOOL_DESCRIPTION,
+      inputSchema: {
+        title: z.string().trim().min(1).max(200).describe("Short, descriptive title."),
+        content: z.string().min(1).max(200_000).describe("The full text to save."),
+        type: z
+          .enum(["knowledge", "document", "presentation", "note"])
+          .default("knowledge")
+          .describe('"knowledge" for markdown reference material, "document" for formatted markdown writing, "presentation" for slides written as markdown split by ---, "note" for plain text.'),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    },
+    async ({ title, content, type }) => {
+      const failed = await send(inbox, { title, content, type });
+      if (failed) return failed;
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Saved "${title}". It will appear in ${DESTINATIONS[type]} the next time the user opens Notlix.`,
+          },
+        ],
+      };
+    },
+  );
+
+  server.registerTool(
+    "edit_in_notlix",
+    {
+      title: "Edit in Notlix",
+      description: EDIT_DESCRIPTION,
+      inputSchema: {
+        ref: z
+          .string()
+          .trim()
+          .regex(EDIT_REF, "Not a Notlix reference. Ask the user to copy one with Edit with AI in Notlix.")
+          .describe("The Notlix reference the user gave you, such as ntx-doc-3f9a1c2b7d4e5f60."),
+        edits: z
+          .array(
+            z.object({
+              find: z.string().min(1).max(10_000).describe("Exact text currently in the item."),
+              replace: z.string().max(50_000).describe("The text to put in its place."),
+            }),
+          )
+          .max(50)
+          .optional()
+          .describe("Find-and-replace changes, such as typo fixes or rewording."),
+        append: z.string().max(200_000).optional().describe("New content to add at the end."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    },
+    async ({ ref, edits = [], append = "" }) => {
+      const refuse = (text) => ({ isError: true, content: [{ type: "text", text }] });
+
+      if (edits.length === 0 && !append.trim()) {
+        return refuse("Nothing to change. Give at least one edit or some text to append.");
+      }
+      if (ref.startsWith("ntx-dgm-") && append.trim()) {
+        return refuse("Diagrams can't take appended content. Use edits to change the text in shapes and connector labels.");
+      }
+      if (edits.some(({ find, replace }) => find === replace)) {
+        return refuse("An edit's find and replace are the same, so it wouldn't change anything.");
+      }
+
+      const failed = await send(inbox, { action: "edit", ref, edits, append });
+      if (failed) return failed;
+
+      const parts = [];
+      if (edits.length) parts.push(`${edits.length} ${edits.length === 1 ? "edit" : "edits"}`);
+      if (append.trim()) parts.push("new content at the end");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Queued ${parts.join(" and ")} for ${ref}. They will be applied the next time the user opens Notlix, if that item still allows AI edits. Any edit whose text doesn't match is skipped, and the user is told.`,
+          },
+        ],
+      };
+    },
+  );
+
+  return server;
+}