imsg-mcp 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and follows [Semantic Versioning](https://semver.org/).
+
+<!-- semantic-release populates entries above this line. -->

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 George G
+
+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

@@ -0,0 +1,127 @@
+# imsg-mcp
+
+[![npm version](https://img.shields.io/npm/v/imsg-mcp.svg)](https://www.npmjs.com/package/imsg-mcp)
+[![CI](https://github.com/george43g/imsg-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/george43g/imsg-mcp/actions/workflows/ci.yml)
+[![Release](https://github.com/george43g/imsg-mcp/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/george43g/imsg-mcp/actions/workflows/release.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**MCP server, CLI, and terminal UI for iMessage on macOS.** Let AI agents read your iMessage / SMS, search history, send messages, and export conversations — without ever leaving your machine. Includes a self-healing watchdog so a wedged query can't take your agent down.
+
+![TUI overview](docs/screenshots/tui-overview.png)
+
+[**More screenshots →**](docs/SCREENSHOTS.md) · [**Workflows →**](docs/WORKFLOWS.md) · [**Tool reference →**](docs/TOOLS.md)
+
+---
+
+## Install
+
+### Claude Desktop (one-click)
+
+Download `imsg-mcp.mcpb` from [the latest release](https://github.com/george43g/imsg-mcp/releases/latest) and double-click. See [llms-install.md](llms-install.md) for the agent-narrated install flow.
+
+### Any MCP host (npx, one-liner)
+
+```json
+{
+  "mcpServers": {
+    "imessage": {
+      "command": "npx",
+      "args": ["-y", "imsg-mcp", "mcp"]
+    }
+  }
+}
+```
+
+Drop into `claude_desktop_config.json` (Claude Desktop) or `mcp.json` (Cursor / Warp). Bun users: `bunx imsg-mcp mcp` is ~10× faster cold-start.
+
+### Autodetect everything
+
+```bash
+npx -y imsg-mcp setup --write claude   # or --write cursor
+npx -y imsg-mcp doctor                  # verify Full Disk Access + DB
+```
+
+---
+
+## Quickstart: Export a group thread
+
+The canonical workflow — find a conversation in the TUI, copy its handle, export it from the CLI:
+
+```bash
+imsg tui                                              # browse, /filter to find the group
+                                                      # press `y` to copy the threadSlug
+imsg export weekend-crew~imsg~d4e5 \
+  --since '3 months ago' \
+  --include-attachments \
+  --output ~/weekend-crew.md
+```
+
+Full walkthrough with screenshots: [**docs/WORKFLOWS.md**](docs/WORKFLOWS.md).
+
+---
+
+## MCP tools
+
+<details>
+<summary><b>15 tools shipped (click to expand)</b></summary>
+
+| Tool | Purpose |
+|------|---------|
+| `get_messages` | Paginated messages from a chat. |
+| `get_unread_messages` | Unread messages across all chats. |
+| `list_conversations` | Chats with `threadSlug`, snippets, unread counts. |
+| `search_messages` | Fuzzy + literal search across history. |
+| `send_message` | Send via Messages.app (text + attachments). |
+| `wait_for_reply` | Poll for the next reply. |
+| `export_messages` | Stream a chat to file (md/csv/json/ndjson). |
+| `search_attachments` | Find attachments by mime/date/chat. |
+| `get_attachment` | Fetch attachment bytes (inline or path). |
+| `check_imessage_availability` | Pre-flight iMessage vs SMS reachability. |
+| `chat_analytics` | Pre-aggregated stats (heatmaps, leaderboards, etc). |
+| `list_contacts` / `search_contacts` / `get_contact` | Contact lookup. |
+| `resolve_handle` | Phone/email → contact name. |
+
+</details>
+
+Full reference (CLI subcommands + MCP tools + every flag): [**docs/TOOLS.md**](docs/TOOLS.md).
+
+---
+
+## Terminal UI
+
+```bash
+imsg tui
+```
+
+Vim-style: `j/k` move, `gg/G` jump, `Enter` drawer, `o` Quick Look an attachment, `:` jump to date, `V` visual select, `e` export, `S` send via other app, `y` copy slug, `c` compose, `q` quit.
+
+Themes (`safe` / `powerline`) and a single accent color drive the whole palette. See [docs/TOOLS.md#tui-configuration](docs/TOOLS.md#tui-configuration).
+
+---
+
+## Permissions
+
+- **Full Disk Access** — required to read `chat.db` and Address Book. System Settings → Privacy & Security → Full Disk Access → add the terminal/IDE you actually run from.
+- **Automation** — required only for sending. macOS prompts on first send.
+
+Privacy: only ever reads your **local** `~/Library/Messages/chat.db`. Nothing is uploaded. The connected MCP host (Claude / Cursor / Warp / …) sees whatever messages the agent fetches — treat those hosts the same way you treat any app with Full Disk Access.
+
+---
+
+## Contributing
+
+```bash
+pnpm install
+pnpm verify              # lint + typecheck + test + build
+pnpm hook:install        # opt-in pre-push hook for screenshot regen (macOS only)
+pnpm screenshots         # regenerate vhs tapes (requires JetBrains Mono)
+pnpm screenshots:native  # regenerate native macOS captures (manual only)
+```
+
+Screenshots are auto-regenerated by a local pre-push hook when `src/tui/**` or `scripts/screenshots/*.tape` change. CI verifies that committed PNGs match the current source. See [docs/SCREENSHOTS.md#regeneration](docs/SCREENSHOTS.md#regeneration).
+
+---
+
+## License
+
+MIT