@xmemo/client 0.4.155 → 0.4.157

package/src/mcp/identity/paths.js

@@ -0,0 +1,155 @@
+import os from 'node:os';
+import path from 'node:path';
+
+export function configRoot(env) {
+  if (env.XMEMO_CONFIG_HOME) {
+    return env.XMEMO_CONFIG_HOME;
+  }
+
+  if (env.MEMORY_OS_CONFIG_HOME) {
+    return env.MEMORY_OS_CONFIG_HOME;
+  }
+
+  if (process.platform === 'win32' && env.LOCALAPPDATA) {
+    return path.join(env.LOCALAPPDATA, 'XMemo', 'CLI');
+  }
+
+  if (env.XDG_CONFIG_HOME) {
+    return path.join(env.XDG_CONFIG_HOME, 'xmemo');
+  }
+
+  const home = env.HOME || os.homedir();
+  return path.join(home, '.config', 'xmemo');
+}
+
+export function defaultCodexConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.codex', 'config.toml');
+}
+
+export function defaultCursorConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.cursor', 'mcp.json');
+}
+
+export function defaultGeminiConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.gemini', 'settings.json');
+}
+
+export function defaultAntigravityConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.gemini', 'config', 'mcp_config.json');
+}
+
+export function defaultAntigravityIdeConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.gemini', 'config', 'mcp_config.json');
+}
+
+export function defaultAntigravity2ConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.gemini', 'config', 'mcp_config.json');
+}
+
+export function defaultAntigravityCliConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.gemini', 'config', 'mcp_config.json');
+}
+
+export function defaultCopilotConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(env.COPILOT_HOME ?? path.join(home, '.copilot'), 'mcp-config.json');
+}
+
+export function defaultWindsurfConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.codeium', 'windsurf', 'mcp_config.json');
+}
+
+export function defaultClineConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, 'Documents', 'Cline', 'MCP', 'cline_mcp_settings.json');
+}
+
+export function defaultContinueConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.continue', 'config.json');
+}
+
+export function defaultClaudeConfigPath(env) {
+  if (process.platform === 'win32' && env.APPDATA) {
+    return path.join(env.APPDATA, 'Claude', 'claude_desktop_config.json');
+  }
+  const home = env.HOME || os.homedir();
+  if (process.platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  }
+  return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
+}
+
+export function defaultOpenclawConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.openclaw', 'openclaw.json');
+}
+
+export function defaultKiroConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.kiro', 'settings', 'mcp.json');
+}
+
+export function defaultZedConfigPath(env) {
+  if (process.platform === 'win32' && env.APPDATA) {
+    return path.join(env.APPDATA, 'Zed', 'settings.json');
+  }
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  return path.join(home, '.config', 'zed', 'settings.json');
+}
+
+export function defaultJetbrainsConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.continue', 'config.json');
+}
+
+export function defaultOpencodeConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.config', 'opencode', 'opencode.json');
+}
+
+export function defaultHermesConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.hermes', 'config.yaml');
+}
+
+export function defaultQwenConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.qwen', 'settings.json');
+}
+
+export function defaultTraeConfigPath(env) {
+  if (process.platform === 'win32' && env.APPDATA) {
+    return path.join(env.APPDATA, 'Trae', 'User', 'mcp.json');
+  }
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  if (process.platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', 'Trae', 'User', 'mcp.json');
+  }
+  return path.join(home, '.config', 'Trae', 'User', 'mcp.json');
+}
+
+export function defaultTraeSoloConfigPath(env) {
+  if (process.platform === 'win32' && env.APPDATA) {
+    return path.join(env.APPDATA, 'TRAE SOLO', 'User', 'mcp.json');
+  }
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  if (process.platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', 'TRAE SOLO', 'User', 'mcp.json');
+  }
+  return path.join(home, '.config', 'TRAE SOLO', 'User', 'mcp.json');
+}
+
+export function defaultClaudecodeConfigPath(env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.claude.json');
+}
+

package/src/mcp/proxy/copilot.js

@@ -0,0 +1,44 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { MCP_SERVER_NAME } from '../../core/constants.js';
+import { UsageError } from '../../core/errors.js';
+import {
+  bestEffortChmod,
+  isPlainObject,
+  parseJsonConfig,
+  readTextIfExists
+} from '../../core/runtime.js';
+import { existingJsonMcpServerName } from '../core/names.js';
+export { mcpProxyCommand } from './server.js';
+
+export async function mergeCopilotMcpConfig(configPath, proxyUrl) {
+  const existing = await readTextIfExists(configPath);
+  const parsed = existing.trim().length === 0 ? {} : parseJsonConfig(existing, configPath);
+
+  if (!isPlainObject(parsed)) {
+    throw new UsageError(`Copilot MCP JSON config must be an object: ${configPath}`);
+  }
+
+  if (!isPlainObject(parsed.mcpServers)) {
+    parsed.mcpServers = {};
+  }
+
+  const existingName = existingJsonMcpServerName(parsed.mcpServers);
+  if (existingName) {
+    throw new UsageError(`MCP config already contains mcpServers.${existingName}. Edit ${configPath} manually to avoid duplicate server definitions.`);
+  }
+
+  parsed.mcpServers[MCP_SERVER_NAME] = copilotLocalProxyServerConfig(proxyUrl);
+  await fs.mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });
+  await fs.writeFile(configPath, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600 });
+  await bestEffortChmod(configPath, 0o600);
+}
+
+export function copilotLocalProxyServerConfig(proxyUrl) {
+  return {
+    type: 'http',
+    url: proxyUrl
+  };
+}
+

package/src/mcp/proxy/server.js

@@ -0,0 +1,112 @@
+import http from 'node:http';
+
+import { optionValue, parsePositiveInteger } from '../../core/args.js';
+import {
+  AGENT_ID_HEADER,
+  AGENT_INSTANCE_HEADER,
+  CLI_VERSION,
+  COMMAND_NAME,
+  DEFAULT_SERVICE_URL,
+  DEFAULT_PROXY_HOST,
+  DEFAULT_PROXY_PORT,
+  PRODUCT_NAME,
+  TOKEN_ENV_VAR
+} from '../../core/constants.js';
+import { credentialsPath, resolveCredentialToken, validateToken } from '../../network/auth.js';
+import { endpointUrl, normalizeBaseUrl } from '../../network/http.js';
+import { UsageError } from '../../core/errors.js';
+import { writeLine } from '../../core/io.js';
+import { closeServer, readAll, waitForShutdown } from '../../core/runtime.js';
+
+export async function mcpProxyCommand(args, io, { agentIdentity }) {
+  const baseUrl = normalizeBaseUrl(baseUrlOption(args, io.env));
+  const mcpUrl = endpointUrl(baseUrl, '/mcp');
+  const host = optionValue(args, '--host') ?? DEFAULT_PROXY_HOST;
+  const port = parsePositiveInteger(optionValue(args, '--port') ?? String(DEFAULT_PROXY_PORT), '--port');
+  const token = await resolveCredentialToken(io.env);
+  if (!token) {
+    throw new UsageError(`No token found. Run \`${COMMAND_NAME} login\` or \`${COMMAND_NAME} token add --from-stdin\` first.`);
+  }
+  validateToken(token);
+  const identity = await agentIdentity('copilot-cli', io.env);
+
+  const server = http.createServer(async (request, response) => {
+    try {
+      await handleMcpProxyRequest({ request, response, mcpUrl, token, identity, io });
+    } catch (error) {
+      response.statusCode = 502;
+      response.setHeader('content-type', 'application/json');
+      response.end(JSON.stringify({ error: 'mcp_proxy_error', message: error.message }));
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+
+  writeLine(io.stdout, `${PRODUCT_NAME} MCP proxy listening on http://${host}:${port}/mcp`);
+  writeLine(io.stdout, `Forwarding to ${mcpUrl}`);
+  writeLine(io.stdout, `Credential source: ${TOKEN_ENV_VAR} or ${credentialsPath(io.env)}`);
+  if (io.keepAlive === false) {
+    await closeServer(server);
+    return 0;
+  }
+
+  await waitForShutdown(server, io);
+  return 0;
+}
+
+async function handleMcpProxyRequest({ request, response, mcpUrl, token, identity, io }) {
+  const requestUrl = new URL(request.url ?? '/', `http://${request.headers.host ?? `${DEFAULT_PROXY_HOST}:${DEFAULT_PROXY_PORT}`}`);
+  if (request.method !== 'POST' || requestUrl.pathname !== '/mcp') {
+    response.statusCode = 404;
+    response.setHeader('content-type', 'application/json');
+    response.end(JSON.stringify({ error: 'not_found' }));
+    return;
+  }
+
+  const body = await readAll(request);
+  const upstreamHeaders = {
+    accept: String(request.headers.accept || 'application/json, text/event-stream'),
+    'content-type': String(request.headers['content-type'] || 'application/json'),
+    authorization: `Bearer ${token}`,
+    [AGENT_ID_HEADER]: identity.agentId,
+    [AGENT_INSTANCE_HEADER]: identity.agentInstanceId,
+    'user-agent': `XMemo-CLI-Proxy/${CLI_VERSION} (+https://github.com/yonro/memory-os-cli)`
+  };
+  const sessionId = request.headers['mcp-session-id'];
+  if (sessionId) {
+    upstreamHeaders['mcp-session-id'] = Array.isArray(sessionId) ? sessionId[0] : sessionId;
+  }
+
+  const upstream = await io.fetch(mcpUrl, {
+    method: 'POST',
+    headers: upstreamHeaders,
+    body
+  });
+
+  response.statusCode = upstream.status;
+  for (const header of ['content-type', 'mcp-session-id']) {
+    const value = upstream.headers.get(header);
+    if (value) {
+      response.setHeader(header, value);
+    }
+  }
+  const buffer = Buffer.from(await upstream.arrayBuffer());
+  response.end(buffer);
+}
+
+function baseUrlOption(args, env) {
+  return optionValue(args, '--url')
+    ?? optionValue(args, '--base-url')
+    ?? env.XMEMO_URL
+    ?? env.XMEMO_BASE_URL
+    ?? env.MEMORY_OS_URL
+    ?? env.MEMORY_OS_BASE_URL
+    ?? DEFAULT_SERVICE_URL;
+}
+

package/src/network/auth.js

@@ -0,0 +1,200 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { stringValue } from '../core/args.js';
+import {
+  CLI_VERSION,
+  DEVICE_LOGIN_START_PATH,
+  DEVICE_LOGIN_TOKEN_PATH,
+  LEGACY_TOKEN_ENV_VAR,
+  PACKAGE_NAME,
+  TOKEN_ENV_VAR
+} from '../core/constants.js';
+import { endpointUrl, postJson } from './http.js';
+import { UsageError } from '../core/errors.js';
+import {
+  bestEffortChmod,
+  parseJsonConfig,
+  readAll,
+  readTextIfExists,
+  sleep
+} from '../core/runtime.js';
+
+export async function startDeviceLogin(baseUrl, timeoutMs, io) {
+  const payload = await postJson(endpointUrl(baseUrl, DEVICE_LOGIN_START_PATH), {
+    client_id: PACKAGE_NAME,
+    cli_version: CLI_VERSION,
+    token_type: 'mcp_token',
+    scopes: ['memory:read', 'memory:write']
+  }, timeoutMs, io);
+
+  const deviceCode = stringValue(payload, ['device_code']);
+  const verificationUri = stringValue(payload, ['verification_uri']);
+  if (!deviceCode || !verificationUri) {
+    throw new UsageError(`Device login did not return device_code and verification_uri from ${baseUrl}.`);
+  }
+
+  return {
+    deviceCode,
+    userCode: stringValue(payload, ['user_code']),
+    verificationUri,
+    verificationUriComplete: stringValue(payload, ['verification_uri_complete']),
+    expiresIn: Number.isFinite(Number(payload.expires_in)) ? Number(payload.expires_in) : 600,
+    interval: Number.isFinite(Number(payload.interval)) ? Math.max(1, Number(payload.interval)) : 5
+  };
+}
+
+export async function pollDeviceLogin(baseUrl, start, loginTimeoutMs, httpTimeoutMs, io, options = {}) {
+  const deadline = Date.now() + Math.min(start.expiresIn * 1000, loginTimeoutMs);
+  const sleepFn = io.sleep ?? sleep;
+  let intervalSeconds = start.interval;
+  while (Date.now() <= deadline) {
+    const payload = await postJson(endpointUrl(baseUrl, DEVICE_LOGIN_TOKEN_PATH), {
+      device_code: start.deviceCode,
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code'
+    }, httpTimeoutMs, io, { allowDevicePending: true });
+
+    const accessToken = stringValue(payload, ['access_token']) ?? stringValue(payload, ['token']);
+    if (accessToken) {
+      validateToken(accessToken);
+      return {
+        accessToken,
+        account: accountFromPayload(payload)
+      };
+    }
+
+    const error = stringValue(payload, ['error']);
+    if (error && error !== 'authorization_pending' && error !== 'slow_down') {
+      throw new UsageError(`Device login failed: ${error}`);
+    }
+    if (options.pollOnce) {
+      throw new UsageError('Device login is still pending.');
+    }
+    if (error === 'slow_down') {
+      intervalSeconds += 5;
+    }
+    await sleepFn(intervalSeconds * 1000);
+  }
+
+  throw new UsageError('Device login expired before authorization completed.');
+}
+
+export async function storeTokenFromStdin(io, metadata = {}) {
+  const token = (await readAll(io.stdin)).trim();
+  validateToken(token);
+  return await storeTokenValue(token, metadata, io.env);
+}
+
+export async function storeTokenValue(token, metadata, env) {
+  validateToken(token);
+  const credentialPath = credentialsPath(env);
+  await writePlaintextCredential(credentialPath, token, metadata);
+  return {
+    credentialPath,
+    tokenPresent: true,
+    tokenPrinted: false,
+    projectFilesModified: false,
+    storage: 'user-scoped-credential-file'
+  };
+}
+
+export async function readStoredCredential(env) {
+  const credentialPath = credentialsPath(env);
+  const content = await readTextIfExists(credentialPath);
+  if (!content.trim()) {
+    return { path: credentialPath, token: null };
+  }
+  const parsed = parseJsonConfig(content, credentialPath);
+  return {
+    path: credentialPath,
+    token: stringValue(parsed, ['token']),
+    storage: stringValue(parsed, ['storage']),
+    account: accountFromPayload(parsed.metadata)
+  };
+}
+
+function accountFromPayload(payload) {
+  const account = payload && typeof payload === 'object'
+    ? (payload.user && typeof payload.user === 'object' ? payload.user : payload.account)
+    : null;
+  if (!account || typeof account !== 'object') {
+    return null;
+  }
+  const userId = stringValue(account, ['user_id']) ?? stringValue(account, ['id']) ?? stringValue(account, ['userId']);
+  const email = stringValue(account, ['email']);
+  const displayName = stringValue(account, ['display_name']) ?? stringValue(account, ['name']) ?? stringValue(account, ['displayName']);
+  if (!userId && !email && !displayName) {
+    return null;
+  }
+  return {
+    userId: userId ?? null,
+    email: email ?? null,
+    displayName: displayName ?? null
+  };
+}
+
+export function formatAccount(account) {
+  const label = account.displayName || account.email || account.userId || 'XMemo account';
+  return account.email && account.displayName ? `${account.displayName} <${account.email}>` : label;
+}
+
+export async function resolveCredentialToken(env) {
+  const environmentToken = env[TOKEN_ENV_VAR] ?? env[LEGACY_TOKEN_ENV_VAR];
+  if (environmentToken) {
+    return environmentToken;
+  }
+  const credential = await readStoredCredential(env);
+  return credential.token;
+}
+
+export function credentialsPath(env) {
+  return path.join(configRoot(env), 'credentials.json');
+}
+
+function configRoot(env) {
+  if (env.XMEMO_CONFIG_HOME) {
+    return env.XMEMO_CONFIG_HOME;
+  }
+  if (env.MEMORY_OS_CONFIG_HOME) {
+    return env.MEMORY_OS_CONFIG_HOME;
+  }
+  if (process.platform === 'win32' && env.LOCALAPPDATA) {
+    return path.join(env.LOCALAPPDATA, 'XMemo', 'CLI');
+  }
+  if (env.XDG_CONFIG_HOME) {
+    return path.join(env.XDG_CONFIG_HOME, 'xmemo');
+  }
+  const home = env.HOME || os.homedir();
+  return path.join(home, '.config', 'xmemo');
+}
+
+async function writePlaintextCredential(credentialPath, token, metadata = {}) {
+  await fs.mkdir(path.dirname(credentialPath), { recursive: true, mode: 0o700 });
+  await bestEffortChmod(path.dirname(credentialPath), 0o700);
+  const payload = {
+    version: 1,
+    tokenEnvVar: TOKEN_ENV_VAR,
+    storage: 'user-scoped-credential-file',
+    createdAt: new Date().toISOString(),
+    metadata,
+    token
+  };
+  await fs.writeFile(credentialPath, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+  await bestEffortChmod(credentialPath, 0o600);
+}
+
+export function validateToken(token) {
+  if (!token) {
+    throw new UsageError('Token from stdin is empty.');
+  }
+
+  if (/\s/.test(token)) {
+    throw new UsageError('Token must not contain whitespace.');
+  }
+
+  if (token.length < 16) {
+    throw new UsageError('Token is too short to be a production credential.');
+  }
+}
+

package/src/network/base-url.js

@@ -0,0 +1,13 @@
+import { optionValue } from '../core/args.js';
+import { DEFAULT_SERVICE_URL } from '../core/constants.js';
+
+export function baseUrlOption(args, env) {
+  return optionValue(args, '--base-url')
+    ?? optionValue(args, '--url')
+    ?? env.XMEMO_BASE_URL
+    ?? env.XMEMO_URL
+    ?? env.MEMORY_OS_BASE_URL
+    ?? env.MEMORY_OS_URL
+    ?? DEFAULT_SERVICE_URL;
+}
+

package/src/network/discovery.js

@@ -0,0 +1,103 @@
+import { arrayValue, booleanValue, stringValue } from '../core/args.js';
+import { TOKEN_ENV_VAR } from '../core/constants.js';
+import { UsageError } from '../core/errors.js';
+import { endpointUrl, fetchJson } from './http.js';
+import { isPlainObject } from '../core/runtime.js';
+
+export function ensureDiscoveryService(discovery, discoveryUrl) {
+  const service = stringValue(discovery, ['service']);
+  if (service && service !== 'memory-os') {
+    throw new UsageError(`Discovery document at ${discoveryUrl} is for '${service}', not 'memory-os'.`);
+  }
+}
+
+export function buildSetupPlan({ baseUrl, discoveryUrl, statusUrl, discovery, status, localClients }) {
+  const apiBase = stringValue(discovery, ['urls', 'api_base'])
+    ?? stringValue(discovery, ['api_base_url'])
+    ?? baseUrl;
+  const mcpUrl = stringValue(discovery, ['urls', 'mcp'])
+    ?? stringValue(discovery, ['mcp_url'])
+    ?? endpointUrl(apiBase, '/mcp');
+  const tokenPortalUrl = stringValue(discovery, ['urls', 'token_portal'])
+    ?? stringValue(discovery, ['token_portal_url'])
+    ?? stringValue(status, ['requirements', 'token_portal_url']);
+  const tokenEnvVar = stringValue(discovery, ['auth', 'token_env_var'])
+    ?? stringValue(status, ['requirements', 'token_env_var'])
+    ?? TOKEN_ENV_VAR;
+
+  return {
+    schemaVersion: '1.0',
+    baseUrl,
+    discoveryUrl,
+    statusUrl,
+    apiBase,
+    mcpUrl,
+    guideUrl: stringValue(discovery, ['urls', 'guide']) ?? endpointUrl(apiBase, '/guide'),
+    docsUrl: stringValue(discovery, ['urls', 'docs']),
+    tokenPortalUrl,
+    tokenEnvVar,
+    onboardingReady: booleanValue(status, ['ready']),
+    supportedClients: discoveryMcpClients(discovery),
+    localClients,
+    privacy: {
+      telemetry: false,
+      tokenSent: false,
+      tokenEmbeddedInConfig: false
+    },
+    boundaries: {
+      clientAllowed: arrayValue(discovery, ['agent_boundary', 'client_allowed'])
+        ?? arrayValue(status, ['agent_boundary', 'client_allowed'])
+        ?? [],
+      adminRequired: arrayValue(discovery, ['agent_boundary', 'admin_required'])
+        ?? arrayValue(status, ['agent_boundary', 'admin_required'])
+        ?? []
+    }
+  };
+}
+
+export async function bestEffortRootVersion(discovery, timeoutMs, io) {
+  const rootDiscoveryUrl = stringValue(discovery, ['urls', 'root_discovery']);
+  if (!rootDiscoveryUrl) {
+    return {};
+  }
+  try {
+    const rootDiscovery = await fetchJson(rootDiscoveryUrl, timeoutMs, io);
+    return { version: stringValue(rootDiscovery, ['version']) ?? undefined };
+  } catch (error) {
+    return { error: error.message };
+  }
+}
+
+export function discoveryMcpUrl(discovery, baseUrl) {
+  return stringValue(discovery, ['api', 'mcp', 'url'])
+    ?? stringValue(discovery, ['urls', 'mcp'])
+    ?? endpointUrl(baseUrl, '/mcp');
+}
+
+export function agentDiscoveryClientIds(discovery) {
+  const clients = Array.isArray(discovery?.clients) ? discovery.clients : [];
+  const ids = clients
+    .filter((client) => isPlainObject(client) && typeof client.id === 'string')
+    .map((client) => client.id);
+  if (ids.length > 0) {
+    return ids;
+  }
+  const supported = arrayValue(discovery, ['supported_clients']);
+  return supported ?? [];
+}
+
+export function discoveryMcpClients(discovery) {
+  const clients = discovery?.clients?.mcp;
+  if (!Array.isArray(clients)) {
+    return [];
+  }
+
+  return clients
+    .filter((client) => isPlainObject(client) && typeof client.id === 'string')
+    .map((client) => ({
+      id: client.id,
+      configEndpoint: typeof client.config_endpoint === 'string' ? client.config_endpoint : null
+    }));
+}
+
+