epicmerch-mcp 1.0.0

package/src/adapters/openapi.js

@@ -0,0 +1,97 @@
+// src/adapters/openapi.js
+import express from 'express';
+import { sessionTools, sessionToolDefs } from '../tools/session.js';
+import { developerTools, developerToolDefs } from '../tools/developer.js';
+import { scaffoldTools, scaffoldToolDefs } from '../tools/scaffold.js';
+import { merchantTools, merchantToolDefs } from '../tools/merchant.js';
+
+function buildOpenApiSpec(toolDefs, serverUrl) {
+  const paths = {};
+  for (const def of toolDefs) {
+    const properties = {};
+    const required = [];
+    for (const [key, schema] of Object.entries(def.schema || {})) {
+      properties[key] = { type: schema.type, description: schema.description || '' };
+      if (schema.required) required.push(key);
+    }
+    paths[`/tools/${def.name}`] = {
+      post: {
+        operationId: def.name,
+        summary: def.description,
+        requestBody: {
+          content: {
+            'application/json': {
+              schema: { type: 'object', properties, ...(required.length ? { required } : {}) },
+            },
+          },
+        },
+        responses: {
+          200: {
+            description: 'Tool result',
+            content: { 'application/json': { schema: { type: 'object' } } },
+          },
+        },
+      },
+    };
+  }
+
+  return {
+    openapi: '3.1.0',
+    info: { title: 'EpicMerch MCP Tools', version: '1.0.0', description: 'EpicMerch tools for Claude and ChatGPT' },
+    servers: [{ url: serverUrl || 'https://mcp.epicmerch.in' }],
+    paths,
+    components: {
+      securitySchemes: {
+        apiKey: { type: 'apiKey', in: 'header', name: 'x-api-key' },
+        bearerAuth: { type: 'http', scheme: 'bearer' },
+      },
+    },
+  };
+}
+
+export function buildOpenApiApp(session, client) {
+  const app = express();
+  app.use(express.json());
+
+  const allToolDefs = [...sessionToolDefs, ...developerToolDefs, ...scaffoldToolDefs, ...merchantToolDefs];
+  const allHandlers = {
+    ...sessionTools(session),
+    ...developerTools(client),
+    ...scaffoldTools(),
+    ...merchantTools(client, session),
+  };
+
+  // X-Store-Name header middleware — switches active store per request
+  app.use((req, _res, next) => {
+    const storeName = req.headers['x-store-name'];
+    if (storeName) {
+      try { session.switch(storeName); } catch (_) { /* ignore unknown store names */ }
+    }
+    next();
+  });
+
+  // Serve OpenAPI spec
+  app.get('/openapi.json', (req, res) => {
+    const host = `${req.protocol}://${req.get('host')}`;
+    res.json(buildOpenApiSpec(allToolDefs, host));
+  });
+
+  // Register tool endpoints
+  for (const def of allToolDefs) {
+    app.post(`/tools/${def.name}`, async (req, res) => {
+      try {
+        const result = await allHandlers[def.name](req.body || {});
+        res.json(result);
+      } catch (err) {
+        res.status(500).json({ isError: true, content: [{ type: 'text', text: err.message }] });
+      }
+    });
+  }
+
+  return app;
+}
+
+export function startOpenApiAdapter(session, client, port = 3101) {
+  const app = buildOpenApiApp(session, client);
+  app.listen(port, () => console.error(`[EpicMerch MCP] OpenAPI server listening on :${port}`));
+}

package/src/auth.js

@@ -0,0 +1,118 @@
+import { readTokenStore } from './token-store.js';
+
+export class Session {
+  #stores;
+  #active;
+  #apiUrl;
+  #jwts = new Map();
+  #authMode;
+  #tokenStore;
+
+  constructor({ stores, defaultStore, apiUrl, authMode = 'apikey', tokenStore = null }) {
+    if (!stores || Object.keys(stores).length === 0) {
+      throw new Error('At least one store must be configured in EPICMERCH_STORES');
+    }
+    this.#stores = { ...stores };
+    this.#active = defaultStore || Object.keys(stores)[0];
+    this.#apiUrl = (apiUrl || 'https://api.epicmerch.in/api').replace(/\/$/, '');
+    this.#authMode = authMode;
+    this.#tokenStore = tokenStore;
+
+    if (!(this.#active in this.#stores)) {
+      throw new Error(`Default store "${this.#active}" not found in EPICMERCH_STORES`);
+    }
+  }
+
+  activeStore() { return this.#active; }
+  getApiKey() { return this.#stores[this.#active]; }
+  getApiUrl() { return this.#apiUrl; }
+
+  getAuthMode() {
+    return this.#authMode;
+  }
+
+  getActiveTokenEntry() {
+    if (this.#authMode !== 'oauth' || !this.#tokenStore) return null;
+    const targetName = process.env.EPICMERCH_ACTIVE_STORE || this.#active;
+    return this.#tokenStore.stores[targetName] ?? null;
+  }
+
+  // Allow refresh.js to update the in-memory token store after a refresh
+  _updateTokenEntry(storeName, entry) {
+    if (this.#tokenStore?.stores) {
+      this.#tokenStore.stores[storeName] = entry;
+    }
+    if (this.#stores) {
+      this.#stores[storeName] = entry.accessToken;
+      // If this is the active store, getApiKey() now returns the new token
+    }
+  }
+
+  switch(name) {
+    if (!(name in this.#stores)) throw new Error(`Store "${name}" not configured`);
+    this.#active = name;
+  }
+
+  addStore(name, apiKey) {
+    this.#stores[name] = apiKey;
+  }
+
+  listStores() {
+    return Object.keys(this.#stores).map(name => ({
+      name,
+      active: name === this.#active,
+    }));
+  }
+
+  setJwt(storeName, jwt) { this.#jwts.set(storeName, jwt); }
+  getJwt(storeName) { return this.#jwts.get(storeName) ?? null; }
+  getActiveJwt() { return this.getJwt(this.#active); }
+
+  static parseStoresEnv(envString) {
+    if (!envString || !envString.trim()) {
+      throw new Error('EPICMERCH_STORES must not be empty');
+    }
+    return Object.fromEntries(
+      envString.split(',').map(pair => {
+        const eqIdx = pair.indexOf('=');
+        if (eqIdx === -1) throw new Error(`Invalid store entry (missing "="): "${pair.trim()}"`);
+        const name = pair.slice(0, eqIdx).trim();
+        const key = pair.slice(eqIdx + 1).trim();
+        if (!name || !key) throw new Error(`Invalid store entry (empty name or key): "${pair.trim()}"`);
+        return [name, key];
+      })
+    );
+  }
+
+  static fromEnv() {
+    // --- Prefer OAuth token file when present ---
+    let tokenStore = null;
+    try { tokenStore = readTokenStore(); } catch (_) { tokenStore = null; }
+
+    if (tokenStore && tokenStore.stores && Object.keys(tokenStore.stores).length > 0) {
+      // Build a name → accessToken map so getApiKey() returns the access token
+      const stores = Object.fromEntries(
+        Object.entries(tokenStore.stores).map(([name, e]) => [name, e.accessToken])
+      );
+      return new Session({
+        stores,
+        defaultStore: tokenStore.defaultStore || Object.keys(stores)[0],
+        apiUrl: process.env.EPICMERCH_API_URL || 'https://api.epicmerch.in/api',
+        authMode: 'oauth',
+        tokenStore,
+      });
+    }
+    // --- End token-file path ---
+
+    // Fallback: env-var API key mode
+    const storesEnv = process.env.EPICMERCH_STORES;
+    if (!storesEnv) throw new Error('EPICMERCH_STORES env var is required (format: name=key,name2=key2)');
+
+    return new Session({
+      stores: Session.parseStoresEnv(storesEnv),
+      defaultStore: process.env.EPICMERCH_DEFAULT_STORE,
+      apiUrl: process.env.EPICMERCH_API_URL,
+      authMode: 'apikey',
+    });
+  }
+}

package/src/client.js

@@ -0,0 +1,81 @@
+// src/client.js
+import { wrapWithRefresh } from './refresh.js';
+
+export class Client {
+  #session;
+  #request;
+
+  constructor(session) {
+    this.#session = session;
+
+    const rawRequest = async (endpoint, options = {}) => {
+      const url = `${this.#session.getApiUrl()}${endpoint}`;
+      // Re-evaluate headers on every call so a refreshed access token from
+      // wrapWithRefresh's retry actually goes on the wire. If headers is a
+      // function, call it now to pick up the freshly-updated session state.
+      const headers = typeof options.headers === 'function'
+        ? options.headers()
+        : options.headers;
+      const res = await fetch(url, { ...options, headers });
+      const data = await res.json();
+      if (!res.ok) {
+        const err = new Error(data.message || `API error ${res.status}`);
+        err.status = res.status;
+        throw err;
+      }
+      return data;
+    };
+
+    this.#request = wrapWithRefresh(rawRequest, session);
+  }
+
+  #baseHeaders() {
+    const headers = { 'Content-Type': 'application/json' };
+    const authMode = this.#session.getAuthMode?.();
+    if (authMode === 'oauth') {
+      const entry = this.#session.getActiveTokenEntry();
+      if (entry?.accessToken) {
+        headers['Authorization'] = `Bearer ${entry.accessToken}`;
+      }
+    } else {
+      headers['x-api-key'] = this.#session.getApiKey();
+    }
+    return headers;
+  }
+
+  #authHeaders() {
+    const jwt = this.#session.getActiveJwt();
+    return {
+      ...this.#baseHeaders(),
+      ...(jwt ? { Authorization: `Bearer ${jwt}` } : {}),
+    };
+  }
+
+  get(endpoint) {
+    return this.#request(endpoint, { headers: () => this.#baseHeaders() });
+  }
+
+  post(endpoint, body) {
+    return this.#request(endpoint, { method: 'POST', headers: () => this.#baseHeaders(), body: JSON.stringify(body) });
+  }
+
+  authGet(endpoint) {
+    return this.#request(endpoint, { headers: () => this.#authHeaders() });
+  }
+
+  authPost(endpoint, body) {
+    return this.#request(endpoint, { method: 'POST', headers: () => this.#authHeaders(), body: JSON.stringify(body) });
+  }
+
+  authPut(endpoint, body) {
+    return this.#request(endpoint, { method: 'PUT', headers: () => this.#authHeaders(), body: JSON.stringify(body) });
+  }
+
+  authDelete(endpoint) {
+    return this.#request(endpoint, { method: 'DELETE', headers: () => this.#authHeaders() });
+  }
+
+  authPatch(endpoint, body) {
+    return this.#request(endpoint, { method: 'PATCH', headers: () => this.#authHeaders(), body: JSON.stringify(body) });
+  }
+}

package/src/index.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// src/index.js
+import { login } from './login.js';
+import { logout } from './logout.js';
+import { status } from './status.js';
+import { install, setup } from './install.js';
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+
+  const storeFlag = argv.findIndex((a) => a === '--store');
+  const storeName = storeFlag >= 0 ? argv[storeFlag + 1] : 'default';
+
+  if (cmd === 'login') { await login({ storeName }); return; }
+  if (cmd === 'logout') { await logout({ storeName }); return; }
+  if (cmd === 'status') { await status(); return; }
+
+  if (cmd === 'install') {
+    const flagSet = new Set(argv);
+    const clientFlag = argv.findIndex((a) => a === '--client');
+    const clientName = clientFlag >= 0 ? argv[clientFlag + 1] : undefined;
+    const code = await install({
+      client: clientName,
+      yes: flagSet.has('--yes') || flagSet.has('-y'),
+      force: flagSet.has('--force'),
+      dryRun: flagSet.has('--dry-run'),
+      noSkills: flagSet.has('--no-skills'),
+    });
+    process.exit(code);
+    return;
+  }
+
+  if (cmd === 'setup') {
+    const code = await setup({ storeName });
+    process.exit(code);
+    return;
+  }
+
+  // No subcommand → start the MCP server (default behavior)
+  const { Session } = await import('./auth.js');
+  const { Client } = await import('./client.js');
+  const { startMcpAdapter } = await import('./adapters/mcp.js');
+  const { startOpenApiAdapter } = await import('./adapters/openapi.js');
+
+  const session = Session.fromEnv();
+  const client = new Client(session);
+
+  const mode = process.env.EPICMERCH_MODE || 'mcp';
+
+  if (mode === 'http') {
+    const port = parseInt(process.env.PORT || '3101', 10);
+    startOpenApiAdapter(session, client, port);
+  } else if (mode === 'both') {
+    const port = parseInt(process.env.PORT || '3101', 10);
+    startOpenApiAdapter(session, client, port);
+    await startMcpAdapter(session, client);
+  } else {
+    // Default: stdio MCP mode
+    await startMcpAdapter(session, client);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/src/install.js

@@ -0,0 +1,269 @@
+// src/install.js
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, copyFileSync } from 'fs';
+import { homedir, platform } from 'os';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const SERVER_NAME = 'epicmerch';
+const SERVER_CONFIG = { command: 'npx', args: ['epicmerch-mcp'] };
+
+// Resolve the directory of OUR bundled skills (~/.../packages/epicmerch-mcp/skills/)
+function bundledSkillsDir() {
+  const __dir = dirname(fileURLToPath(import.meta.url));
+  return join(__dir, '..', 'skills');
+}
+
+// Default install location for slash commands across Claude Code, Cursor, etc.
+function defaultCommandsDir() {
+  return join(homedir(), '.claude', 'commands');
+}
+
+/**
+ * Copy our bundled skill *.md files into ~/.claude/commands/ (or a
+ * specified dir). Skips files that already exist with identical content.
+ * @returns {{ installed: string[], skipped: string[], destDir: string }}
+ */
+export function installSkills(opts = {}) {
+  const srcDir = bundledSkillsDir();
+  const destDir = opts.destDir || defaultCommandsDir();
+  if (!existsSync(srcDir)) {
+    return { installed: [], skipped: [], destDir, error: `Bundled skills directory not found at ${srcDir}` };
+  }
+  mkdirSync(destDir, { recursive: true });
+
+  const installed = [];
+  const skipped = [];
+  const entries = readdirSync(srcDir).filter((f) => f.endsWith('.md'));
+  for (const name of entries) {
+    const src = join(srcDir, name);
+    const dst = join(destDir, name);
+    if (existsSync(dst) && !opts.force) {
+      const same = readFileSync(src, 'utf-8') === readFileSync(dst, 'utf-8');
+      if (same) { skipped.push(name); continue; }
+      if (!opts.force) { skipped.push(name); continue; } // don't overwrite without --force
+    }
+    copyFileSync(src, dst);
+    installed.push(name);
+  }
+  return { installed, skipped, destDir };
+}
+
+/**
+ * Detect installed MCP-aware clients on this machine.
+ * @returns {Array<{ client: 'claude'|'cursor', configPath: string }>}
+ */
+export function detectClients() {
+  const results = [];
+  const plat = platform();
+
+  const claudeDir =
+    plat === 'darwin' ? join(homedir(), 'Library', 'Application Support', 'Claude') :
+    plat === 'win32'  ? join(process.env.APPDATA || '', 'Claude') :
+                        join(homedir(), '.config', 'Claude');
+  if (claudeDir && existsSync(claudeDir)) {
+    results.push({ client: 'claude', configPath: join(claudeDir, 'claude_desktop_config.json') });
+  }
+
+  const cursorDir = join(homedir(), '.cursor');
+  if (existsSync(cursorDir)) {
+    results.push({ client: 'cursor', configPath: join(cursorDir, 'mcp.json') });
+  }
+
+  return results;
+}
+
+/**
+ * Merge an MCP server entry into a config object. Returns a new object.
+ * @param {object} config - Existing config object
+ * @param {string} serverName - Name of the server entry
+ * @param {object} serverConfig - Server config to inject
+ * @param {{ overwrite?: boolean }} opts
+ * @returns {object}
+ */
+export function mergeConfig(config, serverName, serverConfig, opts = {}) {
+  const out = { ...config };
+  out.mcpServers = { ...(out.mcpServers || {}) };
+  if (out.mcpServers[serverName] && !opts.overwrite) {
+    throw new Error(`'${serverName}' entry already exists in mcpServers. Use { overwrite: true } to replace.`);
+  }
+  out.mcpServers[serverName] = serverConfig;
+  return out;
+}
+
+/**
+ * Read existing config (if any), merge in desiredConfig, write back.
+ * @param {string} configPath - Absolute path to the JSON config file
+ * @param {object} desiredConfig - Config object to merge in
+ */
+export function writeConfigFile(configPath, desiredConfig) {
+  let existing = {};
+  if (existsSync(configPath)) {
+    let raw;
+    try { raw = readFileSync(configPath, 'utf-8'); }
+    catch (e) { throw new Error(`Cannot read ${configPath}: ${e.message}`); }
+    if (raw.trim()) {
+      try { existing = JSON.parse(raw); }
+      catch (e) { throw new Error(`Config at ${configPath} is corrupt JSON: ${e.message}`); }
+    }
+  } else {
+    mkdirSync(dirname(configPath), { recursive: true });
+  }
+  const merged = {
+    ...existing,
+    ...desiredConfig,
+    mcpServers: { ...(existing.mcpServers || {}), ...(desiredConfig.mcpServers || {}) },
+  };
+  writeFileSync(configPath, JSON.stringify(merged, null, 2) + '\n');
+}
+
+/**
+ * Top-level install: detect clients, prompt unless --yes, apply.
+ * @param {{ client?: string, yes?: boolean, force?: boolean, dryRun?: boolean }} opts
+ * @returns {Promise<number>} exit code
+ */
+export async function install(opts = {}) {
+  const clients = detectClients().filter((c) => !opts.client || c.client === opts.client);
+  if (clients.length === 0) {
+    console.error('No MCP-aware clients detected. Install Claude Desktop or Cursor first.');
+    return 1;
+  }
+
+  console.error('Detected clients:');
+  for (const c of clients) console.error(`  ✓ ${c.client.padEnd(8)} → ${c.configPath}`);
+  console.error('');
+
+  if (opts.dryRun) {
+    console.error('Dry-run: would write `epicmerch` entry to the above. No changes made.');
+    return 0;
+  }
+
+  if (!opts.yes) {
+    const isTTY = process.stdin.isTTY;
+    if (isTTY) {
+      const readline = await import('node:readline');
+      const answer = await new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        rl.question(`Add 'epicmerch' MCP server to all detected clients? [Y/n] `, (a) => { rl.close(); resolve(a.trim().toLowerCase()); });
+      });
+      if (answer && answer !== 'y' && answer !== 'yes') {
+        console.error('Cancelled.');
+        return 1;
+      }
+    }
+  }
+
+  for (const c of clients) {
+    try {
+      let existing = {};
+      if (existsSync(c.configPath)) {
+        const raw = readFileSync(c.configPath, 'utf-8').trim();
+        if (raw) existing = JSON.parse(raw);
+      }
+      const merged = mergeConfig(existing, SERVER_NAME, SERVER_CONFIG, { overwrite: opts.force });
+      writeConfigFile(c.configPath, merged);
+      console.error(`✓ Added to ${c.client}`);
+    } catch (e) {
+      if (/already exists/i.test(e.message) && !opts.force) {
+        console.error(`⚠ ${c.client}: entry already exists. Re-run with --force to overwrite.`);
+      } else {
+        console.error(`✗ ${c.client}: ${e.message}`);
+      }
+    }
+  }
+
+  // Also install slash commands (skills) unless explicitly opted out
+  if (!opts.noSkills) {
+    const result = installSkills({ force: opts.force });
+    if (result.error) {
+      console.error(`\n⚠ Skill install: ${result.error}`);
+    } else {
+      console.error('');
+      if (result.installed.length > 0) {
+        console.error(`✓ Installed ${result.installed.length} slash command(s) to ${result.destDir}:`);
+        for (const f of result.installed) console.error(`    /${f.replace(/\.md$/, '')}`);
+      }
+      if (result.skipped.length > 0) {
+        console.error(`  (${result.skipped.length} skill(s) already up to date — pass --force to overwrite)`);
+      }
+    }
+  }
+
+  console.error('');
+  console.error('Next:');
+  console.error('  1. Run `npx epicmerch-mcp login` to authenticate (if you haven\'t already).');
+  console.error('  2. Restart Claude Desktop / Cursor / VS Code for the config to take effect.');
+  return 0;
+}
+
+/**
+ * One-shot onboarding: login (skipped if already authed) → install
+ * (MCP config + slash commands). The merchant-friendly path; no
+ * filesystem knowledge required.
+ *
+ * @param {{ storeName?: string, force?: boolean }} opts
+ * @returns {Promise<number>} exit code
+ */
+export async function setup(opts = {}) {
+  const storeName = opts.storeName || 'default';
+  console.error('━━━ EpicMerch setup ━━━');
+  console.error('');
+
+  // --- Step 1: Login (skipped if a valid token already exists) ---
+  // ESM dynamic import of an ESM-mocked token-store needs the same module specifier
+  // as the test mocks; the helper above uses createRequire under the hood when needed.
+  const skipLogin = await import('./token-store.js').then(async (m) => {
+    try {
+      const data = m.readTokenStore();
+      const entry = data?.stores?.[data?.defaultStore];
+      return entry && new Date(entry.refreshTokenExpiresAt) > new Date();
+    } catch (_) { return false; }
+  });
+
+  if (skipLogin) {
+    console.error('Step 1/2: ✓ Already authenticated (skipping browser login).');
+  } else {
+    console.error('Step 1/2: Authenticating via browser…');
+    console.error('');
+    try {
+      const { login } = await import('./login.js');
+      await login({ storeName });
+    } catch (e) {
+      console.error('');
+      console.error(`✗ Login failed: ${e.message}`);
+      console.error('  Re-run \`npx epicmerch-mcp setup\` to try again.');
+      return 1;
+    }
+  }
+
+  // --- Step 2: Install MCP config + skills ---
+  console.error('');
+  console.error('Step 2/2: Wiring up MCP config + slash commands…');
+  console.error('');
+  let installCode;
+  try {
+    installCode = await install({ yes: true, force: opts.force });
+  } catch (e) {
+    console.error('');
+    console.error(`✗ Install failed: ${e.message}`);
+    console.error('  You can retry just this step with: npx epicmerch-mcp install');
+    return 1;
+  }
+
+  if (installCode !== 0) {
+    console.error('');
+    console.error(`✗ Install returned exit code ${installCode}.`);
+    console.error('  You can retry just this step with: npx epicmerch-mcp install');
+    return installCode;
+  }
+
+  console.error('');
+  console.error('━━━ ✓ Done — restart your AI client(s) ━━━');
+  console.error('');
+  console.error('In Claude Desktop / Cursor, try a slash command:');
+  console.error('  /epicmerch              full integration walkthrough');
+  console.error('  /epicmerch-stripe       configure Stripe payments');
+  console.error('  /epicmerch-migrate      migrate a Shopify store');
+  console.error('');
+  console.error('Or just ask: "Show me my EpicMerch products" — Claude will route it.');
+  return 0;
+}