refresh-cv 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# refresh-cv
+
+Install the refresh.cv MCP server for supported agent clients.
+
+## Codex
+
+```bash
+npx -y refresh-cv@latest --client codex
+```
+
+This configures Codex with:
+
+```text
+https://mcp.refresh.cv/mcp
+```
+
+Then it starts the Codex OAuth login flow.
+
+For dev:
+
+```bash
+npx -y refresh-cv@latest --client codex --dev
+```
+
+## Options
+
+- `--client codex`: configure Codex.
+- `--dev`: use `https://mcp.dev.refresh.cv/mcp`.
+- `--url <url>`: override the MCP endpoint.
+- `--name <name>`: override the Codex MCP server name. Defaults to `refresh_cv`.
+- `--force`: replace an existing Codex MCP server with the same name.
+- `--skip-login`: add the MCP server but skip OAuth login.

package/bin/refresh-cv.js

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const PACKAGE_VERSION = '0.1.0';
+const PRODUCTION_MCP_URL = 'https://mcp.refresh.cv/mcp';
+const DEV_MCP_URL = 'https://mcp.dev.refresh.cv/mcp';
+const DEFAULT_SERVER_NAME = 'refresh_cv';
+const SIMPLE_TOML_KEY = /^[A-Za-z0-9_-]+$/;
+
+const HELP = `refresh.cv MCP installer
+
+Usage:
+  npx -y refresh-cv@latest --client codex [options]
+
+Options:
+  --client <client>       Agent client to configure. Currently supports: codex
+  --dev                   Use the dev MCP endpoint (${DEV_MCP_URL})
+  --url <url>             Override the MCP endpoint URL
+  --name <name>           Codex MCP server name (default: ${DEFAULT_SERVER_NAME})
+  --force                 Replace an existing Codex MCP server with the same name
+  --skip-login            Add the server but do not run "codex mcp login"
+  --version               Show this installer version
+  --help                  Show this help message
+
+Examples:
+  npx -y refresh-cv@latest --client codex
+  npx -y refresh-cv@latest --client codex --dev
+`;
+
+main().catch((error) => {
+  fail(error instanceof Error ? error.message : String(error));
+});
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    console.log(HELP);
+    return;
+  }
+
+  if (options.version) {
+    console.log(PACKAGE_VERSION);
+    return;
+  }
+
+  if (!options.client) {
+    fail('Missing --client. Use: npx -y refresh-cv@latest --client codex');
+  }
+
+  if (options.client !== 'codex') {
+    fail(
+      `Unsupported client "${options.client}". This installer currently supports: codex.`,
+    );
+  }
+
+  const serverName = options.name ?? DEFAULT_SERVER_NAME;
+  const mcpUrl =
+    options.url ?? (options.dev ? DEV_MCP_URL : PRODUCTION_MCP_URL);
+
+  assertValidServerName(serverName);
+  assertValidMcpUrl(mcpUrl);
+  assertCommandAvailable('codex');
+
+  const existing = getCodexMcp(serverName);
+  if (existing.exists) {
+    const existingUrl = existing.url;
+    if (existingUrl === mcpUrl) {
+      console.log(
+        `refresh.cv MCP is already configured for Codex as "${serverName}".`,
+      );
+    } else if (options.force && options.skipLogin) {
+      writeCodexMcpConfig(serverName, mcpUrl);
+    } else if (options.force) {
+      runCodex(['mcp', 'remove', serverName], {
+        errorMessage: `Failed to remove existing Codex MCP server "${serverName}".`,
+      });
+      await addCodexMcp(serverName, mcpUrl, options);
+    } else {
+      fail(
+        `Codex MCP server "${serverName}" already exists with URL ${existingUrl || '(unknown)'}.\n` +
+          `Use --force to replace it, or choose a different --name.`,
+      );
+    }
+  } else if (options.skipLogin) {
+    writeCodexMcpConfig(serverName, mcpUrl);
+  } else {
+    await addCodexMcp(serverName, mcpUrl, options);
+  }
+
+  if (options.skipLogin) {
+    console.log(
+      `Skipped login. Run this when ready: codex mcp login ${serverName}`,
+    );
+    return;
+  }
+
+  if (options.loginStartedDuringAdd) {
+    console.log(
+      `Codex started the OAuth login flow for "${serverName}". Finish the browser approval if prompted.`,
+    );
+    return;
+  }
+
+  console.log(`Opening Codex OAuth login for "${serverName}"...`);
+  await runCodexStreaming(['mcp', 'login', serverName], {
+    errorMessage: `Codex login did not complete. Retry with: codex mcp login ${serverName}`,
+  });
+}
+
+function parseArgs(args) {
+  const options = {
+    client: undefined,
+    dev: false,
+    force: false,
+    help: false,
+    loginStartedDuringAdd: false,
+    name: undefined,
+    skipLogin: false,
+    url: undefined,
+    version: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    const [flag, inlineValue] = arg.includes('=') ? arg.split(/=(.*)/s, 2) : [];
+
+    switch (arg) {
+      case '--client':
+        options.client = readValue(args, ++index, '--client').toLowerCase();
+        break;
+      case '--dev':
+        options.dev = true;
+        break;
+      case '--force':
+        options.force = true;
+        break;
+      case '--help':
+      case '-h':
+        options.help = true;
+        break;
+      case '--name':
+        options.name = readValue(args, ++index, '--name');
+        break;
+      case '--skip-login':
+      case '--no-login':
+        options.skipLogin = true;
+        break;
+      case '--url':
+        options.url = readValue(args, ++index, '--url');
+        break;
+      case '--version':
+      case '-v':
+        options.version = true;
+        break;
+      default:
+        if (flag === '--client') {
+          options.client = readInlineValue(
+            inlineValue,
+            '--client',
+          ).toLowerCase();
+          break;
+        }
+        if (flag === '--name') {
+          options.name = readInlineValue(inlineValue, '--name');
+          break;
+        }
+        if (flag === '--url') {
+          options.url = readInlineValue(inlineValue, '--url');
+          break;
+        }
+        fail(`Unknown option "${arg}".\n\n${HELP}`);
+    }
+  }
+
+  return options;
+}
+
+function readValue(args, index, flag) {
+  const value = args[index];
+  if (!value || value.startsWith('--')) {
+    fail(`Missing value for ${flag}.`);
+  }
+  return value;
+}
+
+function readInlineValue(value, flag) {
+  if (!value) {
+    fail(`Missing value for ${flag}.`);
+  }
+  return value;
+}
+
+function assertValidServerName(value) {
+  if (!SIMPLE_TOML_KEY.test(value)) {
+    fail(
+      'Codex MCP server name may only contain letters, numbers, underscores, and hyphens.',
+    );
+  }
+}
+
+function assertValidMcpUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    fail(`Invalid MCP URL: ${value}`);
+  }
+
+  if (parsed.protocol !== 'https:' && parsed.hostname !== 'localhost') {
+    fail('MCP URL must use https, except localhost development URLs.');
+  }
+
+  if (parsed.pathname !== '/mcp') {
+    fail('MCP URL must point to the /mcp endpoint.');
+  }
+}
+
+function assertCommandAvailable(command) {
+  const result = spawnSync(command, ['--version'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.error?.code === 'ENOENT') {
+    fail(
+      `Could not find "${command}" in PATH. Install Codex first, then rerun this command.`,
+    );
+  }
+  if (result.status !== 0) {
+    fail(
+      `Could not run "${command} --version". ${formatCommandOutput(result)}`,
+    );
+  }
+}
+
+function getCodexMcp(serverName) {
+  const result = spawnSync('codex', ['mcp', 'get', serverName, '--json'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  if (result.status !== 0) {
+    return { exists: false, url: undefined };
+  }
+
+  try {
+    const parsed = JSON.parse(result.stdout);
+    return {
+      exists: true,
+      url:
+        parsed?.transport?.type === 'streamable_http'
+          ? parsed.transport.url
+          : undefined,
+    };
+  } catch {
+    return { exists: true, url: undefined };
+  }
+}
+
+async function addCodexMcp(serverName, mcpUrl, options) {
+  console.log(`Adding refresh.cv MCP to Codex as "${serverName}"...`);
+  const result = await runCodexStreaming(
+    ['mcp', 'add', serverName, '--url', mcpUrl],
+    {
+      errorMessage: 'Failed to add refresh.cv MCP to Codex.',
+    },
+  );
+
+  if (codexAddStartedOAuth(result.output)) {
+    options.loginStartedDuringAdd = true;
+  }
+}
+
+function runCodex(args, { errorMessage }) {
+  const result = spawnSync('codex', args, { stdio: 'inherit' });
+  if (result.error?.code === 'ENOENT') {
+    fail('Could not find "codex" in PATH.');
+  }
+  if (result.status !== 0) {
+    fail(errorMessage);
+  }
+}
+
+function runCodexStreaming(args, { errorMessage }) {
+  return new Promise((resolve) => {
+    const child = spawn('codex', args, { stdio: ['inherit', 'pipe', 'pipe'] });
+    let output = '';
+
+    child.stdout.on('data', (chunk) => {
+      const text = chunk.toString();
+      output += text;
+      process.stdout.write(text);
+    });
+    child.stderr.on('data', (chunk) => {
+      const text = chunk.toString();
+      output += text;
+      process.stderr.write(text);
+    });
+    child.on('error', (error) => {
+      if (error.code === 'ENOENT') {
+        fail('Could not find "codex" in PATH.');
+      }
+      fail(`${errorMessage} ${error.message}`);
+    });
+    child.on('close', (status) => {
+      if (status !== 0) {
+        fail(errorMessage);
+      }
+      resolve({ status, output });
+    });
+  });
+}
+
+function codexAddStartedOAuth(output) {
+  return (
+    output.includes('Detected OAuth support') ||
+    output.includes('Starting OAuth flow') ||
+    output.includes('Authorize `')
+  );
+}
+
+function writeCodexMcpConfig(serverName, mcpUrl) {
+  const codexHome = process.env.CODEX_HOME || join(homedir(), '.codex');
+  const configPath = join(codexHome, 'config.toml');
+  mkdirSync(codexHome, { recursive: true });
+
+  const current = existsSync(configPath)
+    ? readFileSync(configPath, 'utf8')
+    : '';
+  const next = `${removeCodexMcpSection(current, serverName).trimEnd()}
+
+[mcp_servers.${serverName}]
+url = ${tomlString(mcpUrl)}
+`;
+
+  writeFileSync(configPath, next.trimStart());
+  console.log(`Configured refresh.cv MCP for Codex as "${serverName}".`);
+}
+
+function removeCodexMcpSection(config, serverName) {
+  const lines = config.split(/\r?\n/);
+  const output = [];
+  let skipping = false;
+  const sectionPrefix = `[mcp_servers.${serverName}`;
+
+  for (const line of lines) {
+    const header = line.trim().match(/^\[[^\]]+\]$/)?.[0];
+    if (header) {
+      skipping = header.startsWith(sectionPrefix);
+    }
+    if (!skipping) {
+      output.push(line);
+    }
+  }
+
+  return output.join('\n');
+}
+
+function tomlString(value) {
+  return JSON.stringify(value);
+}
+
+function formatCommandOutput(result) {
+  return [result.stderr, result.stdout].filter(Boolean).join('\n').trim();
+}
+
+function fail(message) {
+  console.error(`refresh-cv: ${message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "refresh-cv",
+  "version": "0.1.0",
+  "description": "Install refresh.cv MCP connections for supported agent clients.",
+  "type": "module",
+  "bin": {
+    "refresh-cv": "bin/refresh-cv.js"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://refresh.cv",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/refresh-dev/refresh-mcp-server.git",
+    "directory": "packages/refresh-cv"
+  },
+  "bugs": {
+    "url": "https://github.com/refresh-dev/refresh-mcp-server/issues"
+  },
+  "keywords": [
+    "refresh.cv",
+    "mcp",
+    "codex",
+    "work-history",
+    "resume"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}