@netpad/mcp-server-remote 1.4.2 → 1.5.0

package/api/authorize.ts

@@ -487,7 +487,7 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
         return;
       }
 
-      const userData = await response.json();
+      const userData = await response.json() as { userId?: string; user?: { id?: string }; organizationId?: string; organization?: { id?: string } };
       const userId = userData.userId || userData.user?.id || 'unknown';
       const organizationId = userData.organizationId || userData.organization?.id || 'unknown';
 

package/api/lib/metrics.ts

@@ -0,0 +1,208 @@
+/**
+ * MCP Server Metrics Collector
+ *
+ * Collects usage metrics from the MCP server and batches them for reporting
+ * to the NetPad API. Designed for Vercel serverless environment.
+ */
+
+// ============================================
+// Types
+// ============================================
+
+export interface MCPRequestMetric {
+  timestamp: number;
+  organizationId?: string;
+  userId?: string;
+  method: 'GET' | 'POST';
+  tool?: string;
+  authMethod: 'oauth' | 'api_key' | 'none';
+  authSuccess: boolean;
+  durationMs: number;
+  statusCode: number;
+  errorCode?: string;
+  sessionId?: string;
+}
+
+export interface MCPMetricsBatch {
+  serverVersion: string;
+  environment: string;
+  collectedAt: number;
+  metrics: MCPRequestMetric[];
+}
+
+// ============================================
+// Configuration
+// ============================================
+
+// In serverless environments, flush more aggressively since memory is ephemeral
+const BATCH_SIZE = 10; // Reduced from 50 for serverless
+const FLUSH_INTERVAL_MS = 10000; // 10 seconds (reduced from 30)
+
+// In-memory buffer for metrics (serverless-friendly)
+let metricsBuffer: MCPRequestMetric[] = [];
+let lastFlushTime = Date.now();
+
+/**
+ * Get the NetPad API base URL
+ */
+function getNetPadApiUrl(): string {
+  return process.env.NETPAD_API_URL || 'https://www.netpad.io';
+}
+
+/**
+ * Get MCP server version from package or environment
+ */
+function getServerVersion(): string {
+  return process.env.MCP_SERVER_VERSION || '1.4.2';
+}
+
+/**
+ * Get environment (production, staging, development)
+ */
+function getEnvironment(): string {
+  return process.env.VERCEL_ENV || process.env.NODE_ENV || 'development';
+}
+
+// ============================================
+// Metrics Collection
+// ============================================
+
+/**
+ * Record a single MCP request metric
+ */
+export function recordMetric(metric: Omit<MCPRequestMetric, 'timestamp'>): void {
+  const fullMetric: MCPRequestMetric = {
+    ...metric,
+    timestamp: Date.now(),
+  };
+
+  metricsBuffer.push(fullMetric);
+  console.log('[Metrics] Recorded:', {
+    method: metric.method,
+    tool: metric.tool,
+    authMethod: metric.authMethod,
+    durationMs: metric.durationMs,
+    statusCode: metric.statusCode,
+  });
+
+  // Check if we should flush
+  if (metricsBuffer.length >= BATCH_SIZE) {
+    flushMetrics().catch((err) => {
+      console.error('[Metrics] Flush error:', err);
+    });
+  }
+}
+
+/**
+ * Create a metrics context for timing a request
+ */
+export function startMetricsContext(): { startTime: number } {
+  return { startTime: Date.now() };
+}
+
+/**
+ * Calculate duration from metrics context
+ */
+export function getDuration(context: { startTime: number }): number {
+  return Date.now() - context.startTime;
+}
+
+// ============================================
+// Metrics Flushing
+// ============================================
+
+/**
+ * Flush accumulated metrics to the NetPad API
+ */
+export async function flushMetrics(): Promise<void> {
+  if (metricsBuffer.length === 0) {
+    return;
+  }
+
+  // Swap buffer to avoid race conditions
+  const metricsToFlush = metricsBuffer;
+  metricsBuffer = [];
+  lastFlushTime = Date.now();
+
+  const batch: MCPMetricsBatch = {
+    serverVersion: getServerVersion(),
+    environment: getEnvironment(),
+    collectedAt: Date.now(),
+    metrics: metricsToFlush,
+  };
+
+  try {
+    const netpadUrl = getNetPadApiUrl();
+    const response = await fetch(`${netpadUrl}/api/v1/mcp-metrics`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-MCP-Server-Version': getServerVersion(),
+      },
+      body: JSON.stringify(batch),
+    });
+
+    if (!response.ok) {
+      // Put metrics back on failure (at the front)
+      metricsBuffer = [...metricsToFlush, ...metricsBuffer];
+      console.error('[Metrics] Failed to flush:', response.status, await response.text());
+    } else {
+      console.log('[Metrics] Flushed', metricsToFlush.length, 'metrics');
+    }
+  } catch (error) {
+    // Put metrics back on network error
+    metricsBuffer = [...metricsToFlush, ...metricsBuffer];
+    console.error('[Metrics] Network error during flush:', error);
+  }
+}
+
+/**
+ * Force flush all metrics (useful before process exit)
+ */
+export async function forceFlush(): Promise<void> {
+  await flushMetrics();
+}
+
+// ============================================
+// Helper Functions
+// ============================================
+
+/**
+ * Extract tool name from JSON-RPC request body
+ */
+export function extractToolFromBody(body: unknown): string | undefined {
+  if (!body || typeof body !== 'object') {
+    return undefined;
+  }
+
+  const request = body as Record<string, unknown>;
+
+  // JSON-RPC format: { method: 'tools/call', params: { name: 'tool_name' } }
+  if (request.method === 'tools/call' && request.params && typeof request.params === 'object') {
+    const params = request.params as Record<string, unknown>;
+    if (typeof params.name === 'string') {
+      return params.name;
+    }
+  }
+
+  // Also check for direct method calls
+  if (typeof request.method === 'string' && request.method !== 'tools/call') {
+    return request.method;
+  }
+
+  return undefined;
+}
+
+/**
+ * Get buffered metrics count (for testing/debugging)
+ */
+export function getBufferedMetricsCount(): number {
+  return metricsBuffer.length;
+}
+
+/**
+ * Get time since last flush (for testing/debugging)
+ */
+export function getTimeSinceLastFlush(): number {
+  return Date.now() - lastFlushTime;
+}

package/api/lib/oauth.ts

@@ -376,36 +376,100 @@ export function exchangeRefreshToken(refreshToken: string): {
 // CLIENT VALIDATION
 // ============================================================================
 
+/**
+ * Check if a string is a valid HTTPS URL (for Client ID Metadata Documents)
+ */
+function isHttpsUrl(str: string): boolean {
+  try {
+    const url = new URL(str);
+    return url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Validate OAuth client and redirect URI
+ *
+ * Supports:
+ * 1. Pre-registered clients (e.g., 'netpad')
+ * 2. Client ID Metadata Documents (HTTPS URLs as client_id per MCP spec)
  */
 export function validateClient(
   clientId: string,
   redirectUri: string
-): { valid: boolean; error?: string } {
+): { valid: boolean; error?: string; isMetadataDocument?: boolean } {
+  // First check pre-registered clients
   const client = OAUTH_CONFIG.allowedClients[clientId as keyof typeof OAUTH_CONFIG.allowedClients];
 
-  if (!client) {
-    return { valid: false, error: 'invalid_client' };
+  if (client) {
+    if (!client.redirectUris.includes(redirectUri)) {
+      return { valid: false, error: 'invalid_redirect_uri' };
+    }
+    return { valid: true, isMetadataDocument: false };
   }
 
-  if (!client.redirectUris.includes(redirectUri)) {
-    return { valid: false, error: 'invalid_redirect_uri' };
+  // Check if client_id is a URL (Client ID Metadata Document)
+  // Per MCP spec, we accept HTTPS URLs as client_id
+  if (isHttpsUrl(clientId)) {
+    // For Client ID Metadata Documents, we validate:
+    // 1. The redirect_uri should be localhost or HTTPS
+    // 2. The client_id URL must have a path component
+
+    try {
+      const clientUrl = new URL(clientId);
+      // Per spec: client_id URL MUST contain a path component
+      if (!clientUrl.pathname || clientUrl.pathname === '/') {
+        console.log('[OAuth] Client ID Metadata Document URL must have a path component');
+        return { valid: false, error: 'invalid_client' };
+      }
+
+      const redirectUrl = new URL(redirectUri);
+      const isLocalhost = redirectUrl.hostname === 'localhost' ||
+                          redirectUrl.hostname === '127.0.0.1' ||
+                          redirectUrl.hostname === '[::1]';
+      const isHttps = redirectUrl.protocol === 'https:';
+
+      if (!isLocalhost && !isHttps) {
+        console.log('[OAuth] Redirect URI must be localhost or HTTPS');
+        return { valid: false, error: 'invalid_redirect_uri' };
+      }
+
+      // Accept the client - full validation of redirect_uri against the
+      // metadata document would require fetching it (async), which we'll do
+      // in the authorize endpoint if needed
+      console.log('[OAuth] Accepting Client ID Metadata Document:', clientId);
+      return { valid: true, isMetadataDocument: true };
+    } catch {
+      return { valid: false, error: 'invalid_redirect_uri' };
+    }
   }
 
-  return { valid: true };
+  return { valid: false, error: 'invalid_client' };
 }
 
 /**
  * Validate requested scopes
+ *
+ * For Client ID Metadata Documents, we accept all supported scopes
  */
 export function validateScopes(requestedScopes: string, clientId: string): string[] {
   const client = OAUTH_CONFIG.allowedClients[clientId as keyof typeof OAUTH_CONFIG.allowedClients];
-  if (!client) return [];
 
-  const requested = requestedScopes.split(' ').filter(Boolean);
-  const allowed = requested.filter(scope => client.scopes.includes(scope));
+  // For pre-registered clients, filter to allowed scopes
+  if (client) {
+    const requested = requestedScopes.split(' ').filter(Boolean);
+    const allowed = requested.filter(scope => client.scopes.includes(scope));
+    return allowed.length > 0 ? allowed : ['mcp'];
+  }
+
+  // For Client ID Metadata Documents (URL-based client_id), accept all supported scopes
+  if (isHttpsUrl(clientId)) {
+    const requested = requestedScopes.split(' ').filter(Boolean);
+    const allScopes = Object.keys(OAUTH_CONFIG.scopes);
+    const allowed = requested.filter(scope => allScopes.includes(scope));
+    return allowed.length > 0 ? allowed : ['mcp'];
+  }
 
-  // Default to 'mcp' if no valid scopes
-  return allowed.length > 0 ? allowed : ['mcp'];
+  return ['mcp'];
 }

package/api/mcp.ts

@@ -3,6 +3,13 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { IncomingMessage, ServerResponse } from 'node:http';
 import { createNetPadMcpServer } from '@netpad/mcp-server';
 import { validateAccessToken } from './lib/oauth.js';
+import {
+  recordMetric,
+  startMetricsContext,
+  getDuration,
+  extractToolFromBody,
+  flushMetrics,
+} from './lib/metrics.js';
 
 // Store transports by session ID for reconnection
 const transports = new Map<string, StreamableHTTPServerTransport>();
@@ -168,7 +175,7 @@ async function validateApiKey(apiKey: string): Promise<AuthResult> {
     });
 
     if (response.ok) {
-      const data = await response.json();
+      const data = await response.json() as { userId?: string; organizationId?: string };
       // Cache the valid result
       apiKeyCache.set(apiKey, {
         valid: true,
@@ -189,7 +196,7 @@ async function validateApiKey(apiKey: string): Promise<AuthResult> {
     });
 
     // Parse error response
-    const errorData = await response.json().catch(() => ({}));
+    const errorData = await response.json().catch(() => ({})) as { error?: { message?: string; code?: string } };
     return {
       valid: false,
       error: {
@@ -211,6 +218,8 @@ async function validateApiKey(apiKey: string): Promise<AuthResult> {
 
 // Main handler
 export default async function handler(req: VercelRequest, res: VercelResponse) {
+  const metricsContext = startMetricsContext();
+
   // Handle CORS preflight
   if (req.method === 'OPTIONS') {
     res.status(200).end();
@@ -222,6 +231,26 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
   // ============================================================================
   const authResult = await validateRequest(req);
   if (!authResult.valid) {
+    // Record failed auth metric
+    recordMetric({
+      method: req.method as 'GET' | 'POST',
+      authMethod: 'none',
+      authSuccess: false,
+      durationMs: getDuration(metricsContext),
+      statusCode: authResult.error?.status || 401,
+      errorCode: authResult.error?.code,
+    });
+
+    // Flush metrics (serverless: memory is ephemeral)
+    flushMetrics().catch(() => {});
+
+    // Per MCP spec and RFC 9728, include WWW-Authenticate header with resource_metadata
+    // This tells OAuth clients where to find the authorization server
+    const resourceMetadataUrl = 'https://mcp.netpad.io/.well-known/oauth-protected-resource';
+    res.setHeader(
+      'WWW-Authenticate',
+      `Bearer resource_metadata="${resourceMetadataUrl}", scope="mcp read write"`
+    );
     res.status(authResult.error?.status || 401).json({
       error: authResult.error?.error || 'Authentication failed',
       code: authResult.error?.code || 'AUTH_FAILED',
@@ -230,6 +259,11 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
     return;
   }
 
+  // Determine auth method for metrics
+  const authHeader = req.headers['authorization'] || '';
+  const token = authHeader.split(' ')[1] || '';
+  const authMethod: 'oauth' | 'api_key' = token.includes('.') ? 'oauth' : 'api_key';
+
   // Get session ID from headers
   const sessionId = req.headers['mcp-session-id'] as string | undefined;
 
@@ -252,6 +286,21 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
       transports.set(transport.sessionId, transport);
     }
 
+    // Record successful SSE connection metric
+    recordMetric({
+      method: 'GET',
+      organizationId: authResult.organizationId,
+      userId: authResult.userId,
+      authMethod,
+      authSuccess: true,
+      durationMs: getDuration(metricsContext),
+      statusCode: 200,
+      sessionId: transport.sessionId,
+    });
+
+    // Flush metrics (serverless: memory is ephemeral)
+    flushMetrics().catch(() => {});
+
     await transport.handleRequest(
       req as unknown as IncomingMessage,
       res as unknown as ServerResponse
@@ -261,6 +310,9 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
 
   // Handle POST requests
   if (req.method === 'POST') {
+    // Extract tool name from request body for metrics
+    const tool = extractToolFromBody(req.body);
+
     // Try to reuse existing transport for this session
     let transport = sessionId ? transports.get(sessionId) : undefined;
 
@@ -287,9 +339,34 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
       res as unknown as ServerResponse,
       req.body
     );
+
+    // Record POST request metric
+    recordMetric({
+      method: 'POST',
+      organizationId: authResult.organizationId,
+      userId: authResult.userId,
+      tool,
+      authMethod,
+      authSuccess: true,
+      durationMs: getDuration(metricsContext),
+      statusCode: 200,
+      sessionId: sessionId || transport.sessionId,
+    });
+
+    // Opportunistically flush metrics (non-blocking)
+    flushMetrics().catch(() => {});
     return;
   }
 
   // Method not allowed
+  recordMetric({
+    method: req.method as 'GET' | 'POST',
+    authMethod,
+    authSuccess: true,
+    durationMs: getDuration(metricsContext),
+    statusCode: 405,
+    errorCode: 'METHOD_NOT_ALLOWED',
+  });
+  flushMetrics().catch(() => {});
   res.status(405).json({ error: 'Method not allowed' });
 }

package/api/oauth-metadata.ts

@@ -50,6 +50,10 @@ export default function handler(req: VercelRequest, res: VercelResponse) {
     // OPTIONAL: PKCE code challenge methods (RFC 7636)
     code_challenge_methods_supported: ['S256', 'plain'],
 
+    // MCP REQUIRED: Support for Client ID Metadata Documents
+    // This allows Claude.ai to use its hosted client metadata
+    client_id_metadata_document_supported: true,
+
     // OPTIONAL: Service documentation
     service_documentation: 'https://docs.netpad.io/docs/developer/mcp-server',
 

package/api/token.ts

@@ -18,8 +18,11 @@ import {
   generateRefreshToken,
   exchangeRefreshToken,
 } from './lib/oauth.js';
+import { recordMetric, startMetricsContext, getDuration } from './lib/metrics.js';
 
 export default async function handler(req: VercelRequest, res: VercelResponse) {
+  const metricsContext = startMetricsContext();
+
   // Set CORS headers for token endpoint
   res.setHeader('Access-Control-Allow-Origin', '*');
   res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
@@ -35,6 +38,15 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
 
   // Only POST is allowed
   if (req.method !== 'POST') {
+    recordMetric({
+      method: req.method as 'GET' | 'POST',
+      tool: 'oauth/token',
+      authMethod: 'none',
+      authSuccess: false,
+      durationMs: getDuration(metricsContext),
+      statusCode: 405,
+      errorCode: 'METHOD_NOT_ALLOWED',
+    });
     res.status(405).json({ error: 'method_not_allowed' });
     return;
   }
@@ -159,6 +171,18 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
       scope: authCode.scope,
     });
 
+    // Record successful token exchange
+    recordMetric({
+      method: 'POST',
+      organizationId: authCode.organizationId,
+      userId: authCode.userId,
+      tool: 'oauth/token/authorization_code',
+      authMethod: 'oauth',
+      authSuccess: true,
+      durationMs: getDuration(metricsContext),
+      statusCode: 200,
+    });
+
     // Return token response
     console.log('[Token] SUCCESS - returning tokens');
     res.status(200).json({
@@ -193,6 +217,16 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
       return;
     }
 
+    // Record successful refresh token exchange
+    recordMetric({
+      method: 'POST',
+      tool: 'oauth/token/refresh',
+      authMethod: 'oauth',
+      authSuccess: true,
+      durationMs: getDuration(metricsContext),
+      statusCode: 200,
+    });
+
     res.status(200).json({
       access_token: newTokens.accessToken,
       token_type: 'Bearer',
@@ -206,6 +240,15 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
   // ============================================================================
   // Unsupported Grant Type
   // ============================================================================
+  recordMetric({
+    method: 'POST',
+    tool: 'oauth/token',
+    authMethod: 'none',
+    authSuccess: false,
+    durationMs: getDuration(metricsContext),
+    statusCode: 400,
+    errorCode: 'UNSUPPORTED_GRANT_TYPE',
+  });
   res.status(400).json({
     error: 'unsupported_grant_type',
     error_description: 'Only authorization_code and refresh_token grants are supported',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netpad/mcp-server-remote",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Remote MCP server for NetPad - deployable to Vercel for Claude custom connectors. Includes all 80+ tools from @netpad/mcp-server.",
   "author": "Michael Lynn",
   "license": "Apache-2.0",
@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@netpad/mcp-server": "^2.3.0",
+    "@netpad/mcp-server": "^2.4.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {