@koderlabs/inbox-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KoderLabs
+
+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,91 @@
+# @koderlabs/inbox-mcp-server
+
+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.
+
+## Quick facts
+
+| | |
+|---|---|
+| Port | 10405 |
+| Transports | Streamable HTTP (`/mcp`) + stdio (`instantinbox-mcp-stdio`) |
+| Auth | Bearer token: user JWT or `sk_live_*` / `sk_test_*` key |
+| Scopes | `inbox:read`, `inbox:write`, `email:read`, `email:write` |
+
+## Tools (10)
+
+| 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`.
+
+## Environment variables
+
+| Var | Default | Notes |
+|---|---|---|
+| `PORT` | `10405` | HTTP transport |
+| `API_BASE_URL` | `http://localhost:10402/api/v1` | InstantInbox API |
+| `INBOX_API_BASE_URL` | same | stdio override |
+| `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
+
+```json
+{
+  "mcpServers": {
+    "instantinbox": {
+      "command": "npx",
+      "args": ["-y", "@koderlabs/inbox-mcp-server"],
+      "env": {
+        "INBOX_API_BASE_URL": "https://inbox.koderlabs.net/api/v1",
+        "INBOX_API_KEY": "<your token>"
+      }
+    }
+  }
+}
+```
+
+## Example agent workflow
+
+```
+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
+```
+
+## Local dev
+
+```bash
+pnpm --filter @koderlabs/inbox-mcp-server build
+PORT=10405 INBOX_API_KEY=<token> pnpm --filter @koderlabs/inbox-mcp-server start
+```
+
+## Deviations from InstantTasks MCP
+
+- 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.