@uteamup/mcp-server 1.0.0-beta.7 → 1.0.0-beta.8

package/README.md

@@ -6,6 +6,13 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
 
+## Links
+
+- **📦 [npm Package](https://www.npmjs.com/package/@uteamup/mcp-server)** - Install with `npx -y @uteamup/mcp-server`
+- **📖 [Documentation](https://docs.uteamup.com/mcp)** - Full MCP integration guide
+- **🐛 [Issues](https://github.com/uteamup/mcp-server/issues)** - Report bugs and request features
+- **💬 [Support](mailto:support@uteamup.com)** - Get help
+
 ## What is this?
 
 This package enables AI assistants like Claude Desktop and Claude Code to connect to your UteamUP CMMS system using the Model Context Protocol (MCP). It handles OAuth 2.0 authentication automatically, so you can manage work orders, assets, inventory, and more through natural conversation.

package/index.js

@@ -2,7 +2,7 @@
 
 /**
  * UteamUP MCP Proxy - Production-ready OAuth handler with enhanced debugging
- * Version: 1.0.0-beta.7
+ * Version: 1.0.0-beta.8
  *
  * Features:
  * - OAuth 2.0 Authorization Code + PKCE authentication
@@ -22,7 +22,7 @@ const { startTimer, recordOAuthAttempt, recordRequest, recordCacheHit, recordCac
 const { retryWithBackoff } = require('./lib/retry');
 
 // Package version
-const VERSION = '1.0.0-beta.7';
+const VERSION = '1.0.0-beta.8';
 
 // CLI argument handling
 const args = process.argv.slice(2);

package/lib/config.js

@@ -0,0 +1,161 @@
+/**
+ * Configuration validation using Zod
+ * Validates environment variables and provides type-safe configuration
+ */
+
+const { z } = require('zod');
+
+// Configuration schema
+const configSchema = z.object({
+  // Required credentials
+  apiKey: z.string()
+    .length(32, 'API Key must be exactly 32 characters')
+    .describe('MCP-enabled API key from UteamUP'),
+
+  secret: z.string()
+    .min(64, 'Secret must be at least 64 characters')
+    .describe('API key secret from UteamUP'),
+
+  // Optional configuration
+  baseUrl: z.string()
+    .url('Base URL must be a valid URL')
+    .default('https://api.uteamup.com')
+    .describe('API endpoint URL'),
+
+  // Logging configuration
+  logLevel: z.enum(['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR'])
+    .default('INFO')
+    .describe('Logging level'),
+
+  logFormat: z.enum(['text', 'json'])
+    .default('text')
+    .describe('Log output format'),
+
+  // Legacy debug flag (for backward compatibility)
+  debug: z.boolean()
+    .default(false)
+    .describe('Legacy debug mode'),
+
+  // Request configuration
+  requestTimeout: z.number()
+    .int()
+    .min(1000)
+    .max(300000) // 5 minutes max
+    .default(30000)
+    .describe('Request timeout in milliseconds'),
+
+  maxRetries: z.number()
+    .int()
+    .min(0)
+    .max(10)
+    .default(3)
+    .describe('Maximum retry attempts for network errors'),
+
+  // Token management
+  tokenCacheDir: z.string()
+    .optional()
+    .describe('Optional persistent token cache directory'),
+
+  tokenRefreshMargin: z.number()
+    .int()
+    .min(0)
+    .max(3600) // 1 hour max
+    .default(300) // 5 minutes
+    .describe('Token refresh margin in seconds')
+});
+
+/**
+ * Loads and validates configuration from environment variables
+ * @returns {object} Validated configuration object
+ * @throws {Error} If configuration is invalid
+ */
+function loadConfig() {
+  // Parse environment variables
+  const rawConfig = {
+    apiKey: process.env.UTEAMUP_API_KEY,
+    secret: process.env.UTEAMUP_SECRET,
+    baseUrl: process.env.UTEAMUP_API_BASE_URL || 'https://api.uteamup.com',
+    logLevel: (process.env.UTEAMUP_LOG_LEVEL || 'INFO').toUpperCase(),
+    logFormat: (process.env.UTEAMUP_LOG_FORMAT || 'text').toLowerCase(),
+    debug: process.env.UTEAMUP_DEBUG === '1' || process.env.UTEAMUP_DEBUG === 'true',
+    requestTimeout: parseInt(process.env.UTEAMUP_REQUEST_TIMEOUT || '30000', 10),
+    maxRetries: parseInt(process.env.UTEAMUP_MAX_RETRIES || '3', 10),
+    tokenCacheDir: process.env.UTEAMUP_TOKEN_CACHE_DIR,
+    tokenRefreshMargin: parseInt(process.env.UTEAMUP_TOKEN_REFRESH_MARGIN || '300', 10)
+  };
+
+  // If debug mode is enabled, upgrade log level to DEBUG
+  if (rawConfig.debug && rawConfig.logLevel === 'INFO') {
+    rawConfig.logLevel = 'DEBUG';
+  }
+
+  try {
+    // Validate configuration
+    const config = configSchema.parse(rawConfig);
+    return config;
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      // Format validation errors nicely
+      const errors = error.errors.map(err => {
+        const path = err.path.join('.');
+        return `  - ${path}: ${err.message}`;
+      });
+
+      throw new Error(
+        'Configuration validation failed:\n' +
+        errors.join('\n') +
+        '\n\nRequired environment variables:\n' +
+        '  UTEAMUP_API_KEY    - Your MCP-enabled API key (32 characters)\n' +
+        '  UTEAMUP_SECRET     - Your API key secret (64+ characters)\n\n' +
+        'Optional environment variables:\n' +
+        '  UTEAMUP_API_BASE_URL        - API endpoint (default: https://api.uteamup.com)\n' +
+        '  UTEAMUP_LOG_LEVEL           - Log level (default: INFO)\n' +
+        '  UTEAMUP_LOG_FORMAT          - Log format (default: text)\n' +
+        '  UTEAMUP_DEBUG               - Enable debug mode (1 or true)\n' +
+        '  UTEAMUP_REQUEST_TIMEOUT     - Request timeout in ms (default: 30000)\n' +
+        '  UTEAMUP_MAX_RETRIES         - Max retry attempts (default: 3)\n' +
+        '  UTEAMUP_TOKEN_CACHE_DIR     - Persistent token cache directory\n' +
+        '  UTEAMUP_TOKEN_REFRESH_MARGIN - Token refresh margin in seconds (default: 300)'
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Validates configuration without throwing (returns validation result)
+ * @returns {{success: boolean, config?: object, error?: string}} Validation result
+ */
+function validateConfig() {
+  try {
+    const config = loadConfig();
+    return { success: true, config };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Prints configuration summary (with secrets redacted)
+ * @param {object} config - Configuration object
+ */
+function printConfigSummary(config) {
+  console.error('[MCP Proxy] Configuration:');
+  console.error(`  Base URL: ${config.baseUrl}`);
+  console.error(`  API Key: ${config.apiKey.substring(0, 8)}...`);
+  console.error(`  Log Level: ${config.logLevel}`);
+  console.error(`  Log Format: ${config.logFormat}`);
+  console.error(`  Request Timeout: ${config.requestTimeout}ms`);
+  console.error(`  Max Retries: ${config.maxRetries}`);
+  console.error(`  Token Refresh Margin: ${config.tokenRefreshMargin}s`);
+  if (config.tokenCacheDir) {
+    console.error(`  Token Cache Dir: ${config.tokenCacheDir}`);
+  }
+}
+
+module.exports = {
+  loadConfig,
+  validateConfig,
+  printConfigSummary,
+  configSchema
+};

package/lib/logger.js

@@ -0,0 +1,170 @@
+/**
+ * Structured logging module using Pino
+ * Provides production-ready logging with levels, formatting, and redaction
+ */
+
+const pino = require('pino');
+
+// Log levels mapping
+const LOG_LEVELS = {
+  TRACE: 10,
+  DEBUG: 20,
+  INFO: 30,
+  WARN: 40,
+  ERROR: 50
+};
+
+// Get log level from environment (default: INFO)
+const logLevel = process.env.UTEAMUP_LOG_LEVEL?.toUpperCase() || 'INFO';
+const logFormat = process.env.UTEAMUP_LOG_FORMAT?.toLowerCase() || 'text';
+
+// Legacy UTEAMUP_DEBUG support (maps to DEBUG level)
+const effectiveLevel = process.env.UTEAMUP_DEBUG === '1' || process.env.UTEAMUP_DEBUG === 'true'
+  ? 'DEBUG'
+  : logLevel;
+
+// Pino configuration
+const pinoOptions = {
+  level: (LOG_LEVELS[effectiveLevel] !== undefined ? effectiveLevel : 'INFO').toLowerCase(),
+  // Use stderr for all logs (stdout reserved for JSON-RPC protocol)
+  browser: { write: (msg) => process.stderr.write(msg) },
+
+  // Redact sensitive fields
+  redact: {
+    paths: [
+      'Authorization',
+      'client_secret',
+      'code_verifier',
+      'access_token',
+      'accessToken',
+      'bearer',
+      '*.Authorization',
+      '*.client_secret',
+      '*.code_verifier',
+      '*.access_token',
+      '*.accessToken'
+    ],
+    remove: true
+  },
+
+  // Production: JSON format, Development: pretty-printed
+  transport: logFormat === 'json' || process.env.NODE_ENV === 'production'
+    ? undefined
+    : {
+        target: 'pino-pretty',
+        options: {
+          colorize: true,
+          translateTime: 'HH:MM:ss.l',
+          ignore: 'pid,hostname',
+          messageFormat: '[MCP Proxy] {msg}'
+        }
+      }
+};
+
+// Create logger instance
+const logger = pino(pinoOptions, pino.destination({ dest: 2 })); // 2 = stderr
+
+/**
+ * Redacts sensitive information from objects for logging
+ * @param {any} data - Data to redact
+ * @returns {any} Redacted data
+ */
+function redactSensitive(data) {
+  if (!data) return data;
+  if (typeof data !== 'object') return data;
+
+  const sensitiveKeys = [
+    'authorization',
+    'client_secret',
+    'code_verifier',
+    'access_token',
+    'accesstoken',
+    'bearer',
+    'password',
+    'secret'
+  ];
+
+  const redacted = Array.isArray(data) ? [...data] : { ...data };
+
+  for (const key in redacted) {
+    const lowerKey = key.toLowerCase();
+
+    if (sensitiveKeys.some(sk => lowerKey.includes(sk))) {
+      redacted[key] = '[REDACTED]';
+    } else if (typeof redacted[key] === 'object' && redacted[key] !== null) {
+      redacted[key] = redactSensitive(redacted[key]);
+    }
+  }
+
+  return redacted;
+}
+
+/**
+ * Creates a child logger with additional context
+ * @param {object} context - Context to add to all logs
+ * @returns {object} Child logger
+ */
+function createChildLogger(context) {
+  return logger.child(context);
+}
+
+/**
+ * Trace-level logging (most verbose)
+ * @param {string} message - Log message
+ * @param {object} context - Additional context
+ */
+function trace(message, context = {}) {
+  logger.trace(redactSensitive(context), message);
+}
+
+/**
+ * Debug-level logging
+ * @param {string} message - Log message
+ * @param {object} context - Additional context
+ */
+function debug(message, context = {}) {
+  logger.debug(redactSensitive(context), message);
+}
+
+/**
+ * Info-level logging
+ * @param {string} message - Log message
+ * @param {object} context - Additional context
+ */
+function info(message, context = {}) {
+  logger.info(redactSensitive(context), message);
+}
+
+/**
+ * Warning-level logging
+ * @param {string} message - Log message
+ * @param {object} context - Additional context
+ */
+function warn(message, context = {}) {
+  logger.warn(redactSensitive(context), message);
+}
+
+/**
+ * Error-level logging
+ * @param {string} message - Log message
+ * @param {object|Error} contextOrError - Additional context or Error object
+ */
+function error(message, contextOrError = {}) {
+  if (contextOrError instanceof Error) {
+    logger.error({ err: contextOrError }, message);
+  } else {
+    logger.error(redactSensitive(contextOrError), message);
+  }
+}
+
+module.exports = {
+  logger,
+  createChildLogger,
+  redactSensitive,
+  trace,
+  debug,
+  info,
+  warn,
+  error,
+  LOG_LEVELS
+};

package/lib/metrics.js

@@ -0,0 +1,201 @@
+/**
+ * Performance monitoring and metrics tracking
+ * Tracks timing, cache hits/misses, and other performance metrics
+ */
+
+const { debug, info } = require('./logger');
+
+// In-memory metrics storage
+const metrics = {
+  oauth: {
+    totalAttempts: 0,
+    successCount: 0,
+    failureCount: 0,
+    totalDurationMs: 0,
+    avgDurationMs: 0
+  },
+  requests: {
+    totalCount: 0,
+    successCount: 0,
+    errorCount: 0,
+    totalDurationMs: 0,
+    avgDurationMs: 0
+  },
+  tokenCache: {
+    hits: 0,
+    misses: 0,
+    hitRate: 0
+  }
+};
+
+/**
+ * Starts a timer and returns a function to stop it
+ * @param {string} label - Timer label for logging
+ * @returns {Function} Function to stop the timer and return elapsed time
+ */
+function startTimer(label) {
+  const startTime = Date.now();
+
+  return function stopTimer() {
+    const elapsed = Date.now() - startTime;
+    debug(`Timer [${label}] completed`, { durationMs: elapsed });
+    return elapsed;
+  };
+}
+
+/**
+ * Records OAuth flow metrics
+ * @param {boolean} success - Whether OAuth succeeded
+ * @param {number} durationMs - Duration in milliseconds
+ */
+function recordOAuthAttempt(success, durationMs) {
+  metrics.oauth.totalAttempts++;
+
+  if (success) {
+    metrics.oauth.successCount++;
+  } else {
+    metrics.oauth.failureCount++;
+  }
+
+  metrics.oauth.totalDurationMs += durationMs;
+  metrics.oauth.avgDurationMs = Math.round(
+    metrics.oauth.totalDurationMs / metrics.oauth.totalAttempts
+  );
+
+  info('OAuth attempt recorded', {
+    success,
+    durationMs,
+    avgDurationMs: metrics.oauth.avgDurationMs,
+    successRate: (metrics.oauth.successCount / metrics.oauth.totalAttempts * 100).toFixed(2) + '%'
+  });
+}
+
+/**
+ * Records MCP request metrics
+ * @param {boolean} success - Whether request succeeded
+ * @param {number} durationMs - Duration in milliseconds
+ * @param {string} method - Request method
+ */
+function recordRequest(success, durationMs, method) {
+  metrics.requests.totalCount++;
+
+  if (success) {
+    metrics.requests.successCount++;
+  } else {
+    metrics.requests.errorCount++;
+  }
+
+  metrics.requests.totalDurationMs += durationMs;
+  metrics.requests.avgDurationMs = Math.round(
+    metrics.requests.totalDurationMs / metrics.requests.totalCount
+  );
+
+  debug('Request recorded', {
+    method,
+    success,
+    durationMs,
+    avgDurationMs: metrics.requests.avgDurationMs,
+    successRate: (metrics.requests.successCount / metrics.requests.totalCount * 100).toFixed(2) + '%'
+  });
+}
+
+/**
+ * Records token cache hit
+ */
+function recordCacheHit() {
+  metrics.tokenCache.hits++;
+  updateCacheHitRate();
+  debug('Token cache hit', {
+    hits: metrics.tokenCache.hits,
+    hitRate: metrics.tokenCache.hitRate
+  });
+}
+
+/**
+ * Records token cache miss
+ */
+function recordCacheMiss() {
+  metrics.tokenCache.misses++;
+  updateCacheHitRate();
+  debug('Token cache miss', {
+    misses: metrics.tokenCache.misses,
+    hitRate: metrics.tokenCache.hitRate
+  });
+}
+
+/**
+ * Updates token cache hit rate
+ */
+function updateCacheHitRate() {
+  const total = metrics.tokenCache.hits + metrics.tokenCache.misses;
+  metrics.tokenCache.hitRate = total > 0
+    ? parseFloat((metrics.tokenCache.hits / total * 100).toFixed(2))
+    : 0;
+}
+
+/**
+ * Gets current metrics snapshot
+ * @returns {object} Current metrics
+ */
+function getMetrics() {
+  return JSON.parse(JSON.stringify(metrics)); // Deep copy
+}
+
+/**
+ * Resets all metrics (useful for testing)
+ */
+function resetMetrics() {
+  metrics.oauth.totalAttempts = 0;
+  metrics.oauth.successCount = 0;
+  metrics.oauth.failureCount = 0;
+  metrics.oauth.totalDurationMs = 0;
+  metrics.oauth.avgDurationMs = 0;
+
+  metrics.requests.totalCount = 0;
+  metrics.requests.successCount = 0;
+  metrics.requests.errorCount = 0;
+  metrics.requests.totalDurationMs = 0;
+  metrics.requests.avgDurationMs = 0;
+
+  metrics.tokenCache.hits = 0;
+  metrics.tokenCache.misses = 0;
+  metrics.tokenCache.hitRate = 0;
+}
+
+/**
+ * Prints metrics summary
+ */
+function printMetrics() {
+  info('Performance Metrics Summary', {
+    oauth: {
+      attempts: metrics.oauth.totalAttempts,
+      successRate: metrics.oauth.totalAttempts > 0
+        ? (metrics.oauth.successCount / metrics.oauth.totalAttempts * 100).toFixed(2) + '%'
+        : 'N/A',
+      avgDurationMs: metrics.oauth.avgDurationMs
+    },
+    requests: {
+      total: metrics.requests.totalCount,
+      successRate: metrics.requests.totalCount > 0
+        ? (metrics.requests.successCount / metrics.requests.totalCount * 100).toFixed(2) + '%'
+        : 'N/A',
+      avgDurationMs: metrics.requests.avgDurationMs
+    },
+    tokenCache: {
+      hits: metrics.tokenCache.hits,
+      misses: metrics.tokenCache.misses,
+      hitRate: metrics.tokenCache.hitRate + '%'
+    }
+  });
+}
+
+module.exports = {
+  startTimer,
+  recordOAuthAttempt,
+  recordRequest,
+  recordCacheHit,
+  recordCacheMiss,
+  getMetrics,
+  resetMetrics,
+  printMetrics
+};

package/lib/retry.js

@@ -0,0 +1,150 @@
+/**
+ * Retry logic with exponential backoff
+ * Provides resilient error recovery for transient failures
+ */
+
+const { warn, error } = require('./logger');
+
+/**
+ * Sleep utility
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Determines if an error is retryable
+ * @param {Error} err - Error to check
+ * @returns {boolean} Whether error is retryable
+ */
+function isRetryableError(err) {
+  if (!err) return false;
+
+  // Network errors are retryable
+  const networkErrors = ['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'EAI_AGAIN'];
+  if (networkErrors.includes(err.code)) {
+    return true;
+  }
+
+  // Timeout errors are retryable
+  if (err.message && err.message.toLowerCase().includes('timeout')) {
+    return true;
+  }
+
+  // HTTP 429 (rate limiting) is retryable
+  if (err.statusCode === 429 || err.status === 429) {
+    return true;
+  }
+
+  // HTTP 5xx errors are retryable
+  if (err.statusCode >= 500 && err.statusCode < 600) {
+    return true;
+  }
+  if (err.status >= 500 && err.status < 600) {
+    return true;
+  }
+
+  // Not retryable
+  return false;
+}
+
+/**
+ * Calculates exponential backoff delay
+ * @param {number} attempt - Current attempt number (1-indexed)
+ * @param {number} baseDelay - Base delay in ms (default: 1000)
+ * @param {number} maxDelay - Maximum delay in ms (default: 10000)
+ * @returns {number} Delay in milliseconds
+ */
+function calculateBackoff(attempt, baseDelay = 1000, maxDelay = 10000) {
+  const delay = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
+  // Add jitter (±20%) to prevent thundering herd
+  const jitter = delay * 0.2 * (Math.random() * 2 - 1);
+  return Math.floor(delay + jitter);
+}
+
+/**
+ * Retries a function with exponential backoff
+ * @param {Function} fn - Async function to retry
+ * @param {object} options - Retry options
+ * @param {number} options.maxRetries - Maximum retry attempts (default: 3)
+ * @param {number} options.baseDelay - Base delay in ms (default: 1000)
+ * @param {number} options.maxDelay - Maximum delay in ms (default: 10000)
+ * @param {Function} options.shouldRetry - Custom function to determine if error is retryable
+ * @param {string} options.operationName - Name of operation for logging
+ * @returns {Promise<any>} Result of successful function call
+ * @throws {Error} Last error if all retries fail
+ */
+async function retryWithBackoff(fn, options = {}) {
+  const {
+    maxRetries = 3,
+    baseDelay = 1000,
+    maxDelay = 10000,
+    shouldRetry = isRetryableError,
+    operationName = 'operation'
+  } = options;
+
+  let lastError;
+
+  for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+    try {
+      const result = await fn();
+      return result;
+    } catch (err) {
+      lastError = err;
+
+      // If this was the last attempt, throw the error
+      if (attempt > maxRetries) {
+        error(`${operationName} failed after ${maxRetries} retries`, { error: err.message });
+        throw err;
+      }
+
+      // Check if error is retryable
+      if (!shouldRetry(err)) {
+        error(`${operationName} failed with non-retryable error`, { error: err.message });
+        throw err;
+      }
+
+      // Calculate backoff delay
+      const delay = calculateBackoff(attempt, baseDelay, maxDelay);
+
+      warn(`${operationName} failed (attempt ${attempt}/${maxRetries + 1}), retrying in ${delay}ms`, {
+        error: err.message,
+        attempt,
+        maxRetries,
+        delayMs: delay
+      });
+
+      // Wait before retrying
+      await sleep(delay);
+    }
+  }
+
+  // Should never reach here, but just in case
+  throw lastError;
+}
+
+/**
+ * Retries a function with a simple fixed delay
+ * @param {Function} fn - Async function to retry
+ * @param {number} maxRetries - Maximum retry attempts
+ * @param {number} delayMs - Fixed delay between retries in ms
+ * @returns {Promise<any>} Result of successful function call
+ * @throws {Error} Last error if all retries fail
+ */
+async function retryWithFixedDelay(fn, maxRetries = 3, delayMs = 1000) {
+  return retryWithBackoff(fn, {
+    maxRetries,
+    baseDelay: delayMs,
+    maxDelay: delayMs // Same as base = fixed delay
+  });
+}
+
+module.exports = {
+  sleep,
+  isRetryableError,
+  calculateBackoff,
+  retryWithBackoff,
+  retryWithFixedDelay
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uteamup/mcp-server",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.8",
   "description": "MCP server client for UteamUP - enables Claude Desktop/Code integration with automatic OAuth 2.0 authentication",
   "main": "index.js",
   "bin": {
@@ -57,6 +57,7 @@
   },
   "files": [
     "index.js",
+    "lib/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"