MCP overhaul: 24 tools, remote endpoint, agent guide

- Expand MCP from 8 to 24 tools matching every REST endpoint (agent
  management, SMTP config, full calendar/event CRUD, debugging, discovery)
- Add missing parameters to existing tools (metadata, attendees, status,
  webhook config, welcome_event)
- Add remote MCP endpoint at /mcp via Streamable HTTP transport — agents
  connect with just a URL and API key, no local install needed
- Extract shared tool registration into src/lib/mcp-tools.mjs, used by
  both STDIO and HTTP transports
- Rewrite MCP instructions as structured agent-facing quick-start guide
- Add caldave://guide MCP resource with comprehensive getting-started
  docs (setup checklist, workflow examples, field reference, tool catalog)
- Update CALDAVE_SPEC.md, README.md, CHANGELOG.md, and /changelog route

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: plc

CALDAVE_SPEC.md

@@ -520,20 +520,81 @@ For AgentMail, set the `agentmail_api_key` on the calendar via `POST /calendars`
 
 For agents using MCP, CalDave exposes these tools:
 
+**Agent Management**
+
+| Tool | Description |
+|------|-------------|
+| `caldave_get_agent` | Get the authenticated agent profile (name, description, created_at). |
+| `caldave_update_agent` | Update agent name or description. Name appears in outbound email From headers. |
+
+**SMTP Configuration**
+
+| Tool | Description |
+|------|-------------|
+| `caldave_set_smtp` | Configure SMTP for outbound invite/RSVP emails. |
+| `caldave_get_smtp` | View SMTP configuration (password excluded). |
+| `caldave_delete_smtp` | Remove SMTP configuration. Reverts to CalDave built-in delivery. |
+| `caldave_test_smtp` | Send a test email to verify SMTP configuration. |
+
+**Calendars**
+
 | Tool | Description |
 |------|-------------|
-| `caldave_create_calendar` | Create a new calendar. Returns calendar ID, email, and feed URL. |
 | `caldave_list_calendars` | List all calendars for this agent. |
-| `caldave_get_upcoming` | Get next N events from a calendar. |
-| `caldave_create_event` | Create an event on a calendar. |
-| `caldave_update_event` | Update an existing event. |
+| `caldave_get_calendar` | Get a single calendar by ID with full details. |
+| `caldave_create_calendar` | Create a new calendar. Returns calendar ID, email, and feed URL. |
+| `caldave_update_calendar` | Update calendar settings (name, timezone, webhook config). |
+| `caldave_delete_calendar` | Delete a calendar and all its events. |
+| `caldave_test_webhook` | Send a test payload to the calendar webhook URL. |
+
+**Events**
+
+| Tool | Description |
+|------|-------------|
+| `caldave_get_upcoming` | Get next N events from a calendar. Designed for agent polling. |
+| `caldave_list_events` | List events with optional date range and status filters. |
+| `caldave_get_event` | Get a single event by ID. |
+| `caldave_view_calendar` | Plain text table of upcoming events for quick inspection. |
+| `caldave_create_event` | Create an event. Supports recurring (RRULE), metadata, and attendees. |
+| `caldave_update_event` | Update an existing event. Supports metadata, attendees, and recurrence changes. |
 | `caldave_delete_event` | Delete an event. |
 | `caldave_respond_to_invite` | Accept/decline an inbound invite. |
-| `caldave_list_events` | List events with optional date range and status filters. |
+
+**Debugging & Discovery**
+
+| Tool | Description |
+|------|-------------|
+| `caldave_list_errors` | Query recent API errors for your agent. |
+| `caldave_get_error` | Get a single error with full stack trace. |
+| `caldave_get_changelog` | API changelog with personalized recommendations. |
+| `caldave_get_manual` | Machine-readable API manual with all endpoints and curl examples. |
 
 ### Configuration
 
-The MCP server (`src/mcp.mjs`) uses STDIO transport. Configure it in your MCP client:
+CalDave supports two MCP transports:
+
+#### Option 1: Remote URL (Recommended)
+
+No installation needed. Point your MCP client at the CalDave server URL:
+
+```json
+{
+  "mcpServers": {
+    "caldave": {
+      "url": "https://caldave.ai/mcp",
+      "headers": {
+        "Authorization": "Bearer sk_live_..."
+      }
+    }
+  }
+}
+```
+
+The remote endpoint uses Streamable HTTP transport with session management. Auth is via your API key in the `Authorization` header.
+
+#### Option 2: Local STDIO
+
+For local development or offline use, run the STDIO server directly:
 
 **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 ```json
@@ -543,7 +604,8 @@ The MCP server (`src/mcp.mjs`) uses STDIO transport. Configure it in your MCP cl
       "command": "node",
       "args": ["/path/to/caldave/src/mcp.mjs"],
       "env": {
-        "CALDAVE_API_KEY": "sk_live_..."
+        "CALDAVE_API_KEY": "sk_live_...",
+        "CALDAVE_URL": "https://caldave.ai"
       }
     }
   }
@@ -558,7 +620,8 @@ The MCP server (`src/mcp.mjs`) uses STDIO transport. Configure it in your MCP cl
       "command": "node",
       "args": ["/path/to/caldave/src/mcp.mjs"],
       "env": {
-        "CALDAVE_API_KEY": "sk_live_..."
+        "CALDAVE_API_KEY": "sk_live_...",
+        "CALDAVE_URL": "https://caldave.ai"
       }
     }
   }

CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+### Added
+- **MCP server at full parity with API** — Added 16 new MCP tools covering all documented API endpoints. Previously the MCP server only had 8 core tools; it now exposes 24 tools matching every REST endpoint:
+  - **Agent management**: `caldave_get_agent`, `caldave_update_agent`
+  - **SMTP configuration**: `caldave_set_smtp`, `caldave_get_smtp`, `caldave_delete_smtp`, `caldave_test_smtp`
+  - **Calendar management**: `caldave_get_calendar`, `caldave_update_calendar`, `caldave_delete_calendar`, `caldave_test_webhook`
+  - **Event tools**: `caldave_get_event`, `caldave_view_calendar`
+  - **Debugging**: `caldave_list_errors`, `caldave_get_error`
+  - **Discovery**: `caldave_get_changelog`, `caldave_get_manual`
+- **Missing parameters on existing MCP tools** — `caldave_create_event` now supports `metadata`, `attendees`, and `status`. `caldave_update_event` now supports `metadata`, `attendees`, and `recurrence`. `caldave_create_calendar` now supports `webhook_url`, `webhook_secret`, `webhook_offsets`, `agentmail_api_key`, and `welcome_event`.
+- **Remote MCP endpoint at `/mcp`** — CalDave now serves an MCP endpoint via Streamable HTTP transport. Agents can connect with just a URL and API key (`{ "url": "https://caldave.ai/mcp", "headers": { "Authorization": "Bearer sk_live_..." } }`) — no local installation required. Sessions are stateful with automatic 30-minute TTL cleanup.
+- **MCP agent guide** — Enhanced MCP instructions with structured quick-start, workflow descriptions, and tool selection guide. Added `caldave://guide` MCP resource with a comprehensive getting-started guide for agents (setup checklist, code examples, event fields reference, webhook/SMTP config, debugging).
+
 ### Improved
 - **Auth performance** — Added missing database index on `agents.api_key_hash`. Auth lookups now use an index scan instead of a full table scan on every authenticated request.
 - **`/docs` caching** — Static HTML documentation is pre-computed at startup and served with `Cache-Control: public, max-age=86400`. Eliminates ~30KB of string construction per request.

README.md

@@ -20,7 +20,7 @@ A calendar-as-a-service API for AI agents. Agents own calendars, create and mana
 - **PostgreSQL** database with auto-initializing schema
 - **Docker** setup for local development
 - **Fly.io** configuration for production deployment
-- **MCP server** for AI agents using the Model Context Protocol
+- **MCP server** — remote endpoint at `/mcp` (Streamable HTTP) and local STDIO transport
 - **Status page** at `/` showing server and database health
 
 ## Prerequisites
@@ -88,6 +88,7 @@ curl -s "http://127.0.0.1:3720/calendars/CAL_ID/upcoming" \
 | `POST /calendars/:id/events/:eid/respond` | Yes | Accept/decline invite |
 | `GET /feeds/:id.ics?token=TOKEN` | Feed token | iCal feed (subscribable) |
 | `POST /inbound/:token` | Token in URL | Inbound email webhook (per-calendar) |
+| `POST\|GET\|DELETE /mcp` | Yes | Remote MCP endpoint (Streamable HTTP transport) |
 
 Auth = `Authorization: Bearer <api_key>` (except feeds and inbound webhook)
 
@@ -103,6 +104,7 @@ See [CALDAVE_SPEC.md](CALDAVE_SPEC.md) for full request/response examples.
 │   ├── lib/
 │   │   ├── ids.js            # nanoid-based ID generation (agt_, cal_, evt_, inb_)
 │   │   ├── keys.js           # SHA-256 API key hashing
+│   │   ├── mcp-tools.mjs     # Shared MCP tool registration (24 tools)
 │   │   └── recurrence.js     # RRULE parsing + instance materialization
 │   ├── middleware/
 │   │   ├── auth.js           # Bearer token auth
@@ -113,7 +115,7 @@ See [CALDAVE_SPEC.md](CALDAVE_SPEC.md) for full request/response examples.
 │       ├── events.js         # Event CRUD + upcoming + respond
 │       ├── feeds.js          # iCal feed generation
 │       └── inbound.js        # Inbound email webhook (per-calendar token URL)
-│   └── mcp.mjs              # MCP server (STDIO transport, 8 tools)
+│   └── mcp.mjs              # MCP server (STDIO transport, 24 tools)
 ├── scripts/
 │   ├── init-db.sh            # Creates database if it doesn't exist
 │   └── get-port.sh           # Generates deterministic port from project name

src/index.js

@@ -165,6 +165,12 @@ curl -s "https://${DOMAIN}/man?guide"</code></pre>
   res.send(html);
 });
 
+// Remote MCP endpoint (Streamable HTTP transport, auth handled internally)
+// Mounted via dynamic import in start() since route file is ESM
+app.post('/mcp', (req, res, next) => { if (app._mcpHandlers) app._mcpHandlers.handlePost(req, res).catch(next); else res.status(503).json({ error: 'MCP endpoint loading' }); });
+app.get('/mcp', (req, res, next) => { if (app._mcpHandlers) app._mcpHandlers.handleGet(req, res).catch(next); else res.status(503).json({ error: 'MCP endpoint loading' }); });
+app.delete('/mcp', (req, res, next) => { if (app._mcpHandlers) app._mcpHandlers.handleDelete(req, res).catch(next); else res.status(503).json({ error: 'MCP endpoint loading' }); });
+
 // API documentation, quick start, and legal pages (no auth)
 app.use('/docs', docsRouter);
 app.use('/quickstart', quickstartRouter);
@@ -281,6 +287,15 @@ async function start() {
     console.error('Server starting without schema — DB may not be ready yet');
   }
 
+  // Load ESM MCP route handlers
+  try {
+    const mcpHandlers = await import('./routes/mcp.mjs');
+    app._mcpHandlers = mcpHandlers;
+    console.log('MCP HTTP endpoint loaded at /mcp');
+  } catch (err) {
+    console.error('Failed to load MCP HTTP route:', err.message);
+  }
+
   // Extend materialization horizons for recurring events
   extendAllHorizons(pool).catch(err => {
     console.error('Failed to extend horizons on startup:', err.message);