imsg-mcp 1.0.0

package/package.json

@@ -0,0 +1,135 @@
+{
+  "name": "imsg-mcp",
+  "version": "1.0.0",
+  "description": "MCP server, CLI, and TUI for reading and sending iMessage / SMS on macOS — lets AI agents text humans, fetch conversation history, and stream-export entire chats. Includes a self-healing watchdog and an optional Rust acceleration module.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "imsg": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "native/imsg-native.darwin-arm64.node",
+    "native/imsg-native.darwin-x64.node",
+    "native/index.js",
+    "native/index.d.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "skills"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "imessage",
+    "messages",
+    "sms",
+    "macos",
+    "ai-agent",
+    "ai",
+    "anthropic",
+    "claude",
+    "applescript",
+    "tui",
+    "terminal-ui",
+    "cli",
+    "chat-export"
+  ],
+  "author": "George G",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/george43g/imsg-mcp.git"
+  },
+  "homepage": "https://github.com/george43g/imsg-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/george43g/imsg-mcp/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@inkjs/ui": "^2.0.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^12.6.2",
+    "bplist-parser": "^0.3.2",
+    "commander": "^14.0.3",
+    "fullscreen-ink": "^0.1.0",
+    "imsg-mcp": "link:",
+    "ink": "^7.0.1",
+    "react": "^19.2.5",
+    "zod": "^3.23.0",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@napi-rs/cli": "^3.6.2",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.2.14",
+    "ink-testing-library": "^4.0.0",
+    "nodemon": "^3.1.14",
+    "semantic-release": "^25.0.3",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vite": "^7.3.1",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=24",
+    "npm": "not in use"
+  },
+  "volta": {
+    "node": "24.13.0"
+  },
+  "scripts": {
+    "build": "pnpm build:ts && pnpm build:native:optional",
+    "build:ts": "vite build",
+    "build:native": "cd native && napi build --platform --release",
+    "build:native:debug": "cd native && napi build --platform",
+    "build:native:optional": "cd native && (napi build --platform --release || (echo '⚠️  Rust native build skipped (rustc not installed). TS fallback will be used.' && exit 0))",
+    "dev": "vite build --watch",
+    "mcp": "node --env-file=.env --env-file-if-exists=.env.local dist/cli.js mcp",
+    "mcp:ai": "node --env-file=.env --env-file-if-exists=.env.ai dist/cli.js mcp",
+    "mcp:test": "node --env-file=.env.test dist/cli.js mcp",
+    "mcp:test:no-native": "IMSG_DISABLE_NATIVE=1 node --env-file=.env.test dist/cli.js mcp",
+    "mcp:no-native": "IMSG_DISABLE_NATIVE=1 node --env-file=.env --env-file-if-exists=.env.local dist/cli.js mcp",
+    "dev:mcp": "tsx src/cli.ts mcp",
+    "dev:mcp:watch": "nodemon --ext ts --exec 'tsx src/cli.ts mcp'",
+    "start": "node --env-file=.env --env-file-if-exists=.env.local dist/cli.js",
+    "debug": "node --env-file=.env --env-file-if-exists=.env.local dist/cli.js cli",
+    "cli": "node --env-file=.env --env-file-if-exists=.env.local dist/cli.js cli",
+    "cli:test": "node --env-file=.env.test dist/cli.js cli",
+    "tui": "node --env-file=.env --env-file-if-exists=.env.local dist/cli.js tui",
+    "tui:test": "node --env-file=.env.test dist/cli.js tui",
+    "tui:no-native": "IMSG_DISABLE_NATIVE=1 node --env-file=.env --env-file-if-exists=.env.local dist/cli.js tui",
+    "tui:test:no-native": "IMSG_DISABLE_NATIVE=1 node --env-file=.env.test dist/cli.js tui",
+    "doctor": "node --env-file=.env --env-file-if-exists=.env.local dist/cli.js doctor",
+    "test": "vitest run",
+    "test:native": "vitest run --mode development",
+    "test:no-native": "IMSG_DISABLE_NATIVE=1 vitest run",
+    "test:watch": "vitest",
+    "test:rust": "cd native && cargo test --release",
+    "verify": "pnpm lint && pnpm typecheck && pnpm test && pnpm build",
+    "lint": "biome check .",
+    "typecheck": "tsc --noEmit",
+    "fixtures": "tsx scripts/generate-fixtures.ts",
+    "fixtures:fresh": "rm -rf fixtures && pnpm fixtures",
+    "fixtures:stress": "tsx scripts/generate-fixtures.ts --stress --out fixtures-stress",
+    "stress:tui": "tsx scripts/stress-tui.ts",
+    "screenshots": "fc-list | grep -qi 'jetbrains mono' || { echo 'Install: brew install --cask font-jetbrains-mono'; exit 1; }; for f in scripts/screenshots/*.tape; do vhs \"$f\"; done",
+    "screenshots:check": "pnpm screenshots && git diff --exit-code docs/screenshots/",
+    "screenshots:native": "for f in scripts/screenshots/native/*.sh; do echo \"→ $f\"; bash \"$f\" || echo \"  (script failed; continuing)\"; done",
+    "hook:install": "git config core.hooksPath .githooks && echo '✓ pre-push hook installed (regenerates screenshots before push on macOS)'",
+    "pack:mcpb": "pnpm build && rm -rf release/mcpb && mkdir -p release/mcpb && cp -R dist dxt-manifest.json release/mcpb/ && (cd release/mcpb && zip -r ../imsg-mcp.mcpb . -x '*.DS_Store') && echo 'Built release/imsg-mcp.mcpb'",
+    "fixtures:if-missing": "node -e \"if(!require('fs').existsSync('fixtures/chat.db')){require('child_process').execSync('pnpm fixtures', {stdio:'inherit'})}\"",
+    "rebuild": "pnpm rebuild better-sqlite3",
+    "native:build": "cd native && napi build --platform --release",
+    "native:build:debug": "cd native && napi build --platform",
+    "stress": "tsx scripts/stress-mcp.ts .env.test",
+    "stress:live": "tsx scripts/stress-mcp.ts .env.local"
+  }
+}

package/skills/imsg-mcp/SKILL.md

@@ -0,0 +1,168 @@
+# imsg-mcp
+
+Companion skill for agents using or developing the `imsg-mcp` iMessage MCP server.
+
+## When to use
+
+- When an agent needs to text the human for clarification or approval.
+- When an agent should wait for an iMessage reply before continuing.
+- When an agent needs to inspect recent conversations or unread messages.
+- When developing/debugging the imsg-mcp codebase itself.
+
+## Quick start
+
+1. Run `imsg doctor` on a new machine to check permissions.
+2. Use `list_conversations` to identify the correct thread (returns `threadSlug`).
+3. Use `send_message` with `threadSlug` for existing threads, especially groups.
+4. Use `wait_for_reply` after sending when the workflow depends on a human answer.
+
+## Local machine requirements
+
+- macOS only for live reads and sends.
+- Full Disk Access required to read `~/Library/Messages/chat.db` and Address Book.
+- Messages.app must be open to send messages.
+- Node >= 24 (see `package.json` / Volta).
+
+## Git LFS (required in cloud / CI / fresh clones)
+
+Large binaries (`*.db`, `*.abcddb`) are stored with Git LFS. A normal clone may leave pointer stubs.
+
+```bash
+git lfs install   # once per machine
+git lfs pull      # before pnpm install / tests / running against env-data/
+```
+
+## Thread slugs
+
+Stable, human-readable IDs for conversations: `{name}~{service}~{4-hex}` (e.g. `alice~imsg~a3f2`).
+
+- `list_conversations` returns `threadSlug` per row
+- `send_message` accepts `threadSlug` or `recipient`
+- `wait_for_reply` accepts `threadSlug` or `chatIdentifier`
+- See `src/thread-slug.ts`, `src/slug-store.ts`
+
+## Binaries
+
+| Binary | Purpose |
+|--------|---------|
+| `imsg mcp` | MCP stdio server (used by AI hosts like Claude, Cursor) |
+| `imsg cli` | Interactive CLI with REPL |
+| `imsg tui` | Full-screen TUI (Ink/React) |
+
+## TUI (`imsg`)
+
+Vim-style keybindings: `j/k` move, `gg/G` top/bottom, `Ctrl-d/u` half-page, `{/}` group-jump, `Enter` message details, `o` open attachment, `y` copy slug, `d` toggle dev stats, `Tab` switch panes, `/` filter, `c` compose, `q` quit.
+
+## Native Rust module (optional)
+
+`native/` contains a Rust acceleration module (`napi-rs` + `rusqlite` + `rayon`). Build with `pnpm native:build`. Falls back to TypeScript automatically if not built. The dev stats panel (`d` key in TUI) shows which engine is active.
+
+## Tool limits
+
+`limit: 0` = unlimited (bounded only by the per-tool timeout). No upper cap.
+Defaults: 20 for most tools, 100 for `get_unread_messages`.
+
+## Self-healing watchdog
+
+`src/watchdog.ts` runs three monitors that self-kill (so the host respawns) on:
+- Event-loop p99 lag > 10s
+- RSS > 1GB or monotonic heap growth across 10 × 60s samples
+- Uptime > 24h with no activity in the last hour
+
+All thresholds are env-overridable (`IMSG_EVENT_LOOP_KILL_MS`, `IMSG_MAX_RSS_MB`, etc.).
+
+## MCP cancellation
+
+The server honors `notifications/cancelled`. Long-running handlers (`wait_for_reply`) abort cleanly when the host cancels.
+
+## MCP pagination & export
+
+- `get_messages` returns a footer with `oldestMessageId`. Pass it as `beforeMessageId` to paginate. Hard cap 5000/call.
+- `export_messages` streams a chat to a file (markdown/csv/json/ndjson) — use this instead of huge `get_messages` calls.
+
+## TUI date jump + selection + export
+
+- `:` open date-jump (e.g. `1 year ago`, `2024-01-15`).
+- `V` enter visual select; `e` export selection; `y` copy text.
+
+## Bounded memory
+
+When loaded messages exceed `IMSG_TUI_MSG_HARD_CAP` (default 5000), middle is evicted; first 200 (anchor) + window around cursor stay. Gap markers show evicted regions.
+
+## TUI lazy loading + cache
+
+- 200 conversations load initially; another 100 lazy-load when within 20 of the end.
+- Older messages lazy-load when scrolling within 10 of the top of a thread.
+- Per-chat cache holds messages for fast re-entry. Tunable: `IMSG_TUI_CACHE_TTL_MS`, `IMSG_TUI_CACHE_STALE_MS`, `IMSG_TUI_CACHE_MEM_PRESSURE_MB`.
+
+## Debugging & Logs
+
+### MCP tool: `health_check`
+
+Returns vital signs (uptime, heap, RSS, event-loop p99, tool calls, engine) in milliseconds — works even when the DB is wedged.
+
+### MCP tool: `get_logs`
+
+```
+get_logs({ tail: 50, source: "all" })
+```
+
+- `source: "memory"` — in-process buffer (default)
+- `source: "file"` — NDJSON log from `$TMPDIR/imsg-mcp/`
+- `source: "all"` — both
+
+### Log files
+
+Full NDJSON logs are written to `$TMPDIR/imsg-mcp/imsg-mcp-{PID}-{date}.ndjson`. These persist across restarts and contain:
+
+- `level: "perf"` + `dur_ms` — performance spans for every DB query
+- `level: "info"`, `msg: "heartbeat"` — periodic memory/uptime (every 60s)
+- `msg: "startup"` — process start marker (with PID, node version)
+- `msg: "shutdown"` — graceful exit marker (with uptime, reason)
+
+**Crash detection:** If a log file has no `"shutdown"` entry, the process crashed or hung.
+
+### Process lifecycle
+
+- `src/shutdown.ts` — central cleanup registry, signal handlers (SIGINT, SIGTERM, SIGHUP, SIGQUIT)
+- Orphan detection: parent PID watchdog (detects reparenting to launchd) + stdin EOF detection (MCP host died)
+- After TUI crashes, check for orphans: `ps aux | grep imsg`
+
+## Environment variables (Vite / Vitest)
+
+Precedence: `.env` → `.env.local` → `.env.[mode]` → `.env.[mode].local`
+
+| File | Role |
+|------|------|
+| `.env` | Baseline: `VITE_ENV=development` |
+| `.env.local` | Machine paths (`VITE_IMSG_DB_PATH`, etc.) |
+| `.env.test` | `VITE_ENV=ai` + `env-data/` paths for `pnpm test` |
+
+- `pnpm test` — Vitest mode `test` (loads `.env.test`)
+- `pnpm test:native` — mode `development` (Mac paths from `.env.local`)
+- Vitest always mocks AppleScript sends (`VITEST=true`)
+
+## Code map
+
+| Area | Location |
+|------|----------|
+| MCP tools / Zod | `src/index.ts` |
+| SQLite messages | `src/imessage-db.ts` |
+| Blob parsing | `src/attributed-body-text.ts`, `src/parsers/typedstream-parser.ts` |
+| Contacts | `src/contacts-db.ts` |
+| Slugs | `src/thread-slug.ts`, `src/slug-store.ts` |
+| Send / mock | `src/applescript.ts`, `src/mock-send-db.ts` |
+| TUI | `src/tui/` (Ink/React) |
+| Native module | `native/` (Rust + napi-rs) |
+| Shutdown | `src/shutdown.ts` |
+| Logging | `src/logger.ts` |
+| Config | `src/config.ts` |
+| Types | `src/types.ts` |
+| DB schema | `docs/IMESSAGE_DB_SCHEMA.md` |
+
+## Security / guardrails
+
+- Treat iMessage data as sensitive local user data.
+- Never publish private message content.
+- Confirm before sending messages on behalf of the user.
+- See `AGENTS.md` for thread isolation and MCP guardrails.