@hcu-lab.me/mcp-device 1.0.10 → 1.0.12

package/control-plane/scripts/upstreams/config.mjs

@@ -0,0 +1,158 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { validateExternalToolPrefix, validateUpstreamId } from './names.mjs';
+import { expandMcpPreset, expandPlaceholders, normalizeRunnerCommand } from './presets.mjs';
+import {
+  findUnifiedMcpConfigPath,
+  loadUnifiedMcpTomlConfig,
+  resolveTrustedRootPaths,
+  trustedRootsTomlToRaw
+} from '../projects/trusted-roots-projects.mjs';
+
+const DEFAULT_EXTERNAL = {
+  enabled: true,
+  fail_gateway_on_startup_error: false,
+  catalog_cache: 'startup',
+  catalog_cache_ttl_ms: 30000,
+  startup_timeout_ms: 15000,
+  shutdown_timeout_ms: 5000,
+  default_transport: 'stdio',
+  default_enabled: false,
+  exposure_mode: 'direct',
+  eager_schema_budget_bytes: 24576,
+  eager_allowlist: []
+};
+
+function envFlag(value, defaultValue = true) {
+  const text = String(value ?? '').trim().toLowerCase();
+  if (!text) return defaultValue;
+  if (['1', 'true', 'yes', 'y', 'on'].includes(text)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(text)) return false;
+  return defaultValue;
+}
+
+function asMs(value, fallback, label) {
+  const n = Number(value ?? fallback);
+  if (!Number.isFinite(n) || n < 0) throw new Error(`Invalid ${label}: ${value}`);
+  return n;
+}
+
+function asNonNegativeInteger(value, fallback, label) {
+  const n = Number(value ?? fallback);
+  if (!Number.isInteger(n) || n < 0) throw new Error(`Invalid ${label}: ${value}`);
+  return n;
+}
+
+function normalizeStringList(value, fallback, label) {
+  if (value === undefined) return [...fallback];
+  if (!Array.isArray(value)) throw new Error(`Invalid ${label}: expected an array of tool names.`);
+  const items = value.map(item => String(item).trim());
+  if (items.some(item => !item)) throw new Error(`Invalid ${label}: tool names must be non-empty strings.`);
+  if (new Set(items).size !== items.length) throw new Error(`Invalid ${label}: duplicate tool names are not allowed.`);
+  return items;
+}
+
+function asMsWithSec(raw, msKey, secKey, fallback, label) {
+  if (raw && Object.prototype.hasOwnProperty.call(raw, msKey)) return asMs(raw[msKey], fallback, label);
+  if (raw && Object.prototype.hasOwnProperty.call(raw, secKey)) {
+    const n = Number(raw[secKey]);
+    if (!Number.isFinite(n) || n <= 0) throw new Error(`Invalid ${secKey}: ${raw[secKey]}`);
+    return n * 1000;
+  }
+  return asMs(undefined, fallback, label);
+}
+
+function trustedRootsFromConfig(raw, repoRoot) {
+  const trustedRootsRaw = trustedRootsTomlToRaw(raw.trusted_roots, { repoRoot });
+  if (!trustedRootsRaw.trim()) return [];
+  return resolveTrustedRootPaths(trustedRootsRaw).existingRoots;
+}
+
+function resolveMaybeRelative(value, baseDir) {
+  if (!value) return undefined;
+  const text = String(value).replace(/^['"]|['"]$/g, '');
+  return path.isAbsolute(text) ? path.resolve(text) : path.resolve(baseDir, text);
+}
+
+export function findExternalMcpConfigPath(env = process.env, repoRoot = process.cwd()) {
+  return findUnifiedMcpConfigPath(env, repoRoot);
+}
+
+export async function loadExternalMcpConfig({ env = process.env, repoRoot = process.cwd() } = {}) {
+  const configPath = findExternalMcpConfigPath(env, repoRoot);
+  if (!configPath) {
+    return normalizeExternalMcpConfig({}, { configPath: null, repoRoot, env, noConfig: true });
+  }
+  const raw = loadUnifiedMcpTomlConfig(configPath);
+  return normalizeExternalMcpConfig(raw, { configPath, repoRoot, env });
+}
+
+export function normalizeExternalMcpConfig(raw = {}, { configPath = null, repoRoot = process.cwd(), env = process.env, noConfig = false } = {}) {
+  const externalRaw = raw.external_mcp || {};
+  const catalogCache = String(externalRaw.catalog_cache ?? DEFAULT_EXTERNAL.catalog_cache).trim().toLowerCase();
+  const exposureMode = String(externalRaw.exposure_mode ?? DEFAULT_EXTERNAL.exposure_mode).trim().toLowerCase();
+  const external = {
+    ...DEFAULT_EXTERNAL,
+    ...externalRaw,
+    enabled: envFlag(env.MCP_EXTERNAL_MCP_ENABLED, externalRaw.enabled ?? DEFAULT_EXTERNAL.enabled),
+    catalog_cache: catalogCache,
+    catalog_cache_ttl_ms: DEFAULT_EXTERNAL.catalog_cache_ttl_ms,
+    exposure_mode: exposureMode,
+    eager_schema_budget_bytes: asNonNegativeInteger(externalRaw.eager_schema_budget_bytes, DEFAULT_EXTERNAL.eager_schema_budget_bytes, 'eager_schema_budget_bytes'),
+    eager_allowlist: normalizeStringList(externalRaw.eager_allowlist, DEFAULT_EXTERNAL.eager_allowlist, 'eager_allowlist'),
+    startup_timeout_ms: asMsWithSec(externalRaw, 'startup_timeout_ms', 'startup_timeout_sec', DEFAULT_EXTERNAL.startup_timeout_ms, 'startup_timeout_ms'),
+    shutdown_timeout_ms: asMsWithSec(externalRaw, 'shutdown_timeout_ms', 'shutdown_timeout_sec', DEFAULT_EXTERNAL.shutdown_timeout_ms, 'shutdown_timeout_ms')
+  };
+  external.fail_gateway_on_startup_error = Boolean(externalRaw.fail_gateway_on_startup_error ?? DEFAULT_EXTERNAL.fail_gateway_on_startup_error);
+  if (!['startup', 'ttl', 'none'].includes(external.catalog_cache)) throw new Error(`Invalid catalog_cache: ${external.catalog_cache}`);
+  if (!['direct', 'brokered', 'hybrid'].includes(external.exposure_mode)) throw new Error(`Invalid exposure_mode: ${external.exposure_mode}`);
+  if (external.catalog_cache === 'ttl') {
+    external.catalog_cache_ttl_ms = asMs(externalRaw.catalog_cache_ttl_ms, DEFAULT_EXTERNAL.catalog_cache_ttl_ms, 'catalog_cache_ttl_ms');
+    if (external.catalog_cache_ttl_ms <= 0) {
+      throw new Error('catalog_cache_ttl_ms must be positive when catalog_cache = "ttl"');
+    }
+  }
+  if (!['stdio', 'http'].includes(external.default_transport)) throw new Error(`Invalid default_transport: ${external.default_transport}`);
+
+  const baseDir = configPath ? path.dirname(configPath) : repoRoot;
+  const serversRaw = raw.mcp_servers || {};
+  const trustedRoots = trustedRootsFromConfig(raw, repoRoot);
+  const placeholderContext = { repoRoot: path.resolve(repoRoot), cwd: baseDir, env, trustedRoots, platform: process.platform };
+  const servers = [];
+  for (const [rawId, rawServerRaw] of Object.entries(serversRaw)) {
+    const id = validateUpstreamId(rawId);
+    const serverRaw = expandMcpPreset(id, rawServerRaw, placeholderContext);
+    const enabled = Boolean(serverRaw.enabled ?? external.default_enabled);
+    let transport = serverRaw.transport;
+    if (!transport && serverRaw.url) transport = 'http';
+    if (!transport && (serverRaw.command || serverRaw.runner)) transport = 'stdio';
+    transport = String(transport || external.default_transport).trim().toLowerCase();
+    if (!['stdio', 'http'].includes(transport)) throw new Error(`Invalid transport for ${id}: ${transport}`);
+    const toolPrefix = validateExternalToolPrefix(serverRaw.tool_prefix || id, `tool_prefix for ${id}`);
+    const server = {
+      id,
+      enabled,
+      transport,
+      toolPrefix,
+      startupTimeoutMs: asMsWithSec(serverRaw, 'startup_timeout_ms', 'startup_timeout_sec', external.startup_timeout_ms, `startup_timeout_ms for ${id}`),
+      shutdownTimeoutMs: asMsWithSec(serverRaw, 'shutdown_timeout_ms', 'shutdown_timeout_sec', external.shutdown_timeout_ms, `shutdown_timeout_ms for ${id}`)
+    };
+    if (transport === 'stdio') {
+      const command = serverRaw.command || normalizeRunnerCommand(serverRaw.runner, process.platform);
+      if (!command || typeof command !== 'string') throw new Error(`stdio upstream ${id} requires command`);
+      server.command = command;
+      server.args = Array.isArray(serverRaw.args) ? serverRaw.args.map(item => expandPlaceholders(String(item), placeholderContext)) : [];
+      server.cwd = resolveMaybeRelative(expandPlaceholders(serverRaw.cwd || '.', placeholderContext), baseDir);
+    } else {
+      if (!serverRaw.url || typeof serverRaw.url !== 'string') throw new Error(`http upstream ${id} requires url`);
+      server.url = expandPlaceholders(serverRaw.url, placeholderContext);
+      if (serverRaw.bearer_token) throw new Error(`http upstream ${id} must use bearer_token_env, not literal bearer_token`);
+      if (serverRaw.bearer_token_env) {
+        server.bearerTokenEnv = String(serverRaw.bearer_token_env);
+        server.bearerToken = env[server.bearerTokenEnv] || '';
+      }
+    }
+    if (enabled) servers.push(server);
+  }
+  return { configPath, noConfig, external, servers: external.enabled ? servers : [] };
+}

package/control-plane/scripts/upstreams/diagnostics.mjs

@@ -0,0 +1,21 @@
+export function diagnosticsResource(uri, data) {
+  return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(data, null, 2) }] };
+}
+
+export function summarizeDiagnostics(statuses, catalogState = {}, config = {}) {
+  const snapshot = catalogState.snapshot || {};
+  return {
+    source: 'external-mcp',
+    generatedAt: new Date().toISOString(),
+    configPath: config.configPath || null,
+    cacheMode: config.external?.catalog_cache || 'startup',
+    catalogTtlMs: config.external?.catalog_cache_ttl_ms ?? null,
+    generation: catalogState.generation ?? snapshot.generation ?? 0,
+    lastRefreshAt: catalogState.lastRefreshAt || null,
+    lastRefreshError: catalogState.lastRefreshError || null,
+    refreshInFlight: Boolean(catalogState.refreshInFlight),
+    catalog: snapshot.exposure?.diagnostics || null,
+    servers: [...statuses.entries()].map(([id, value]) => ({ id, ...value })),
+    upstreams: Object.fromEntries([...statuses.entries()].map(([id, value]) => [id, value]))
+  };
+}

package/control-plane/scripts/upstreams/http-client.mjs

@@ -0,0 +1,67 @@
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+
+function withTimeout(promise, ms, label) {
+  let timer;
+  return Promise.race([
+    promise.finally(() => clearTimeout(timer)),
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    })
+  ]);
+}
+
+// SDK 1.29 callTool() validates structured errors against the success output schema.
+async function callToolPreservingStructuredErrors(client, params) {
+  if (client.isToolTaskRequired(params.name)) {
+    throw new ProtocolError(
+      ProtocolErrorCode.InvalidRequest,
+      `Tool "${params.name}" requires task-based execution. Use client.experimental.tasks.callToolStream() instead.`
+    );
+  }
+  const result = await client.request({ method: 'tools/call', params });
+  const validator = client.getToolOutputValidator(params.name);
+  if (validator && !result.isError) {
+    if (!result.structuredContent) {
+      throw new ProtocolError(ProtocolErrorCode.InvalidRequest, `Tool ${params.name} has an output schema but did not return structured content`);
+    }
+    const validationResult = validator(result.structuredContent);
+    if (!validationResult.valid) {
+      throw new ProtocolError(
+        ProtocolErrorCode.InvalidParams,
+        `Structured content does not match the tool's output schema: ${validationResult.errorMessage}`
+      );
+    }
+  }
+  return result;
+}
+
+export async function createHttpUpstreamClient(serverConfig) {
+  const headers = {
+    'accept': 'application/json, text/event-stream'
+  };
+  if (serverConfig.bearerToken) headers.authorization = `Bearer ${serverConfig.bearerToken}`;
+  const transport = new StreamableHTTPClientTransport(new URL(serverConfig.url), {
+    requestInit: { headers }
+  });
+  const client = new Client({ name: `agent-mcp-gateway-upstream-${serverConfig.id}`, version: '1.0.0' }, { capabilities: {} });
+  await withTimeout(client.connect(transport), serverConfig.startupTimeoutMs || 15000, `upstream ${serverConfig.id} initialize`);
+  const capabilities = client.getServerCapabilities?.() || {};
+  return {
+    id: serverConfig.id,
+    config: serverConfig,
+    client,
+    transport,
+    capabilities,
+    async listTools() { return await client.listTools(); },
+    async callTool(params) { return await client.callTool(params); },
+    async listResources() { return await client.listResources(); },
+    async listResourceTemplates() { return await client.listResourceTemplates(); },
+    async readResource(params) { return await client.readResource(params); },
+    async listPrompts() { return await client.listPrompts(); },
+    async getPrompt(params) { return await client.getPrompt(params); },
+    async close() {
+      await client.close().catch(() => {});
+      await transport.close().catch(() => {});
+    }
+  };
+}