mcp-twake-mail 0.1.0

package/README.md

@@ -0,0 +1,332 @@
+# mcp-twake-mail
+
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
+[![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
+
+**MCP server for [Twake.ai](https://www.twake.ai/) — integrate your sovereign JMAP email server with any MCP-compatible AI assistant**
+
+![Twake Mail](assets/twake-mail-screenshot.png)
+
+## Overview
+
+mcp-twake-mail is a Model Context Protocol (MCP) server that connects any MCP-compatible AI assistant (Claude Desktop, Claude Code, etc.) to your JMAP email server. Compatible with JMAP-compliant servers including Apache James, Cyrus IMAP, and other RFC 8620/8621 implementations.
+
+**Key benefits:**
+- Your data stays on your own servers — sovereign infrastructure
+- Works with any MCP-compatible AI assistant
+- Full control over email data — read, write, send, and organize
+- Multiple authentication methods: Basic, Bearer token, or OIDC
+- Secure HTTPS-only connections
+
+## Features
+
+**Email Read Tools:**
+- `list_emails` - List emails with filtering, search, and pagination
+- `get_email` - Get full email content including body and headers
+- `search_emails` - Search emails by keywords
+- `get_thread` - Get all emails in a conversation thread
+
+**Email Compose Tools:**
+- `send_email` - Compose and send a new email (plain text and/or HTML)
+- `reply_email` - Reply to an email with proper threading (In-Reply-To, References)
+- `create_draft` - Create a draft email for later editing or sending
+
+**Email Management Tools:**
+- `mark_as_read` - Mark an email as read
+- `mark_as_unread` - Mark an email as unread
+- `delete_email` - Move to trash or permanently delete
+- `move_email` - Move an email to a different mailbox
+- `add_label` - Add a label/mailbox to an email
+- `remove_label` - Remove a label/mailbox from an email
+
+**Mailbox Tools:**
+- `list_mailboxes` - List all mailboxes (Inbox, Sent, Drafts, etc.)
+
+**Attachment Tools:**
+- `get_attachments` - List attachment metadata for an email
+- `download_attachment` - Download attachment content (auto-saves large files to disk)
+
+**Advanced Features:**
+- OIDC authentication with PKCE (S256) for enterprise SSO
+- Automatic token refresh for OIDC sessions
+- Thread-based email grouping
+- Inline vs regular attachment detection
+- Large attachment handling (auto-saves to ~/Downloads for files > 750KB)
+- MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint)
+
+## Prerequisites
+
+- **Node.js** >= 20.0.0
+- **JMAP Server** - A JMAP-compliant email server such as:
+  - Apache James
+  - Cyrus IMAP
+  - Stalwart Mail Server
+  - Fastmail
+- **MCP-compatible AI assistant** - Claude Desktop, Claude Code, or any MCP client
+
+## Installation
+
+**From source:**
+```bash
+git clone https://github.com/linagora/mcp-twake-mail.git
+cd mcp-twake-mail
+npm install
+npm run build
+```
+
+## Quick Setup (Recommended)
+
+The easiest way to configure mcp-twake-mail is to use the interactive setup wizard:
+
+```bash
+npx mcp-twake-mail setup
+```
+
+The wizard will:
+1. Ask for your JMAP server session URL
+2. Ask for your authentication method (Basic, Bearer, or OIDC)
+3. Collect the required credentials
+4. Test the connection to your JMAP server
+5. Generate and optionally write the configuration to your Claude Desktop config file
+
+Example session:
+```
+=== MCP Twake Mail Setup Wizard ===
+
+JMAP Session URL: https://jmap.example.com/jmap/session
+
+Authentication method:
+  1. Basic (username/password)
+  2. Bearer token (JWT)
+  3. OIDC (OpenID Connect)
+Choose [1-3]: 1
+
+Username: user@example.com
+Password: ********
+
+Testing connection...
+Connected! Account ID: abc123
+
+Server name for Claude config [twake-mail]: twake-mail
+
+--- Generated Claude Desktop Config ---
+{
+  "mcpServers": {
+    "twake-mail": {
+      "command": "npx",
+      "args": ["-y", "mcp-twake-mail"],
+      "env": {
+        "JMAP_SESSION_URL": "https://jmap.example.com/jmap/session",
+        "JMAP_AUTH_METHOD": "basic",
+        "JMAP_USERNAME": "user@example.com",
+        "JMAP_PASSWORD": "********"
+      }
+    }
+  }
+}
+---------------------------------------
+
+Write to Claude Desktop config? [Y/n]: y
+
+Config written successfully!
+Restart Claude Desktop to load the new configuration.
+```
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `mcp-twake-mail` | Start MCP server (default) |
+| `mcp-twake-mail setup` | Interactive configuration wizard |
+| `mcp-twake-mail auth` | Re-run OIDC authentication flow |
+| `mcp-twake-mail check` | Verify configuration and test connection |
+
+## Configuration
+
+### Environment Variables
+
+#### Basic Auth
+
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `JMAP_SESSION_URL` | Yes | JMAP session endpoint URL | `https://jmap.example.com/jmap/session` |
+| `JMAP_AUTH_METHOD` | No | Set to `basic` (default) | `basic` |
+| `JMAP_USERNAME` | Yes | Username for authentication | `user@example.com` |
+| `JMAP_PASSWORD` | Yes | Password for authentication | `your-password` |
+
+#### Bearer Token
+
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `JMAP_SESSION_URL` | Yes | JMAP session endpoint URL | `https://jmap.example.com/jmap/session` |
+| `JMAP_AUTH_METHOD` | Yes | Must be set to `bearer` | `bearer` |
+| `JMAP_TOKEN` | Yes | JWT Bearer token | `eyJhbGciOiJSUzI1NiIs...` |
+
+#### OIDC Authentication
+
+For enterprise SSO with OpenID Connect (PKCE S256):
+
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `JMAP_SESSION_URL` | Yes | JMAP session endpoint URL | `https://jmap.example.com/jmap/session` |
+| `JMAP_AUTH_METHOD` | Yes | Must be set to `oidc` | `oidc` |
+| `JMAP_OIDC_ISSUER` | Yes | OIDC provider issuer URL | `https://sso.example.com` |
+| `JMAP_OIDC_CLIENT_ID` | Yes | OIDC client ID | `my-client-id` |
+| `JMAP_OIDC_SCOPE` | No | OIDC scopes | `openid profile email offline_access` |
+| `JMAP_OIDC_REDIRECT_URI` | No | Callback URI for OIDC flow | `http://localhost:5678/callback` |
+
+#### Optional
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `LOG_LEVEL` | Log verbosity: `fatal`, `error`, `warn`, `info`, `debug`, `trace` | `info` |
+| `JMAP_REQUEST_TIMEOUT` | Request timeout in milliseconds | `30000` |
+
+### Claude Desktop Configuration
+
+Add the following to your Claude Desktop configuration file:
+
+**Configuration file location:**
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+**Configuration (Basic Auth):**
+
+```json
+{
+  "mcpServers": {
+    "twake-mail": {
+      "command": "node",
+      "args": ["/path/to/mcp-twake-mail/build/index.js"],
+      "env": {
+        "JMAP_SESSION_URL": "https://jmap.example.com/jmap/session",
+        "JMAP_AUTH_METHOD": "basic",
+        "JMAP_USERNAME": "user@example.com",
+        "JMAP_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+**Configuration (OIDC):**
+
+```json
+{
+  "mcpServers": {
+    "twake-mail": {
+      "command": "node",
+      "args": ["/path/to/mcp-twake-mail/build/index.js"],
+      "env": {
+        "JMAP_SESSION_URL": "https://jmap.example.com/jmap/session",
+        "JMAP_AUTH_METHOD": "oidc",
+        "JMAP_OIDC_ISSUER": "https://sso.example.com",
+        "JMAP_OIDC_CLIENT_ID": "my-client-id",
+        "JMAP_OIDC_SCOPE": "openid profile email offline_access",
+        "JMAP_OIDC_REDIRECT_URI": "http://localhost:5678/callback"
+      }
+    }
+  }
+}
+```
+
+After updating the configuration, restart Claude Desktop for changes to take effect.
+
+## Usage Examples
+
+Once configured, you can ask Claude natural language questions about your email:
+
+**Email queries:**
+- "What are my unread emails?"
+- "Show me emails from Pierre"
+- "What's the latest email in my inbox?"
+- "Find emails about the budget meeting"
+- "Show the conversation thread for this email"
+
+**Email composition:**
+- "Send an email to pierre@example.com about the meeting tomorrow"
+- "Reply to this email thanking them for the information"
+- "Create a draft email to the team about the project update"
+
+**Email management:**
+- "Mark this email as read"
+- "Move this email to the Archive folder"
+- "Delete all spam emails"
+- "Add the 'Important' label to this email"
+
+**Attachments:**
+- "What attachments are in this email?"
+- "Download the PDF attachment"
+
+## Available Tools
+
+| Tool Name | Description |
+|-----------|-------------|
+| `list_emails` | List emails with optional filters (mailbox, limit, search) |
+| `get_email` | Get full email content by ID |
+| `search_emails` | Search emails by keywords |
+| `get_thread` | Get all emails in a thread |
+| `send_email` | Send a new email |
+| `reply_email` | Reply to an email with threading |
+| `create_draft` | Create a draft email |
+| `mark_as_read` | Mark email as read |
+| `mark_as_unread` | Mark email as unread |
+| `delete_email` | Delete or trash an email |
+| `move_email` | Move email to another mailbox |
+| `add_label` | Add mailbox/label to email |
+| `remove_label` | Remove mailbox/label from email |
+| `list_mailboxes` | List all mailboxes |
+| `get_attachments` | List attachment metadata |
+| `download_attachment` | Download attachment content |
+
+## Development
+
+```bash
+git clone https://github.com/linagora/mcp-twake-mail.git
+cd mcp-twake-mail
+npm install
+npm run build    # compile TypeScript
+npm test         # run tests
+npm run dev      # watch mode (auto-rebuild on file changes)
+```
+
+The server uses the MCP stdio transport and communicates via JSON-RPC on stdin/stdout.
+
+## Architecture
+
+mcp-twake-mail is built with a layered architecture:
+
+1. **Configuration Layer** - Zod-based environment variable validation with fail-fast behavior
+2. **Logging Layer** - Pino logger configured for stderr output (prevents stdout contamination in MCP stdio transport)
+3. **Authentication Layer** - Multi-method auth support (Basic, Bearer, OIDC with PKCE)
+4. **Token Management** - Automatic token refresh for OIDC with secure token storage
+5. **JMAP Client Layer** - Session management, request batching, blob download support
+6. **Transformation Layer** - Email/Mailbox data transformation for AI-friendly output
+7. **MCP Tool Layer** - 16 MCP tools exposing email functionality with tool annotations
+8. **Entry Point** - MCP server initialization with stdio transport
+
+**Key design decisions:**
+- ESM modules with `.js` import extensions (required by MCP SDK)
+- JMAP RFC 8620/8621 compliance for broad server compatibility
+- AI-friendly error formatting for troubleshooting
+- Large attachment handling (auto-save to disk for files > 750KB)
+- MCP tool annotations for AI clients (readOnlyHint, destructiveHint, idempotentHint)
+
+## License
+
+This project is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**.
+
+See the [LICENSE](LICENSE) file for details.
+
+**Copyright (c) 2026 LINAGORA** <https://linagora.com>
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on the development workflow, code style, and pull request process.
+
+## Support
+
+For issues, questions, or feature requests, please open an issue on the GitHub repository.
+
+For commercial support or inquiries, contact LINAGORA at <https://linagora.com>.

package/build/auth/index.d.ts

@@ -0,0 +1,3 @@
+export * from './token-store.js';
+export * from './token-refresh.js';
+export * from './oidc-flow.js';

package/build/auth/index.js

@@ -0,0 +1,4 @@
+export * from './token-store.js';
+export * from './token-refresh.js';
+export * from './oidc-flow.js';
+//# sourceMappingURL=index.js.map

package/build/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC"}

package/build/auth/oidc-flow.d.ts

@@ -0,0 +1,47 @@
+import { type StoredTokens } from './token-store.js';
+/**
+ * Options for performing OIDC authorization code flow with PKCE
+ */
+export interface OIDCFlowOptions {
+    /** OIDC issuer URL (e.g., https://auth.example.com) */
+    issuerUrl: string;
+    /** OAuth client ID registered with the OIDC provider */
+    clientId: string;
+    /** OAuth scopes to request (space-separated) */
+    scope: string;
+    /** Redirect URI (must be registered with the OIDC provider) */
+    redirectUri: string;
+    /** Local port for callback server (overrides port extracted from redirectUri) */
+    localPort?: number;
+}
+/**
+ * Perform OIDC authorization code flow with PKCE (S256)
+ *
+ * This function:
+ * 1. Discovers OIDC provider configuration
+ * 2. Generates PKCE code verifier and challenge (S256)
+ * 3. Builds authorization URL with PKCE
+ * 4. Opens browser for user authentication
+ * 5. Captures authorization code via localhost callback
+ * 6. Exchanges code for tokens
+ * 7. Saves tokens to secure storage
+ *
+ * @param options - OIDC flow configuration
+ * @returns Stored tokens after successful authentication
+ * @throws JMAPError on OIDC flow failures
+ */
+export declare function performOIDCFlow(options: OIDCFlowOptions): Promise<StoredTokens>;
+/**
+ * Helper to extract OIDC flow options from environment config
+ *
+ * @param config - Config object with OIDC fields
+ * @returns OIDCFlowOptions or null if OIDC is not configured
+ */
+export declare function getOIDCOptionsFromConfig(config: {
+    JMAP_AUTH_METHOD: string;
+    JMAP_OIDC_ISSUER?: string;
+    JMAP_OIDC_CLIENT_ID?: string;
+    JMAP_OIDC_SCOPE: string;
+    JMAP_OIDC_REDIRECT_URI: string;
+    JMAP_OIDC_LOCAL_PORT?: number;
+}): OIDCFlowOptions | null;

package/build/auth/oidc-flow.js

@@ -0,0 +1,146 @@
+import * as client from 'openid-client';
+import { getAuthCode } from 'oauth-callback';
+import open from 'open';
+import { saveTokens } from './token-store.js';
+import { JMAPError } from '../errors.js';
+/**
+ * Perform OIDC authorization code flow with PKCE (S256)
+ *
+ * This function:
+ * 1. Discovers OIDC provider configuration
+ * 2. Generates PKCE code verifier and challenge (S256)
+ * 3. Builds authorization URL with PKCE
+ * 4. Opens browser for user authentication
+ * 5. Captures authorization code via localhost callback
+ * 6. Exchanges code for tokens
+ * 7. Saves tokens to secure storage
+ *
+ * @param options - OIDC flow configuration
+ * @returns Stored tokens after successful authentication
+ * @throws JMAPError on OIDC flow failures
+ */
+export async function performOIDCFlow(options) {
+    const { issuerUrl, clientId, scope, redirectUri, localPort } = options;
+    // Parse redirect URI to extract port and path
+    const redirectUrl = new URL(redirectUri);
+    const isLocalhost = ['localhost', '127.0.0.1', '::1'].includes(redirectUrl.hostname);
+    // Determine callback port: explicit localPort > port from URI > defaults
+    let callbackPort;
+    if (localPort) {
+        // Explicit local port provided (useful for ngrok scenarios)
+        callbackPort = localPort;
+    }
+    else if (redirectUrl.port) {
+        // Explicit port in URI - use it
+        callbackPort = parseInt(redirectUrl.port, 10);
+    }
+    else if (isLocalhost) {
+        // Localhost without explicit port - use protocol default
+        callbackPort = redirectUrl.protocol === 'https:' ? 443 : 80;
+    }
+    else {
+        // Remote URL (ngrok, etc.) without explicit port - use default 3000
+        callbackPort = 3000;
+    }
+    // Extract callback path from redirect URI (default to /callback if no path)
+    const callbackPath = redirectUrl.pathname || '/callback';
+    // Step 1: OIDC Discovery
+    let config;
+    try {
+        config = await client.discovery(new URL(issuerUrl), clientId, undefined, // No client secret (public client with PKCE)
+        client.None() // Public client authentication
+        );
+    }
+    catch (error) {
+        throw JMAPError.oidcFlowError('discovery', error instanceof Error ? error.message : String(error));
+    }
+    // Step 2: Generate PKCE values (S256 - NEVER use plain)
+    const codeVerifier = client.randomPKCECodeVerifier();
+    const codeChallenge = await client.calculatePKCECodeChallenge(codeVerifier);
+    const state = client.randomState();
+    // Step 4: Build authorization URL with PKCE S256
+    const authParams = {
+        redirect_uri: redirectUri,
+        scope,
+        code_challenge: codeChallenge,
+        code_challenge_method: 'S256', // CRITICAL: Always S256, never plain (AUTH-04)
+        state,
+    };
+    const authorizationUrl = client.buildAuthorizationUrl(config, authParams);
+    // Step 5: Launch browser and capture callback
+    let authCode;
+    let returnedState;
+    try {
+        const result = await getAuthCode({
+            port: callbackPort,
+            callbackPath,
+            authorizationUrl: authorizationUrl.toString(),
+            launch: open,
+            timeout: 120000, // 2 minutes for user to complete auth
+        });
+        authCode = result.code;
+        // State can be in params (older oauth-callback) or directly on result (newer versions)
+        returnedState = result.params?.state ?? result.state;
+    }
+    catch (error) {
+        throw JMAPError.oidcFlowError('callback', error instanceof Error ? error.message : String(error));
+    }
+    // Step 6: Validate state to prevent CSRF attacks
+    if (returnedState !== state) {
+        throw JMAPError.oidcFlowError('state validation', 'State parameter mismatch. Possible CSRF attack.');
+    }
+    // Step 7: Exchange code for tokens
+    let tokenResponse;
+    try {
+        // Build callback URL with the authorization code for authorizationCodeGrant
+        const callbackUrl = new URL(redirectUri);
+        callbackUrl.searchParams.set('code', authCode);
+        callbackUrl.searchParams.set('state', state);
+        tokenResponse = await client.authorizationCodeGrant(config, callbackUrl, {
+            pkceCodeVerifier: codeVerifier,
+            expectedState: state,
+        });
+    }
+    catch (error) {
+        if (error instanceof client.AuthorizationResponseError) {
+            throw JMAPError.oidcFlowError('authorization', error.error_description || error.error);
+        }
+        if (error instanceof client.ResponseBodyError) {
+            throw JMAPError.oidcFlowError('token exchange', error.message);
+        }
+        throw JMAPError.oidcFlowError('token exchange', error instanceof Error ? error.message : String(error));
+    }
+    // Step 8: Build and save StoredTokens
+    const tokens = {
+        accessToken: tokenResponse.access_token,
+        refreshToken: tokenResponse.refresh_token,
+        idToken: tokenResponse.id_token,
+        expiresAt: tokenResponse.expires_in
+            ? Math.floor(Date.now() / 1000) + tokenResponse.expires_in
+            : undefined,
+    };
+    await saveTokens(tokens);
+    return tokens;
+}
+/**
+ * Helper to extract OIDC flow options from environment config
+ *
+ * @param config - Config object with OIDC fields
+ * @returns OIDCFlowOptions or null if OIDC is not configured
+ */
+export function getOIDCOptionsFromConfig(config) {
+    if (config.JMAP_AUTH_METHOD !== 'oidc') {
+        return null;
+    }
+    if (!config.JMAP_OIDC_ISSUER || !config.JMAP_OIDC_CLIENT_ID) {
+        return null;
+    }
+    return {
+        issuerUrl: config.JMAP_OIDC_ISSUER,
+        clientId: config.JMAP_OIDC_CLIENT_ID,
+        scope: config.JMAP_OIDC_SCOPE,
+        redirectUri: config.JMAP_OIDC_REDIRECT_URI,
+        localPort: config.JMAP_OIDC_LOCAL_PORT,
+    };
+}
+//# sourceMappingURL=oidc-flow.js.map

package/build/auth/oidc-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc-flow.js","sourceRoot":"","sources":["../../src/auth/oidc-flow.ts"],"names":[],"mappings":"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"}

package/build/auth/token-refresh.d.ts

@@ -0,0 +1,56 @@
+import * as client from 'openid-client';
+import type { StoredTokens } from './token-store.js';
+/**
+ * Refresh tokens 60 seconds before actual expiry
+ * This buffer ensures tokens are refreshed before they become invalid
+ */
+export declare const TOKEN_EXPIRY_BUFFER = 60;
+/**
+ * Token refresher with mutex for concurrent access safety
+ *
+ * When an MCP server handles multiple simultaneous requests, each may try
+ * to refresh the token if it's expiring soon. Without coordination, this
+ * causes "invalid_grant" errors. This class ensures only one refresh
+ * happens at a time and all callers get the fresh token.
+ */
+export declare class TokenRefresher {
+    private issuerUrl;
+    private clientId;
+    private refreshPromise;
+    private cachedConfig;
+    constructor(issuerUrl: string, clientId: string);
+    /**
+     * Get or create cached OIDC issuer configuration
+     */
+    getIssuerConfig(): Promise<client.Configuration>;
+    /**
+     * Check if token is valid (not expired or expiring soon)
+     * Returns false if token will expire within TOKEN_EXPIRY_BUFFER seconds
+     */
+    isTokenValid(tokens: StoredTokens): boolean;
+    /**
+     * Ensure we have a valid token, refreshing if necessary
+     *
+     * Uses a mutex pattern: if a refresh is already in progress,
+     * all callers wait for that same promise rather than starting
+     * parallel refresh requests.
+     */
+    ensureValidToken(): Promise<StoredTokens>;
+    /**
+     * Perform the actual token refresh
+     */
+    private doRefresh;
+    /**
+     * Clear cached configuration (useful for testing)
+     */
+    clearCache(): void;
+}
+/**
+ * Factory function to create a TokenRefresher instance
+ */
+export declare function createTokenRefresher(issuerUrl: string, clientId: string): TokenRefresher;
+/**
+ * Convenience function to ensure valid token with a new refresher
+ * For simple use cases that don't need to maintain refresher state
+ */
+export declare function ensureValidToken(issuerUrl: string, clientId: string): Promise<StoredTokens>;