@tiongcreative/assistant-mcp 0.0.0-stage → 0.1.1

package/src/connection.js

@@ -0,0 +1,115 @@
+// Finding a running app and calling its local API.
+//
+// Each app that allows assistant access writes <data root>/<app>/local_data/assistant.json
+// while it is open: { app, port, pid, version, token, startedAt }. The file is readable
+// only by the user account that runs the app, which is also the account running this
+// server. The token is sent as a Bearer header. Nothing here listens on the network;
+// every call goes to 127.0.0.1.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const HOST = '127.0.0.1';
+
+// Where the apps keep their data. TC_DATA_ROOT is for tests and the standalone servers.
+export function dataRoot() {
+  return process.env.TC_DATA_ROOT || path.join(os.homedir(), 'Library', 'Application Support');
+}
+
+// Most apps keep their files in a local_data folder under their data dir; an app that
+// writes to the data dir itself says so with tokenFile.
+function tokenFile(app) {
+  return path.join(
+    dataRoot(),
+    app.dataDir,
+    app.tokenFile ?? path.join('local_data', 'assistant.json'),
+  );
+}
+
+/**
+ * Whether the app exists on this Mac: its bundle in Applications, or a data folder it has
+ * written. Tools are only offered for installed apps, so an assistant never tells the user
+ * to turn on a switch in an app they do not have.
+ */
+export function isInstalled(app) {
+  if (process.env.TC_DATA_ROOT) return fs.existsSync(path.join(dataRoot(), app.dataDir));
+  const bundles = [
+    path.join('/Applications', `${app.bundleName}.app`),
+    path.join(os.homedir(), 'Applications', `${app.bundleName}.app`),
+  ];
+  return bundles.some((b) => fs.existsSync(b)) || fs.existsSync(path.join(dataRoot(), app.dataDir));
+}
+
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reads the app's token file and checks the app answers. Returns
+ * { ok: true, baseUrl, token, version } or { ok: false, reason }.
+ */
+export async function appConnection(app) {
+  let record;
+  try {
+    record = JSON.parse(fs.readFileSync(tokenFile(app), 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { ok: false, reason: isInstalled(app) ? 'not-enabled' : 'not-installed' };
+    }
+    return { ok: false, reason: 'unreadable', detail: err.message };
+  }
+  if (!record || typeof record.port !== 'number' || typeof record.token !== 'string') {
+    return { ok: false, reason: 'unreadable', detail: 'token file has an unexpected shape' };
+  }
+  if (record.pid && !processAlive(record.pid)) return { ok: false, reason: 'not-running' };
+  const baseUrl = `http://${HOST}:${record.port}`;
+  try {
+    const res = await fetch(`${baseUrl}/api/health`, { signal: AbortSignal.timeout(2000) });
+    if (!res.ok) return { ok: false, reason: 'not-running' };
+  } catch {
+    return { ok: false, reason: 'not-running' };
+  }
+  return { ok: true, baseUrl, token: record.token, version: record.version ?? null };
+}
+
+export class ApiError extends Error {
+  constructor(message, status, problems = []) {
+    super(message);
+    this.status = status;
+    this.problems = problems;
+  }
+}
+
+export async function apiCall(conn, method, urlPath, body) {
+  const res = await fetch(conn.baseUrl + urlPath, {
+    method,
+    headers: {
+      authorization: `Bearer ${conn.token}`,
+      ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(10000),
+  });
+  const text = await res.text();
+  const data = text ? JSON.parse(text) : null;
+  if (!res.ok) {
+    throw new ApiError(data?.error ?? `Request failed (${res.status})`, res.status, data?.problems);
+  }
+  return data;
+}
+
+/** The result a tool returns when the app cannot be reached. */
+export function notAvailable(app, conn) {
+  const reasons = {
+    'not-enabled': `${app.name} is installed but not sharing with assistants. In ${app.name}, open Settings and turn on "Allow assistant access".`,
+    'not-installed': `${app.name} is not installed on this Mac.`,
+    'not-running': `${app.name} is not open. Ask the user whether to open it, then call open_app with app "${app.id}".`,
+    unreadable: `${app.name}'s assistant file could not be read: ${conn.detail ?? 'unknown error'}.`,
+  };
+  return { app: app.name, available: false, reason: conn.reason, message: reasons[conn.reason] };
+}

package/src/dates.js

@@ -0,0 +1,18 @@
+// Date strings are YYYY-MM-DD in the user's local calendar, as the apps store them.
+
+export function todayLocal(now = new Date()) {
+  const y = now.getFullYear();
+  const m = String(now.getMonth() + 1).padStart(2, '0');
+  const d = String(now.getDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+function toUtcDay(dateString) {
+  const [y, m, d] = dateString.split('-').map(Number);
+  return Date.UTC(y, m - 1, d);
+}
+
+/** Whole days from `from` to `to`; negative when `to` is earlier. */
+export function daysBetween(from, to) {
+  return Math.round((toUtcDay(to) - toUtcDay(from)) / 86400000);
+}

package/src/index.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Tiong Creative assistant: an MCP server over stdio that lets the assistant running it
+// (Claude Desktop, Claude Code) use the Tiong Creative apps on this Mac.
+//
+// It opens no network listener. Each app is reached on 127.0.0.1 with a token the app
+// writes only while its "Allow assistant access" setting is on (src/connection.js).
+// Tools that change data say so in their description and return what they changed.
+import { execFile } from 'node:child_process';
+import { createRequire } from 'node:module';
+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 * as dueAgain from './apps/due-again.js';
+import * as giftKeeper from './apps/gift-keeper.js';
+import * as clientManager from './apps/client-manager.js';
+import * as listsAndNotes from './apps/lists-and-notes.js';
+
+const { version } = createRequire(import.meta.url)('../package.json');
+
+// 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
+// app they do not have. Checked once at start-up: install an app, restart the assistant.
+const APPS = ALL_APPS.filter((a) => isInstalled(a.app));
+const MISSING = ALL_APPS.filter((a) => !isInstalled(a.app)).map((a) => a.app.name);
+
+function text(value) {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+
+function failure(err) {
+  const message =
+    err instanceof ApiError
+      ? `${err.message}${err.problems?.length ? ': ' + err.problems.join('; ') : ''}`
+      : err?.message || String(err);
+  return { isError: true, content: [{ type: 'text', text: message }] };
+}
+
+const server = new McpServer({ name: 'tiongcreative-assistant', version });
+
+server.registerTool(
+  'whats_on',
+  {
+    title: "What's on",
+    description:
+      'Everything coming up across the Tiong Creative apps on this Mac within a number of days: overdue and due items, with the app each one belongs to. Start here for "what needs my attention".',
+    inputSchema: {
+      days: z.number().int().min(0).max(365).default(14).describe('How far ahead to look'),
+    },
+  },
+  async ({ days }) => {
+    const sections = await Promise.all(APPS.map((a) => a.attention(days)));
+    const items = sections
+      .flatMap((s) => s.items)
+      .sort((a, b) => (a.daysUntilDue ?? 0) - (b.daysUntilDue ?? 0));
+    const unavailable = sections
+      .filter((s) => !s.available)
+      .map((s) => ({ app: s.app, reason: s.reason }));
+    return text({
+      days,
+      count: items.length,
+      items,
+      unavailable,
+      ...(APPS.length === 0
+        ? {
+            note: `No Tiong Creative apps are installed on this Mac. The assistant works with: ${MISSING.join(', ')}.`,
+          }
+        : {}),
+    });
+  },
+);
+
+server.registerTool(
+  'open_app',
+  {
+    title: 'Open an app',
+    description:
+      'Opens one of the Tiong Creative apps on this Mac so its tools can be used. Only call this after the user has agreed to open it.',
+    inputSchema: {
+      app: z.enum(APPS.length ? APPS.map((a) => a.app.id) : ['none']),
+    },
+  },
+  async ({ app }) => {
+    const entry = APPS.find((a) => a.app.id === app);
+    if (!entry) return failure(new Error('That app is not installed on this Mac.'));
+    await new Promise((resolve, reject) => {
+      execFile('open', ['-a', entry.app.bundleName], (err) => (err ? reject(err) : resolve()));
+    });
+    return text({ app: entry.app.name, opened: true, note: 'Give it a few seconds to start.' });
+  },
+);
+
+for (const { tools } of APPS) {
+  for (const tool of tools) {
+    server.registerTool(
+      tool.name,
+      {
+        description: tool.description,
+        inputSchema: tool.input.shape,
+        annotations: tool.write
+          ? { readOnlyHint: false, destructiveHint: false, idempotentHint: false }
+          : { readOnlyHint: true },
+      },
+      async (input) => {
+        try {
+          return text(await tool.run(tool.input.parse(input)));
+        } catch (err) {
+          return failure(err);
+        }
+      },
+    );
+  }
+}
+
+await server.connect(new StdioServerTransport());