inboxctl 0.1.0

package/.env.example

@@ -0,0 +1,14 @@
+# Google OAuth2 credentials (from Google Cloud Console)
+GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=your-client-secret
+
+# Optional: fixed redirect URI for a Web application OAuth client
+# Default: http://127.0.0.1:3456/callback
+# GOOGLE_REDIRECT_URI=http://127.0.0.1:3456/callback
+
+# Optional: choose Gmail transport adapter
+# auto = try @googleapis/gmail first, fall back to REST if the client transport
+#        fails authenticated Gmail requests in this environment
+# google-api = force @googleapis/gmail
+# rest = force direct Gmail REST calls
+# INBOXCTL_GMAIL_TRANSPORT=auto

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Freeman
+
+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,277 @@
+# inboxctl
+
+**An MCP server that gives AI agents structured, safe access to your Gmail inbox, with a CLI and TUI for when you want to inspect or drive the same workflows yourself.**
+
+![inboxctl demo](https://raw.githubusercontent.com/matfreeman/inboxctl/main/demo.gif)
+
+## Why MCP-native?
+
+Most email tools put the intelligence inside the app. `inboxctl` does the opposite: it is the infrastructure layer, and your AI agent is the brain.
+
+Connect any MCP client, including Claude Desktop, Claude Code, or another MCP-compatible agent, and it gets structured access to search your inbox, review sender patterns, detect newsletter noise, triage unread mail, apply labels, archive, create Gmail filters, and manage rules. `inboxctl` handles the Gmail plumbing, audit trail, and undo path.
+
+The CLI and TUI ship alongside MCP so you can always inspect what an agent did, undo it, or run the same work manually.
+
+Emails are never deleted. The tool can label, archive, mark read, and forward, but it does not destroy data.
+
+## What the MCP server exposes
+
+| | Count | Examples |
+|---|---|---|
+| **Tools** | 25 | `search_emails`, `archive_emails`, `label_emails`, `mark_read`, `get_top_senders`, `get_newsletter_senders`, `deploy_rule`, `run_rule`, `create_filter`, `undo_run` |
+| **Resources** | 6 | `inbox://recent`, `inbox://summary`, `rules://deployed`, `rules://history`, `stats://senders`, `stats://overview` |
+| **Prompts** | 5 | `summarize-inbox`, `review-senders`, `find-newsletters`, `suggest-rules`, `triage-inbox` |
+
+An agent can read your inbox summary, review your noisiest senders, suggest a YAML rule to handle them, deploy it in dry-run, show you the results, and apply it, all through MCP calls.
+
+## Quick start
+
+### Published package
+
+```bash
+npx inboxctl@latest setup
+npx inboxctl@latest sync
+npx inboxctl@latest
+```
+
+### Development checkout
+
+```bash
+npm install
+npm run build
+npm link
+inboxctl setup
+inboxctl sync
+inboxctl
+```
+
+## Connect your AI agent
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "inboxctl": {
+      "command": "npx",
+      "args": ["-y", "inboxctl@latest", "mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```json
+{
+  "mcpServers": {
+    "inboxctl": {
+      "command": "npx",
+      "args": ["-y", "inboxctl@latest", "mcp"]
+    }
+  }
+}
+```
+
+For a local checkout, replace the command with `node` and point the args at `dist/cli.js`:
+
+```json
+{
+  "mcpServers": {
+    "inboxctl": {
+      "command": "node",
+      "args": ["/absolute/path/to/inboxctl/dist/cli.js", "mcp"]
+    }
+  }
+}
+```
+
+Then ask your agent things like:
+
+- "What are my noisiest unread senders?"
+- "Find all emails that look like receipts and label them Receipts."
+- "Create a Gmail filter to auto-archive future mail from noreply@example.com."
+- "Show me what the label-receipts rule would match, then apply it."
+
+## Use the CLI or TUI directly
+
+```bash
+inboxctl                    # launch the TUI
+inboxctl mcp                # start MCP server on stdio
+inboxctl demo               # launch the seeded demo mailbox
+```
+
+## Features
+
+- **MCP server** with the full feature set exposed as tools, resources, and prompts.
+- **Rules as code** in YAML, with deploy, dry-run, apply, drift detection, audit logging, and undo.
+- **Local-first analytics** on top senders, unread rates, newsletter detection, labels, and volume trends.
+- **Gmail filter management** for always-on server-side rules on future incoming mail.
+- **Full audit trail** with before/after state snapshots for reversible actions.
+- **Interactive TUI** for inbox triage, email detail, stats, rules, and search.
+- **Guided setup wizard** for Google Cloud and local OAuth configuration.
+- **Demo mode** with realistic seeded data for screenshots, recordings, and safe exploration.
+
+## Rules as code
+
+Rules live in a `rules/` directory. Deploy them, run them against your synced inbox, and undo them if needed.
+
+```yaml
+name: label-receipts
+description: Label emails that look like receipts
+enabled: true
+priority: 30
+
+conditions:
+  operator: OR
+  matchers:
+    - field: from
+      values:
+        - "receipts@stripe.com"
+        - "no-reply@paypal.com"
+    - field: subject
+      contains:
+        - "receipt"
+        - "order confirmation"
+        - "invoice"
+
+actions:
+  - type: label
+    label: "Receipts"
+```
+
+Rules default to dry-run. Pass `--apply` to execute them.
+
+## CLI reference
+
+```bash
+# sync and read
+inboxctl sync
+inboxctl sync --full
+inboxctl inbox -n 20
+inboxctl search "from:github.com"
+inboxctl email <id>
+
+# actions
+inboxctl archive <id>
+inboxctl archive --query "label:newsletters"
+inboxctl label <id> Receipts
+inboxctl read <id>
+inboxctl forward <id> you@example.com
+inboxctl undo <run-id>
+inboxctl history
+
+# analytics
+inboxctl stats
+inboxctl stats senders --top 20
+inboxctl stats newsletters
+inboxctl stats volume --period week
+
+# rules
+inboxctl rules deploy
+inboxctl rules run label-receipts
+inboxctl rules run label-receipts --apply
+inboxctl rules diff
+inboxctl rules undo <run-id>
+
+# filters
+inboxctl filters list
+inboxctl filters create --from newsletter@example.com --label Newsletters --archive
+inboxctl filters delete <id>
+
+# labels
+inboxctl labels list
+inboxctl labels create Receipts
+```
+
+## Configuration
+
+`inboxctl` reads from environment variables in `.env` and persistent settings in `~/.config/inboxctl/config.json`.
+
+```bash
+GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=your-client-secret
+```
+
+Optional:
+
+```bash
+GOOGLE_REDIRECT_URI=http://127.0.0.1:3456/callback
+INBOXCTL_GMAIL_TRANSPORT=auto
+```
+
+Run `inboxctl setup` for a guided walkthrough.
+
+If you want to configure Google manually:
+
+1. Create or select a Google Cloud project.
+2. Enable the Gmail API.
+3. Configure the OAuth consent screen.
+4. Create a Web application OAuth client.
+5. Add `http://127.0.0.1:3456/callback` as an authorized redirect URI.
+6. Copy the client ID and client secret into `.env` or `~/.config/inboxctl/config.json`.
+
+Required scopes:
+
+- `https://www.googleapis.com/auth/gmail.modify`
+- `https://www.googleapis.com/auth/gmail.labels`
+- `https://www.googleapis.com/auth/gmail.settings.basic`
+- `https://www.googleapis.com/auth/userinfo.email`
+
+Helpful console links:
+
+- [Google Cloud APIs dashboard](https://console.cloud.google.com/apis/dashboard)
+- [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)
+- [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent)
+- [Credentials page](https://console.cloud.google.com/apis/credentials)
+
+| Path | Purpose |
+|------|---------|
+| `~/.config/inboxctl/config.json` | Persistent settings |
+| `~/.config/inboxctl/emails.db` | SQLite cache |
+| `~/.config/inboxctl/tokens.json` | OAuth tokens |
+| `./rules/` | YAML rule definitions |
+
+## Requirements
+
+- Node.js 20 or newer
+- A Google Cloud project with OAuth credentials and the Gmail API enabled
+- A Gmail or Google Workspace account
+- Build tooling for `better-sqlite3`
+
+Native dependency note:
+
+- macOS: install Xcode Command Line Tools with `xcode-select --install`
+- Debian or Ubuntu: install `build-essential`
+- Windows: install Visual Studio Build Tools with C++ support
+
+## Safety
+
+- No deletion. There is no code path that calls `messages.delete` or `messages.trash`.
+- Minimal OAuth scopes: `gmail.modify`, `gmail.labels`, `gmail.settings.basic`, and `userinfo.email`.
+- Dry-run by default for rules.
+- Audit trail for every reversible mutation.
+- Undo support for reversible actions.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run lint
+npm test
+npm run test:coverage
+```
+
+### Regenerating the demo recording
+
+```bash
+npm run build
+vhs demo.tape
+```
+
+This writes `demo.gif` at the repo root. It requires [VHS](https://github.com/charmbracelet/vhs).
+
+## License
+
+MIT