@neuctra/notlix-mcp 1.0.0 → 2.0.1

package/README.md

@@ -1,26 +1,35 @@
 # @neuctra/notlix-mcp
 
-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.
+MCP server for Neuctra Notlix. It lets Claude Code, Claude Desktop, Cursor and other MCP tools work
+with your Notes, Knowledge, Documents, Presentations and Diagrams.
 
-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>`.
+| Tool | What it does |
+|---|---|
+| `list_notlix_items` | Lists or searches items, newest first, with ids |
+| `read_notlix_item` | Reads one item in full |
+| `create_notlix_item` | Creates a note, Knowledge item, document (from markdown), presentation (markdown, `---` between slides) or diagram (nodes and connectors, laid out for you) |
+| `edit_notlix_item` | Renames, applies find-and-replace edits, appends content, or adds nodes and connectors to a diagram |
 
-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.
+Nothing can be deleted. The vault (passwords, secure notes, API keys, files) is encrypted and out
+of reach. The AI acts as you, so it can read every item of these five types: only connect tools
+you trust.
 
 ## Setup
 
-In Notlix, open **Connect AI** and copy the connection token (`<id>.<secret>`).
+Requires Node.js 20 or later.
+
+```bash
+npx -y @neuctra/notlix-mcp login     # asks for your Notlix email and password
+```
+
+This saves a session (not your password) in `~/.config/notlix/session.json`, readable only by you.
+It's the same file the Notlix CLI uses, so one login covers both. Sessions last a day; when the AI
+says the sign-in has expired, run `login` again. No restart needed.
 
 Claude Code:
 
 ```bash
-claude mcp add notlix -e NOTLIX_TOKEN=<token> -- npx -y @neuctra/notlix-mcp
+claude mcp add notlix -- npx -y @neuctra/notlix-mcp
 ```
 
 Claude Desktop, Cursor and others (`mcp.json`):
@@ -28,37 +37,53 @@ Claude Desktop, Cursor and others (`mcp.json`):
 ```json
 {
   "mcpServers": {
-    "notlix": {
-      "command": "npx",
-      "args": ["-y", "@neuctra/notlix-mcp"],
-      "env": { "NOTLIX_TOKEN": "<token>" }
-    }
+    "notlix": { "command": "npx", "args": ["-y", "@neuctra/notlix-mcp"] }
   }
 }
 ```
 
-| Variable | |
+Other commands: `npx -y @neuctra/notlix-mcp whoami` and `npx -y @neuctra/notlix-mcp logout`.
+
+For Claude.ai and ChatGPT, use the remote server (`neuctra-notlix-mcp-http`) instead.
+
+## How it signs in
+
+Like the Notlix CLI, it talks to Authix with the website's publishable key (`pk_live_…`, already
+public in the website) and the website's `Origin`. Authix checks Origin to stop other websites
+using a browser's cookie; here you sign in with your own password. If the Notlix app on Authix
+ever gets an IP allowlist, this stops working, along with the CLI and every browser.
+
+| Variable | Default |
 |---|---|
-| `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`. |
+| `NOTLIX_AUTHIX_URL`, `NOTLIX_PUBLISHABLE_KEY`, `NOTLIX_APP_ID`, `NOTLIX_ORIGIN` | the website's settings, in `src/defaults.js` |
+| `NOTLIX_CONFIG_DIR` | `~/.config/notlix` |
+| `NOTLIX_EMAIL`, `NOTLIX_PASSWORD` | asked for by `login` when unset |
 
-Requires Node.js 20 or later.
+Plan item limits are checked by the website, not here, so items created through MCP aren't
+counted against them when they're created.
 
 ## As a library
 
-The remote Worker (`neuctra-notlix-mcp-http`) uses this package, so the tools exist in one place:
+Works in Node and on Cloudflare Workers; the remote server uses it:
 
 ```js
-import { createInboxClient, createNotlixServer, parseConnection } from "@neuctra/notlix-mcp";
+import { AuthixClient, createNotlixServer, sharedItemText } from "@neuctra/notlix-mcp";
 import { handleMcpRequest } from "@neuctra/notlix-mcp/http"; // Streamable HTTP, web-standard Request/Response
 ```
 
+`sharedItemText(authix, token)` returns a live-shared item (note, Knowledge, document or AI
+Brief) as plain text, with no sign-in. It powers "Link for AI".
+
 ## Development
 
 ```bash
 npm install
-npm test   # runs the tools against the real neuctra-notlix-server app with fake bindings
+npm run sync   # copy the website's helpers into src/shared, and its public settings into src/defaults.js
+npm test       # runs against a fake Authix
 ```
 
-The tests import `../neuctra-notlix-server` and `../neuctra-notlix-client`, so run `npm install` in
-the server folder first.
+Run `npm run sync` after changing `presentations.js`, `slideShapes.js`, `diagrams.js`,
+`aiEdits.js`, `records.js` or `contextPacks.js` in the client; a test fails when the copies drift.
+
+To release: bump `version` here and `VERSION` in `src/server.js`, `npm test`, `npm publish`, then
+update `@neuctra/notlix-mcp` in `neuctra-notlix-mcp-http` and redeploy it.

package/bin/notlix-mcp.js

@@ -1,29 +1,87 @@
 #!/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.
+// Notlix MCP for local AI tools.
+//
+//   npx -y @neuctra/notlix-mcp login     sign in (asks for email and password)
+//   npx -y @neuctra/notlix-mcp whoami    show who is signed in
+//   npx -y @neuctra/notlix-mcp logout    sign out
+//   npx -y @neuctra/notlix-mcp           run the MCP server over stdio (what AI tools start)
+//
+// stdout carries the MCP protocol when serving, so messages go to stderr.
 
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-import { DEFAULT_API_URL, createInboxClient, createNotlixServer, parseConnection } from "../src/index.js";
+import { AuthixClient, authixConfig, createNotlixServer } from "../src/index.js";
+import { ask } from "../src/cli/prompt.js";
+import { clearSession, configDir, isExpired, readSession, writeSession } from "../src/cli/session.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 LOGIN = "npx -y @neuctra/notlix-mcp login";
+const env = process.env;
+const dir = configDir(env);
+const config = authixConfig({
+  authixUrl: env.NOTLIX_AUTHIX_URL,
+  publishableKey: env.NOTLIX_PUBLISHABLE_KEY,
+  appId: env.NOTLIX_APP_ID,
+  origin: env.NOTLIX_ORIGIN,
+});
+const hint = `Ask the user to run this in a terminal, then try again: ${LOGIN}`;
+
+/** Reads the session file on every request, so a new login works without restarting the AI tool. */
+class FileSessionClient extends AuthixClient {
+  get session() {
+    const session = readSession(dir);
+    return session && !isExpired(session) ? session : null;
+  }
+
+  set session(_value) {}
+}
+
+function flag(name) {
+  const index = process.argv.indexOf(`--${name}`);
+  return index === -1 ? undefined : process.argv[index + 1];
+}
+
+async function login() {
+  const email = flag("email") || env.NOTLIX_EMAIL || (await ask("Notlix email: "));
+  const password = env.NOTLIX_PASSWORD || (await ask("Password: ", { hidden: true }));
+  const client = new AuthixClient({ config });
+  const session = await client.login(email.trim(), password);
+  writeSession(dir, session);
+  console.error(`Signed in as ${session.email}. AI tools can use Notlix until ${new Date(session.expiresAt).toLocaleString()}.`);
+}
+
+async function whoami() {
+  const session = readSession(dir);
+  if (!session || isExpired(session)) throw new Error(`Not signed in. Run: ${LOGIN}`);
+  const user = await new AuthixClient({ config, session, signInHint: `Run: ${LOGIN}` }).whoami();
+  if (!user) throw new Error(`Your session has expired. Run: ${LOGIN}`);
+  console.error(`Signed in as ${user.email}, until ${new Date(session.expiresAt).toLocaleString()}.`);
 }
 
-const apiUrl = process.env.NOTLIX_API_URL || DEFAULT_API_URL;
-const inbox = createInboxClient({ apiUrl, ...connection });
-const server = createNotlixServer(inbox);
-await server.connect(new StdioServerTransport());
+async function logout() {
+  const session = readSession(dir);
+  if (session) await new AuthixClient({ config, session }).logout();
+  clearSession(dir);
+  console.error("Signed out.");
+}
+
+async function serve() {
+  const authix = new FileSessionClient({ config, signInHint: hint });
+  const server = createNotlixServer(authix);
+  await server.connect(new StdioServerTransport());
+  if (!authix.session) console.error(`notlix-mcp: not signed in. Run: ${LOGIN}`);
+}
 
-// A bad token shouldn't stop the tools from listing, but say so early.
-inbox.getPublicKey().catch((err) => console.error(`notlix-mcp: ${err.message}`));
+const commands = { login, whoami, logout, serve };
+const command = process.argv[2] && !process.argv[2].startsWith("-") ? process.argv[2] : "serve";
+
+if (!commands[command]) {
+  console.error(`Unknown command "${command}". Use login, whoami, logout, or no command to serve.`);
+  process.exit(1);
+}
+
+try {
+  await commands[command]();
+} catch (err) {
+  console.error(err.message || String(err));
+  process.exit(1);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@neuctra/notlix-mcp",
-  "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.",
+  "version": "2.0.1",
+  "description": "MCP server for Neuctra Notlix: lets Claude Code, Claude Desktop, Cursor and other AI tools list, read, create and edit your Notes, Knowledge, Documents, Presentations and Diagrams.",
   "type": "module",
   "bin": {
     "notlix-mcp": "bin/notlix-mcp.js"
@@ -17,6 +17,7 @@
   ],
   "scripts": {
     "start": "node bin/notlix-mcp.js",
+    "sync": "node scripts/sync.mjs",
     "test": "node --test \"test/*.test.js\""
   },
   "engines": {
@@ -24,7 +25,16 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
+    "linkedom": "^0.18.15",
+    "marked": "^18.1.3",
     "zod": "^4.6.7"
   },
-  "license": "UNLICENSED"
+  "license": "UNLICENSED",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "notlix",
+    "neuctra",
+    "notes"
+  ]
 }

package/src/authix.js

@@ -0,0 +1,153 @@
+import defaults from "./defaults.js";
+import { itemsOf, nextCursorOf } from "./shared/records.js";
+
+// A small Authix client that works in Node and on Cloudflare Workers. It keeps
+// the user's session cookie itself and sends the website's Origin, the same way
+// the Notlix CLI does. Authix checks Origin to stop other websites using a
+// signed-in browser's cookie; here the user signed in with their own password.
+//
+// It acts only as the signed-in user, with the website's publishable key.
+
+export const SESSION_COOKIE = "authix_user_session";
+
+export class AuthixError extends Error {
+  constructor(message, { status = 0, code = "" } = {}) {
+    super(message);
+    this.name = "AuthixError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** Connection settings: the website's public ones, overridable. */
+export function authixConfig(overrides = {}) {
+  const pick = (key) => overrides[key] || defaults[key];
+  return {
+    authixUrl: String(pick("authixUrl")).replace(/\/+$/, ""),
+    publishableKey: pick("publishableKey"),
+    appId: pick("appId"),
+    origin: pick("origin"),
+  };
+}
+
+export class AuthixClient {
+  /**
+   * `session`: { cookie, userId, email, expiresAt } or null.
+   * `signInHint`: what to tell the user when the session has expired.
+   */
+  constructor({ config = authixConfig(), session = null, fetch: doFetch, signInHint = "Sign in again." } = {}) {
+    this.config = config;
+    this.session = session;
+    // Workers refuse fetch called as a method of another object, so it's wrapped.
+    this.fetch = doFetch || ((url, init) => globalThis.fetch(url, init));
+    this.signInHint = signInHint;
+  }
+
+  async request(method, path, body) {
+    const headers = {
+      "x-api-key": this.config.publishableKey,
+      Origin: this.config.origin,
+      Accept: "application/json",
+    };
+    if (this.session?.cookie) headers.Cookie = `${SESSION_COOKIE}=${this.session.cookie}`;
+
+    let payload;
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      payload = JSON.stringify({ ...(this.config.appId ? { appId: this.config.appId } : {}), ...body });
+    }
+
+    let response;
+    try {
+      response = await this.fetch(`${this.config.authixUrl}${path}`, { method, headers, body: payload });
+    } catch (err) {
+      // stderr: Worker logs, or the AI tool's MCP log. Never stdout, which carries MCP over stdio.
+      console.error(`notlix-mcp: request to Authix failed: ${err?.message || err}`);
+      throw new AuthixError("Can't reach Notlix. Check the internet connection.");
+    }
+
+    const data = await response.json().catch(() => null);
+    if (!response.ok) {
+      if (response.status === 401 && path !== "/users/login") {
+        throw new AuthixError(`The Notlix sign-in has expired. ${this.signInHint}`, { status: 401, code: data?.code });
+      }
+      throw new AuthixError(data?.message || `Notlix answered ${response.status}.`, {
+        status: response.status,
+        code: data?.code,
+      });
+    }
+    return { data, response };
+  }
+
+  /** Signs in and returns { cookie, userId, email, expiresAt }. */
+  async login(email, password) {
+    const { data, response } = await this.request("POST", "/users/login", { email, password });
+    const cookies = response.headers.getSetCookie?.() ?? [response.headers.get("set-cookie") || ""];
+    const match = cookies.map((line) => line.match(new RegExp(`^${SESSION_COOKIE}=([^;]+)`))).find(Boolean);
+    if (!match || !data?.user?.id) throw new AuthixError("Signed in, but no session came back.");
+
+    const maxAge = Number(cookies.join(";").match(/Max-Age=(\d+)/i)?.[1]);
+    this.session = {
+      cookie: match[1],
+      userId: data.user.id,
+      email: data.user.email,
+      expiresAt: new Date(Date.now() + (maxAge ? maxAge * 1000 : 86_400_000)).toISOString(),
+    };
+    return this.session;
+  }
+
+  async logout() {
+    await this.request("POST", "/users/logout", {}).catch(() => {});
+  }
+
+  /** The signed-in user, or null when the session no longer works. */
+  async whoami() {
+    const { data } = await this.request("GET", "/users/session");
+    return data?.authenticated ? data.user : null;
+  }
+
+  /**
+   * A record someone shared by link (Authix shareUserData), read with no
+   * sign-in: the token is the credential. Null when it isn't shared.
+   */
+  async getShared(token) {
+    try {
+      const { data } = await this.request("GET", `/shared/${encodeURIComponent(token)}`);
+      const record = data?.data && typeof data.data === "object" && !Array.isArray(data.data) ? data.data : null;
+      return record ? { ...record, dataCategory: String(record.dataCategory || "").toLowerCase() } : null;
+    } catch (err) {
+      if (err instanceof AuthixError && (err.status === 404 || err.code === "SHARE_NOT_FOUND")) return null;
+      throw err;
+    }
+  }
+
+  #userPath(rest = "") {
+    if (!this.session?.userId) throw new AuthixError(`Not signed in to Notlix. ${this.signInHint}`, { status: 401 });
+    return `/users/${encodeURIComponent(this.session.userId)}/data${rest}`;
+  }
+
+  /** Every record in a category, following pagination. */
+  async list(category) {
+    const all = [];
+    let cursor;
+    do {
+      const query = new URLSearchParams({ limit: "100", category });
+      if (cursor) query.set("cursor", cursor);
+      const { data } = await this.request("GET", this.#userPath(`?${query}`));
+      all.push(...itemsOf(data));
+      cursor = nextCursorOf(data);
+    } while (cursor);
+    return all;
+  }
+
+  async add(category, record) {
+    const { data } = await this.request("POST", this.#userPath(), { dataCategory: category, ...record });
+    return data?.data && typeof data.data === "object" && !Array.isArray(data.data) ? data.data : data;
+  }
+
+  /** Authix merges the fields given into the record. */
+  async update(dataId, fields) {
+    const { data } = await this.request("PUT", this.#userPath(`/${encodeURIComponent(dataId)}`), fields);
+    return data;
+  }
+}

package/src/cli/prompt.js

@@ -0,0 +1,27 @@
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+
+/** Asks on the terminal. Hidden input isn't echoed, for passwords. */
+export function ask(question, { hidden = false } = {}) {
+  if (!process.stdin.isTTY) {
+    return Promise.reject(new Error(`Can't ask "${question.trim()}" without a terminal.`));
+  }
+
+  let muted = false;
+  const output = new Writable({
+    write(chunk, encoding, done) {
+      if (!muted) process.stderr.write(chunk, encoding);
+      done();
+    },
+  });
+  const rl = createInterface({ input: process.stdin, output, terminal: true });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      if (hidden) process.stderr.write("\n");
+      resolve(answer);
+    });
+    muted = hidden;
+  });
+}

package/src/cli/session.js

@@ -0,0 +1,37 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// The sign-in session, in the same file the Notlix CLI uses
+// (~/.config/notlix/session.json, readable only by this user), so one login
+// covers both. It holds the Authix session cookie, never the password.
+
+export function configDir(env = process.env) {
+  return env.NOTLIX_CONFIG_DIR || join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "notlix");
+}
+
+const fileOf = (dir) => join(dir, "session.json");
+
+export function readSession(dir) {
+  try {
+    const session = JSON.parse(readFileSync(fileOf(dir), "utf8"));
+    return session?.cookie && session?.userId ? session : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeSession(dir, session) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = fileOf(dir);
+  writeFileSync(file, `${JSON.stringify(session, null, 2)}\n`, { mode: 0o600 });
+  // The mode only applies when the file is created.
+  chmodSync(file, 0o600);
+}
+
+export function clearSession(dir) {
+  const file = fileOf(dir);
+  if (existsSync(file)) rmSync(file);
+}
+
+export const isExpired = (session) => Boolean(session?.expiresAt) && Date.parse(session.expiresAt) <= Date.now();