@tiongcreative/assistant-mcp 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.2.0] - 2026-10-19
+
+### Added
+
+- `npx @tiongcreative/assistant-mcp install` sets the assistant up in Claude Desktop: adds one entry to its config file with the full path to npx (a desktop app cannot see the shell's PATH), keeps a backup, refuses to touch a file it cannot parse, and prints the next steps. `uninstall` removes the entry; `status` reports it. `--allow-fresh` passes npm's release-age override into the entry for Macs that refuse packages younger than a few days. Unit tests cover create, merge, idempotence, corrupt files and removal.
+
+### Changed
+
+- README setup is now the one-command path.
+
 ## [0.1.1] - 2026-10-19
 
 ### Changed

package/README.md

@@ -21,23 +21,24 @@ More apps follow, and the assistant can also open an app for you, but only after
 
 ## Setup
 
-You need Node.js 20 or later and Claude Desktop. Add this to Claude Desktop's config file
-(Settings → Developer → Edit Config), then restart Claude Desktop:
-
-```json
-{
-  "mcpServers": {
-    "tiongcreative": {
-      "command": "npx",
-      "args": ["-y", "@tiongcreative/assistant-mcp"]
-    }
-  }
-}
+You need Node.js and Claude Desktop. If you do not have Node.js, install it from
+nodejs.org (the LTS download), which also gives you the `npx` command used below.
+
+Open Terminal and run:
+
+```
+npx @tiongcreative/assistant-mcp install
 ```
 
-In each app, turn on **Allow assistant access** in Settings. Open the app, then ask Claude
-what's on. The assistant only offers tools for the apps installed on your Mac, checked when it
-starts, so after installing another app restart Claude Desktop once.
+It adds the assistant to Claude Desktop's settings and keeps a backup of the previous file.
+Then quit Claude Desktop completely, open it again, and allow the "tiongcreative" server the
+first time it asks. In each app, turn on **Allow assistant access** in Settings. With the apps
+open, ask Claude what's on this week.
+
+The assistant only offers tools for the apps installed on your Mac, checked when Claude
+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`.
 
 For Claude Code: `claude mcp add tiongcreative -- npx -y @tiongcreative/assistant-mcp`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiongcreative/assistant-mcp",
-  "version": "0.1.1",
+  "version": "0.2.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",
+    "test:unit": "node --test tests/dates.test.js tests/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/index.js

@@ -11,6 +11,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { ApiError, isInstalled } from './connection.js';
+import { runCli } from './install.js';
 import * as dueAgain from './apps/due-again.js';
 import * as giftKeeper from './apps/gift-keeper.js';
 import * as clientManager from './apps/client-manager.js';
@@ -18,6 +19,12 @@ import * as listsAndNotes from './apps/lists-and-notes.js';
 
 const { version } = createRequire(import.meta.url)('../package.json');
 
+// `npx @tiongcreative/assistant-mcp install|uninstall|status` is the member's setup path.
+// With no command, this process is the MCP server Claude Desktop launches.
+if (process.argv.length > 2) {
+  process.exit(runCli(process.argv.slice(2)));
+}
+
 // One entry per app. Add an app by adding a module with the same shape.
 const ALL_APPS = [dueAgain, giftKeeper, clientManager, listsAndNotes];
 // Only apps present on this Mac get tools, so the assistant never points the user at an

package/src/install.js

@@ -0,0 +1,156 @@
+// `npx @tiongcreative/assistant-mcp install`: sets the assistant up in Claude Desktop so a
+// member never edits JSON by hand. It adds one entry to Claude Desktop's config file (and
+// nothing else), keeps a backup, and records the full path to npx, because a desktop app
+// does not see the shell's PATH and would otherwise fail to find it.
+//
+// `uninstall` removes the entry. `status` says whether it is set up.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const SERVER_KEY = 'tiongcreative';
+const PACKAGE = '@tiongcreative/assistant-mcp';
+
+/** Claude Desktop's config file on this Mac (TC_CLAUDE_CONFIG overrides it, for tests). */
+export function configPath() {
+  if (process.env.TC_CLAUDE_CONFIG) return process.env.TC_CLAUDE_CONFIG;
+  if (process.platform !== 'darwin') {
+    throw new Error('The Tiong Creative apps run on macOS, so this installer does too.');
+  }
+  return path.join(
+    os.homedir(),
+    'Library',
+    'Application Support',
+    'Claude',
+    'claude_desktop_config.json',
+  );
+}
+
+/** The npx beside the node that is running this command: the one Claude Desktop will use. */
+export function npxPath() {
+  const candidate = path.join(path.dirname(process.execPath), 'npx');
+  if (fs.existsSync(candidate)) return candidate;
+  throw new Error(`Could not find npx next to node at ${process.execPath}.`);
+}
+
+function readConfig(file) {
+  if (!fs.existsSync(file)) return { config: {}, existed: false };
+  const raw = fs.readFileSync(file, 'utf8');
+  if (!raw.trim()) return { config: {}, existed: true };
+  try {
+    const config = JSON.parse(raw);
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+      throw new Error('not an object');
+    }
+    return { config, existed: true };
+  } catch (err) {
+    throw new Error(
+      `Claude Desktop's config file could not be read as JSON (${err.message}), so nothing was changed. File: ${file}`,
+    );
+  }
+}
+
+function writeConfig(file, config, existed) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  let backup = null;
+  if (existed) {
+    backup = `${file}.backup-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+    fs.copyFileSync(file, backup);
+  }
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n');
+  fs.renameSync(tmp, file);
+  return backup;
+}
+
+export function install({ env } = {}) {
+  const file = configPath();
+  const { config, existed } = readConfig(file);
+  const entry = { command: npxPath(), args: ['-y', PACKAGE] };
+  if (env && Object.keys(env).length) entry.env = env;
+  const servers =
+    config.mcpServers && typeof config.mcpServers === 'object' ? config.mcpServers : {};
+  const already = JSON.stringify(servers[SERVER_KEY]) === JSON.stringify(entry);
+  config.mcpServers = { ...servers, [SERVER_KEY]: entry };
+  const backup = already ? null : writeConfig(file, config, existed);
+  return { file, backup, already, entry };
+}
+
+export function uninstall() {
+  const file = configPath();
+  const { config, existed } = readConfig(file);
+  if (!existed || !config.mcpServers || !(SERVER_KEY in config.mcpServers)) {
+    return { file, removed: false };
+  }
+  const rest = { ...config.mcpServers };
+  delete rest[SERVER_KEY];
+  config.mcpServers = rest;
+  const backup = writeConfig(file, config, true);
+  return { file, removed: true, backup };
+}
+
+export function status() {
+  const file = configPath();
+  try {
+    const { config, existed } = readConfig(file);
+    const entry = existed ? config.mcpServers?.[SERVER_KEY] : undefined;
+    return { file, installed: !!entry, entry: entry ?? null };
+  } catch (err) {
+    return { file, installed: false, error: err.message };
+  }
+}
+
+const NEXT_STEPS = [
+  '1. Quit Claude Desktop completely and open it again.',
+  '2. The first time you chat, allow the "tiongcreative" server when Claude Desktop asks.',
+  '3. In each Tiong Creative app, open Settings and turn on "Allow assistant access".',
+  '4. With the apps open, ask Claude what is on this week.',
+];
+
+/** Runs the command and returns the process exit code. Prints with the given writer. */
+export function runCli(args, print = console.log) {
+  const [command] = args;
+  try {
+    if (command === 'install') {
+      const env = {};
+      // Developer convenience: `install --allow-fresh` passes npm's release-age override
+      // through to the server entry, for Macs that refuse packages younger than a few days.
+      if (args.includes('--allow-fresh')) env.npm_config_min_release_age = '0';
+      const r = install({ env });
+      print(
+        r.already
+          ? `The Tiong Creative assistant is already set up in Claude Desktop (${r.file}).`
+          : `Added the Tiong Creative assistant to Claude Desktop.\n  Config: ${r.file}${r.backup ? `\n  Backup of the previous file: ${r.backup}` : ''}`,
+      );
+      print('\nNext:\n' + NEXT_STEPS.join('\n'));
+      return 0;
+    }
+    if (command === 'uninstall') {
+      const r = uninstall();
+      print(
+        r.removed
+          ? `Removed the Tiong Creative assistant from Claude Desktop (${r.file}). Restart Claude Desktop to finish.`
+          : `The Tiong Creative assistant was not set up in Claude Desktop (${r.file}), so nothing changed.`,
+      );
+      return 0;
+    }
+    if (command === 'status') {
+      const r = status();
+      if (r.error) print(r.error);
+      else
+        print(
+          r.installed
+            ? `Set up in Claude Desktop: ${r.file}`
+            : `Not set up in Claude Desktop (${r.file}).`,
+        );
+      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).`,
+    );
+    return command === 'help' || command === '--help' ? 0 : 2;
+  } catch (err) {
+    print(`Could not finish: ${err.message}`);
+    return 1;
+  }
+}