@agentmailbox/mcp-auth 1.0.0

package/README.md

@@ -0,0 +1,75 @@
+# @agentmailbox/mcp-auth
+
+OAuth2 Client Credentials wrapper for MCP servers. Enables M2M (machine-to-machine) authentication with [AgentMailbox](https://agentmailbox.to).
+
+## Installation
+
+No installation required! Use `npx` to run directly:
+
+```bash
+npx @agentmailbox/mcp-auth <mcp-url> <token-endpoint> [scope]
+```
+
+## Usage with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "agentmail": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@agentmailbox/mcp-auth",
+        "https://mcp.agentmailbox.to/tenant/YOUR_TENANT/mailbox/YOUR_MAILBOX",
+        "https://auth.agentmailbox.to/oauth2/token",
+        "mcp-api/email.full"
+      ],
+      "env": {
+        "MCP_OAUTH_CLIENT_ID": "your-client-id",
+        "MCP_OAUTH_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+Replace:
+- `YOUR_TENANT` - Your AgentMailbox tenant codename (e.g., `peach`)
+- `YOUR_MAILBOX` - The mailbox username (e.g., `admin`)
+- `your-client-id` - Your OAuth2 Client ID from the credentials page
+- `your-client-secret` - Your OAuth2 Client Secret
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `mcp-url` | Yes | The MCP server URL |
+| `token-endpoint` | Yes | The OAuth2 token endpoint |
+| `scope` | No | OAuth2 scope (default: `mcp-api/email.full`) |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MCP_OAUTH_CLIENT_ID` | Yes | Your OAuth2 client ID |
+| `MCP_OAUTH_CLIENT_SECRET` | Yes | Your OAuth2 client secret |
+
+## How It Works
+
+1. Fetches an OAuth2 access token using the Client Credentials flow
+2. Passes the token to `@anthropic/mcp-remote` via environment variable
+3. Forwards all MCP communication to the AgentMailbox server
+
+## Requirements
+
+- Node.js 18 or later
+- `@anthropic/mcp-remote` (installed automatically via npx)
+
+## License
+
+MIT

package/index.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * @agentmailbox/mcp-auth
+ *
+ * OAuth2 Client Credentials wrapper for MCP servers.
+ * Handles M2M (machine-to-machine) authentication for AgentMailbox MCP endpoints.
+ *
+ * Usage with npx in claude_desktop_config.json:
+ * {
+ *   "mcpServers": {
+ *     "agentmail": {
+ *       "command": "npx",
+ *       "args": [
+ *         "-y",
+ *         "@agentmailbox/mcp-auth",
+ *         "https://mcp.agentmailbox.to/tenant/mytenant/mailbox/admin",
+ *         "https://auth.agentmailbox.to/oauth2/token",
+ *         "mcp-api/email.full"
+ *       ],
+ *       "env": {
+ *         "MCP_OAUTH_CLIENT_ID": "your-client-id",
+ *         "MCP_OAUTH_CLIENT_SECRET": "your-client-secret"
+ *       }
+ *     }
+ *   }
+ * }
+ */
+
+import { spawn } from 'child_process';
+
+// Default timeout for token requests (30 seconds)
+const TOKEN_TIMEOUT_MS = 30000;
+
+const [mcpUrl, tokenEndpoint, scope] = process.argv.slice(2);
+const clientId = process.env.MCP_OAUTH_CLIENT_ID;
+const clientSecret = process.env.MCP_OAUTH_CLIENT_SECRET;
+
+if (!mcpUrl || !tokenEndpoint || !clientId || !clientSecret) {
+  console.error('Usage: npx @agentmailbox/mcp-auth <mcp-url> <token-endpoint> [scope]');
+  console.error('');
+  console.error('Arguments:');
+  console.error('  mcp-url        The MCP server URL (e.g., https://mcp.agentmailbox.to/tenant/mytenant/mailbox/admin)');
+  console.error('  token-endpoint The OAuth2 token endpoint (e.g., https://auth.agentmailbox.to/oauth2/token)');
+  console.error('  scope          Optional OAuth2 scope (default: mcp-api/email.full)');
+  console.error('');
+  console.error('Environment variables required:');
+  console.error('  MCP_OAUTH_CLIENT_ID     Your OAuth2 client ID');
+  console.error('  MCP_OAUTH_CLIENT_SECRET Your OAuth2 client secret');
+  process.exit(1);
+}
+
+/**
+ * Build a minimal environment for the child process.
+ * Only passes through essential variables to avoid leaking secrets.
+ */
+function buildChildEnv(env) {
+  const allowList = [
+    // Essential for process execution
+    'PATH', 'HOME', 'USERPROFILE',
+    // Temp directories
+    'TMP', 'TEMP', 'TMPDIR',
+    // Windows-specific
+    'SystemRoot', 'ComSpec', 'WINDIR', 'PATHEXT',
+    // Proxy settings (important for corporate environments)
+    'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY',
+    'http_proxy', 'https_proxy', 'no_proxy',
+    // Node.js configuration
+    'NODE_EXTRA_CA_CERTS', 'NODE_OPTIONS',
+    // MCP-specific
+    'MCP_REMOTE_CONFIG_DIR',
+  ];
+
+  return Object.fromEntries(
+    allowList.flatMap((key) => (env[key] ? [[key, env[key]]] : []))
+  );
+}
+
+async function getAccessToken() {
+  const params = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: clientId,
+    client_secret: clientSecret,
+    scope: scope || 'mcp-api/email.full',
+  });
+
+  // Use AbortController for timeout
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), TOKEN_TIMEOUT_MS);
+
+  let response;
+  try {
+    response = await fetch(tokenEndpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: params.toString(),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    clearTimeout(timeoutId);
+    if (err.name === 'AbortError') {
+      throw new Error(`Token request timed out after ${TOKEN_TIMEOUT_MS}ms`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Token request failed: ${response.status} ${error}`);
+  }
+
+  const data = await response.json();
+  if (!data || typeof data.access_token !== 'string' || data.access_token.trim() === '') {
+    throw new Error('Missing or invalid access_token in token response');
+  }
+  return data.access_token;
+}
+
+async function main() {
+  try {
+    const token = await getAccessToken();
+
+    // Build minimal environment with only necessary variables, plus the token
+    const childEnv = buildChildEnv(process.env);
+    childEnv.AUTH_TOKEN = token;
+
+    // Launch @anthropic/mcp-remote with token passed via environment variable
+    const child = spawn('npx', [
+      '-y',
+      '@anthropic/mcp-remote',
+      mcpUrl,
+    ], {
+      stdio: 'inherit',
+      env: childEnv,
+    });
+
+    child.on('error', (err) => {
+      console.error('Failed to start @anthropic/mcp-remote:', err);
+      process.exit(1);
+    });
+
+    child.on('exit', (code, signal) => {
+      if (code !== null) {
+        process.exit(code);
+      } else if (signal !== null) {
+        // Child was terminated by signal - exit with non-zero
+        process.exit(128);
+      } else {
+        process.exit(0);
+      }
+    });
+
+    // Forward signals to child process for graceful shutdown
+    const forwardSignal = (sig) => {
+      if (child.pid) {
+        child.kill(sig);
+      }
+    };
+    process.on('SIGINT', () => forwardSignal('SIGINT'));
+    process.on('SIGTERM', () => forwardSignal('SIGTERM'));
+  } catch (err) {
+    console.error('Error:', err.message);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@agentmailbox/mcp-auth",
+  "version": "1.0.0",
+  "description": "OAuth2 Client Credentials wrapper for MCP servers - enables M2M authentication with AgentMailbox",
+  "type": "module",
+  "bin": {
+    "mcp-auth": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "oauth2",
+    "client-credentials",
+    "agentmailbox",
+    "claude",
+    "anthropic",
+    "m2m",
+    "machine-to-machine"
+  ],
+  "author": "AgentMailbox",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/compostableai/SES-deployment-in-AWS.git",
+    "directory": "mcp/mcp-auth"
+  },
+  "bugs": {
+    "url": "https://github.com/compostableai/SES-deployment-in-AWS/issues"
+  },
+  "homepage": "https://github.com/compostableai/SES-deployment-in-AWS/tree/main/mcp/mcp-auth#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@anthropic/mcp-remote": ">=0.1.0"
+  }
+}