@humanagencyp/erp-mcp 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@humanagencyp/erp-mcp",
+  "version": "0.1.0",
+  "description": "ERP MCP server for the Human Agency Protocol — quote-to-order: items, customers, quotes, orders",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/humanagencyprotocol/hap-erp-mcp.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "dist/index.js",
+  "bin": {
+    "erp-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build",
+    "release:patch": "npm version patch && git push --follow-tags",
+    "release:minor": "npm version minor && git push --follow-tags",
+    "release:major": "npm version major && git push --follow-tags"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "better-sqlite3": "^13.0.0",
+    "uuid": "^10.0.0"
+  },
+  "peerDependencies": {
+    "pg": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^20.0.0",
+    "@types/uuid": "^10.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  },
+  "homepage": "https://humanagencyprotocol.org"
+}

package/src/db.ts

@@ -0,0 +1,248 @@
+import { existsSync, mkdirSync, copyFileSync, statSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+export interface Db {
+  run(sql: string, params?: any[]): Promise<void>;
+  get<T>(sql: string, params?: any[]): Promise<T | undefined>;
+  all<T>(sql: string, params?: any[]): Promise<T[]>;
+  close(): Promise<void>;
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS items (
+  id TEXT PRIMARY KEY,
+  sku TEXT NOT NULL UNIQUE,
+  name TEXT NOT NULL,
+  unit TEXT NOT NULL DEFAULT 'pcs',
+  list_price REAL NOT NULL,
+  currency TEXT NOT NULL DEFAULT 'EUR',
+  stock INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS customers (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  email TEXT,
+  country TEXT,
+  currency TEXT NOT NULL DEFAULT 'EUR',
+  credit_limit REAL NOT NULL DEFAULT 0,
+  open_balance REAL NOT NULL DEFAULT 0,
+  payment_terms TEXT
+);
+
+CREATE TABLE IF NOT EXISTS quotes (
+  id TEXT PRIMARY KEY,
+  number TEXT NOT NULL UNIQUE,
+  customer_id TEXT NOT NULL REFERENCES customers(id),
+  status TEXT CHECK(status IN ('draft','sent','converted','cancelled')) NOT NULL DEFAULT 'draft',
+  currency TEXT NOT NULL,
+  discount_pct REAL NOT NULL DEFAULT 0,
+  net_total REAL NOT NULL DEFAULT 0,
+  valid_until TEXT,
+  notes TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now')),
+  sent_at TEXT,
+  receipt_id TEXT
+);
+
+CREATE TABLE IF NOT EXISTS quote_lines (
+  id TEXT PRIMARY KEY,
+  quote_id TEXT NOT NULL REFERENCES quotes(id) ON DELETE CASCADE,
+  item_id TEXT NOT NULL REFERENCES items(id),
+  qty INTEGER NOT NULL,
+  list_price REAL NOT NULL,
+  line_total REAL NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS orders (
+  id TEXT PRIMARY KEY,
+  number TEXT NOT NULL UNIQUE,
+  quote_id TEXT NOT NULL REFERENCES quotes(id),
+  customer_id TEXT NOT NULL REFERENCES customers(id),
+  status TEXT CHECK(status IN ('confirmed')) NOT NULL DEFAULT 'confirmed',
+  net_total REAL NOT NULL,
+  currency TEXT NOT NULL,
+  requested_delivery TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now')),
+  receipt_id 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;
+
+  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 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);
+  }
+}
+
+// SQLite adapter using better-sqlite3 (synchronous API wrapped in async)
+async function createSqliteDb(dbPath: string): Promise<Db> {
+  const { default: Database } = await import("better-sqlite3");
+
+  const db = new Database(dbPath);
+  db.pragma("foreign_keys = ON");
+  db.exec(SCHEMA);
+  seedSqlite(db);
+
+  // 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.
+  for (const table of RECEIPT_ID_TABLES) {
+    const cols = db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+    if (!cols.some((c) => c.name === "receipt_id")) {
+      db.exec(`ALTER TABLE ${table} ADD COLUMN receipt_id TEXT`);
+    }
+  }
+
+  return {
+    async run(sql: string, params: any[] = []): Promise<void> {
+      db.prepare(sql).run(...params);
+    },
+    async get<T>(sql: string, params: any[] = []): Promise<T | undefined> {
+      return db.prepare(sql).get(...params) as T | undefined;
+    },
+    async all<T>(sql: string, params: any[] = []): Promise<T[]> {
+      return db.prepare(sql).all(...params) as T[];
+    },
+    async close(): Promise<void> {
+      db.close();
+    },
+  };
+}
+
+// Postgres adapter using pg Pool
+async function createPostgresDb(connectionString: string): Promise<Db> {
+  const { default: pg } = await import("pg");
+  const pool = new pg.Pool({ connectionString });
+
+  // Adapt SQLite-style ? placeholders to Postgres $1, $2, ... style
+  function adaptSql(sql: string): string {
+    let i = 0;
+    return sql.replace(/\?/g, () => `$${++i}`);
+  }
+
+  const pgSchema = SCHEMA.replace(/datetime\('now'\)/g, "NOW()");
+
+  const client = await pool.connect();
+  try {
+    await client.query(pgSchema);
+    // Migration: add receipt_id to pre-existing tables (Content Provenance §4.1).
+    for (const table of RECEIPT_ID_TABLES) {
+      await client.query(`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS receipt_id TEXT`);
+    }
+    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]
+        );
+      }
+    }
+  } finally {
+    client.release();
+  }
+
+  return {
+    async run(sql: string, params: any[] = []): Promise<void> {
+      await pool.query(adaptSql(sql), params);
+    },
+    async get<T>(sql: string, params: any[] = []): Promise<T | undefined> {
+      const result = await pool.query(adaptSql(sql), params);
+      return result.rows[0] as T | undefined;
+    },
+    async all<T>(sql: string, params: any[] = []): Promise<T[]> {
+      const result = await pool.query(adaptSql(sql), params);
+      return result.rows as T[];
+    },
+    async close(): Promise<void> {
+      await pool.end();
+    },
+  };
+}
+
+function maybeBackupSqlite(dbPath: string): void {
+  const backupPath = dbPath.replace(/\.db$/, ".backup.db");
+  if (!existsSync(dbPath)) return;
+
+  const shouldBackup =
+    !existsSync(backupPath) ||
+    Date.now() - statSync(backupPath).mtimeMs > 24 * 60 * 60 * 1000;
+
+  if (shouldBackup) {
+    try {
+      copyFileSync(dbPath, backupPath);
+      console.error(`[erp-mcp] backup written to ${backupPath}`);
+    } catch (err) {
+      console.error(`[erp-mcp] backup failed: ${err}`);
+    }
+  }
+}
+
+export async function createDb(): Promise<Db> {
+  const databaseUrl = process.env.DATABASE_URL ?? "";
+
+  if (databaseUrl.startsWith("postgres://") || databaseUrl.startsWith("postgresql://")) {
+    console.error("[erp-mcp] using Postgres");
+    return createPostgresDb(databaseUrl);
+  }
+
+  // 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 });
+  }
+
+  const dbPath = databaseUrl || join(hapDir, "erp.db");
+  maybeBackupSqlite(dbPath);
+
+  console.error(`[erp-mcp] using SQLite at ${dbPath}`);
+  return createSqliteDb(dbPath);
+}

package/src/index.ts

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} 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";
+
+const RECEIPT_FIELD = {
+  type: "string" as const,
+  description: "Suveren authorizing receipt id. Injected by the gateway — agents do not set this.",
+};
+
+const LINE_SCHEMA = {
+  type: "object" as const,
+  properties: {
+    item_id: { type: "string", description: "Item ID" },
+    qty: { type: "number", description: "Quantity (positive integer)" },
+  },
+  required: ["item_id", "qty"],
+};
+
+const TOOL_DEFINITIONS = [
+  // --- Reads ---
+  {
+    name: "list_items",
+    description: "List/search catalog items (sku, name, unit, list price, stock)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Text search across sku and name" },
+        limit: { type: "number", description: "Maximum results to return (default: 50)" },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "get_item",
+    description: "Get a single item, including stock and list price",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Item ID" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "find_customers",
+    description: "Search customers by name or email",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Text search across name and email" },
+        limit: { type: "number", description: "Maximum results to return (default: 50)" },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "get_customer",
+    description: "Get a single customer, including credit limit, open balance, and available credit",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Customer ID" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "list_quotes",
+    description: "List quotes, optionally filtered by status or customer",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: { type: "string", enum: ["draft", "sent", "converted", "cancelled"], description: "Filter by status" },
+        customer_id: { type: "string", description: "Filter by customer ID" },
+        limit: { type: "number", description: "Maximum results to return (default: 50)" },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "get_quote",
+    description: "Get a single quote with its lines",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Quote ID" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "list_orders",
+    description: "List orders, optionally filtered by customer",
+    inputSchema: {
+      type: "object",
+      properties: {
+        customer_id: { type: "string", description: "Filter by customer ID" },
+        limit: { type: "number", description: "Maximum results to return (default: 50)" },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "get_order",
+    description: "Get a single order with its lines",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Order ID" },
+      },
+      required: ["id"],
+    },
+  },
+
+  // --- Changes ---
+  {
+    name: "create_quote",
+    description:
+      "Create a draft quote for a customer. The connector recomputes the net total from the lines and the discount " +
+      "and refuses the call if the declared value, discount, or currency does not match.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        customer_id: { type: "string", description: "Customer ID" },
+        lines: { type: "array", items: LINE_SCHEMA, description: "Quote lines" },
+        discount_pct: { type: "number", description: "Document discount against list price, in percent (0-100)" },
+        value: { type: "number", description: "Net document total — must equal sum(qty*list_price)*(1-discount_pct/100)" },
+        currency: { type: "string", description: "Document currency — must match the customer's currency" },
+        valid_until: { type: "string", description: "ISO 8601 date the quote is valid until (optional)" },
+        notes: { type: "string", description: "Free-form notes (optional)" },
+        receipt_id: RECEIPT_FIELD,
+      },
+      required: ["customer_id", "lines", "discount_pct", "value", "currency"],
+    },
+  },
+  {
+    name: "update_quote",
+    description:
+      "Update a draft quote (lines, discount, valid_until, notes). Only draft quotes can be updated. The connector " +
+      "recomputes the net total and refuses the call if the declared value, discount, or currency does not match.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Quote ID" },
+        lines: { type: "array", items: LINE_SCHEMA, description: "Replacement quote lines (optional — omit to keep existing lines)" },
+        discount_pct: { type: "number", description: "Document discount against list price, in percent (0-100)" },
+        value: { type: "number", description: "Net document total — must equal sum(qty*list_price)*(1-discount_pct/100)" },
+        currency: { type: "string", description: "Document currency — must match the quote's currency" },
+        valid_until: { type: "string", description: "ISO 8601 date the quote is valid until (optional)" },
+        notes: { type: "string", description: "Free-form notes (optional)" },
+        receipt_id: RECEIPT_FIELD,
+      },
+      required: ["id", "discount_pct", "value", "currency"],
+    },
+  },
+  {
+    name: "send_quote",
+    description:
+      "Send a draft quote to the customer (draft -> sent). Simulated: marks the quote sent and records sent_at. " +
+      "The declared value, discount, and currency must match the quote as stored.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Quote ID" },
+        value: { type: "number", description: "Net document total — must match the quote's stored net total" },
+        discount_pct: { type: "number", description: "Must match the quote's stored discount — cannot change at send time" },
+        currency: { type: "string", description: "Must match the quote's stored currency" },
+        receipt_id: RECEIPT_FIELD,
+      },
+      required: ["id", "value", "discount_pct", "currency"],
+    },
+  },
+  {
+    name: "convert_quote_to_order",
+    description:
+      "Convert a sent quote into a confirmed order (sent -> order). Reserves stock for every line and refuses if the " +
+      "customer's credit limit would be exceeded or any line lacks sufficient stock.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Quote ID" },
+        value: { type: "number", description: "Net document total — must match the quote's stored net total" },
+        discount_pct: { type: "number", description: "Must match the quote's stored discount — cannot change at conversion time" },
+        currency: { type: "string", description: "Must match the quote's stored currency" },
+        requested_delivery: { type: "string", description: "Requested delivery date (ISO 8601, optional)" },
+        receipt_id: RECEIPT_FIELD,
+      },
+      required: ["id", "value", "discount_pct", "currency"],
+    },
+  },
+] as const;
+
+type ToolName = (typeof TOOL_DEFINITIONS)[number]["name"];
+
+async function main() {
+  const db = await createDb();
+
+  const server = new Server(
+    { name: "erp", version: "0.1.0" },
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOL_DEFINITIONS };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    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}`);
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`[erp-mcp] tool error (${name}):`, message);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ error: message }, null, 2),
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+
+  process.on("SIGINT", async () => {
+    await db.close();
+    process.exit(0);
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[erp-mcp] server started");
+}
+
+main().catch((err) => {
+  console.error("[erp-mcp] fatal:", err);
+  process.exit(1);
+});

package/src/money.ts

@@ -0,0 +1,43 @@
+/**
+ * The gateway enforces bounds (value_max, discount_max, ...) on the DECLARED
+ * `value`/`discount_pct`/`currency` fields of a tool call — it never inspects
+ * line items. That makes the declaration the security boundary: if the
+ * connector executed a document whose real total didn't match what was
+ * declared and bound-checked, the enforcement would be checking a number
+ * that has nothing to do with what actually happened. Every change tool in
+ * this connector must recompute the real total from the lines and refuse the
+ * call outright when the declaration doesn't match — never merely proceed
+ * with the "real" number instead.
+ */
+
+/** Tolerance for float rounding drift, in currency units. */
+export const VALUE_TOLERANCE = 0.01;
+
+export function roundToCents(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+export interface PricedLine {
+  qty: number;
+  list_price: number;
+}
+
+/** Net document total = sum(qty × list_price) × (1 − discount_pct/100), rounded to cents. */
+export function computeNetTotal(lines: PricedLine[], discountPct: number): number {
+  const gross = lines.reduce((sum, l) => sum + l.qty * l.list_price, 0);
+  return roundToCents(gross * (1 - discountPct / 100));
+}
+
+export function valuesMatch(a: number, b: number): boolean {
+  return Math.abs(a - b) <= VALUE_TOLERANCE;
+}
+
+export class RefusalError extends Error {}
+
+/** Refuse naming the field, the declared value, and the computed/expected value. */
+export function refuse(field: string, declared: unknown, expected: unknown, extra?: string): never {
+  const suffix = extra ? ` ${extra}` : "";
+  throw new RefusalError(
+    `Refused: ${field} mismatch — declared ${JSON.stringify(declared)}, expected ${JSON.stringify(expected)}.${suffix}`
+  );
+}

package/src/tools/customers.ts

@@ -0,0 +1,50 @@
+import type { Db } from "../db.js";
+import { roundToCents } from "../money.js";
+
+export interface Customer {
+  id: string;
+  name: string;
+  email: string | null;
+  country: string | null;
+  currency: string;
+  credit_limit: number;
+  open_balance: number;
+  payment_terms: string | null;
+}
+
+function withAvailableCredit(row: Customer) {
+  return { ...row, available_credit: roundToCents(row.credit_limit - row.open_balance) };
+}
+
+export async function find_customers(db: Db, args: Record<string, any>) {
+  const { query, limit = 50 } = args;
+
+  const conditions: string[] = [];
+  const params: any[] = [];
+
+  if (query) {
+    conditions.push("(name LIKE ? OR email LIKE ?)");
+    const like = `%${query}%`;
+    params.push(like, like);
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  params.push(limit);
+
+  const rows = await db.all<Customer>(`SELECT * FROM customers ${where} ORDER BY name LIMIT ?`, params);
+  return rows.map(withAvailableCredit);
+}
+
+export async function get_customer(db: Db, args: Record<string, any>) {
+  const { id } = args;
+  const row = await db.get<Customer>("SELECT * FROM customers WHERE id = ?", [id]);
+  if (!row) throw new Error(`Unknown customer id: ${id}`);
+  return withAvailableCredit(row);
+}
+
+/** Shared lookup used by the quote/order tools — throws the same "unknown id" shape as the read tool. */
+export async function requireCustomer(db: Db, id: string): Promise<Customer> {
+  const row = await db.get<Customer>("SELECT * FROM customers WHERE id = ?", [id]);
+  if (!row) throw new Error(`Unknown customer id: ${id}`);
+  return row;
+}