@koderlabs/inbox-mcp 0.1.1 → 0.1.3

package/README.md

@@ -1,51 +1,19 @@
 # @koderlabs/inbox-mcp
 
-MCP server for InstantInbox (inbox.koderlabs.net). Lets AI dev agents create
-disposable inboxes and read received emails so any app's email-driven flow
-(signup verification, password reset, magic link, OTP) can be tested end-to-end.
+MCP server for [InstantInbox](https://inbox.koderlabs.net) — disposable email inboxes for end-to-end testing.
 
-## Quick facts
+Lets AI coding agents (Claude Desktop, Claude Code, Cursor, etc.) create temporary email addresses on demand and read messages received at them. Useful for testing any email-driven flow: signup verification, password reset, magic links, OTP codes, transactional notifications.
 
-| | |
-|---|---|
-| Port | 10405 |
-| Transports | Streamable HTTP (`/mcp`) + stdio (`instantinbox-mcp`) |
-| Auth | Bearer token: user JWT or `sk_live_*` / `sk_test_*` key |
-| Scopes | `inbox:read`, `inbox:write`, `email:read`, `email:write` |
+## Install
 
-## Tools (10)
+No global install needed. MCP clients launch it via `npx`.
 
-| Tool | Scope | Purpose |
-|---|---|---|
-| `whoami` | (none) | Confirm token + show granted scopes |
-| `list_inboxes` | `inbox:read` | List the caller's inboxes |
-| `create_inbox` | `inbox:write` | Create a new disposable inbox; returns the email address |
-| `get_inbox` | `inbox:read` | Look up an inbox by id or address |
-| `delete_inbox` | `inbox:write` | Permanently delete an inbox |
-| `list_emails` | `email:read`, `inbox:read` | List emails in an inbox (headers only) |
-| `get_email` | `email:read` | Fetch a single email's full body |
-| `wait_for_email` | `email:read`, `inbox:read` | Long-poll until a matching email arrives (or timeout) |
-| `delete_email` | `email:write` | Delete one email |
-| `mark_email_read` | `email:write` | Mark read / unread |
-
-`wait_for_email` is the killer tool — most email tests are
-`trigger → wait → extract link/code → click`.
+## Configure
 
-## Environment variables
+### Claude Desktop
 
-| Var | Default | Notes |
-|---|---|---|
-| `PORT` | `10405` | HTTP transport |
-| `API_BASE_URL` | `http://localhost:10402/api/v1` | HTTP transport — points at local API (self-host) |
-| `INBOX_API_BASE_URL` | `https://inbox.koderlabs.net/api/v1` | stdio transport — defaults to hosted instance |
-| `INBOX_API_KEY` | — | stdio: required Bearer token |
-| `MCP_ALLOWED_ORIGINS` | empty | CSV; required for browser-hosted clients |
-| `MCP_RATE_LIMIT_RPM` | `120` | Per-token request budget per minute |
-| `MCP_MAX_BODY_BYTES` | `1048576` | POST /mcp body cap |
-| `MCP_INTROSPECT_KEY` | — | Future OAuth introspection key (not yet required) |
-| `MCP_PUBLIC_URL` | `https://inbox.koderlabs.net/mcp` | OAuth discovery |
-
-## Claude Desktop configuration
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+`%APPDATA%\Claude\claude_desktop_config.json` (Windows)
 
 ```json
 {
@@ -54,7 +22,6 @@ disposable inboxes and read received emails so any app's email-driven flow
       "command": "npx",
       "args": ["-y", "@koderlabs/inbox-mcp"],
       "env": {
-        "INBOX_API_BASE_URL": "https://inbox.koderlabs.net/api/v1",
         "INBOX_API_KEY": "<your token>"
       }
     }
@@ -62,30 +29,79 @@ disposable inboxes and read received emails so any app's email-driven flow
 }
 ```
 
-## Example agent workflow
+### Claude Code
 
-```
-1. create_inbox        → returns ab12cd@inbox.koderlabs.net (id u_abc)
-2. (agent triggers signup with that address in the app under test)
-3. wait_for_email      → inboxId=u_abc, subjectContains="verify", timeoutSec=60
-4. (parse verification link from returned body)
-5. (agent visits link to complete signup)
-6. delete_inbox        → cleanup
-```
+Add to `.mcp.json` in your project root, same shape as above.
 
-## Local dev
+### Cursor
 
-```bash
-pnpm --filter @koderlabs/inbox-mcp build
-PORT=10405 INBOX_API_KEY=<token> pnpm --filter @koderlabs/inbox-mcp start
-```
+**Settings → MCP Servers → Add Server**
+- Command: `npx`
+- Args: `-y @koderlabs/inbox-mcp`
+- Env: `INBOX_API_KEY=<your token>`
+
+### Getting a token
+
+1. Sign up at [inbox.koderlabs.net](https://inbox.koderlabs.net)
+2. Generate an API key from **Settings → API Keys**, or use your session JWT
+
+Restart your MCP client after editing config.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `whoami` | Show identity + granted scopes |
+| `list_inboxes` | List your inboxes |
+| `create_inbox` | Create a disposable inbox. Returns full email address (e.g. `ab12cd@inbox.koderlabs.net`) |
+| `get_inbox` | Look up by id or address |
+| `delete_inbox` | Permanently delete an inbox |
+| `list_emails` | List emails in an inbox (headers only) |
+| `get_email` | Fetch a single email's full body (text + html + headers) |
+| `wait_for_email` | Long-poll until a matching email arrives (up to 120s). Filter by `subjectContains`, `fromContains`. |
+| `delete_email` | Delete one email |
+| `mark_email_read` | Mark email read / unread |
+
+`wait_for_email` is the workhorse — most email tests are `trigger → wait → extract → click`.
+
+## Example agent prompts
+
+> Create a disposable inbox, sign up at https://example.com using that address, then read the verification email and click the link.
+
+> Test the password-reset flow on staging: create an inbox, request reset, wait for the email, extract the reset token, and confirm reset works with a new password.
+
+> Spin up 5 disposable inboxes and trigger our newsletter signup with each — verify the welcome email arrives within 30 seconds.
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `INBOX_API_KEY` | — | **Required.** Bearer token for the InstantInbox API |
+| `INBOX_API_BASE_URL` | `https://inbox.koderlabs.net/api/v1` | API base — override only if self-hosting |
+
+## Scopes
+
+Tokens carry scopes; tools require specific ones:
+
+| Scope | Grants |
+|---|---|
+| `inbox:read` | View inboxes |
+| `inbox:write` | Create / delete inboxes |
+| `email:read` | Read emails |
+| `email:write` | Delete / mark emails |
+
+The server returns a clear error if a tool is called without the required scope.
+
+## Self-hosting
+
+Besides stdio, this package also ships a Streamable-HTTP transport for self-hosted deployments. See [the repo](https://github.com/jawaidgadiwala/instant-inbox) for source, docker compose, and configuration details.
+
+## Links
+
+- **Service:** [inbox.koderlabs.net](https://inbox.koderlabs.net)
+- **Source:** [github.com/jawaidgadiwala/instant-inbox](https://github.com/jawaidgadiwala/instant-inbox)
+- **Issues:** [github.com/jawaidgadiwala/instant-inbox/issues](https://github.com/jawaidgadiwala/instant-inbox/issues)
 
-## Deviations from InstantTasks MCP
+## License
 
-- No audit-shipping middleware (`withAudit`) — InstantInbox API has no
-  `/audit/mcp` endpoint yet. Add later if needed.
-- Auth currently delegates to `GET /auth/me` and grants all four scopes
-  on success; the inbox API has no per-key scoping today. Swap to real
-  introspection once the API has it.
-- OAuth flow is a stub — it tries `POST /oauth/introspect` and fails
-  cleanly if absent.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koderlabs/inbox-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "MIT",
   "description": "InstantInbox MCP server — disposable email inboxes for AI agent E2E testing. Streamable HTTP + stdio transports.",
   "keywords": [
@@ -35,11 +35,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/jawaidgadiwala/inbox.git",
+    "url": "git+https://github.com/jawaidgadiwala/instant-inbox.git",
     "directory": "apps/mcp"
   },
   "bugs": {
-    "url": "https://github.com/jawaidgadiwala/inbox/issues"
+    "url": "https://github.com/jawaidgadiwala/instant-inbox/issues"
   },
   "homepage": "https://inbox.koderlabs.net",
   "engines": {