cloudflare-mcp-smart-proxy 1.2.0 → 1.3.0

package/src/connector-bridge.js

@@ -0,0 +1,284 @@
+import os from 'os';
+import path from 'path';
+import { CloudClient } from './cloud-client.js';
+import { DeviceIdentity } from './device-identity.js';
+import { discoverProjectProbe } from './project-probe-discovery.js';
+import { detectIde, applyBrainSnapshot } from './ide-configurator.js';
+
+function normalizeString(value, fallback = '') {
+  const normalized = typeof value === 'string' ? value.trim() : '';
+  return normalized || fallback;
+}
+
+function defaultConnectorId() {
+  return `connector.${os.hostname().replace(/[^a-zA-Z0-9_.-]/g, '_')}.local`;
+}
+
+function defaultWorkspaceId(workspaceRoot) {
+  return `workspace.${path.basename(workspaceRoot || process.cwd()).replace(/[^a-zA-Z0-9_.-]/g, '_')}`;
+}
+
+function buildIdempotencyKey(...parts) {
+  return parts
+    .map((entry) => normalizeString(entry))
+    .filter(Boolean)
+    .join(':');
+}
+
+export class ConnectorBridge {
+  constructor({
+    cloudUrl,
+    cloudApiKey,
+    workspaceRoot,
+    clientProfileId,
+    connectorId,
+    connectorType,
+    workspaceId,
+    deviceIdentity = null,
+    cloudClient = null
+  }) {
+    this.workspaceRoot = workspaceRoot || process.cwd();
+    this.clientProfileId = normalizeString(clientProfileId);
+    this.connectorId = normalizeString(connectorId, defaultConnectorId());
+    this.connectorType = normalizeString(connectorType, 'smart_proxy');
+    this.workspaceId = normalizeString(workspaceId, defaultWorkspaceId(this.workspaceRoot));
+    this.deviceIdentity = deviceIdentity || new DeviceIdentity();
+    this.cloudClient = cloudClient || new CloudClient({
+      cloudUrl,
+      cloudApiKey,
+      deviceIdentity: this.deviceIdentity
+    });
+    this.state = {
+      initializedAt: Date.now(),
+      lastWorkspaceGrant: null,
+      lastInstallPlan: null,
+      lastStatusReport: null,
+      lastProjectProbe: null,
+      lastGeneratedContextPack: null,
+      lastSyncAt: null,
+      lastProjectProbeReportAt: null,
+      lastError: null
+    };
+  }
+
+  isConfigured() {
+    return Boolean(this.clientProfileId);
+  }
+
+  getBridgeStatus() {
+    return {
+      objectType: 'connector_bridge_status',
+      configured: this.isConfigured(),
+      clientProfileId: this.clientProfileId || null,
+      connectorId: this.connectorId,
+      connectorType: this.connectorType,
+      workspaceId: this.workspaceId,
+      workspaceRoot: this.workspaceRoot,
+      state: this.state
+    };
+  }
+
+  async initialize({
+    autoSyncProfile = true,
+    autoApplyBrain = true,
+    autoReportProjectProbe = false,
+    autoGenerateContextPack = false
+  } = {}) {
+    if (!this.isConfigured()) {
+      return this.getBridgeStatus();
+    }
+
+    try {
+      if (typeof this.cloudClient?.registerDevice === 'function') {
+        await this.ensureDeviceRegistration();
+      }
+      const canApplyBrain = autoApplyBrain && typeof this.cloudClient?.fetchBrainSnapshot === 'function';
+      if (canApplyBrain) {
+        try {
+          await this.applyBrain();
+        } catch (error) {
+          if (!autoSyncProfile) {
+            throw error;
+          }
+          await this.syncProfile();
+        }
+      } else if (autoSyncProfile) {
+        await this.syncProfile();
+      }
+      if (autoReportProjectProbe) {
+        await this.reportProjectProbe({ autoGenerateContextPack });
+      }
+    } catch (error) {
+      this.state.lastError = error.message;
+    }
+    return this.getBridgeStatus();
+  }
+
+  async ensureDeviceRegistration() {
+    const identity = await this.deviceIdentity.loadOrCreate();
+    const response = await this.cloudClient.registerDevice({
+      deviceId: identity.deviceId,
+      publicKeyJwk: identity.publicKeyJwk,
+      clientProfileId: this.clientProfileId || null,
+      connectorId: this.connectorId,
+      workspaceId: this.workspaceId,
+      label: `${this.connectorType}:${os.hostname()}`
+    });
+    this.state.deviceBinding = response?.deviceBinding || null;
+    this.state.device = response?.device || null;
+    return response;
+  }
+
+  /**
+   * Fetch the brain snapshot from the cloud and apply it to the local IDE.
+   * This is the core of the "cerebral cortex" flow:
+   *   admin configures skills/rules/backends → connector detects IDE → applies natively.
+   */
+  async applyBrain() {
+    if (!this.isConfigured()) {
+      throw new Error('client profile id is required for brain apply');
+    }
+
+    const snapshotResponse = await this.cloudClient.fetchBrainSnapshot({
+      clientProfileId: this.clientProfileId,
+      workspaceId: this.workspaceId
+    });
+    const snapshot = snapshotResponse?.brainSnapshot;
+    if (!snapshot) {
+      throw new Error('brain snapshot returned empty response');
+    }
+
+    this.state.lastBrainSnapshot = snapshot;
+    this.state.lastBrainAppliedAt = Date.now();
+
+    const ide = detectIde(this.workspaceRoot);
+    const applyResult = await applyBrainSnapshot(snapshot, this.workspaceRoot, ide);
+
+    this.state.lastBrainApplyResult = applyResult;
+    this.state.lastSyncAt = Date.now();
+    this.state.lastError = null;
+
+    return {
+      success: true,
+      ide,
+      applied: applyResult.applied,
+      meta: snapshot.meta
+    };
+  }
+
+  async syncProfile() {
+    if (!this.isConfigured()) {
+      throw new Error('client profile id is required for bridge sync');
+    }
+
+    const workspaceGrantResponse = await this.cloudClient.fetchWorkspaceGrant({
+      clientProfileId: this.clientProfileId,
+      workspaceId: this.workspaceId,
+      connectorId: this.connectorId
+    });
+    this.state.lastWorkspaceGrant = workspaceGrantResponse?.workspaceGrant || null;
+
+    const installPlanResponse = await this.cloudClient.fetchInstallPlan({
+      clientProfileId: this.clientProfileId,
+      workspaceId: this.workspaceId
+    });
+    this.state.lastInstallPlan = installPlanResponse?.installPlan || null;
+
+    const statusReportsResponse = await this.cloudClient.listConnectorStatusReports({
+      clientProfileId: this.clientProfileId,
+      workspaceId: this.workspaceId,
+      connectorId: this.connectorId,
+      limit: 5
+    });
+    this.state.lastStatusReport = Array.isArray(statusReportsResponse?.connectorStatusReports)
+      ? (statusReportsResponse.connectorStatusReports[0] || null)
+      : null;
+    this.state.lastSyncAt = Date.now();
+
+    this.state.lastError = null;
+    return {
+      success: true,
+      workspaceGrant: this.state.lastWorkspaceGrant,
+      installPlan: this.state.lastInstallPlan,
+      lastStatusReport: this.state.lastStatusReport
+    };
+  }
+
+  async reportStatus({
+    status = 'succeeded',
+    summary = {},
+    operationResults = [],
+    issues = []
+  } = {}) {
+    if (!this.isConfigured()) {
+      throw new Error('client profile id is required for status reporting');
+    }
+
+    const report = {
+      idempotencyKey: buildIdempotencyKey(
+        'status_report',
+        this.clientProfileId,
+        this.workspaceId,
+        this.connectorId,
+        this.state.lastInstallPlan?.id || 'no-plan',
+        status
+      ),
+      connectorId: this.connectorId,
+      connectorType: this.connectorType,
+      workspaceId: this.workspaceId,
+      installPlanId: this.state.lastInstallPlan?.id || null,
+      status,
+      summary,
+      operationResults,
+      issues
+    };
+
+    const response = await this.cloudClient.createConnectorStatusReport({
+      clientProfileId: this.clientProfileId,
+      report
+    });
+    this.state.lastStatusReport = response?.connectorStatusReport || null;
+    this.state.lastError = null;
+    return response;
+  }
+
+  async discoverProjectProbe() {
+    const probe = await discoverProjectProbe({
+      workspaceRoot: this.workspaceRoot,
+      workspaceId: this.workspaceId,
+      clientProfileId: this.clientProfileId || null,
+      connectorId: this.connectorId,
+      connectorType: this.connectorType
+    });
+    this.state.lastProjectProbe = probe;
+    return probe;
+  }
+
+  async reportProjectProbe({ autoGenerateContextPack = false } = {}) {
+    if (!this.isConfigured()) {
+      throw new Error('client profile id is required for project probe reporting');
+    }
+
+    const probe = await this.discoverProjectProbe();
+    const probeWithIdempotency = {
+      ...probe,
+      idempotencyKey: buildIdempotencyKey(
+        'project_probe',
+        this.clientProfileId,
+        this.workspaceId,
+        this.connectorId,
+        probe.id || probe.repoName || 'workspace'
+      )
+    };
+    const response = await this.cloudClient.createProjectProbe({
+      clientProfileId: this.clientProfileId,
+      probe: probeWithIdempotency,
+      autoGenerateContextPack
+    });
+    this.state.lastProjectProbe = response?.projectProbe || probe;
+    this.state.lastGeneratedContextPack = response?.generatedContextPack || null;
+    this.state.lastProjectProbeReportAt = Date.now();
+    this.state.lastError = null;
+    return response;
+  }
+}

package/src/device-identity.js

@@ -0,0 +1,87 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { webcrypto } from 'crypto';
+
+const subtle = webcrypto.subtle;
+const DEVICE_SIGNATURE_VERSION = 'device_sig_v1';
+
+function bytesToBase64(bytes) {
+  return Buffer.from(bytes).toString('base64');
+}
+
+async function sha256Hex(value) {
+  const digest = await subtle.digest('SHA-256', new TextEncoder().encode(String(value || '')));
+  return Buffer.from(digest).toString('hex');
+}
+
+function defaultIdentityPath() {
+  return path.join(os.homedir(), '.cloudmcp', 'device-identity.json');
+}
+
+function ensureParent(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+export class DeviceIdentity {
+  constructor({ identityPath = defaultIdentityPath() } = {}) {
+    this.identityPath = identityPath;
+    this.record = null;
+    this.privateKey = null;
+  }
+
+  async loadOrCreate() {
+    if (this.record && this.privateKey) return this.record;
+    if (fs.existsSync(this.identityPath)) {
+      this.record = JSON.parse(fs.readFileSync(this.identityPath, 'utf8'));
+    } else {
+      const keyPair = await subtle.generateKey(
+        { name: 'ECDSA', namedCurve: 'P-256' },
+        true,
+        ['sign', 'verify']
+      );
+      this.record = {
+        deviceId: `dev_${crypto.randomUUID()}`,
+        publicKeyJwk: await subtle.exportKey('jwk', keyPair.publicKey),
+        privateKeyJwk: await subtle.exportKey('jwk', keyPair.privateKey),
+        createdAt: Date.now()
+      };
+      ensureParent(this.identityPath);
+      fs.writeFileSync(this.identityPath, `${JSON.stringify(this.record, null, 2)}\n`, { mode: 0o600 });
+    }
+    this.privateKey = await subtle.importKey(
+      'jwk',
+      this.record.privateKeyJwk,
+      { name: 'ECDSA', namedCurve: 'P-256' },
+      false,
+      ['sign']
+    );
+    return this.record;
+  }
+
+  async buildSignedHeaders({ method, pathname, body = '' }) {
+    const record = await this.loadOrCreate();
+    const timestamp = String(Date.now());
+    const nonce = crypto.randomUUID();
+    const bodyHash = await sha256Hex(body);
+    const canonical = [
+      DEVICE_SIGNATURE_VERSION,
+      String(method || 'GET').toUpperCase(),
+      pathname || '/',
+      bodyHash,
+      timestamp,
+      nonce
+    ].join('\n');
+    const signature = await subtle.sign(
+      { name: 'ECDSA', hash: 'SHA-256' },
+      this.privateKey,
+      new TextEncoder().encode(canonical)
+    );
+    return {
+      'X-CloudMCP-Device-ID': record.deviceId,
+      'X-CloudMCP-Device-Timestamp': timestamp,
+      'X-CloudMCP-Device-Nonce': nonce,
+      'X-CloudMCP-Device-Signature': bytesToBase64(signature)
+    };
+  }
+}

package/src/ide-configurator.js

@@ -0,0 +1,316 @@
+/**
+ * ide-configurator.js
+ *
+ * Detects which IDE the connector is running inside, then applies
+ * a brain snapshot natively (rules files, MCP server config, context files).
+ *
+ * Supported IDEs:
+ *   codex        — Codex CLI (~/.codex/config.toml)
+ *   cursor       — Cursor editor  (.cursor/rules + ~/.cursor/mcp.json)
+ *   claude_code  — Claude Code (.mcp.json / ~/.claude.json)
+ *   claude       — Claude Desktop legacy (~/Library/…/claude_desktop_config.json)
+ *   vscode       — VS Code Copilot (.github/copilot-instructions.md + .vscode/mcp.json)
+ *   unknown      — fallback: only write project-local files if possible
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { mergeCodexConfig, mergeClaudeCodeConfig } from './reference-connectors.js';
+
+// ── IDE detection ─────────────────────────────────────────────────────────────
+
+/**
+ * Returns the IDE identifier string.
+ * Priority: explicit env override → process/env signals → filesystem signals.
+ */
+export function detectIde(workspaceRoot) {
+  // 1. Explicit override from env (useful in non-standard setups)
+  const override = (process.env.CLOUDMCP_IDE || '').trim().toLowerCase();
+  if (['codex', 'cursor', 'claude_code', 'claude', 'vscode'].includes(override)) {
+    return override;
+  }
+
+  // 2. Codex-specific env vars should win over the VSCode host shell it often runs inside
+  if (_isCodex()) return 'codex';
+
+  // 3. Claude Code project markers
+  if (_isClaudeCode(workspaceRoot)) return 'claude_code';
+
+  // 4. VSCode family: reliable env var
+  if (process.env.VSCODE_PID || process.env.VSCODE_IPC_HOOK || process.env.TERM_PROGRAM === 'vscode') {
+    // Distinguish Cursor (a VSCode fork) from vanilla VSCode
+    if (_isCursor()) return 'cursor';
+    return 'vscode';
+  }
+
+  // 5. Cursor-specific env vars (set by Cursor launcher)
+  if (_isCursor()) return 'cursor';
+
+  // 6. Claude Desktop legacy — checks parent process name or known env var
+  if (process.env.CLAUDE_CONFIG_DIR || process.env.CLAUDE_DESKTOP_APP) {
+    return 'claude';
+  }
+
+  // 7. Filesystem heuristic: if workspace has a .cursor directory, assume Cursor
+  if (workspaceRoot && fs.existsSync(path.join(workspaceRoot, '.cursor'))) {
+    return 'cursor';
+  }
+
+  // 8. Fallback
+  return 'unknown';
+}
+
+function _isCodex() {
+  return !!(
+    process.env.CODEX_CI ||
+    process.env.CODEX_THREAD_ID ||
+    process.env.CODEX_HOME ||
+    (process.env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE || '').toLowerCase().includes('codex')
+  );
+}
+
+function _isCursor() {
+  return !!(
+    process.env.CURSOR_TRACE ||
+    process.env.CURSOR_CHANNEL ||
+    process.env.CURSOR_SESSION_ID ||
+    // Cursor sets GIT_ASKPASS to a cursor-specific binary
+    (process.env.GIT_ASKPASS || '').toLowerCase().includes('cursor')
+  );
+}
+
+function _isClaudeCode(workspaceRoot) {
+  return !!(
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.env.CLAUDE_CODE_ENTRYPOINT ||
+    (workspaceRoot && fs.existsSync(path.join(workspaceRoot, '.claude')))
+  );
+}
+
+// ── Brain snapshot application ────────────────────────────────────────────────
+
+/**
+ * Apply a brain snapshot to the detected IDE.
+ * Returns a summary of what was written.
+ */
+export async function applyBrainSnapshot(snapshot, workspaceRoot, ide = null) {
+  const detectedIde = ide || detectIde(workspaceRoot);
+  const results = [];
+
+  switch (detectedIde) {
+    case 'codex':
+      results.push(..._applyCodex(snapshot, workspaceRoot));
+      break;
+    case 'cursor':
+      results.push(..._applyCursor(snapshot, workspaceRoot));
+      break;
+    case 'claude_code':
+      results.push(..._applyClaudeCode(snapshot, workspaceRoot));
+      break;
+    case 'claude':
+      results.push(..._applyClaude(snapshot, workspaceRoot));
+      break;
+    case 'vscode':
+      results.push(..._applyVSCode(snapshot, workspaceRoot));
+      break;
+    default:
+      // Unknown IDE: write project-local files only (no global config touched)
+      results.push(..._applyLocal(snapshot, workspaceRoot));
+      break;
+  }
+
+  return { ide: detectedIde, applied: results };
+}
+
+// ── Codex ─────────────────────────────────────────────────────────────────────
+
+function _applyCodex(snapshot, workspaceRoot) {
+  const results = [];
+  const mcpServers = snapshot.mcpServers || {};
+
+  if (Object.keys(mcpServers).length > 0) {
+    const configDir = path.join(os.homedir(), '.codex');
+    const configFile = path.join(configDir, 'config.toml');
+    _ensureDir(configFile);
+    let content = fs.existsSync(configFile) ? fs.readFileSync(configFile, 'utf8') : '';
+    for (const [serverName, serverDefinition] of Object.entries(mcpServers)) {
+      content = mergeCodexConfig(content, serverName, {
+        ...serverDefinition,
+        enabled: serverDefinition?.enabled !== false
+      });
+    }
+    fs.writeFileSync(configFile, content, 'utf8');
+    results.push({ action: 'merged_mcp', file: configFile, count: Object.keys(mcpServers).length });
+  }
+
+  results.push(..._writeContextEntries(snapshot.contextEntries, workspaceRoot, '.cloudmcp/codex'));
+  return results;
+}
+
+// ── Cursor ────────────────────────────────────────────────────────────────────
+
+function _applyCursor(snapshot, workspaceRoot) {
+  const results = [];
+
+  // 1. System prompt → .cursor/rules/cloudmcp.md  (project-local, alwaysApply)
+  if (snapshot.systemPrompt) {
+    const rulesDir = path.join(workspaceRoot, '.cursor', 'rules');
+    _ensureDir(rulesDir);
+    const rulesFile = path.join(rulesDir, 'cloudmcp.md');
+    const content = [
+      '---',
+      'description: CloudMCP brain — auto-applied by connector, do not edit manually',
+      'alwaysApply: true',
+      '---',
+      '',
+      snapshot.systemPrompt
+    ].join('\n');
+    fs.writeFileSync(rulesFile, content, 'utf8');
+    results.push({ action: 'wrote', file: rulesFile });
+  }
+
+  // 2. Additional MCP backends → merge into ~/.cursor/mcp.json
+  //    (the proxy itself is already registered; this adds extra backends from the profile)
+  const mcpServers = snapshot.mcpServers || {};
+  if (Object.keys(mcpServers).length > 0) {
+    const cursorConfigDir = path.join(os.homedir(), '.cursor');
+    _ensureDir(cursorConfigDir);
+    const mcpFile = path.join(cursorConfigDir, 'mcp.json');
+    const existing = _readJson(mcpFile, { mcpServers: {} });
+    existing.mcpServers = { ...(existing.mcpServers || {}), ...mcpServers };
+    fs.writeFileSync(mcpFile, JSON.stringify(existing, null, 2), 'utf8');
+    results.push({ action: 'merged_mcp', file: mcpFile, count: Object.keys(mcpServers).length });
+  }
+
+  // 3. Context entries → .cursor/context/cloudmcp-context.md
+  results.push(..._writeContextEntries(snapshot.contextEntries, workspaceRoot, '.cursor/context'));
+
+  return results;
+}
+
+// ── Claude Code ───────────────────────────────────────────────────────────────
+
+function _applyClaudeCode(snapshot, workspaceRoot) {
+  const results = [];
+  const mcpServers = snapshot.mcpServers || {};
+
+  if (Object.keys(mcpServers).length > 0) {
+    const configFile = path.join(workspaceRoot, '.mcp.json');
+    const existing = _readJson(configFile, {});
+    let nextConfig = existing;
+    for (const [serverName, serverDefinition] of Object.entries(mcpServers)) {
+      nextConfig = mergeClaudeCodeConfig(nextConfig, serverName, serverDefinition);
+    }
+    _ensureDir(configFile);
+    fs.writeFileSync(configFile, JSON.stringify(nextConfig, null, 2), 'utf8');
+    results.push({ action: 'merged_mcp', file: configFile, count: Object.keys(mcpServers).length });
+  }
+
+  results.push(..._writeContextEntries(snapshot.contextEntries, workspaceRoot, '.cloudmcp/claude-code'));
+  return results;
+}
+
+// ── Claude Desktop ────────────────────────────────────────────────────────────
+
+function _applyClaude(snapshot, workspaceRoot) {
+  const results = [];
+
+  // Claude Desktop MCP config location
+  let configDir;
+  if (process.platform === 'darwin') {
+    configDir = path.join(os.homedir(), 'Library', 'Application Support', 'Claude');
+  } else if (process.platform === 'win32') {
+    configDir = path.join(process.env.APPDATA || os.homedir(), 'Claude');
+  } else {
+    configDir = path.join(os.homedir(), '.config', 'Claude');
+  }
+  _ensureDir(configDir);
+
+  // Merge MCP servers
+  const mcpServers = snapshot.mcpServers || {};
+  if (Object.keys(mcpServers).length > 0) {
+    const configFile = path.join(configDir, 'claude_desktop_config.json');
+    const existing = _readJson(configFile, { mcpServers: {} });
+    existing.mcpServers = { ...(existing.mcpServers || {}), ...mcpServers };
+    fs.writeFileSync(configFile, JSON.stringify(existing, null, 2), 'utf8');
+    results.push({ action: 'merged_mcp', file: configFile, count: Object.keys(mcpServers).length });
+  }
+
+  // Claude Desktop doesn't have a rules file; write context as project-local markdown
+  results.push(..._writeContextEntries(snapshot.contextEntries, workspaceRoot, '.cloudmcp'));
+
+  return results;
+}
+
+// ── VS Code Copilot ───────────────────────────────────────────────────────────
+
+function _applyVSCode(snapshot, workspaceRoot) {
+  const results = [];
+
+  // 1. System prompt → .github/copilot-instructions.md
+  if (snapshot.systemPrompt) {
+    const ghDir = path.join(workspaceRoot, '.github');
+    _ensureDir(ghDir);
+    const instructionsFile = path.join(ghDir, 'copilot-instructions.md');
+    fs.writeFileSync(instructionsFile, snapshot.systemPrompt, 'utf8');
+    results.push({ action: 'wrote', file: instructionsFile });
+  }
+
+  // 2. MCP servers → .vscode/mcp.json
+  const mcpServers = snapshot.mcpServers || {};
+  if (Object.keys(mcpServers).length > 0) {
+    const vscodeDir = path.join(workspaceRoot, '.vscode');
+    _ensureDir(vscodeDir);
+    const mcpFile = path.join(vscodeDir, 'mcp.json');
+    const existing = _readJson(mcpFile, { servers: {} });
+    // VSCode uses "servers" not "mcpServers"
+    existing.servers = { ...(existing.servers || {}), ...mcpServers };
+    fs.writeFileSync(mcpFile, JSON.stringify(existing, null, 2), 'utf8');
+    results.push({ action: 'merged_mcp', file: mcpFile, count: Object.keys(mcpServers).length });
+  }
+
+  // 3. Context entries
+  results.push(..._writeContextEntries(snapshot.contextEntries, workspaceRoot, '.vscode/cloudmcp'));
+
+  return results;
+}
+
+// ── Fallback (unknown IDE) ────────────────────────────────────────────────────
+
+function _applyLocal(snapshot, workspaceRoot) {
+  return _writeContextEntries(snapshot.contextEntries, workspaceRoot, '.cloudmcp');
+}
+
+// ── Shared helpers ────────────────────────────────────────────────────────────
+
+function _writeContextEntries(entries, workspaceRoot, subDir) {
+  if (!Array.isArray(entries) || entries.length === 0) return [];
+  const results = [];
+  const dir = path.join(workspaceRoot, subDir);
+  _ensureDir(dir);
+  const outFile = path.join(dir, 'context.md');
+  const lines = ['# CloudMCP Project Context', ''];
+  for (const entry of entries) {
+    if (!entry?.content) continue;
+    lines.push(`## ${entry.title || entry.entryId || 'Context'}`, '', entry.content, '');
+  }
+  fs.writeFileSync(outFile, lines.join('\n'), 'utf8');
+  results.push({ action: 'wrote', file: outFile, count: entries.length });
+  return results;
+}
+
+function _ensureDir(dir) {
+  const targetDir = path.extname(dir) ? path.dirname(dir) : dir;
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+}
+
+function _readJson(filePath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}