forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/mcp-config-renderer.js

@@ -0,0 +1,288 @@
+'use strict';
+
+/**
+ * Per-harness MCP config renderer.
+ *
+ * Renders a GENERIC MCP server descriptor into each harness's native MCP config,
+ * using read → merge → write (idempotent, preserves user/other servers). This
+ * replaces the old skip-if-exists behavior in setup, which silently refused to
+ * add a server whenever a config file already existed.
+ *
+ * Frozen descriptor interface (consumers build this shape; this module never
+ * references any specific server):
+ *
+ *   {
+ *     name: string,                       // server key
+ *     transport: 'stdio' | 'http',        // launch transport
+ *     command: string,                    // executable (stdio) / launcher
+ *     args: string[],                     // command arguments
+ *     envRefs: Record<string, string>,    // env var REFERENCES ('${VAR}') — never secrets
+ *   }
+ *
+ * `envRefs` values MUST be `${VAR}` reference strings; literal secrets are rejected.
+ * Each harness expands them per its own semantics:
+ *
+ *   - Claude : `.mcp.json`            (JSON `mcpServers` map)
+ *   - Cursor : `.cursor/mcp.json`     (JSON `mcpServers` map)
+ *   - Codex  : `.codex/config.toml`   (TOML `[mcp_servers.<name>]` tables)
+ *
+ * Dependency-free (no TOML lib) so it runs under `bun test` and the release gates.
+ *
+ * @module mcp-config-renderer
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const HARNESS_MCP_FILES = {
+  claude: '.mcp.json',
+  cursor: '.cursor/mcp.json',
+  codex: '.codex/config.toml',
+};
+
+const ENV_REF_PATTERN = /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;
+
+/** Thrown when an existing config file cannot be parsed — signals "do not overwrite". */
+class McpConfigParseError extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.name = 'McpConfigParseError';
+    this.cause = cause;
+  }
+}
+
+/**
+ * Validate + normalize a generic MCP server descriptor.
+ * @param {object} d
+ * @returns {{ name, transport, command, args, url, envRefs }}
+ */
+// MCP server names key an object entry and are written into JSON/TOML config, so
+// restrict them to a safe identifier charset (no dots/quotes/whitespace that could
+// break the TOML table header `[mcp_servers.<name>]` or collide on merge).
+const MCP_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+// Extracted so validateDescriptor stays under the cognitive-complexity gate.
+function validateEnvRefs(rawEnvRefs) {
+  const envRefs = rawEnvRefs && typeof rawEnvRefs === 'object' ? rawEnvRefs : {};
+  for (const [key, value] of Object.entries(envRefs)) {
+    if (typeof value !== 'string' || !ENV_REF_PATTERN.test(value)) {
+      throw new Error(
+        `MCP descriptor.envRefs.${key} must be a '\${VAR}' reference string, not a literal value`,
+      );
+    }
+  }
+  return envRefs;
+}
+
+function validateDescriptor(d) {
+  if (!d || typeof d !== 'object') {
+    throw new Error('MCP descriptor must be an object');
+  }
+  if (!d.name || typeof d.name !== 'string') {
+    throw new Error('MCP descriptor.name is required');
+  }
+  if (!MCP_NAME_PATTERN.test(d.name)) {
+    throw new Error(`MCP descriptor.name must match ${MCP_NAME_PATTERN} (got '${d.name}')`);
+  }
+  const transport = d.transport || 'stdio';
+  if (transport !== 'stdio' && transport !== 'http') {
+    throw new Error(`MCP descriptor.transport must be 'stdio' or 'http' (got ${transport})`);
+  }
+  const command = typeof d.command === 'string' ? d.command : '';
+  const args = Array.isArray(d.args) ? d.args.map(String) : [];
+  const url = typeof d.url === 'string' ? d.url : '';
+  // stdio launches a process (command/args); http connects to a url. Enforce the
+  // field each transport needs so the frozen descriptor can represent both.
+  if (transport === 'http' && !url) {
+    throw new Error("MCP descriptor.url is required for transport 'http'");
+  }
+  if (transport === 'stdio' && !command) {
+    throw new Error("MCP descriptor.command is required for transport 'stdio'");
+  }
+  const envRefs = validateEnvRefs(d.envRefs);
+  return { name: d.name, transport, command, args, url, envRefs };
+}
+
+/** Build the JSON server entry (Claude + Cursor share the `mcpServers` schema). */
+function toJsonServerEntry(descriptor) {
+  const d = validateDescriptor(descriptor);
+  const entry = {};
+  if (d.transport === 'http') {
+    entry.type = 'http';
+    entry.url = d.url;
+  } else {
+    if (d.command) entry.command = d.command;
+    if (d.args.length) entry.args = d.args;
+  }
+  if (Object.keys(d.envRefs).length) entry.env = { ...d.envRefs };
+  return entry;
+}
+
+/**
+ * Merge descriptors into an existing JSON MCP config string (read → merge → write).
+ * Preserves every server not named in `descriptors`.
+ * @param {string} existingText
+ * @param {object[]} descriptors
+ * @returns {string}
+ */
+function mergeJsonMcp(existingText, descriptors) {
+  let obj = {};
+  if (existingText && existingText.trim()) {
+    try {
+      obj = JSON.parse(existingText);
+    } catch (err) {
+      // DATA-LOSS GUARD: never silently discard a populated-but-unparseable config
+      // (e.g. Cursor JSONC with comments/trailing commas). Signal the caller so it
+      // can back up and skip instead of overwriting the user's servers.
+      throw new McpConfigParseError('existing MCP config is not valid JSON', err);
+    }
+  }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) obj = {};
+  if (!obj.mcpServers || typeof obj.mcpServers !== 'object') obj.mcpServers = {};
+  for (const descriptor of descriptors) {
+    const d = validateDescriptor(descriptor);
+    obj.mcpServers[d.name] = toJsonServerEntry(d);
+  }
+  return JSON.stringify(obj, null, 2) + '\n';
+}
+
+function tomlString(value) {
+  return '"' + String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+
+function tomlArray(values) {
+  return '[' + values.map(tomlString).join(', ') + ']';
+}
+
+/** Render a single Codex `[mcp_servers.<name>]` TOML block (+ optional env table). */
+function renderCodexServerBlock(descriptor) {
+  const d = validateDescriptor(descriptor);
+  const lines = [`[mcp_servers.${d.name}]`];
+  if (d.transport === 'http') {
+    lines.push(`url = ${tomlString(d.url)}`);
+    lines.push('transport = "http"');
+  } else {
+    if (d.command) lines.push(`command = ${tomlString(d.command)}`);
+    lines.push(`args = ${tomlArray(d.args)}`);
+  }
+  let block = lines.join('\n') + '\n';
+  const envKeys = Object.keys(d.envRefs);
+  if (envKeys.length) {
+    block += `\n[mcp_servers.${d.name}.env]\n`;
+    for (const key of envKeys) {
+      block += `${key} = ${tomlString(d.envRefs[key])}\n`;
+    }
+  }
+  return block;
+}
+
+/** Remove a TOML section (header line through the line before the next `[section]`). */
+function stripTomlSection(text, header) {
+  const lines = String(text).split('\n');
+  const out = [];
+  let skipping = false;
+  for (const line of lines) {
+    const isHeader = line.trimStart().startsWith('[');
+    if (isHeader) {
+      if (line.trim() === header) {
+        skipping = true;
+        continue;
+      }
+      skipping = false;
+    }
+    if (!skipping) out.push(line);
+  }
+  return out.join('\n');
+}
+
+/**
+ * Merge descriptors into an existing Codex `config.toml` string (read → merge →
+ * write). Only the targeted `[mcp_servers.<name>]` (+ `.env`) sections are
+ * replaced; all other config is preserved. Idempotent.
+ * @param {string} existingText
+ * @param {object[]} descriptors
+ * @returns {string}
+ */
+function mergeCodexToml(existingText, descriptors) {
+  let text = existingText || '';
+  for (const descriptor of descriptors) {
+    const d = validateDescriptor(descriptor);
+    text = stripTomlSection(text, `[mcp_servers.${d.name}]`);
+    text = stripTomlSection(text, `[mcp_servers.${d.name}.env]`);
+  }
+  const preamble = text.replace(/\s+$/, '');
+  let result = preamble ? preamble + '\n\n' : '';
+  result += descriptors.map(renderCodexServerBlock).join('\n');
+  return result.replace(/\n{3,}/g, '\n\n').replace(/\s+$/, '') + '\n';
+}
+
+/**
+ * Copy `filePath` to a stable `<file>.bak` (then numbered `.bak.1`, `.2`, …) so a
+ * repeated back-up never clobbers an earlier snapshot. Mirrors the AGENTS.md
+ * markerless-backup behavior in lib/commands/setup.js.
+ * @param {string} filePath
+ * @returns {string} the backup path written
+ */
+function backupFile(filePath) {
+  let backupPath = `${filePath}.bak`;
+  if (fs.existsSync(backupPath)) {
+    let suffix = 1;
+    while (fs.existsSync(`${filePath}.bak.${suffix}`)) suffix += 1;
+    backupPath = `${filePath}.bak.${suffix}`;
+  }
+  fs.copyFileSync(filePath, backupPath);
+  return backupPath;
+}
+
+/**
+ * Render (merge) MCP descriptors into one harness's native config on disk.
+ * Read → merge → write. If the existing file cannot be parsed, it is BACKED UP and
+ * left untouched (never overwritten) to avoid destroying user-defined servers.
+ *
+ * @param {object} params
+ * @param {'claude'|'cursor'|'codex'} params.harness
+ * @param {string} params.targetRoot - Project root.
+ * @param {object[]} params.descriptors - Generic MCP server descriptors.
+ * @returns {{ file: string, existed: boolean, skipped: boolean, backup?: string }}
+ */
+function renderMcpConfig({ harness, targetRoot, descriptors }) {
+  const rel = HARNESS_MCP_FILES[harness];
+  if (!rel) throw new Error(`Unknown MCP harness: ${harness}`);
+  const filePath = path.join(targetRoot, rel);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const existed = fs.existsSync(filePath);
+  const existing = existed ? fs.readFileSync(filePath, 'utf-8') : '';
+
+  let merged;
+  try {
+    merged = harness === 'codex'
+      ? mergeCodexToml(existing, descriptors)
+      : mergeJsonMcp(existing, descriptors);
+  } catch (err) {
+    if (err instanceof McpConfigParseError && existed) {
+      const backup = backupFile(filePath);
+      console.warn(
+        `  ⚠ ${rel} is not valid JSON (comments/trailing commas?) — left untouched to ` +
+        `avoid data loss. Backed up to ${path.basename(backup)}; add the MCP server manually.`,
+      );
+      return { file: filePath, existed, skipped: true, backup };
+    }
+    throw err;
+  }
+
+  fs.writeFileSync(filePath, merged, 'utf-8');
+  return { file: filePath, existed, skipped: false };
+}
+
+module.exports = {
+  HARNESS_MCP_FILES,
+  McpConfigParseError,
+  validateDescriptor,
+  toJsonServerEntry,
+  mergeJsonMcp,
+  renderCodexServerBlock,
+  mergeCodexToml,
+  stripTomlSection,
+  backupFile,
+  renderMcpConfig,
+};

package/lib/memory/graphiti-mcp.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * @module memory/graphiti-mcp
+ *
+ * DATA-ONLY descriptor for the `graphiti-memory` MCP server. This module does
+ * NOT write any file — it defines the harness-agnostic server descriptor shape
+ * so a per-harness MCP renderer can materialize it into the right place for
+ * each agent. `forge setup` does this today for Claude (`.mcp.json`) and Cursor
+ * (`.cursor/mcp.json`) via `lib/mcp-config-renderer.js` when the memory backend
+ * resolves to `graphiti`. Forge never speaks to Graphiti at runtime; agents
+ * do, over MCP.
+ *
+ * LOCKED interface (consumed by the parity agent's MCP renderer):
+ *   { name, transport: 'stdio'|'http', command, args, envRefs }
+ * `envRefs` values are ALWAYS `${VAR}` reference strings — never literal keys or
+ * secrets — because each harness expands them differently and nothing sensitive
+ * may be baked into committed config.
+ *
+ * Design: docs/work/2026-07-06-graphiti-memory/research.md §1.7 / §2.2. The entry
+ * shape matches the Graphiti MCP server README (stdio transport, `uv run`).
+ */
+
+/**
+ * Documented recommended defaults for a fresh opt-in (FalkorDB + OpenAI-compatible).
+ *
+ * CONSUMED TODAY by `buildGraphitiServerDescriptor`: `transport`, `command`,
+ * `mcpServerPath`, `graphDb`, `apiKeyEnv`.
+ *
+ * RESERVED for the fast-follow MCP wiring (the per-harness renderer that turns
+ * this descriptor into concrete env values) — `dbUri`, `neo4jUri`, `llmProvider`,
+ * `model`, `groupId` have NO EFFECT until then: the descriptor emits `${VAR}`
+ * references, not these literal values. They are kept here (and documented) so
+ * the shape is stable when the renderer lands; setting them now is a no-op.
+ */
+const DEFAULTS = Object.freeze({
+  transport: 'stdio', // 'stdio' | 'http'   (consumed)
+  command: 'uv', //                          (consumed)
+  mcpServerPath: './graphiti/mcp_server', // (consumed)
+  graphDb: 'falkordb', // 'falkordb' | 'falkordb-lite' | 'neo4j'   (consumed)
+  apiKeyEnv: 'OPENAI_API_KEY', //            (consumed — emitted as ${OPENAI_API_KEY})
+  // --- reserved (no effect until the fast-follow MCP renderer) ---
+  dbUri: 'redis://localhost:6379', // documented default for the FalkorDB path
+  neo4jUri: 'bolt://localhost:7687',
+  llmProvider: 'openai',
+  model: 'gpt-5.5',
+  groupId: 'forge',
+});
+
+const SERVER_NAME = 'graphiti-memory';
+
+/** Build a `${VAR}` reference string. */
+function ref(name) {
+  return `\${${name}}`;
+}
+
+/**
+ * Build the harness-agnostic Graphiti MCP server descriptor.
+ *
+ * @param {object} [config] - Partial override of DEFAULTS (graphDb, apiKeyEnv,
+ *   mcpServerPath, transport, ...). Concrete secret/URI VALUES are never placed
+ *   here — only which env vars the server needs, as `${VAR}` references.
+ * @returns {{ name: string, transport: string, command: string, args: string[], envRefs: Object<string,string> }}
+ */
+function buildGraphitiServerDescriptor(config = {}) {
+  const c = { ...DEFAULTS, ...config };
+
+  const args = [
+    'run',
+    '--isolated',
+    '--directory',
+    c.mcpServerPath,
+    '--project',
+    '.',
+    'main.py',
+    '--transport',
+    c.transport,
+  ];
+
+  const envRefs = {};
+  if (c.graphDb === 'neo4j') {
+    envRefs.NEO4J_URI = ref('NEO4J_URI');
+    envRefs.NEO4J_USER = ref('NEO4J_USER');
+    envRefs.NEO4J_PASSWORD = ref('NEO4J_PASSWORD');
+  } else {
+    envRefs.FALKORDB_URI = ref('FALKORDB_URI');
+  }
+  // LLM key referenced by env-var NAME only — never inlined.
+  envRefs[c.apiKeyEnv] = ref(c.apiKeyEnv);
+  envRefs.MODEL_NAME = ref('MODEL_NAME');
+  envRefs.GROUP_ID = ref('GRAPHITI_GROUP_ID');
+
+  return {
+    name: SERVER_NAME,
+    transport: c.transport,
+    command: c.command,
+    args,
+    envRefs,
+  };
+}
+
+module.exports = {
+  DEFAULTS,
+  SERVER_NAME,
+  buildGraphitiServerDescriptor,
+};