@tiongcreative/assistant-mcp 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.4.0] - 2026-10-19
+
+### Added
+
+- One-command setup, status and removal for ChatGPT desktop on the same Mac. ChatGPT runs the existing local assistant server; app access still depends on each app's assistant setting.
+
+## [0.3.0] - 2026-10-19
+
+### Added
+
+- Lists & Notes can now be changed, with Lists & Notes 1.23.0 or later: `lists_and_notes_add_items`, `lists_and_notes_update_items` (tick, untick, reword or annotate items named by their text), `lists_and_notes_add_list`, `lists_and_notes_add_note` and `lists_and_notes_update_note` (append, replace or rename). Changes to an existing list or note send the `modified` stamp last read; if the user changed it in the meantime the app refuses, and the tool re-reads and retries once. Item ids are always sent back. An older Lists & Notes gets a message saying which version writes need. No delete tool. End-to-end test against the real 1.23.0 server.
+
 ## [0.2.0] - 2026-10-19
 
 ### Added

package/README.md

@@ -10,12 +10,12 @@ nothing else happens.
 
 ## Apps
 
-| App                           | Reads                                                                                                            | Changes                                                                                    |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| Due Again 1.1.0 or later      | items with status and next due date, an item's history                                                           | add an item, record that an item was done                                                  |
-| Gift Keeper 1.3.0 or later    | people with interests, sizes and preferences; upcoming occasions with budget, spend and whether a gift is chosen | add a gift idea for a person, mark a gift as given                                         |
-| Client Manager 1.6.0 or later | pending reminders, open tasks, invoices owing with totals and balance, one client with their jobs                | add a client, a job, a reminder or a task, change a job, task or reminder, log an activity |
-| Lists & Notes 1.22.0 or later | lists with their items, notes with previews, the full text of a note                                             | nothing yet                                                                                |
+| App                                                 | Reads                                                                                                            | Changes                                                                                    |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Due Again 1.1.0 or later                            | items with status and next due date, an item's history                                                           | add an item, record that an item was done                                                  |
+| Gift Keeper 1.3.0 or later                          | people with interests, sizes and preferences; upcoming occasions with budget, spend and whether a gift is chosen | add a gift idea for a person, mark a gift as given                                         |
+| Client Manager 1.6.0 or later                       | pending reminders, open tasks, invoices owing with totals and balance, one client with their jobs                | add a client, a job, a reminder or a task, change a job, task or reminder, log an activity |
+| Lists & Notes 1.22.0 or later (changes need 1.23.0) | lists with their items, notes with previews, the full text of a note                                             | add a list or a note, add items, tick off or reword items, add to or rename a note         |
 
 More apps follow, and the assistant can also open an app for you, but only after you agree.
 
@@ -40,6 +40,20 @@ Desktop starts it, so after installing another app restart Claude Desktop once.
 
 To remove it: `npx @tiongcreative/assistant-mcp uninstall`. To check: `npx @tiongcreative/assistant-mcp status`.
 
+### ChatGPT desktop on the same Mac
+
+For ChatGPT desktop, run this one command instead:
+
+```
+npx @tiongcreative/assistant-mcp install chatgpt
+```
+
+It registers the same local server in ChatGPT's MCP settings. Restart ChatGPT, turn on
+**Allow assistant access** in each app, and type `/mcp` in ChatGPT to check the connection.
+The Tiong Creative apps must be open on this Mac. This setup is for ChatGPT desktop, not
+ChatGPT in a web browser. To check or remove it, run `npx @tiongcreative/assistant-mcp status chatgpt`
+or `npx @tiongcreative/assistant-mcp uninstall chatgpt`.
+
 For Claude Code: `claude mcp add tiongcreative -- npx -y @tiongcreative/assistant-mcp`.
 
 ## How it stays on your Mac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiongcreative/assistant-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP server that lets an AI assistant on your Mac use your Tiong Creative apps while they are open.",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "prepare": "husky",
     "validate": "npm run lint && npm run format:check",
     "quality": "npm run validate && npm run sast && npm run security && npm run secrets && npm run licenses && npm run deps:check && npm run review",
-    "test:unit": "node --test tests/dates.test.js tests/install.test.js",
+    "test:unit": "node --test tests/dates.test.js tests/install.test.js tests/chatgpt-install.test.js",
     "test:integration": "node --test tests/due-again.test.js tests/gift-keeper.test.js tests/client-manager.test.js tests/lists-and-notes.test.js"
   },
   "license": "MIT",

package/src/apps/lists-and-notes.js

@@ -1,9 +1,12 @@
-// Lists & Notes: checklists and markdown notes. Read-only for now: the app's list
-// endpoint replaces the whole file from the request, so writes wait until that is
-// hardened (see the plan). Talks to the app's local API with the per-launch token it
-// writes while "Allow assistant access" is on (list-manager/assistant-access.js).
+// Lists & Notes: checklists and markdown notes. Writes need Lists & Notes 1.23.0 or later,
+// which gives the assistant its own per-list and per-note routes (the whole-file save is
+// window-only). Changing an existing list or note sends the `modified` stamp last read
+// (`baseModified`); if the user changed it since, the app refuses and the tool re-reads and
+// retries once. Item ids are always sent back, or the app would treat items as new. There
+// is no delete tool. Talks to the app's local API with the per-launch token it writes while
+// "Allow assistant access" is on (list-manager/assistant-access.js).
 import { z } from 'zod';
-import { appConnection, apiCall, notAvailable } from '../connection.js';
+import { ApiError, appConnection, apiCall, notAvailable } from '../connection.js';
 
 export const app = {
   id: 'lists-and-notes',
@@ -47,6 +50,63 @@ function matches(text, q) {
   return typeof text === 'string' && text.toLowerCase().includes(q);
 }
 
+const WRITES_FROM = '1.23.0';
+
+function olderThan(version, min) {
+  const a = String(version ?? '0')
+    .split('.')
+    .map(Number);
+  const b = min.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] || 0) !== b[i]) return (a[i] || 0) < b[i];
+  }
+  return false;
+}
+
+/** The app's version must support writes; returns a result to send back, or null. */
+function needsUpdate(conn) {
+  if (!olderThan(conn.version, WRITES_FROM)) return null;
+  return {
+    app: app.name,
+    changed: false,
+    message: `Changing lists and notes needs Lists & Notes ${WRITES_FROM} or later (this Mac has ${conn.version ?? 'an older version'}). Reading still works.`,
+  };
+}
+
+async function findList(conn, name) {
+  const lists = await apiCall(conn, 'GET', '/api/data/lists');
+  const wanted = name.trim().toLowerCase();
+  return {
+    list: lists.find((l) => l.name.toLowerCase() === wanted),
+    names: lists.map((l) => l.name),
+  };
+}
+
+async function findNote(conn, title) {
+  const notes = await apiCall(conn, 'GET', '/api/data/notes');
+  const wanted = title.trim().toLowerCase();
+  return {
+    note: notes.find((n) => n.title.toLowerCase() === wanted),
+    titles: notes.map((n) => n.title),
+  };
+}
+
+/** Runs a change against the latest copy; on a 409 (changed in the window) re-reads once. */
+async function withRetry(load, change) {
+  let current = await load();
+  try {
+    return await change(current);
+  } catch (err) {
+    if (!(err instanceof ApiError) || err.status !== 409) throw err;
+    current = await load();
+    return change(current);
+  }
+}
+
+function itemMatches(item, text) {
+  return item.text.trim().toLowerCase() === text.trim().toLowerCase();
+}
+
 export const tools = [
   {
     name: 'lists_and_notes_lists',
@@ -156,6 +216,248 @@ export const tools = [
       };
     },
   },
+  {
+    name: 'lists_and_notes_add_items',
+    description:
+      'Add items to an existing list in Lists & Notes, by list name. Items are added unticked at the end. If the list does not exist, the reply lists the lists.',
+    input: z.object({
+      list: z.string().min(1).max(75),
+      items: z.array(z.string().trim().min(1).max(2000)).min(1).max(100),
+    }),
+    write: true,
+    async run(input) {
+      const conn = await appConnection(app);
+      if (!conn.ok) return notAvailable(app, conn);
+      const old = needsUpdate(conn);
+      if (old) return old;
+      const { list, names } = await findList(conn, input.list);
+      if (!list)
+        return {
+          app: app.name,
+          changed: false,
+          message: `No list called "${input.list}".`,
+          lists: names,
+        };
+      const updated = await apiCall(
+        conn,
+        'POST',
+        `/api/data/lists/${encodeURIComponent(list.id)}/items`,
+        {
+          items: input.items.map((text) => ({ text })),
+        },
+      );
+      return { app: app.name, changed: true, list: summariseList(updated), added: input.items };
+    },
+  },
+  {
+    name: 'lists_and_notes_update_items',
+    description:
+      "Tick off, untick, reword or add notes to items on a list in Lists & Notes. Name the list and each item by its current text. Items not mentioned are left as they are. If an item's text does not match, the reply lists the items.",
+    input: z.object({
+      list: z.string().min(1).max(75),
+      changes: z
+        .array(
+          z.object({
+            item: z.string().min(1).max(2000).describe('The item as it reads now'),
+            done: z.boolean().optional(),
+            text: z.string().trim().min(1).max(2000).optional().describe('New wording'),
+            notes: z.string().max(2000).optional(),
+          }),
+        )
+        .min(1)
+        .max(100),
+    }),
+    write: true,
+    async run(input) {
+      const conn = await appConnection(app);
+      if (!conn.ok) return notAvailable(app, conn);
+      const old = needsUpdate(conn);
+      if (old) return old;
+      const first = await findList(conn, input.list);
+      if (!first.list)
+        return {
+          app: app.name,
+          changed: false,
+          message: `No list called "${input.list}".`,
+          lists: first.names,
+        };
+      const id = first.list.id;
+      const load = async () =>
+        (await apiCall(conn, 'GET', '/api/data/lists')).find((l) => l.id === id);
+      return withRetry(load, async (list) => {
+        if (!list)
+          return { app: app.name, changed: false, message: 'That list has just been removed.' };
+        const items = (list.items ?? []).map((i) => ({ ...i }));
+        const missing = input.changes
+          .filter((c) => !items.some((i) => itemMatches(i, c.item)))
+          .map((c) => c.item);
+        if (missing.length) {
+          return {
+            app: app.name,
+            changed: false,
+            message: `No item reading ${missing.map((m) => `"${m}"`).join(', ')} on ${list.name}.`,
+            items: items.map((i) => i.text),
+          };
+        }
+        for (const c of input.changes) {
+          const item = items.find((i) => itemMatches(i, c.item));
+          if (c.done !== undefined) item.completed = c.done;
+          if (c.text !== undefined) item.text = c.text;
+          if (c.notes !== undefined) item.notes = c.notes;
+        }
+        const updated = await apiCall(conn, 'PATCH', `/api/data/lists/${encodeURIComponent(id)}`, {
+          items,
+          baseModified: list.metadata?.modified,
+        });
+        return { app: app.name, changed: true, list: summariseList(updated) };
+      });
+    },
+  },
+  {
+    name: 'lists_and_notes_add_list',
+    description:
+      'Create a new list in Lists & Notes with optional first items. The category must already exist in the app; if it does not, the reply lists the categories.',
+    input: z.object({
+      name: z.string().trim().min(1).max(75),
+      items: z.array(z.string().trim().min(1).max(2000)).max(100).optional(),
+      category: z.string().max(100).optional().describe('Defaults to personal'),
+      tags: z.array(z.string().max(50)).max(10).optional(),
+    }),
+    write: true,
+    async run(input) {
+      const conn = await appConnection(app);
+      if (!conn.ok) return notAvailable(app, conn);
+      const old = needsUpdate(conn);
+      if (old) return old;
+      const [{ list: existing }, categories] = await Promise.all([
+        findList(conn, input.name),
+        apiCall(conn, 'GET', '/api/data/categories'),
+      ]);
+      if (existing)
+        return {
+          app: app.name,
+          added: false,
+          message: `There is already a list called "${input.name}".`,
+        };
+      const category = input.category
+        ? categories.find((c) => c.toLowerCase() === input.category.trim().toLowerCase())
+        : 'personal';
+      if (!category)
+        return {
+          app: app.name,
+          added: false,
+          message: `No category called "${input.category}".`,
+          categories,
+        };
+      const list = await apiCall(conn, 'POST', '/api/data/lists/add', {
+        name: input.name,
+        category,
+        ...(input.tags ? { tags: input.tags } : {}),
+        items: (input.items ?? []).map((text) => ({ text, completed: false, notes: '' })),
+      });
+      return { app: app.name, added: true, list: summariseList(list) };
+    },
+  },
+  {
+    name: 'lists_and_notes_add_note',
+    description:
+      'Create a note in Lists & Notes with a title and markdown content. The category must already exist; if it does not, the reply lists the categories.',
+    input: z.object({
+      title: z.string().trim().min(1).max(75),
+      content: z.string().max(200000).default(''),
+      category: z.string().max(100).optional().describe('Defaults to personal'),
+      tags: z.array(z.string().max(50)).max(10).optional(),
+    }),
+    write: true,
+    async run(input) {
+      const conn = await appConnection(app);
+      if (!conn.ok) return notAvailable(app, conn);
+      const old = needsUpdate(conn);
+      if (old) return old;
+      const categories = await apiCall(conn, 'GET', '/api/data/categories');
+      const category = input.category
+        ? categories.find((c) => c.toLowerCase() === input.category.trim().toLowerCase())
+        : 'personal';
+      if (!category)
+        return {
+          app: app.name,
+          added: false,
+          message: `No category called "${input.category}".`,
+          categories,
+        };
+      const note = await apiCall(conn, 'POST', '/api/data/notes', {
+        title: input.title,
+        category,
+        content: input.content,
+        ...(input.tags ? { tags: input.tags } : {}),
+      });
+      return { app: app.name, added: true, note: summariseNote(note) };
+    },
+  },
+  {
+    name: 'lists_and_notes_update_note',
+    description:
+      "Change a note in Lists & Notes, by title: add text to the end (append), replace its text, or rename it. If the user edits the note at the same moment, the change is applied to their latest version; the app keeps the previous text in the note's history.",
+    input: z.object({
+      title: z.string().min(1).max(75).describe('The note as it is titled now'),
+      append: z.string().max(200000).optional().describe('Text added on a new line at the end'),
+      content: z.string().max(200000).optional().describe('Replaces the whole text'),
+      newTitle: z.string().trim().min(1).max(75).optional(),
+    }),
+    write: true,
+    async run(input) {
+      const conn = await appConnection(app);
+      if (!conn.ok) return notAvailable(app, conn);
+      const old = needsUpdate(conn);
+      if (old) return old;
+      if (
+        input.append === undefined &&
+        input.content === undefined &&
+        input.newTitle === undefined
+      ) {
+        return {
+          app: app.name,
+          changed: false,
+          message: 'Nothing to change: give text to append, new content or a new title.',
+        };
+      }
+      if (input.append !== undefined && input.content !== undefined) {
+        return {
+          app: app.name,
+          changed: false,
+          message: 'Give either append or content, not both.',
+        };
+      }
+      const first = await findNote(conn, input.title);
+      if (!first.note)
+        return {
+          app: app.name,
+          changed: false,
+          message: `No note called "${input.title}".`,
+          titles: first.titles,
+        };
+      const id = first.note.id;
+      const load = () => apiCall(conn, 'GET', `/api/data/notes/${encodeURIComponent(id)}`);
+      return withRetry(load, async (note) => {
+        const body = { baseModified: note.metadata?.modified };
+        if (input.content !== undefined) body.content = input.content;
+        if (input.append !== undefined) {
+          const current = typeof note.content === 'string' ? note.content : '';
+          body.content = current
+            ? `${current.replace(/\s+$/, '')}\n\n${input.append}`
+            : input.append;
+        }
+        if (input.newTitle !== undefined) body.title = input.newTitle;
+        const updated = await apiCall(
+          conn,
+          'PUT',
+          `/api/data/notes/${encodeURIComponent(id)}`,
+          body,
+        );
+        return { app: app.name, changed: true, note: summariseNote(updated) };
+      });
+    },
+  },
 ];
 
 /** Lists & Notes has no dated items, so it adds nothing to "what's on". */

package/src/chatgpt-install.js

@@ -0,0 +1,78 @@
+// ChatGPT desktop and Codex share MCP configuration. Use the CLI shipped with
+// ChatGPT to edit it, so other servers and unrelated settings stay intact.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { npxPath, SERVER_KEY } from './install.js';
+
+const PACKAGE = '@tiongcreative/assistant-mcp';
+
+function cliPath() {
+  const relative = path.join('Contents', 'Resources', 'codex-cli', 'bin', 'codex');
+  for (const apps of ['/Applications', path.join(os.homedir(), 'Applications')]) {
+    const candidate = path.join(apps, 'ChatGPT.app', relative);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  throw new Error(
+    'ChatGPT desktop was not found in Applications. Install it before running this command.',
+  );
+}
+
+function run(cli, args) {
+  try {
+    return execFileSync(cli, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (err) {
+    const detail = err.stderr?.toString().trim() || err.message;
+    throw new Error(`ChatGPT could not update its MCP settings: ${detail}`);
+  }
+}
+
+function current(cli) {
+  const servers = JSON.parse(run(cli, ['mcp', 'list', '--json']));
+  if (!Array.isArray(servers)) throw new Error('ChatGPT returned an unexpected MCP server list.');
+  return servers.find((server) => server.name === SERVER_KEY) ?? null;
+}
+
+function matches(server, env) {
+  const transport = server?.transport;
+  return (
+    transport?.type === 'stdio' &&
+    transport.command === npxPath() &&
+    JSON.stringify(transport.args) === JSON.stringify(['-y', PACKAGE]) &&
+    JSON.stringify(transport.env ?? {}) === JSON.stringify(env)
+  );
+}
+
+export function chatGptStatus(cli = cliPath()) {
+  const server = current(cli);
+  return { installed: !!server, managed: matches(server, server?.transport?.env ?? {}) };
+}
+
+export function installChatGpt({ allowFresh = false, cli = cliPath() } = {}) {
+  const env = allowFresh ? { npm_config_min_release_age: '0' } : {};
+  const server = current(cli);
+  if (matches(server, env)) return { already: true };
+  if (server) {
+    throw new Error(
+      'An MCP server named "tiongcreative" already exists in ChatGPT. Remove it in ChatGPT settings before installing this one.',
+    );
+  }
+  const args = ['mcp', 'add'];
+  for (const [key, value] of Object.entries(env)) args.push('--env', `${key}=${value}`);
+  args.push(SERVER_KEY, '--', npxPath(), '-y', PACKAGE);
+  run(cli, args);
+  return { already: false };
+}
+
+export function uninstallChatGpt(cli = cliPath()) {
+  const server = current(cli);
+  if (!server) return { removed: false };
+  if (!matches(server, server.transport?.env ?? {})) {
+    throw new Error(
+      'The "tiongcreative" entry in ChatGPT does not match this package; nothing was removed.',
+    );
+  }
+  run(cli, ['mcp', 'remove', SERVER_KEY]);
+  return { removed: true };
+}

package/src/install.js

@@ -7,6 +7,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { chatGptStatus, installChatGpt, uninstallChatGpt } from './chatgpt-install.js';
 
 export const SERVER_KEY = 'tiongcreative';
 const PACKAGE = '@tiongcreative/assistant-mcp';
@@ -109,8 +110,45 @@ const NEXT_STEPS = [
 
 /** Runs the command and returns the process exit code. Prints with the given writer. */
 export function runCli(args, print = console.log) {
-  const [command] = args;
+  const [command, client] = args;
   try {
+    if (client === 'chatgpt' && ['install', 'uninstall', 'status'].includes(command)) {
+      if (command === 'install') {
+        const result = installChatGpt({ allowFresh: args.includes('--allow-fresh') });
+        print(
+          result.already
+            ? 'The Tiong Creative assistant is already set up in ChatGPT.'
+            : 'Added the Tiong Creative assistant to ChatGPT.',
+        );
+        print(
+          '\nNext:\n1. Restart the ChatGPT desktop app.\n2. Open each Tiong Creative app and turn on "Allow assistant access" in Settings.\n3. Type /mcp in ChatGPT to check the connection.',
+        );
+      } else if (command === 'uninstall') {
+        const result = uninstallChatGpt();
+        print(
+          result.removed
+            ? 'Removed the Tiong Creative assistant from ChatGPT. Restart ChatGPT to finish.'
+            : 'The Tiong Creative assistant was not set up in ChatGPT.',
+        );
+      } else {
+        const result = chatGptStatus();
+        print(
+          result.managed
+            ? 'Set up in ChatGPT.'
+            : result.installed
+              ? 'ChatGPT has a different MCP server named "tiongcreative".'
+              : 'Not set up in ChatGPT.',
+        );
+      }
+      return 0;
+    }
+    if (
+      client &&
+      client !== '--allow-fresh' &&
+      ['install', 'uninstall', 'status'].includes(command)
+    ) {
+      throw new Error('Choose "chatgpt" as the client, or omit it for Claude Desktop.');
+    }
     if (command === 'install') {
       const env = {};
       // Developer convenience: `install --allow-fresh` passes npm's release-age override
@@ -146,7 +184,7 @@ export function runCli(args, print = console.log) {
       return 0;
     }
     print(
-      `Usage:\n  npx ${PACKAGE} install     add the assistant to Claude Desktop\n  npx ${PACKAGE} uninstall   remove it\n  npx ${PACKAGE} status      say whether it is set up\n\nWith no command, this runs the MCP server itself (Claude Desktop does that for you).`,
+      `Usage:\n  npx ${PACKAGE} install              add the assistant to Claude Desktop\n  npx ${PACKAGE} install chatgpt      add it to ChatGPT desktop\n  npx ${PACKAGE} uninstall [chatgpt] remove it from the chosen client\n  npx ${PACKAGE} status [chatgpt]    check the chosen client\n\nWith no command, this runs the MCP server itself.`,
     );
     return command === 'help' || command === '--help' ? 0 : 2;
   } catch (err) {