@ecommclaw/ops-mcp-server 0.2.0

package/README.md

@@ -0,0 +1,40 @@
+# @ecommclaw/ops-mcp-server
+
+MCP server for external EcommClaw Ops module and pipeline development.
+
+It is designed to be installed by developers and called by Claude, Cursor, Codex, or any MCP-compatible AI tool.
+
+## Install
+
+```bash
+npm install -g @ecommclaw/ops-mcp-server
+```
+
+## Claude MCP Config
+
+```json
+{
+  "mcpServers": {
+    "ecommclaw-ops": {
+      "command": "ecommclaw-ops-mcp",
+      "env": {
+        "ECOMMCLAW_API_BASE": "https://www.ecommclaw.com",
+        "ECOMMCLAW_API_KEY": "YOUR_ECOMMCLAW_UUID_OR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+- `list_modules`
+- `get_module_spec`
+- `list_pipeline_templates`
+- `get_pipeline_template`
+- `scaffold_module`
+- `validate_module`
+- `validate_module_source`
+- `inspect_databag_schema`
+
+This first version does not expose production run, publish, deploy, delete, or secret-write tools.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@ecommclaw/ops-mcp-server",
+  "version": "0.2.0",
+  "private": false,
+  "description": "MCP server for EcommClaw Ops external module and pipeline development",
+  "type": "commonjs",
+  "bin": {
+    "ecommclaw-ops-mcp": "server.js"
+  },
+  "files": [
+    "server.js",
+    "README.md",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED"
+}

package/server.js

@@ -0,0 +1,438 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const API_BASE = String(process.env.ECOMMCLAW_API_BASE || 'https://www.ecommclaw.com').replace(/\/+$/, '');
+const API_KEY = process.env.ECOMMCLAW_API_KEY || process.env.ECOMMCLAW_DEV_API_KEY || '';
+const LOCAL_ROOT = process.env.ECOMMCLAW_OPS_ROOT ? findOpsRoot(process.env.ECOMMCLAW_OPS_ROOT) : null;
+const LOCAL_PROJECT = process.env.ECOMMCLAW_OPS_PROJECT
+  || (LOCAL_ROOT ? path.join(LOCAL_ROOT, 'examples', 'experiments', 'sourcing-1688') : null);
+
+const TOOLS = [
+  {
+    name: 'list_modules',
+    description: 'List public EcommClaw ops modules from the platform developer API.',
+    inputSchema: {
+      type: 'object',
+      properties: { include_schemas: { type: 'boolean', default: false } },
+    },
+  },
+  {
+    name: 'get_module_spec',
+    description: 'Return one public module spec, schema, and capabilities.',
+    inputSchema: {
+      type: 'object',
+      properties: { module_id: { type: 'string' } },
+      required: ['module_id'],
+    },
+  },
+  {
+    name: 'list_pipeline_templates',
+    description: 'List public EcommClaw pipeline templates from the platform developer API.',
+    inputSchema: {
+      type: 'object',
+      properties: { include_stages: { type: 'boolean', default: false } },
+    },
+  },
+  {
+    name: 'get_pipeline_template',
+    description: 'Return one public pipeline template spec.',
+    inputSchema: {
+      type: 'object',
+      properties: { pipeline_id: { type: 'string' } },
+      required: ['pipeline_id'],
+    },
+  },
+  {
+    name: 'scaffold_module',
+    description: 'Create a local SDK module template for an external developer. This does not publish or deploy it.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        module_id: { type: 'string' },
+        module_type: { type: 'string', enum: ['server', 'browser-agent', 'distributed-agent'] },
+        target_dir: { type: 'string', description: 'Directory to create the module in.' },
+        overwrite: { type: 'boolean', default: false },
+      },
+      required: ['module_id'],
+    },
+  },
+  {
+    name: 'validate_module',
+    description: 'Statically validate a local module file against EcommClaw ops SDK rules. Does not execute user code.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string' },
+        module_id: { type: 'string' },
+      },
+      required: ['file_path'],
+    },
+  },
+  {
+    name: 'validate_module_source',
+    description: 'Validate module source text through the platform developer API.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        source: { type: 'string' },
+        module_id: { type: 'string' },
+      },
+      required: ['source'],
+    },
+  },
+  {
+    name: 'inspect_databag_schema',
+    description: 'Return the EcommClaw databag schema, patch rules, artifact rules, and error codes.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'list_pipelines',
+    description: 'Alias for list_pipeline_templates.',
+    inputSchema: {
+      type: 'object',
+      properties: { include_stages: { type: 'boolean', default: false } },
+    },
+  },
+  {
+    name: 'get_pipeline_spec',
+    description: 'Alias for get_pipeline_template.',
+    inputSchema: {
+      type: 'object',
+      properties: { pipeline_id: { type: 'string' } },
+      required: ['pipeline_id'],
+    },
+  },
+];
+
+const handlers = {
+  list_modules: async (args) => {
+    if (LOCAL_ROOT) return { modules: listLocalModules(args.include_schemas === true), source: 'local' };
+    const data = await developerGet(`/api/developer/v1/modules?include_schemas=${args.include_schemas === true ? '1' : '0'}`);
+    return { modules: data.modules || [], source: 'platform' };
+  },
+  get_module_spec: async (args) => {
+    if (LOCAL_ROOT) {
+      const modules = listLocalModules(true);
+      const mod = modules.find(m => m.id === args.module_id || m.name === args.module_id);
+      if (!mod) throw new Error(`module not found: ${args.module_id}`);
+      return mod;
+    }
+    const data = await developerGet(`/api/developer/v1/modules/${encodeURIComponent(args.module_id)}`);
+    return data.module;
+  },
+  list_pipeline_templates: async (args) => {
+    if (LOCAL_ROOT) return { pipelines: listLocalPipelines(args.include_stages === true), source: 'local' };
+    const data = await developerGet(`/api/developer/v1/pipeline-templates?include_stages=${args.include_stages === true ? '1' : '0'}`);
+    return { pipelines: data.pipelines || [], source: 'platform' };
+  },
+  get_pipeline_template: async (args) => {
+    if (LOCAL_ROOT) {
+      const pipelines = listLocalPipelines(true);
+      const spec = pipelines.find(p => p.id === args.pipeline_id);
+      if (!spec) throw new Error(`pipeline not found: ${args.pipeline_id}`);
+      return spec;
+    }
+    const data = await developerGet(`/api/developer/v1/pipeline-templates/${encodeURIComponent(args.pipeline_id)}`);
+    return data.pipeline;
+  },
+  list_pipelines: async (args) => handlers.list_pipeline_templates(args),
+  get_pipeline_spec: async (args) => handlers.get_pipeline_template(args),
+  scaffold_module: async (args) => scaffoldModule(args),
+  validate_module: async (args) => validateModuleFile(args.file_path, args.module_id),
+  validate_module_source: async (args) => {
+    const data = await developerPost('/api/developer/v1/modules/validate', args);
+    return data.validation;
+  },
+  inspect_databag_schema: async () => databagSchema(),
+};
+
+async function developerGet(pathname) {
+  return developerFetch(pathname, { method: 'GET' });
+}
+
+async function developerPost(pathname, body) {
+  return developerFetch(pathname, { method: 'POST', body: JSON.stringify(body || {}) });
+}
+
+async function developerFetch(pathname, init) {
+  const headers = { 'content-type': 'application/json' };
+  if (API_KEY) headers.authorization = `Bearer ${API_KEY}`;
+  const resp = await fetch(API_BASE + pathname, { ...init, headers });
+  const text = await resp.text();
+  let json = null;
+  try { json = text ? JSON.parse(text) : null; } catch { /* leave null */ }
+  if (!resp.ok || (json && json.ok === false)) {
+    const msg = json && (json.error || json.message) || `HTTP ${resp.status}`;
+    throw new Error(msg);
+  }
+  return json;
+}
+
+function findOpsRoot(start) {
+  let cur = path.resolve(start);
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(cur, 'engine', 'pipeline_loader.js'))
+      && fs.existsSync(path.join(cur, 'sdk', 'defineModule.js'))) return cur;
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  throw new Error(`ECOMMCLAW_OPS_ROOT is not an ozon-ops root: ${start}`);
+}
+
+function listLocalModules(includeSchemas) {
+  const modulesDir = path.join(LOCAL_PROJECT, 'modules');
+  if (!fs.existsSync(modulesDir)) throw new Error(`modules directory not found: ${modulesDir}`);
+  return fs.readdirSync(modulesDir)
+    .filter(f => f.endsWith('.js') && !f.startsWith('_'))
+    .sort()
+    .map(file => {
+      const filePath = path.join(modulesDir, file);
+      try {
+        delete require.cache[require.resolve(filePath)];
+        const mod = require(filePath);
+        return sanitizeModule(mod, { includeSchemas });
+      } catch (e) {
+        return { id: path.basename(file, '.js'), name: path.basename(file, '.js'), load_error: e.message };
+      }
+    });
+}
+
+function sanitizeModule(mod, { includeSchemas = false } = {}) {
+  const out = {
+    id: mod.id || mod.name,
+    name: mod.name || mod.id,
+    description: mod.description || '',
+    version: mod.version || null,
+    type: mod.type || (mod.needsClient ? 'browser-agent' : 'server'),
+    runtime: mod.runtime || 'inproc',
+    needsClient: mod.needsClient === true,
+    capabilities: Array.isArray(mod.capabilities) ? mod.capabilities : [],
+    sdk: mod.sdk || null,
+  };
+  if (includeSchemas) {
+    out.inputSchema = mod.inputSchema || mod.inputs || null;
+    out.outputSchema = mod.outputSchema || mod.outputs || null;
+  }
+  return out;
+}
+
+function listLocalPipelines(includeStages) {
+  const pipelinesDir = path.join(LOCAL_PROJECT, 'pipelines');
+  if (!fs.existsSync(pipelinesDir)) throw new Error(`pipelines directory not found: ${pipelinesDir}`);
+  const { loadFromYamlFile } = require(path.join(LOCAL_ROOT, 'engine', 'pipeline_loader'));
+  return fs.readdirSync(pipelinesDir)
+    .filter(f => /\.ya?ml$/i.test(f))
+    .sort()
+    .map(file => {
+      const pipe = loadFromYamlFile(path.join(pipelinesDir, file));
+      const out = {
+        id: pipe.id,
+        description: pipe.description || '',
+        start: pipe.start,
+        stage_count: pipe.stages ? Object.keys(pipe.stages).length : 0,
+      };
+      if (includeStages) out.stages = pipe.stages;
+      return out;
+    });
+}
+
+function scaffoldModule(args = {}) {
+  const moduleId = normalizeModuleId(args.module_id);
+  const type = args.module_type || 'server';
+  if (!['server', 'browser-agent', 'distributed-agent'].includes(type)) throw new Error(`invalid module_type: ${type}`);
+  const dir = path.resolve(args.target_dir || path.join(process.cwd(), 'ecommclaw-modules'));
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, `${moduleId}.js`);
+  if (fs.existsSync(filePath) && !args.overwrite) throw new Error(`file already exists: ${filePath}`);
+  fs.writeFileSync(filePath, templateFor(moduleId, type));
+  return {
+    ok: true,
+    module_id: moduleId,
+    module_type: type,
+    file_path: filePath,
+    next_steps: [
+      'Edit business logic inside run() or plan/runTask/reduce().',
+      'Run validate_module on the generated file.',
+      'Submit the module for review only after validation passes.',
+    ],
+  };
+}
+
+function normalizeModuleId(input) {
+  const id = String(input || '').trim().replace(/[^a-zA-Z0-9_-]+/g, '_').replace(/^_+|_+$/g, '');
+  if (!id) throw new Error('module_id required');
+  return id;
+}
+
+function templateFor(moduleId, type) {
+  if (type === 'distributed-agent') return `const { defineModule } = require('@ecommclaw/ops-sdk');\n\nmodule.exports = defineModule({\n  id: '${moduleId}',\n  name: '${moduleId}',\n  version: '0.1.0',\n  type: 'distributed-agent',\n  inputSchema: {\n    type: 'object',\n    properties: {\n      agent_pool: { type: 'array', items: { type: 'string' } },\n      max_items: { type: ['number', 'null'], default: null },\n    },\n    required: ['agent_pool'],\n  },\n  outputSchema: { type: 'object', properties: { metrics: { type: 'object' } } },\n  capabilities: ['databag:read', 'databag:patch'],\n\n  async plan(ctx) {\n    const items = await ctx.databag.listItems();\n    return items.map(item => ({\n      task_id: '${moduleId}:' + item.id,\n      item_id: item.id,\n      payload: { item_id: item.id },\n      idempotency_key: '${moduleId}:' + item.id,\n    }));\n  },\n\n  async runTask(ctx, task) {\n    return {\n      item_id: task.item_id,\n      patch: { 'module_outputs.${moduleId}.status': 'done' },\n    };\n  },\n\n  async reduce(ctx, taskResults) {\n    await ctx.databag.patchItems(taskResults.map(r => ({ id: r.item_id, patch: r.patch })));\n    return { status: 'success', metrics: { total: taskResults.length, success: taskResults.length, skipped: 0, failed: 0 } };\n  },\n});\n`;
+  const caps = type === 'browser-agent'
+    ? "['databag:read', 'databag:patch', 'browser:navigate']"
+    : "['databag:read', 'databag:patch']";
+  const browserBody = type === 'browser-agent'
+    ? "\n    // Use ctx.browser.run(command) for browser work; do not call CDP directly.\n"
+    : '';
+  return `const { defineModule } = require('@ecommclaw/ops-sdk');\n\nmodule.exports = defineModule({\n  id: '${moduleId}',\n  name: '${moduleId}',\n  version: '0.1.0',\n  type: '${type}',\n  inputSchema: { type: 'object', properties: {} },\n  outputSchema: { type: 'object', properties: { metrics: { type: 'object' } } },\n  capabilities: ${caps},\n\n  async run(ctx) {${browserBody}\n    const items = await ctx.databag.listItems();\n    await ctx.databag.patchItems(items.map(item => ({\n      id: item.id,\n      patch: { 'module_outputs.${moduleId}.status': 'done' },\n    })));\n    return { status: 'success', metrics: { total: items.length, success: items.length, skipped: 0, failed: 0 } };\n  },\n});\n`;
+}
+
+function validateModuleFile(filePath, expectedId) {
+  const abs = path.resolve(filePath);
+  if (!fs.existsSync(abs)) throw new Error(`module file not found: ${abs}`);
+  const syntax = spawnSync(process.execPath, ['--check', abs], { encoding: 'utf8' });
+  if (syntax.status !== 0) {
+    return { ok: false, file_path: abs, errors: [{ code: 'syntax_error', message: syntax.stderr || syntax.stdout }], warnings: [] };
+  }
+  return validateModuleSource(fs.readFileSync(abs, 'utf8'), { module_id: expectedId, file_path: abs });
+}
+
+function validateModuleSource(source, opts = {}) {
+  const errors = [];
+  const warnings = [];
+  const moduleId = opts.module_id || extractStringProp(source, 'id') || extractStringProp(source, 'name');
+  const name = extractStringProp(source, 'name');
+  const version = extractStringProp(source, 'version');
+  const type = extractStringProp(source, 'type');
+  const caps = extractArrayProp(source, 'capabilities');
+
+  if (!/defineModule\s*\(/.test(source)) errors.push({ code: 'missing_define_module', message: 'module must use defineModule()' });
+  if (!moduleId) errors.push({ code: 'missing_id', message: 'id is required' });
+  if (opts.module_id && moduleId && opts.module_id !== moduleId && opts.module_id !== name) {
+    errors.push({ code: 'module_id_mismatch', message: `expected ${opts.module_id}, got ${moduleId}` });
+  }
+  if (!name) errors.push({ code: 'missing_name', message: 'name is required' });
+  if (!version) errors.push({ code: 'missing_version', message: 'version is required' });
+  if (!['server', 'browser-agent', 'distributed-agent'].includes(type)) {
+    errors.push({ code: 'invalid_type', message: 'type must be server, browser-agent, or distributed-agent' });
+  }
+  if (!/\binputSchema\s*:/.test(source) && !/\binputs\s*:/.test(source)) errors.push({ code: 'missing_input_schema', message: 'inputSchema is required' });
+  if (!/\boutputSchema\s*:/.test(source) && !/\boutputs\s*:/.test(source)) errors.push({ code: 'missing_output_schema', message: 'outputSchema is required' });
+  if (!/\bcapabilities\s*:/.test(source)) errors.push({ code: 'missing_capabilities', message: 'capabilities array is required' });
+  if (type === 'distributed-agent') {
+    for (const fn of ['plan', 'runTask', 'reduce']) {
+      if (!new RegExp(`\\b${fn}\\s*\\(`).test(source)) errors.push({ code: 'missing_lifecycle', message: `distributed-agent requires ${fn}()` });
+    }
+  } else if (!/\brun\s*\(/.test(source)) {
+    errors.push({ code: 'missing_run', message: `${type || 'module'} requires run(ctx)` });
+  }
+
+  const risky = [
+    ['direct_db_access', /\b(better-sqlite3|getDB\(|new\s+Database\s*\()/, 'error'],
+    ['filesystem_write', /\b(fs\.writeFile|fs\.appendFile|fs\.rm|fs\.unlink|fs\.rename|createWriteStream)\b/, 'warning'],
+    ['process_spawn', /\b(child_process|spawn\(|exec\(|execFile\()/, 'warning'],
+    ['env_secret_access', /\bprocess\.env\b/, 'warning'],
+    ['large_context_write_risk', /\bcontext\s*=\s*|return\s+\{[\s\S]{0,200}\bitems\s*:/, 'warning'],
+  ];
+  for (const [code, re, severity] of risky) {
+    if (re.test(source)) (severity === 'error' ? errors : warnings).push({ code, message: `${code} detected` });
+  }
+  if (moduleId) {
+    const bad = [...source.matchAll(/module_outputs\.([a-zA-Z0-9_-]+)\./g)]
+      .map(m => m[1])
+      .filter(ns => ns !== moduleId);
+    if (bad.length) {
+      errors.push({ code: 'patches_other_module_namespace', message: [...new Set(bad)].join(', ') });
+    }
+  }
+  if (caps && caps.includes('secret:read')) warnings.push({ code: 'secret_capability_requires_review', message: 'secret:read requires manual review' });
+
+  return {
+    ok: errors.length === 0,
+    file_path: opts.file_path || null,
+    module: { id: moduleId || null, name: name || null, version: version || null, type: type || null, capabilities: caps || [] },
+    errors,
+    warnings,
+  };
+}
+
+function extractStringProp(source, key) {
+  const re = new RegExp(`\\b${key}\\s*:\\s*['"\`]([^'"\`]+)['"\`]`);
+  const m = source.match(re);
+  return m ? m[1] : null;
+}
+
+function extractArrayProp(source, key) {
+  const re = new RegExp(`\\b${key}\\s*:\\s*\\[([\\s\\S]*?)\\]`);
+  const m = source.match(re);
+  if (!m) return null;
+  return [...m[1].matchAll(/['"`]([^'"`]+)['"`]/g)].map(x => x[1]);
+}
+
+function databagSchema() {
+  return {
+    version: '0.1',
+    databag: {
+      version: '0.1',
+      items: [{ id: 'string', type: 'string', source: {}, group_id: 'string?', status: 'string?', errors: [], artifacts: [], module_outputs: {} }],
+      groups: [{ id: 'string', type: 'string', source: {}, module_outputs: {} }],
+      artifacts: [{ id: 'string', type: 'image|video|html|json|file', path: 'string', mime_type: 'string?', size_bytes: 'number?', sha256: 'string?' }],
+      meta: {},
+    },
+    allowed_item_patch_paths: ['module_outputs.<current_module_id>.*', 'status', 'errors', 'artifacts'],
+    forbidden: [
+      'Do not patch another module namespace.',
+      'Do not write large images, videos, HTML, or long logs into main context.',
+      'Do not read or write the database directly from a module.',
+      'Do not manage multi-agent concurrency manually; use distributed-agent lifecycle and agent_pool.',
+    ],
+    error_codes: [
+      'missing_input', 'invalid_config', 'agent_unavailable', 'captcha_required',
+      'network_error', 'timeout', 'parse_failed', 'no_match', 'validation_failed',
+      'api_rate_limited', 'api_rejected', 'permission_denied', 'quota_exceeded',
+    ],
+  };
+}
+
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+}
+
+function contentResult(value) {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+
+async function handleRequest(req) {
+  if (req.method === 'initialize') {
+    return {
+      protocolVersion: req.params && req.params.protocolVersion || '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: { name: 'ecommclaw-ops-mcp', version: '0.2.0' },
+    };
+  }
+  if (req.method === 'tools/list') return { tools: TOOLS };
+  if (req.method === 'tools/call') {
+    const name = req.params && req.params.name;
+    const args = req.params && req.params.arguments || {};
+    if (!handlers[name]) throw new Error(`unknown tool: ${name}`);
+    return contentResult(await handlers[name](args));
+  }
+  if (req.method === 'ping') return {};
+  throw new Error(`unsupported method: ${req.method}`);
+}
+
+let buffer = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => {
+  buffer += chunk;
+  let idx;
+  while ((idx = buffer.indexOf('\n')) >= 0) {
+    const line = buffer.slice(0, idx).trim();
+    buffer = buffer.slice(idx + 1);
+    if (!line) continue;
+    let req;
+    Promise.resolve()
+      .then(() => {
+        req = JSON.parse(line);
+        if (req.id === undefined || req.id === null) return null;
+        return handleRequest(req).then(result => send({ jsonrpc: '2.0', id: req.id, result }));
+      })
+      .catch(e => {
+        const id = req && req.id !== undefined ? req.id : null;
+        send({ jsonrpc: '2.0', id, error: { code: -32000, message: e.message } });
+      });
+  }
+});