@tiongcreative/assistant-mcp 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## [0.1.0] - 2026-10-18
+
+### Fixed
+
+- Gift Keeper dates came out a day early east of UTC: the occasion date is local midnight as an ISO timestamp and was cut to its UTC day; it is now formatted in local time (found on real data, 2026-10-18)
+- `package.json` version set back to 0.1.0: a Gift Keeper version bump had been run in this folder by mistake and committed as 1.3.0; nothing was published under that number
+
+### Added
+
+- MCP server over stdio (`src/index.js`) for Claude Desktop and Claude Code, with tools `whats_on` (upcoming items across every available app), `open_app` (opens an app only after the user agrees), and Due Again tools `due_again_items`, `due_again_history`, `due_again_add_item` (category given by name; a miss returns the category list) and `due_again_complete`.
+- Gift Keeper reads `gift_keeper_ideas` (the ideas pool, including ideas not tied to an occasion) and `gift_keeper_gifts` (every tracked gift by stage), both filterable by person. Found in use: asking what gifts were available only showed gifts already attached to an occasion.
+- Change tools so every app can be edited, not only added to: Due Again `update_item`, `reschedule`, `skip`; Gift Keeper `update_gift`, `add_person`, `add_occasion`, `complete_occasion`; Client Manager `add_client`, `add_job`, `update_job`. Each returns the changed record and refuses a call with nothing to change.
+- Tools are registered only for apps installed on this Mac (app bundle in Applications, or a data folder), checked at start-up. An installed app with the switch off still says so; an app the user does not have is simply absent, so the assistant never tells them to enable it. `whats_on` says which apps it works with when none are installed.
+- Client Manager: `client_manager_update_task` (move the due date, change status, edit title or notes) and `client_manager_update_reminder` (complete, snooze, move or edit; completing a recurring reminder lets the app create the next one). Found in use: the assistant could add a task but not move an overdue one to today.
+- Lists & Notes tools, read-only: `lists_and_notes_lists` (all lists, or one by name with its items), `lists_and_notes_notes` (search titles, previews, summaries and tags) and `lists_and_notes_note` (the full markdown of one note by title). End-to-end test against a real Lists & Notes server.
+- Client Manager tools: `client_manager_reminders`, `client_manager_tasks`, `client_manager_invoices` (with totals and balance from `?totals=1`), `client_manager_client`, `client_manager_add_reminder`, `client_manager_add_task`, `client_manager_log_activity`; reminders, dated tasks and invoices owing appear in `whats_on`. End-to-end test against a real Client Manager server. Apps may name their token file (`tokenFile`) when it is not under `local_data`.
+- Gift Keeper tools: `gift_keeper_upcoming`, `gift_keeper_people`, `gift_keeper_add_idea` (person given by name; a miss returns the people list) and `gift_keeper_mark_gift_given`; Gift Keeper occasions appear in `whats_on`. End-to-end test against a real Gift Keeper server (`tests/gift-keeper.test.js`).
+- App discovery and auth (`src/connection.js`): reads each app's per-launch `local_data/assistant.json` (port, pid, token) under `~/Library/Application Support` (or `TC_DATA_ROOT`), checks the process and `/api/health`, and calls the app's API on 127.0.0.1 with a Bearer token; no network listener of its own.
+- Tests: `tests/due-again.test.js` runs a real Due Again server on a temp data folder and drives this server through the SDK stdio client (tool listing, not-enabled state, reads, a completion, the app's validation error, revocation); `tests/dates.test.js`.
+- Release workflow (`.github/workflows/publish.yml`): on a `v*` tag, validates, tests and publishes to npm through trusted publishing with automatic provenance; the tag must match `package.json`. `publishConfig.access` set to public for the scoped name.
+- Project scaffold from build-policy (CI, husky, allowlist, lint, prettier), MIT licence.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Tiong (Tiong Creative)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# Tiong Creative assistant (MCP server)
 
-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.
+Lets an AI assistant on your Mac, such as Claude Desktop, use your Tiong Creative apps while
+they are open. Ask "what's on this month" and it reads Due Again, Gift Keeper, Client Manager and Lists & Notes; say "mark the car insurance
+done" and Due Again records it and works out the next date, the same as if you had clicked.
+
+It only works with the apps, and only while each app has **Settings → Assistant → Allow
+assistant access** turned on. With it off, or the app closed, the assistant is told so and
+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                                                                                |
+
+More apps follow, and the assistant can also open an app for you, but only after you agree.
+
+## 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"]
+    }
+  }
+}
+```
+
+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.
+
+For Claude Code: `claude mcp add tiongcreative -- npx -y @tiongcreative/assistant-mcp`.
+
+## How it stays on your Mac
+
+- The server opens no network connection of its own. It talks to each app on 127.0.0.1 only.
+- While assistant access is on, the app writes a small file in its own data folder holding its
+  port and a token made fresh for that launch, readable only by your user account. The server
+  reads it and sends the token with each request. The file is removed when you turn the setting
+  off or quit the app, so there is nothing to copy or store.
+- What the assistant reads goes to whichever AI service it uses. Turn access on only for an
+  assistant you trust.
+- The package holds no secrets and never contacts tiongcreative.com.au.
+
+## Development
+
+```bash
+npm install
+npm test            # needs ../due-again checked out: runs its server on a temp data folder
+npm run validate
+```
+
+Registering a local checkout with Claude Code: `claude mcp add tiongcreative -- node /path/to/src/index.js`.
+
+## Licence
+
+Released under the MIT licence.

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@tiongcreative/assistant-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server that lets an AI assistant on your Mac use your Tiong Creative apps while they are open.",
+  "type": "module",
+  "bin": {
+    "tiongcreative-assistant-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "npm run test:unit && npm run test:integration",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "security": "npm audit --audit-level=high --omit=dev",
+    "sast": "semgrep scan --config auto --error --quiet --exclude-rule javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal --exclude-rule javascript.express.security.audit.express-path-join-resolve-traversal.express-path-join-resolve-traversal --exclude-rule javascript.express.security.audit.express-res-sendfile.express-res-sendfile --exclude-rule javascript.express.security.audit.remote-property-injection.remote-property-injection --exclude-rule html.security.audit.missing-integrity.missing-integrity",
+    "secrets": "betterleaks git . --redact",
+    "secrets:staged": "betterleaks git --staged --redact",
+    "licenses": "license-checker --production --failOn 'GPL-2.0;GPL-3.0;AGPL-1.0;AGPL-3.0' --summary",
+    "licenses:file": "license-checker --production --relativeLicensePath | sed -e \"s|$PWD/||g\" -e \"s|$PWD|.|g\" > THIRD-PARTY-LICENSES.txt",
+    "deps:check": "node ../build-policy/scripts/check-allowlist.js .",
+    "deps:verify": "node ../build-policy/scripts/verify-package.js",
+    "review": "coderabbit review --agent --include-untracked",
+    "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: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",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.27.0",
+    "eslint": "^9.27.0",
+    "eslint-plugin-security": "^3.0.1",
+    "husky": "^9.1.7",
+    "license-checker": "^25.0.1",
+    "prettier": "^3.5.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davettt/assistant-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "tiongcreative",
+    "due-again"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}