@humanagencyp/erp-mcp 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test

package/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # for npm provenance
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Upgrade npm
+        # Trusted Publishing (OIDC) needs npm 11.5+ to use the OIDC token instead
+        # of a bearer token. Mirrors hap-core's publish workflow.
+        run: npm install -g npm@11
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Verify tag matches package.json version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "Tag version ($TAG_VERSION) does not match package.json version ($PKG_VERSION)"
+            exit 1
+          fi
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Publish to npm
+        # Trusted Publishing via OIDC — no NPM_TOKEN. Requires a Trusted Publisher
+        # configured for this package on npmjs.com (repo + this workflow file).
+        run: npm publish --access public --provenance

package/README.md

@@ -0,0 +1,148 @@
+# HAP ERP MCP Server
+
+A generic ERP for AI agents, built as an [MCP](https://modelcontextprotocol.io) server and gated through the [Human Agency Protocol](https://humanagencyprotocol.org).
+
+> **@humanagencyp/erp-mcp** — unpublished (version 0.1.0, not yet on npm)
+
+---
+
+## What It Does
+
+The quote-to-order flow — the common subset of Microsoft Dynamics 365 Business Central
+(`salesQuotes` / `salesOrders` / `items` / `customers`), SAP Business One (`Quotations` /
+`Orders` / `Items` / `BusinessPartners`), and Odoo (`sale.order` / `product.product` /
+`res.partner`).
+
+- **Items** — catalog: sku, name, unit, list price, stock
+- **Customers** — name, currency, credit limit, open balance, payment terms
+- **Quotes** — draft → sent → converted, with lines priced off the item catalog
+- **Orders** — created by converting a sent quote; reserves stock
+
+Every write is gated through the HAP `sales` profile (`hap-profiles/sales/0.1.profile.json`).
+
+### Out of scope for 0.1
+
+No invoices, delivery notes, payments, credit memos, or master-data changes
+(no creating/editing items or customers). This connector only drives the
+quote-to-order flow; billing and fulfillment stay in the source ERP.
+
+---
+
+## Quick Start
+
+### Standalone
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+Starts the MCP server with a SQLite database at `~/.hap/erp.db` (seeded with a
+small demo dataset — 8 items, 5 customers — on first run).
+
+For Postgres:
+
+```bash
+DATABASE_URL=postgres://user:pass@host:5432/mydb node dist/index.js
+```
+
+---
+
+## Tools
+
+### Reads
+
+| Tool | Description |
+|------|-------------|
+| `list_items` | Search items by sku/name |
+| `get_item` | Get an item, including stock and list price |
+| `find_customers` | Search customers by name/email |
+| `get_customer` | Get a customer, including credit limit, open balance, available credit |
+| `list_quotes` | List quotes, filter by status/customer |
+| `get_quote` | Get a quote with its lines |
+| `list_orders` | List orders, filter by customer |
+| `get_order` | Get an order with its lines |
+
+### Changes
+
+| Tool | Description |
+|------|-------------|
+| `create_quote` | Create a draft quote (customer, lines, discount, value, currency) |
+| `update_quote` | Update a draft quote (lines, discount, value, currency) — draft only |
+| `send_quote` | Mark a draft quote sent (simulated — no email is actually sent) — draft → sent |
+| `convert_quote_to_order` | Convert a sent quote into a confirmed order, reserving stock — sent → order |
+
+Every change tool **requires** `value`, `discount_pct`, and `currency` in its call arguments.
+
+---
+
+## Why the connector re-derives the total (this is the point)
+
+The gateway's bounds engine enforces limits on the **declared** `value`,
+`discount_pct`, and `currency` fields of a tool call — it has no visibility
+into line items. That makes the declaration the security boundary: if this
+connector executed whatever document the lines actually describe while the
+gateway bound-checked a different, merely-asserted number, the bound would be
+decorative.
+
+So every change tool:
+
+1. **Recomputes** the net total as `sum(qty × list_price) × (1 − discount_pct / 100)`,
+   rounded to cents, and refuses the call if the declared `value` differs by
+   more than 0.01.
+2. Refuses if the declared `discount_pct` is outside `[0, 100]`, or — on
+   `send_quote` / `convert_quote_to_order` — differs from the discount already
+   recorded on the document (the discount is fixed once a quote is sent).
+3. Refuses if the declared `currency` differs from the customer's currency
+   (on `create_quote`) or the document's stored currency (on
+   `update_quote` / `send_quote` / `convert_quote_to_order`).
+4. On `convert_quote_to_order`: refuses if `open_balance + net_total` would
+   exceed the customer's `credit_limit`, and refuses if any line lacks
+   sufficient stock. Only after every line clears the stock check does it
+   reserve (decrement) stock — a shortfall on any line rejects the whole
+   conversion instead of partially reserving.
+5. Enforces the document state machine: `update_quote` and `send_quote` only
+   act on `draft` quotes; `convert_quote_to_order` only acts on `sent` quotes
+   (which also blocks double-conversion — a converted quote is no longer
+   `sent`).
+6. Refuses unknown `customer_id`/`item_id`, and non-positive or non-integer
+   `qty`.
+
+Every refusal is returned as `isError: true` with a message naming the field,
+the declared value, and the computed/expected value.
+
+---
+
+## Database
+
+**SQLite (default)** — zero config. Data stored at `~/.hap/erp.db` (or
+`${HAP_DATA_DIR}/erp.db` when the gateway sets `HAP_DATA_DIR`). Auto-backup to
+`erp.backup.db` daily.
+
+**Postgres** — set `DATABASE_URL` to a connection string. For teams where
+multiple gateways need shared access.
+
+Schema is created automatically on first start, and a deterministic demo
+dataset is seeded when the `items` table is empty.
+
+---
+
+## HAP Profile
+
+This server is gated through the `sales` profile
+(`github.com/humanagencyprotocol/hap-profiles/sales@0.1`):
+
+- **Action types** — `quote`, `send`, `order`
+- **Bounds** — `read_access`, `value_max`, `discount_max`, `order_value_daily_max`,
+  `quote_daily_max`, `send_daily_max`, `order_daily_max`
+- **Execution fields** — `value`, `discount_pct`, `currency` (all `source: "declared"`,
+  verified by this connector against the lines before the gateway ever sees them)
+
+---
+
+## License
+
+MIT
+
+See [humanagencyprotocol.org](https://humanagencyprotocol.org) for the full protocol specification.

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node