@uteamup/mcp-server 1.0.0-beta.9 → 2.3.0-beta.9

package/lib/config.js

@@ -4,6 +4,7 @@
  */
 
 const { z } = require('zod');
+const { normalizeBackendBaseUrl } = require('./transport-security');
 
 // Configuration schema
 const configSchema = z.object({
@@ -19,10 +20,25 @@ const configSchema = z.object({
   // Optional configuration
   baseUrl: z.string()
     .url('Base URL must be a valid URL')
+    .transform((value, context) => {
+      try {
+        return normalizeBackendBaseUrl(value);
+      } catch (error) {
+        context.addIssue({
+          code: 'custom',
+          message: error.message
+        });
+        return z.NEVER;
+      }
+    })
     .default('https://api.uteamup.com')
     .describe('API endpoint URL'),
 
   // Logging configuration
+  mcpPath: z.enum(['/mcp', '/mcp/read-only'])
+    .default('/mcp')
+    .describe('MCP transport path; the read-only pilot is enforced by the backend'),
+
   logLevel: z.enum(['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR'])
     .default('INFO')
     .describe('Logging level'),
@@ -51,6 +67,20 @@ const configSchema = z.object({
     .default(3)
     .describe('Maximum retry attempts for network errors'),
 
+  maxRequestBytes: z.number()
+    .int()
+    .min(1024)
+    .max(10485760)
+    .default(1048576)
+    .describe('Maximum size of one JSON-RPC request'),
+
+  maxResponseBytes: z.number()
+    .int()
+    .min(1024)
+    .max(104857600)
+    .default(10485760)
+    .describe('Maximum size of one backend response'),
+
   // Token management
   tokenCacheDir: z.string()
     .optional()
@@ -61,7 +91,22 @@ const configSchema = z.object({
     .min(0)
     .max(3600) // 1 hour max
     .default(300) // 5 minutes
-    .describe('Token refresh margin in seconds')
+    .describe('Token refresh margin in seconds'),
+
+  // UTEAMUP-SEC-2026-05-02-008: explicit opt-in to disable TLS verification
+  // for self-signed dev certs. Without this flag the MCP proxy validates
+  // TLS like any other production HTTPS client. Defense-in-depth: even when
+  // set, the flag is ignored for the production host (api.uteamup.com).
+  insecureTLS: z.boolean()
+    .default(false)
+    .describe('Disable TLS certificate verification (dev only — never set against api.uteamup.com)')
+}).transform(config => {
+  // Apply the production policy after URL parsing has canonicalized the host.
+  const hostname = new URL(config.baseUrl).hostname.replace(/\.$/, '');
+  if (hostname === 'api.uteamup.com') {
+    config.insecureTLS = false;
+  }
+  return config;
 });
 
 /**
@@ -75,13 +120,17 @@ function loadConfig() {
     apiKey: process.env.UTEAMUP_API_KEY,
     secret: process.env.UTEAMUP_SECRET,
     baseUrl: process.env.UTEAMUP_API_BASE_URL || 'https://api.uteamup.com',
+    mcpPath: process.env.UTEAMUP_MCP_PATH || '/mcp',
     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),
+    maxRequestBytes: parseInt(process.env.UTEAMUP_MAX_REQUEST_BYTES || '1048576', 10),
+    maxResponseBytes: parseInt(process.env.UTEAMUP_MAX_RESPONSE_BYTES || '10485760', 10),
     tokenCacheDir: process.env.UTEAMUP_TOKEN_CACHE_DIR,
-    tokenRefreshMargin: parseInt(process.env.UTEAMUP_TOKEN_REFRESH_MARGIN || '300', 10)
+    tokenRefreshMargin: parseInt(process.env.UTEAMUP_TOKEN_REFRESH_MARGIN || '300', 10),
+    insecureTLS: process.env.UTEAMUP_INSECURE_TLS === '1' || process.env.UTEAMUP_INSECURE_TLS === 'true'
   };
 
   // If debug mode is enabled, upgrade log level to DEBUG
@@ -95,8 +144,9 @@ function loadConfig() {
     return config;
   } catch (error) {
     if (error instanceof z.ZodError) {
-      // Format validation errors nicely
-      const errors = error.errors.map(err => {
+      // Format validation errors nicely.
+      // zod 4 renamed `error.errors` -> `error.issues`.
+      const errors = error.issues.map(err => {
         const path = err.path.join('.');
         return `  - ${path}: ${err.message}`;
       });
@@ -109,11 +159,14 @@ function loadConfig() {
         '  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_MCP_PATH            - /mcp or /mcp/read-only (default: /mcp)\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_MAX_REQUEST_BYTES   - Max JSON-RPC request bytes (default: 1048576)\n' +
+        '  UTEAMUP_MAX_RESPONSE_BYTES  - Max backend response bytes (default: 10485760)\n' +
         '  UTEAMUP_TOKEN_CACHE_DIR     - Persistent token cache directory\n' +
         '  UTEAMUP_TOKEN_REFRESH_MARGIN - Token refresh margin in seconds (default: 300)'
       );
@@ -142,11 +195,13 @@ function validateConfig() {
 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('  API Key: configured');
   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(`  Max Request Bytes: ${config.maxRequestBytes}`);
+  console.error(`  Max Response Bytes: ${config.maxResponseBytes}`);
   console.error(`  Token Refresh Margin: ${config.tokenRefreshMargin}s`);
   if (config.tokenCacheDir) {
     console.error(`  Token Cache Dir: ${config.tokenCacheDir}`);

package/lib/logger.js

@@ -37,12 +37,48 @@ const pinoOptions = {
       'code_verifier',
       'access_token',
       'accessToken',
+      'apiKey',
+      'api_key',
+      'cookie',
+      'setCookie',
+      'set-cookie',
+      'refreshToken',
+      'refresh_token',
+      'idToken',
+      'id_token',
+      'oauthRedirect',
       'bearer',
       '*.Authorization',
       '*.client_secret',
       '*.code_verifier',
       '*.access_token',
-      '*.accessToken'
+      '*.accessToken',
+      '*.apiKey',
+      '*.api_key',
+      '*.cookie',
+      '*.setCookie',
+      '*.set-cookie',
+      '*.refreshToken',
+      '*.refresh_token',
+      '*.idToken',
+      '*.id_token',
+      '*.oauthRedirect',
+      'numericCode',
+      'numeric_code',
+      '*.numericCode',
+      '*.numeric_code',
+      'photo',
+      'bytes',
+      'blob',
+      'gps',
+      'latitude',
+      'longitude',
+      '*.photo',
+      '*.bytes',
+      '*.blob',
+      '*.gps',
+      '*.latitude',
+      '*.longitude'
     ],
     remove: true
   },
@@ -80,9 +116,25 @@ function redactSensitive(data) {
     'code_verifier',
     'access_token',
     'accesstoken',
+    'apikey',
+    'api_key',
+    'cookie',
+    'refreshtoken',
+    'refresh_token',
+    'idtoken',
+    'id_token',
+    'oauthredirect',
     'bearer',
     'password',
-    'secret'
+    'secret',
+    'numericcode',
+    'numeric_code',
+    'photo',
+    'bytes',
+    'blob',
+    'gps',
+    'latitude',
+    'longitude'
   ];
 
   const redacted = Array.isArray(data) ? [...data] : { ...data };

package/lib/mcp-http-headers.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * Streamable HTTP headers mirrored from a JSON-RPC MCP message (SEP-2243).
+ *
+ * The C# SDK 2.x backend requires these on protocol 2026-07-28+. Down-level
+ * initialize-handshake clients omit protocol version in the body; we omit
+ * MCP-Protocol-Version in that case so SDK 2.x keeps its back-compat path.
+ */
+
+const PROTOCOL_VERSION_META_KEY = 'io.modelcontextprotocol/protocolVersion';
+const NAMED_METHODS = new Set(['tools/call', 'prompts/get', 'resources/read']);
+
+function readProtocolVersion(request) {
+  const params = request && typeof request.params === 'object' && request.params !== null
+    ? request.params
+    : null;
+  if (!params) {
+    return undefined;
+  }
+
+  const meta = params._meta;
+  if (meta && typeof meta === 'object' && typeof meta[PROTOCOL_VERSION_META_KEY] === 'string') {
+    const fromMeta = meta[PROTOCOL_VERSION_META_KEY].trim();
+    if (fromMeta) {
+      return fromMeta;
+    }
+  }
+
+  if (request.method === 'initialize' && typeof params.protocolVersion === 'string') {
+    const fromInit = params.protocolVersion.trim();
+    if (fromInit) {
+      return fromInit;
+    }
+  }
+
+  return undefined;
+}
+
+function readTargetName(request) {
+  if (!NAMED_METHODS.has(request.method)) {
+    return undefined;
+  }
+
+  const params = request.params;
+  if (!params || typeof params !== 'object') {
+    return undefined;
+  }
+
+  const raw = request.method === 'resources/read' ? params.uri : params.name;
+  if (typeof raw !== 'string') {
+    return undefined;
+  }
+
+  const value = raw.trim();
+  return value.length > 0 ? value : undefined;
+}
+
+/**
+ * @param {object} request JSON-RPC 2.0 MCP request or notification
+ * @returns {Record<string, string>}
+ */
+function buildMcpForwardHeaders(request) {
+  const headers = {};
+  if (!request || typeof request.method !== 'string' || request.method.length === 0) {
+    return headers;
+  }
+
+  headers['Mcp-Method'] = request.method;
+
+  const version = readProtocolVersion(request);
+  if (version) {
+    headers['MCP-Protocol-Version'] = version;
+  }
+
+  const name = readTargetName(request);
+  if (name) {
+    headers['Mcp-Name'] = name;
+  }
+
+  return headers;
+}
+
+module.exports = {
+  PROTOCOL_VERSION_META_KEY,
+  buildMcpForwardHeaders
+};

package/lib/retry.js

@@ -4,6 +4,7 @@
  */
 
 const { warn, error } = require('./logger');
+const { toPublicErrorMessage } = require('./transport-security');
 
 /**
  * Sleep utility
@@ -96,13 +97,21 @@ async function retryWithBackoff(fn, options = {}) {
 
       // If this was the last attempt, throw the error
       if (attempt > maxRetries) {
-        error(`${operationName} failed after ${maxRetries} retries`, { error: err.message });
+        error(`${operationName} failed after ${maxRetries} retries`, {
+          error: toPublicErrorMessage(err),
+          errorCode: err?.code,
+          statusCode: err?.statusCode
+        });
         throw err;
       }
 
       // Check if error is retryable
       if (!shouldRetry(err)) {
-        error(`${operationName} failed with non-retryable error`, { error: err.message });
+        error(`${operationName} failed with non-retryable error`, {
+          error: toPublicErrorMessage(err),
+          errorCode: err?.code,
+          statusCode: err?.statusCode
+        });
         throw err;
       }
 
@@ -110,7 +119,7 @@ async function retryWithBackoff(fn, options = {}) {
       const delay = calculateBackoff(attempt, baseDelay, maxDelay);
 
       warn(`${operationName} failed (attempt ${attempt}/${maxRetries + 1}), retrying in ${delay}ms`, {
-        error: err.message,
+        error: toPublicErrorMessage(err),
         attempt,
         maxRetries,
         delayMs: delay

package/lib/transport-security.js

@@ -0,0 +1,252 @@
+/**
+ * Security helpers for the stdio-to-HTTPS transport boundary.
+ *
+ * Only ProxyTransportError messages are safe to return to an MCP client. All
+ * other errors may contain backend response bodies, local paths, or secrets.
+ */
+
+class ProxyTransportError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ProxyTransportError';
+  }
+}
+
+const RETRY_SAFE_MCP_METHODS = new Set([
+  'ping',
+  'prompts/get',
+  'prompts/list',
+  'resources/list',
+  'resources/read',
+  'resources/templates/list',
+  'server/discover',
+  'tools/list'
+]);
+
+/**
+ * Parse the token response and require the backend-provided lifetime. Guessing
+ * a lifetime can leave an expired token cached long after the server rejects it.
+ *
+ * @param {string} data
+ * @returns {{accessToken: string, expiresInSeconds: number}}
+ */
+function parseOAuthTokenResponse(data) {
+  let json;
+  try {
+    json = JSON.parse(data);
+  } catch {
+    throw new ProxyTransportError('Token exchange returned invalid JSON');
+  }
+
+  if (json === null || typeof json !== 'object' || Array.isArray(json)) {
+    throw new ProxyTransportError('Token exchange returned an invalid response');
+  }
+
+  const accessToken = json.accessToken || json.access_token;
+  const expiresInValue = json.expiresIn ?? json.expires_in;
+  const expiresInSeconds = Number(expiresInValue);
+  if (
+    typeof accessToken !== 'string' ||
+    accessToken.trim().length === 0 ||
+    !Number.isSafeInteger(expiresInSeconds) ||
+    expiresInSeconds <= 0
+  ) {
+    throw new ProxyTransportError('Token exchange returned an invalid response');
+  }
+
+  return { accessToken, expiresInSeconds };
+}
+
+/**
+ * Only retry protocol reads. `tools/call` may mutate business data, and the
+ * proxy cannot prove that every tool is idempotent after a lost response.
+ *
+ * @param {string} method
+ * @param {number} configuredMaxRetries
+ * @returns {number}
+ */
+function getMcpRetryLimit(method, configuredMaxRetries) {
+  return RETRY_SAFE_MCP_METHODS.has(method) ? configuredMaxRetries : 0;
+}
+
+/**
+ * Accept only a bare HTTPS origin for the configured backend.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeBackendBaseUrl(value) {
+  let url;
+
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ProxyTransportError('Base URL must be a valid HTTPS origin');
+  }
+
+  const hasUnexpectedPath = url.pathname !== '' && url.pathname !== '/';
+  if (
+    url.protocol !== 'https:' ||
+    !url.hostname ||
+    url.username ||
+    url.password ||
+    hasUnexpectedPath ||
+    url.search ||
+    url.hash
+  ) {
+    throw new ProxyTransportError('Base URL must be a bare HTTPS origin without credentials, path, query, or fragment');
+  }
+
+  return url.origin;
+}
+
+/**
+ * Incrementally reads newline-delimited input without allowing one untrusted
+ * request to grow memory without bound.
+ */
+class BoundedLineBuffer {
+  constructor(maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+      throw new TypeError('maxBytes must be a positive safe integer');
+    }
+
+    this.maxBytes = maxBytes;
+    this.pending = Buffer.alloc(0);
+    this.discardingOversizedLine = false;
+  }
+
+  /**
+   * @param {string|Buffer} chunk
+   * @returns {Array<{line: string}|{oversized: true}>}
+   */
+  push(chunk) {
+    let remaining = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf8');
+    const events = [];
+
+    while (remaining.length > 0) {
+      if (this.discardingOversizedLine) {
+        const newlineIndex = remaining.indexOf(0x0a);
+        if (newlineIndex === -1) {
+          return events;
+        }
+
+        remaining = remaining.subarray(newlineIndex + 1);
+        this.discardingOversizedLine = false;
+        continue;
+      }
+
+      const newlineIndex = remaining.indexOf(0x0a);
+      if (newlineIndex === -1) {
+        if (this.pending.length + remaining.length > this.maxBytes) {
+          this.pending = Buffer.alloc(0);
+          this.discardingOversizedLine = true;
+          events.push({ oversized: true });
+        } else {
+          this.pending = Buffer.concat([this.pending, remaining]);
+        }
+        return events;
+      }
+
+      const lineRemainder = remaining.subarray(0, newlineIndex);
+      const lineLength = this.pending.length + lineRemainder.length;
+
+      if (lineLength > this.maxBytes) {
+        events.push({ oversized: true });
+      } else {
+        let line = Buffer.concat([this.pending, lineRemainder]).toString('utf8');
+        if (line.endsWith('\r')) {
+          line = line.slice(0, -1);
+        }
+        events.push({ line });
+      }
+
+      this.pending = Buffer.alloc(0);
+      remaining = remaining.subarray(newlineIndex + 1);
+    }
+
+    return events;
+  }
+}
+
+/**
+ * Collect an HTTP response body up to a strict byte limit.
+ *
+ * @param {import('stream').Readable & {headers?: object}} response
+ * @param {number} maxBytes
+ * @param {string} label
+ * @returns {Promise<string>}
+ */
+function collectResponseBody(response, maxBytes, label) {
+  const declaredLength = Number(response.headers?.['content-length']);
+  if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+    response.resume?.();
+    return Promise.reject(new ProxyTransportError(`${label} exceeded the configured size limit`));
+  }
+
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let totalBytes = 0;
+    let settled = false;
+
+    const rejectOnce = error => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    };
+
+    response.on('data', chunk => {
+      if (settled) return;
+
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      totalBytes += buffer.length;
+      if (totalBytes > maxBytes) {
+        rejectOnce(new ProxyTransportError(`${label} exceeded the configured size limit`));
+        response.destroy?.();
+        return;
+      }
+
+      chunks.push(buffer);
+    });
+
+    response.once('end', () => {
+      if (settled) return;
+      settled = true;
+      resolve(Buffer.concat(chunks).toString('utf8'));
+    });
+    response.once('aborted', () => rejectOnce(new ProxyTransportError(`${label} was interrupted`)));
+    response.once('error', rejectOnce);
+  });
+}
+
+/**
+ * Ensure socket timeouts terminate the underlying request.
+ *
+ * @param {import('stream').Writable} request
+ * @param {string} label
+ */
+function attachRequestTimeout(request, label) {
+  request.once('timeout', () => {
+    request.destroy(new ProxyTransportError(`${label} timed out`));
+  });
+}
+
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function toPublicErrorMessage(error) {
+  return error instanceof ProxyTransportError
+    ? error.message
+    : 'The MCP request could not be completed';
+}
+
+module.exports = {
+  BoundedLineBuffer,
+  ProxyTransportError,
+  attachRequestTimeout,
+  collectResponseBody,
+  getMcpRetryLimit,
+  normalizeBackendBaseUrl,
+  parseOAuthTokenResponse,
+  toPublicErrorMessage
+};