@humanagencyp/erp-mcp 0.1.0 → 0.2.0

package/src/cli.ts

@@ -0,0 +1,99 @@
+/**
+ * Local operator commands. Deliberately NOT MCP tools: the agent under test must
+ * be able neither to read nor to change the record its work is measured by.
+ *
+ *   erp-mcp export                 everything needed to line up trigger → ticket → effect (changes + refusals)
+ *   erp-mcp scenario next <file>   hand over the next request, record when
+ *   erp-mcp scenario status <file> which requests were handed over, which are pending
+ */
+import { readFileSync } from "fs";
+import { createDb, type Db } from "./db.js";
+import { getMode } from "./mode.js";
+
+export interface ScenarioRequest {
+  id: string;
+  request: string;
+  /** What a correct outcome looks like, e.g. { customer_id, lines, value }. Free-form, carried into the export. */
+  expected?: unknown;
+}
+
+export function loadScenario(path: string): ScenarioRequest[] {
+  let raw: any;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new Error(`Scenario file ${path} cannot be read as JSON (${err instanceof Error ? err.message : String(err)})`);
+  }
+  const list = raw?.requests;
+  if (!Array.isArray(list) || list.length === 0) throw new Error(`Scenario file ${path}: \`requests\` must be a non-empty list`);
+  const ids = new Set<string>();
+  return list.map((r: any, i: number) => {
+    if (typeof r?.id !== "string" || !r.id.trim()) throw new Error(`Scenario file ${path}: requests[${i}].id is required`);
+    if (ids.has(r.id)) throw new Error(`Scenario file ${path}: request id ${JSON.stringify(r.id)} appears twice`);
+    ids.add(r.id);
+    if (typeof r.request !== "string" || !r.request.trim()) throw new Error(`Scenario file ${path}: requests[${i}].request is required`);
+    return { id: r.id, request: r.request, expected: r.expected };
+  });
+}
+
+/** Records the hand-over time of the first request not yet handed over. Null when all are done. */
+export async function nextRequest(db: Db, scenario: ScenarioRequest[]): Promise<(ScenarioRequest & { triggered_at: string }) | null> {
+  const done = new Set((await db.all<{ scenario_id: string }>(`SELECT scenario_id FROM triggers`)).map((r) => r.scenario_id));
+  const next = scenario.find((r) => !done.has(r.id));
+  if (!next) return null;
+  await db.run(`INSERT INTO triggers (scenario_id, request, expected) VALUES (?, ?, ?)`, [
+    next.id, next.request, next.expected === undefined ? null : JSON.stringify(next.expected),
+  ]);
+  const row = await db.get<{ triggered_at: string }>(`SELECT triggered_at FROM triggers WHERE scenario_id = ?`, [next.id]);
+  return { ...next, triggered_at: row!.triggered_at };
+}
+
+export async function exportRecord(db: Db, mode = getMode()) {
+  const quotes = await db.all<any>(`SELECT * FROM quotes ORDER BY created_at, number`);
+  const lines = await db.all<any>(`SELECT * FROM quote_lines`);
+  const byQuote = new Map<string, any[]>();
+  for (const l of lines) byQuote.set(l.quote_id, [...(byQuote.get(l.quote_id) ?? []), l]);
+  return {
+    mode,
+    exported_at: new Date().toISOString(),
+    triggers: (await db.all<any>(`SELECT * FROM triggers ORDER BY triggered_at`)).map((t) => ({
+      ...t, expected: t.expected ? JSON.parse(t.expected) : null,
+    })),
+    quotes: quotes.map((q) => ({ ...q, lines: byQuote.get(q.id) ?? [] })),
+    orders: await db.all<any>(`SELECT * FROM orders ORDER BY created_at, number`),
+    changes: await db.all<any>(`SELECT * FROM changes ORDER BY at`),
+    refusals: await db.all<any>(`SELECT * FROM refusals ORDER BY at`),
+  };
+}
+
+const USAGE = `usage: erp-mcp export | erp-mcp scenario next <file> | erp-mcp scenario status <file>`;
+
+export async function runCli(argv: string[]): Promise<number> {
+  const [cmd, sub, file] = argv;
+  try {
+    if (cmd === "export") {
+      const db = await createDb();
+      process.stdout.write(JSON.stringify(await exportRecord(db), null, 2) + "\n");
+      await db.close();
+      return 0;
+    }
+    if (cmd === "scenario" && (sub === "next" || sub === "status") && file) {
+      const scenario = loadScenario(file);
+      const db = await createDb();
+      if (sub === "next") {
+        const next = await nextRequest(db, scenario);
+        process.stdout.write(next ? `[${next.id}] handed over ${next.triggered_at} UTC\n${next.request}\n` : "All requests handed over.\n");
+      } else {
+        const done = new Map((await db.all<any>(`SELECT scenario_id, triggered_at FROM triggers`)).map((r) => [r.scenario_id, r.triggered_at]));
+        for (const r of scenario) process.stdout.write(`${r.id}\t${done.get(r.id) ?? "pending"}\t${r.request}\n`);
+      }
+      await db.close();
+      return 0;
+    }
+    process.stderr.write(USAGE + "\n");
+    return 2;
+  } catch (err) {
+    process.stderr.write(`[erp-mcp] ${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  }
+}

package/src/company.ts

@@ -0,0 +1,115 @@
+/**
+ * Company file: the test data the simulated ERP starts from — the company's
+ * items, prices, stock and customers, invented but realistic, prepared after the
+ * first conversation. Loaded once into an empty database (ERP_COMPANY_FILE).
+ *
+ * Validated strictly and refused whole on the first problem: a half-loaded or
+ * silently "fixed" company would make every later measurement of correctness
+ * compare against data nobody wrote.
+ */
+import { readFileSync } from "fs";
+
+export interface CompanyItem {
+  id: string;
+  sku: string;
+  name: string;
+  unit: string;
+  list_price: number;
+  stock: number;
+}
+
+export interface CompanyCustomer {
+  id: string;
+  name: string;
+  email: string | null;
+  country: string | null;
+  credit_limit: number;
+  open_balance: number;
+  payment_terms: string | null;
+}
+
+export interface Company {
+  name: string;
+  currency: string;
+  items: CompanyItem[];
+  customers: CompanyCustomer[];
+}
+
+function fail(path: string, msg: string): never {
+  throw new Error(`Company file ${path}: ${msg}`);
+}
+
+function str(v: unknown): v is string {
+  return typeof v === "string" && v.trim() !== "";
+}
+
+function num(v: unknown): v is number {
+  return typeof v === "number" && Number.isFinite(v);
+}
+
+export function parseCompany(raw: unknown, path = "(inline)"): Company {
+  if (!raw || typeof raw !== "object") fail(path, "must be a JSON object");
+  const c = raw as Record<string, unknown>;
+  if (!str(c.name)) fail(path, "`name` is required");
+  if (!str(c.currency) || !/^[A-Z]{3}$/.test(c.currency)) fail(path, "`currency` must be a 3-letter ISO code, e.g. EUR");
+  if (!Array.isArray(c.items) || c.items.length === 0) fail(path, "`items` must be a non-empty list");
+  if (!Array.isArray(c.customers) || c.customers.length === 0) fail(path, "`customers` must be a non-empty list");
+
+  const skus = new Set<string>();
+  const items = c.items.map((it, i): CompanyItem => {
+    const o = (it ?? {}) as Record<string, unknown>;
+    const at = `items[${i}]`;
+    if (!str(o.sku)) fail(path, `${at}.sku is required`);
+    if (skus.has(o.sku)) fail(path, `${at}.sku ${JSON.stringify(o.sku)} appears twice`);
+    skus.add(o.sku);
+    if (!str(o.name)) fail(path, `${at}.name is required`);
+    if (!num(o.list_price) || o.list_price < 0) fail(path, `${at}.list_price must be a number >= 0`);
+    if (!num(o.stock) || !Number.isInteger(o.stock) || o.stock < 0) fail(path, `${at}.stock must be a whole number >= 0`);
+    return {
+      id: str(o.id) ? o.id : `item-${i + 1}`,
+      sku: o.sku,
+      name: o.name,
+      unit: str(o.unit) ? o.unit : "pcs",
+      list_price: o.list_price,
+      stock: o.stock,
+    };
+  });
+
+  const customers = c.customers.map((cu, i): CompanyCustomer => {
+    const o = (cu ?? {}) as Record<string, unknown>;
+    const at = `customers[${i}]`;
+    if (!str(o.name)) fail(path, `${at}.name is required`);
+    if (!num(o.credit_limit) || o.credit_limit < 0) fail(path, `${at}.credit_limit must be a number >= 0`);
+    const open = o.open_balance ?? 0;
+    if (!num(open) || open < 0) fail(path, `${at}.open_balance must be a number >= 0`);
+    return {
+      id: str(o.id) ? o.id : `cust-${i + 1}`,
+      name: o.name,
+      email: str(o.email) ? o.email : null,
+      country: str(o.country) ? o.country : null,
+      credit_limit: o.credit_limit,
+      open_balance: open,
+      payment_terms: str(o.payment_terms) ? o.payment_terms : null,
+    };
+  });
+
+  for (const [label, list] of [["item", items], ["customer", customers]] as const) {
+    const ids = new Set<string>();
+    for (const { id } of list) {
+      if (ids.has(id)) fail(path, `${label} id ${JSON.stringify(id)} appears twice`);
+      ids.add(id);
+    }
+  }
+
+  return { name: c.name, currency: c.currency, items, customers };
+}
+
+export function loadCompanyFile(path: string): Company {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    fail(path, `cannot be read as JSON (${err instanceof Error ? err.message : String(err)})`);
+  }
+  return parseCompany(raw, path);
+}

package/src/db.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, copyFileSync, statSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
+import { loadCompanyFile, type Company } from "./company.js";
 
 export interface Db {
   run(sql: string, params?: any[]): Promise<void>;
@@ -69,60 +70,111 @@ CREATE TABLE IF NOT EXISTS orders (
   updated_at TEXT DEFAULT (datetime('now')),
   receipt_id TEXT
 );
+
+-- Calls the connector refused AFTER the gateway let them through. When the gateway
+-- injected a receipt_id, a ticket exists for an action that never happened; this
+-- table is the only place that says so (the ticket alone reads like a done action).
+CREATE TABLE IF NOT EXISTS refusals (
+  id TEXT PRIMARY KEY,
+  at TEXT DEFAULT (datetime('now')),
+  tool TEXT NOT NULL,
+  receipt_id TEXT,
+  message TEXT NOT NULL
+);
+
+-- Every change the ERP performed, one row per call — the effect each ticket produced.
+-- A document's own receipt_id column holds only its latest ticket (send overwrites
+-- create), so this table, not the document, is what lines up ticket ↔ effect 1:1.
+CREATE TABLE IF NOT EXISTS changes (
+  id TEXT PRIMARY KEY,
+  at TEXT DEFAULT (datetime('now')),
+  tool TEXT NOT NULL,
+  receipt_id TEXT,
+  document_id TEXT,
+  document_number TEXT,
+  status TEXT,
+  net_total REAL
+);
+
+-- Scenario requests handed to the agent, with the moment they were handed over.
+CREATE TABLE IF NOT EXISTS triggers (
+  scenario_id TEXT PRIMARY KEY,
+  triggered_at TEXT DEFAULT (datetime('now')),
+  request TEXT NOT NULL,
+  expected TEXT
+);
 `;
 
 /** Tables that carry an authorizing receipt_id (Content Provenance §4.1). */
 const RECEIPT_ID_TABLES = ["quotes", "orders"];
 
-/** Deterministic demo dataset, seeded once when the items table is empty. */
-const SEED_ITEMS: Array<[string, string, string, string, number, number]> = [
-  // id, sku, name, unit, list_price, stock
-  ["item-1", "WIDGET-100", "Widget 100", "pcs", 25.0, 500],
-  ["item-2", "WIDGET-200", "Widget 200 Pro", "pcs", 45.0, 300],
-  ["item-3", "GEAR-A1", "Precision Gear A1", "pcs", 120.0, 80],
-  ["item-4", "GEAR-B2", "Precision Gear B2", "pcs", 150.0, 60],
-  ["item-5", "PANEL-S", "Control Panel S", "pcs", 89.5, 150],
-  ["item-6", "PANEL-L", "Control Panel L", "pcs", 149.5, 90],
-  ["item-7", "CABLE-5M", "Cable 5m", "pcs", 12.0, 1000],
-  ["item-8", "SERVICE-KIT", "Maintenance Kit", "set", 340.0, 20],
-];
-
-const SEED_CUSTOMERS: Array<[string, string, string, string, number, number, string]> = [
-  // id, name, email, country, credit_limit, open_balance, payment_terms
-  ["cust-1", "Nordkap Manufacturing GmbH", "ap@nordkap.example", "DE", 50000, 12000, "NET30"],
-  ["cust-2", "Alpine Components AG", "finance@alpinecomp.example", "AT", 20000, 4000, "NET30"],
-  ["cust-3", "Baltic Retail Group", "accounts@balticretail.example", "LV", 8000, 7500, "NET14"],
-  ["cust-4", "Meridian Industrial Ltd", "payables@meridianind.example", "IE", 100000, 0, "NET60"],
-  ["cust-5", "Solstice Equipment Co", "finance@solsticeeq.example", "NL", 5000, 4800, "NET7"],
-];
-
-function seedSqlite(db: import("better-sqlite3").Database): void {
-  const { count } = db.prepare("SELECT COUNT(*) as count FROM items").get() as { count: number };
-  if (count > 0) return;
+/** Demo company used when no ERP_COMPANY_FILE is given. Deterministic. */
+export const DEMO_COMPANY: Company = {
+  name: "Demo Industrial",
+  currency: "EUR",
+  items: [
+    { id: "item-1", sku: "WIDGET-100", name: "Widget 100", unit: "pcs", list_price: 25.0, stock: 500 },
+    { id: "item-2", sku: "WIDGET-200", name: "Widget 200 Pro", unit: "pcs", list_price: 45.0, stock: 300 },
+    { id: "item-3", sku: "GEAR-A1", name: "Precision Gear A1", unit: "pcs", list_price: 120.0, stock: 80 },
+    { id: "item-4", sku: "GEAR-B2", name: "Precision Gear B2", unit: "pcs", list_price: 150.0, stock: 60 },
+    { id: "item-5", sku: "PANEL-S", name: "Control Panel S", unit: "pcs", list_price: 89.5, stock: 150 },
+    { id: "item-6", sku: "PANEL-L", name: "Control Panel L", unit: "pcs", list_price: 149.5, stock: 90 },
+    { id: "item-7", sku: "CABLE-5M", name: "Cable 5m", unit: "pcs", list_price: 12.0, stock: 1000 },
+    { id: "item-8", sku: "SERVICE-KIT", name: "Maintenance Kit", unit: "set", list_price: 340.0, stock: 20 },
+  ],
+  customers: [
+    { id: "cust-1", name: "Nordkap Manufacturing GmbH", email: "ap@nordkap.example", country: "DE", credit_limit: 50000, open_balance: 12000, payment_terms: "NET30" },
+    { id: "cust-2", name: "Alpine Components AG", email: "finance@alpinecomp.example", country: "AT", credit_limit: 20000, open_balance: 4000, payment_terms: "NET30" },
+    { id: "cust-3", name: "Baltic Retail Group", email: "accounts@balticretail.example", country: "LV", credit_limit: 8000, open_balance: 7500, payment_terms: "NET14" },
+    { id: "cust-4", name: "Meridian Industrial Ltd", email: "payables@meridianind.example", country: "IE", credit_limit: 100000, open_balance: 0, payment_terms: "NET60" },
+    { id: "cust-5", name: "Solstice Equipment Co", email: "finance@solsticeeq.example", country: "NL", credit_limit: 5000, open_balance: 4800, payment_terms: "NET7" },
+  ],
+};
 
-  const insertItem = db.prepare(
-    `INSERT INTO items (id, sku, name, unit, list_price, currency, stock) VALUES (?, ?, ?, ?, ?, 'EUR', ?)`
-  );
-  for (const [id, sku, name, unit, listPrice, stock] of SEED_ITEMS) {
-    insertItem.run(id, sku, name, unit, listPrice, stock);
-  }
+const INSERT_ITEM = `INSERT INTO items (id, sku, name, unit, list_price, currency, stock) VALUES (?, ?, ?, ?, ?, ?, ?)`;
+const INSERT_CUSTOMER = `INSERT INTO customers (id, name, email, country, currency, credit_limit, open_balance, payment_terms) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`;
 
-  const insertCustomer = db.prepare(
-    `INSERT INTO customers (id, name, email, country, currency, credit_limit, open_balance, payment_terms) VALUES (?, ?, ?, ?, 'EUR', ?, ?, ?)`
-  );
-  for (const [id, name, email, country, creditLimit, openBalance, terms] of SEED_CUSTOMERS) {
-    insertCustomer.run(id, name, email, country, creditLimit, openBalance, terms);
+function companyRows(company: Company): { items: any[][]; customers: any[][] } {
+  return {
+    items: company.items.map((i) => [i.id, i.sku, i.name, i.unit, i.list_price, company.currency, i.stock]),
+    customers: company.customers.map((c) => [
+      c.id, c.name, c.email, c.country, company.currency, c.credit_limit, c.open_balance, c.payment_terms,
+    ]),
+  };
+}
+
+/** The company to seed from: ERP_COMPANY_FILE if set (refused whole if invalid), else the demo. */
+export function resolveCompany(env: NodeJS.ProcessEnv = process.env): Company {
+  const path = env.ERP_COMPANY_FILE?.trim();
+  return path ? loadCompanyFile(path) : DEMO_COMPANY;
+}
+
+function seedSqlite(db: import("better-sqlite3").Database, company: Company): void {
+  const { count } = db.prepare("SELECT COUNT(*) as count FROM items").get() as { count: number };
+  if (count > 0) {
+    if (process.env.ERP_COMPANY_FILE) {
+      console.error("[erp-mcp] database already holds data — ERP_COMPANY_FILE not loaded (start from an empty database to load it)");
+    }
+    return;
   }
+  const rows = companyRows(company);
+  const insertItem = db.prepare(INSERT_ITEM);
+  const insertCustomer = db.prepare(INSERT_CUSTOMER);
+  db.transaction(() => {
+    for (const r of rows.items) insertItem.run(...r);
+    for (const r of rows.customers) insertCustomer.run(...r);
+  })();
+  console.error(`[erp-mcp] seeded "${company.name}": ${company.items.length} items, ${company.customers.length} customers`);
 }
 
 // SQLite adapter using better-sqlite3 (synchronous API wrapped in async)
-async function createSqliteDb(dbPath: string): Promise<Db> {
+async function createSqliteDb(dbPath: string, company: Company): Promise<Db> {
   const { default: Database } = await import("better-sqlite3");
 
   const db = new Database(dbPath);
   db.pragma("foreign_keys = ON");
   db.exec(SCHEMA);
-  seedSqlite(db);
+  seedSqlite(db, company);
 
   // Migration: add receipt_id to pre-existing tables (Content Provenance §4.1).
   // ALTER ... ADD COLUMN throws if it already exists, so guard on table_info.
@@ -150,7 +202,7 @@ async function createSqliteDb(dbPath: string): Promise<Db> {
 }
 
 // Postgres adapter using pg Pool
-async function createPostgresDb(connectionString: string): Promise<Db> {
+async function createPostgresDb(connectionString: string, company: Company): Promise<Db> {
   const { default: pg } = await import("pg");
   const pool = new pg.Pool({ connectionString });
 
@@ -171,18 +223,9 @@ async function createPostgresDb(connectionString: string): Promise<Db> {
     }
     const { rows } = await client.query("SELECT COUNT(*)::int as count FROM items");
     if (rows[0].count === 0) {
-      for (const [id, sku, name, unit, listPrice, stock] of SEED_ITEMS) {
-        await client.query(
-          `INSERT INTO items (id, sku, name, unit, list_price, currency, stock) VALUES ($1, $2, $3, $4, $5, 'EUR', $6)`,
-          [id, sku, name, unit, listPrice, stock]
-        );
-      }
-      for (const [id, name, email, country, creditLimit, openBalance, terms] of SEED_CUSTOMERS) {
-        await client.query(
-          `INSERT INTO customers (id, name, email, country, currency, credit_limit, open_balance, payment_terms) VALUES ($1, $2, $3, $4, 'EUR', $5, $6, $7)`,
-          [id, name, email, country, creditLimit, openBalance, terms]
-        );
-      }
+      const seed = companyRows(company);
+      for (const r of seed.items) await client.query(adaptSql(INSERT_ITEM), r);
+      for (const r of seed.customers) await client.query(adaptSql(INSERT_CUSTOMER), r);
     }
   } finally {
     client.release();
@@ -224,25 +267,27 @@ function maybeBackupSqlite(dbPath: string): void {
   }
 }
 
-export async function createDb(): Promise<Db> {
+export async function createDb(company: Company = resolveCompany()): Promise<Db> {
   const databaseUrl = process.env.DATABASE_URL ?? "";
 
   if (databaseUrl.startsWith("postgres://") || databaseUrl.startsWith("postgresql://")) {
     console.error("[erp-mcp] using Postgres");
-    return createPostgresDb(databaseUrl);
+    return createPostgresDb(databaseUrl, company);
   }
 
   // SQLite path — honor HAP_DATA_DIR so docker (with a mounted /app/data) and
   // local dev (~/.hap) write to the same place the gateway uses. The gateway
   // injects HAP_DATA_DIR into the child env when spawning this MCP server.
-  const hapDir = process.env.HAP_DATA_DIR ?? join(homedir(), ".hap");
-  if (!existsSync(hapDir)) {
-    mkdirSync(hapDir, { recursive: true });
+  // Only create the data directory when the default path is actually used — an
+  // explicit DATABASE_URL must not leave an empty ~/.hap behind.
+  let dbPath = databaseUrl;
+  if (!dbPath) {
+    const hapDir = process.env.HAP_DATA_DIR ?? join(homedir(), ".hap");
+    if (!existsSync(hapDir)) mkdirSync(hapDir, { recursive: true });
+    dbPath = join(hapDir, "erp.db");
   }
-
-  const dbPath = databaseUrl || join(hapDir, "erp.db");
   maybeBackupSqlite(dbPath);
 
   console.error(`[erp-mcp] using SQLite at ${dbPath}`);
-  return createSqliteDb(dbPath);
+  return createSqliteDb(dbPath, company);
 }

package/src/dispatch.ts

@@ -0,0 +1,66 @@
+/**
+ * One entry point for every tool call — used by the MCP server and by the tests,
+ * so the tests exercise exactly what the server runs.
+ */
+import { randomUUID } from "crypto";
+import type { Db } from "./db.js";
+import { LIVE_NOT_AVAILABLE, type ErpMode } from "./mode.js";
+import { list_items, get_item } from "./tools/items.js";
+import { find_customers, get_customer } from "./tools/customers.js";
+import { create_quote, update_quote, send_quote, list_quotes, get_quote } from "./tools/quotes.js";
+import { convert_quote_to_order, list_orders, get_order } from "./tools/orders.js";
+
+/** Tools that change the ERP — the ones the gateway issues a ticket for. */
+export const CHANGE_TOOLS = new Set(["create_quote", "update_quote", "send_quote", "convert_quote_to_order"]);
+
+async function runTool(db: Db, name: string, args: Record<string, any>): Promise<unknown> {
+  switch (name) {
+    case "list_items": return list_items(db, args);
+    case "get_item": return get_item(db, args);
+    case "find_customers": return find_customers(db, args);
+    case "get_customer": return get_customer(db, args);
+    case "list_quotes": return list_quotes(db, args);
+    case "get_quote": return get_quote(db, args);
+    case "list_orders": return list_orders(db, args);
+    case "get_order": return get_order(db, args);
+    case "create_quote": return create_quote(db, args);
+    case "update_quote": return update_quote(db, args);
+    case "send_quote": return send_quote(db, args);
+    case "convert_quote_to_order": return convert_quote_to_order(db, args);
+    default: throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+/**
+ * Run a tool in the given mode. Every successful change is recorded (`changes`)
+ * with the receipt_id the gateway injected; a refused change call is recorded with the
+ * receipt_id the gateway injected — that is the trace of a ticket whose action
+ * never happened. In live mode nothing runs and nothing is recorded locally:
+ * there is no local system to have refused anything.
+ */
+export async function callTool(db: Db, mode: ErpMode, name: string, args: Record<string, any>): Promise<unknown> {
+  if (mode === "live") throw new Error(LIVE_NOT_AVAILABLE);
+  try {
+    const result = await runTool(db, name, args);
+    if (CHANGE_TOOLS.has(name)) {
+      const doc = (result ?? {}) as Record<string, unknown>;
+      await db.run(
+        `INSERT INTO changes (id, at, tool, receipt_id, document_id, document_number, status, net_total) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          randomUUID(), new Date().toISOString(), name, typeof args.receipt_id === "string" ? args.receipt_id : null,
+          doc.id ?? null, doc.number ?? null, doc.status ?? null, typeof doc.net_total === "number" ? doc.net_total : null,
+        ],
+      );
+    }
+    return result;
+  } catch (err) {
+    if (CHANGE_TOOLS.has(name)) {
+      const message = err instanceof Error ? err.message : String(err);
+      const receiptId = typeof args.receipt_id === "string" ? args.receipt_id : null;
+      await db.run(`INSERT INTO refusals (id, at, tool, receipt_id, message) VALUES (?, ?, ?, ?, ?)`, [
+        randomUUID(), new Date().toISOString(), name, receiptId, message,
+      ]);
+    }
+    throw err;
+  }
+}

package/src/index.ts

@@ -8,10 +8,9 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 import { createDb } from "./db.js";
-import { list_items, get_item } from "./tools/items.js";
-import { find_customers, get_customer } from "./tools/customers.js";
-import { create_quote, update_quote, send_quote, list_quotes, get_quote } from "./tools/quotes.js";
-import { convert_quote_to_order, list_orders, get_order } from "./tools/orders.js";
+import { callTool } from "./dispatch.js";
+import { getMode } from "./mode.js";
+import { runCli } from "./cli.js";
 
 const RECEIPT_FIELD = {
   type: "string" as const,
@@ -201,13 +200,18 @@ const TOOL_DEFINITIONS = [
   },
 ] as const;
 
-type ToolName = (typeof TOOL_DEFINITIONS)[number]["name"];
-
 async function main() {
+  // `erp-mcp export` / `erp-mcp scenario …` are local operator commands, not MCP tools.
+  if (process.argv.length > 2) {
+    process.exit(await runCli(process.argv.slice(2)));
+  }
+
+  const mode = getMode();
   const db = await createDb();
+  console.error(`[erp-mcp] mode: ${mode}`);
 
   const server = new Server(
-    { name: "erp", version: "0.1.0" },
+    { name: "erp", version: "0.2.0" },
     { capabilities: { tools: {} } }
   );
 
@@ -220,48 +224,7 @@ async function main() {
     const safeArgs = (args ?? {}) as Record<string, any>;
 
     try {
-      let result: unknown;
-
-      switch (name as ToolName) {
-        case "list_items":
-          result = await list_items(db, safeArgs);
-          break;
-        case "get_item":
-          result = await get_item(db, safeArgs);
-          break;
-        case "find_customers":
-          result = await find_customers(db, safeArgs);
-          break;
-        case "get_customer":
-          result = await get_customer(db, safeArgs);
-          break;
-        case "list_quotes":
-          result = await list_quotes(db, safeArgs);
-          break;
-        case "get_quote":
-          result = await get_quote(db, safeArgs);
-          break;
-        case "list_orders":
-          result = await list_orders(db, safeArgs);
-          break;
-        case "get_order":
-          result = await get_order(db, safeArgs);
-          break;
-        case "create_quote":
-          result = await create_quote(db, safeArgs);
-          break;
-        case "update_quote":
-          result = await update_quote(db, safeArgs);
-          break;
-        case "send_quote":
-          result = await send_quote(db, safeArgs);
-          break;
-        case "convert_quote_to_order":
-          result = await convert_quote_to_order(db, safeArgs);
-          break;
-        default:
-          throw new Error(`Unknown tool: ${name}`);
-      }
+      const result = await callTool(db, mode, name, safeArgs);
 
       return {
         content: [

package/src/mode.ts

@@ -0,0 +1,26 @@
+/**
+ * Connector mode: `simulation` answers from the built-in simulated ERP (SQLite);
+ * `live` would talk to a company's real ERP.
+ *
+ * The switch exists so a three-week test runs on exactly the connector, tools and
+ * profile that go live later — only the system behind the connector changes. No
+ * live adapter ships in 0.x, so `live` refuses every call loudly instead of
+ * silently falling back to the simulation: a test that believes it is live (or a
+ * go-live that is secretly still simulated) is the failure this must not hide.
+ */
+
+export type ErpMode = "simulation" | "live";
+
+export const MODES: readonly ErpMode[] = ["simulation", "live"];
+
+/** Reads ERP_MODE (default `simulation`). An unknown value stops the server at start. */
+export function getMode(env: NodeJS.ProcessEnv = process.env): ErpMode {
+  const raw = (env.ERP_MODE ?? "").trim().toLowerCase();
+  if (raw === "") return "simulation";
+  if ((MODES as readonly string[]).includes(raw)) return raw as ErpMode;
+  throw new Error(`ERP_MODE must be one of ${MODES.join(", ")} — got ${JSON.stringify(env.ERP_MODE)}.`);
+}
+
+export const LIVE_NOT_AVAILABLE =
+  "Refused: this ERP connector is in live mode, but no live ERP adapter is installed (0.x ships the simulation only). " +
+  "Nothing was read or changed. Set ERP_MODE=simulation, or install the adapter for your ERP.";