From fbb0767f84c3159ea8b48c27a9cdbdb18232b1b7 Mon Sep 17 00:00:00 2001 From: Eugene Kim Date: Tue, 25 Nov 2025 15:50:21 -0500 Subject: [PATCH 1/5] Set publishConfig to public --- .github/workflows/release.yml | 4 ++-- server/package.json | 3 +++ 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ed8abc0..fc42cd5 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -73,7 +73,7 @@ jobs: - name: Publish to NPM working-directory: server - run: npm publish + run: npm publish --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} @@ -127,4 +127,4 @@ jobs: ### Changes See [CHANGELOG.md](CHANGELOG.md) for details. draft: false - prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') || contains(github.ref, 'rc') }} \ No newline at end of file + prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') || contains(github.ref, 'rc') }} diff --git a/server/package.json b/server/package.json index f04e808..b933947 100644 --- a/server/package.json +++ b/server/package.json @@ -73,6 +73,9 @@ "engines": { "node": ">=18.0.0" }, + "publishConfig": { + "access": "public" + }, "files": [ "dist", "schemas", From 110042eab3dd1d9e9ffce4c84d149cbbf2153872 Mon Sep 17 00:00:00 2001 From: Tim Dauer Date: Mon, 2 Mar 2026 09:09:04 +0100 Subject: [PATCH 2/5] docs/issue-29: Add CLAUDE.md & some structure for AI-assisted development Provide structured guidance for e.g. Claue Code including project structure development commands, architecture overview, and MCP adapter behavioral principles. --- CLAUDE.md | 150 ++++++++++++++++++++++++++ backends/README.md | 48 +++++++++ backends/your-backend/CAPABILITIES.md | 79 ++++++++++++++ 3 files changed, 277 insertions(+) create mode 100644 CLAUDE.md create mode 100644 backends/README.md create mode 100644 backends/your-backend/CAPABILITIES.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..1faeaac --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,150 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Commerce Operations Foundation MCP Server - implements the Order Network eXchange Standard (onX) providing a standardized interface between AI agents and fulfillment systems via the Model Context Protocol (MCP). + +## Project Structure + +``` +/server - Core MCP server implementation (main development here) +/adapter-template - Template for creating custom fulfillment adapters +/schemas - JSON Schema definitions for domain models +/backends - Backend-specific capability manifests +/docs - Specification and integration guides +``` + +## Development Commands + +All primary development happens in `/server`. Run these from the `server/` directory: + +```bash +# Build +npm run build # Compile TypeScript +npm run dev # Run with hot reload (vite-node) +npm start # Run production build + +# Test +npm test # Build + run all tests +npm run test:unit # Unit tests only +npm run test:integration # Integration tests +npx vitest tests/unit/adapters/adapter-factory.test.ts # Single test file +npx vitest tests/unit --grep "pattern" # Tests matching pattern + +# Quality +npm run lint # ESLint +npm run format # Prettier +npm run typecheck # Type checking +``` + +For adapter development (`adapter-template/`): +```bash +npm run build # tsc +npm run dev # tsc --watch +npm test # Jest with ES modules +``` + +## Architecture + +### MCP Server (server/) + +Three-layer architecture: +1. **Protocol Layer** - MCP SDK integration, stdio transport, request routing +2. **Service Layer** - `ServiceOrchestrator` facade, `AdapterManager`, health monitoring, validation +3. **Adapter Layer** - `AdapterFactory` with dynamic loading (built-in, NPM, or local adapters) + +**Tools**: 5 action tools + 7 query tools defined in `src/tools/`, registered via `registerTools()` in `ToolRegistry` + +**Configuration**: Environment variables override config file which overrides defaults. Key vars: `ADAPTER_TYPE`, `ADAPTER_NAME/PACKAGE/PATH`, `LOG_LEVEL` + +See [server/CLAUDE.md](server/CLAUDE.md) for detailed server architecture. + +### ES Module Requirements + +- All imports use `.js` extension +- `type: "module"` in package.json +- Use `import`/`export`, not `require` + +--- + +# MCP Server Principles + +The MCP server acts as an adapter between a generic tool schema and a concrete backend. It does not implement business logic, does not infer missing data, and remains fully backend-agnostic. + +--- + +## Core Principles + +### 1. Backend-Agnostic Behavior + +- The MCP server must not assume or enforce backend-specific requirements. +- It implements only the tool specification and passes requests/responses through. +- It performs no additional validation beyond the minimal schema validation defined by the MCP tool. + +### 2. No Business Logic Inside the MCP Server + +- The MCP server must not fill in missing fields. +- It must not generate placeholder values (e.g., "Unknown", "N/A"). +- It must not attempt to "fix" or "repair" incomplete requests. +- It must not apply heuristics to guess user intent or missing data. + +### 3. Transparent Error Propagation + +- Backend errors must be returned to the agent exactly as received. +- The MCP server must not modify, hide, or reinterpret backend errors. +- The agent is responsible for asking the user for missing information. + +--- + +## Error Handling Philosophy + +### Behavior When Required Fields Are Missing + +If the backend requires additional fields (e.g., `customerName`) that are not mandatory in the MCP schema: + +1. The MCP server forwards the request unchanged to the backend. +2. The backend returns an error. +3. The MCP server returns this error unchanged to the agent. +4. The agent asks the user for the missing information. + +### General Error Handling Rules + +- The MCP server must propagate backend errors transparently. +- It must never attempt to repair or complete invalid requests. +- Backend-specific error codes and messages should pass through unchanged. + +--- + +## Capability Definition + +Each backend integration must define its own **capability manifest** that specifies: + +1. **Actions** (write operations) - Methods that modify state +2. **Queries** (read operations) - Methods that retrieve data without side effects +3. **Error documentation** - Backend-specific error handling rules + +See the `backends/` directory for backend-specific capability definitions. + +--- + +## Usage Rules for Claude + +These rules apply to all MCP server integrations: + +- Claude MUST use only the methods defined in the backend's capability manifest. +- Claude MUST NOT invent new methods or assume additional capabilities. +- Claude MUST choose the correct method based on user intent (read vs. write). +- Claude MUST follow all error-handling rules defined in the backend's error documentation. +- Claude MUST NOT attempt to bypass the MCP server or call backend endpoints directly. + +--- + +## Backend Integrations + +| Backend | Capability Manifest | +|---------|---------------------| +| [your-backend] | [backends/your-backend/CAPABILITIES.md](backends/your-backend/CAPABILITIES.md) | + +> To add a new backend, create a new directory under `backends/` with a `CAPABILITIES.md` file following the same structure. diff --git a/backends/README.md b/backends/README.md new file mode 100644 index 0000000..ea35486 --- /dev/null +++ b/backends/README.md @@ -0,0 +1,48 @@ +# Backend Integrations + +This directory contains backend-specific capability definitions for the MCP server. + +## Structure + +Each backend has its own directory containing: + +``` +backends/ +├── README.md # This file +└── [your-backend]/ # Your backend + └── CAPABILITIES.md # Capability manifest +``` + +## Adding a New Backend + +1. Create a new directory under `backends/` with your backend name +2. Create a `CAPABILITIES.md` file following this structure: + +```markdown +# [Backend Name] Backend Capabilities + +## Canonical Tool List +[List all supported methods] + +### Actions (Write Operations) +[Methods that modify state] + +### Queries (Read Operations) +[Methods that retrieve data] + +## Usage Rules for Claude +[Backend-specific usage guidelines] + +## Error Documentation +[Links to error handling documentation] +``` + +3. Update the "Backend Integrations" table in the root `CLAUDE.md` + +## Principles + +All backend integrations must follow the generic MCP adapter principles defined in [CLAUDE.md](../CLAUDE.md): + +- Backend-agnostic behavior +- No business logic in the adapter +- Transparent error propagation diff --git a/backends/your-backend/CAPABILITIES.md b/backends/your-backend/CAPABILITIES.md new file mode 100644 index 0000000..d5f4d3f --- /dev/null +++ b/backends/your-backend/CAPABILITIES.md @@ -0,0 +1,79 @@ +# [Your Backend] Capabilities + +This document defines the MCP server capabilities for your backend integration. +It follows the generic MCP adapter principles defined in [CLAUDE.md](../../CLAUDE.md). + +--- + +## Canonical Tool List + +These operations define the full surface area of the MCP specification for this backend integration. + +The MCP server MUST NOT introduce additional methods, rename existing ones, or change their semantics. +Each method maps directly to a backend API endpoint as described below. + +--- + +### Actions (Write Operations) + +These operations modify state in the backend. +Claude should use them only when the user explicitly requests a state-changing operation. + +- **createSalesOrder(input)** + Maps to: `POST /api/orders` + Creates a new sales order in the backend. + +- **cancelOrder(input)** + Maps to: `POST /api/orders/:id/cancel` + Cancels an existing order. + +- **updateOrder(input)** + Maps to: `PATCH /api/orders/:id` + Updates fields of an existing order. + +> Note: Additional action methods may be implemented in future iterations. + +--- + +### Queries (Read Operations) + +These operations retrieve data from the backend and MUST NOT modify state. + +- **getOrders(input)** + Maps to: `GET /api/orders/:id` + Retrieves order details. + +> Note: Additional query methods may be implemented in future iterations. + +--- + +## Usage Rules for Claude + +- Claude MUST use these methods as the only valid tool interface for interacting with this backend. +- Claude MUST NOT invent new methods or assume additional capabilities. +- Claude MUST choose the correct method based on user intent (read vs. write). +- Claude MUST follow all error-handling rules defined in the linked error documentation. +- Claude MUST NOT attempt to bypass the MCP server or call backend endpoints directly. + +--- + +## Error Documentation + +The MCP server must propagate backend errors transparently and never attempt to repair or complete invalid requests. + +| Operation | Error Reference | +|-----------|-----------------| +| Create order | [Link to error documentation] | +| Cancel order | [Link to error documentation] | +| Update order | [Link to error documentation] | +| Get order | [Link to error documentation] | + +> Note: Replace these with links to your actual error documentation. + +--- + +## Related Documentation + +- [Link to your backend API documentation] +- [Link to authentication documentation] +- [Link to additional resources] From c3c1570bfb8b9b4e93cf658b0e41af992fdd3f8f Mon Sep 17 00:00:00 2001 From: Tim Dauer <59570228+timdauer@users.noreply.github.com> Date: Mon, 2 Mar 2026 09:48:41 +0100 Subject: [PATCH 3/5] Update backends/your-backend/CAPABILITIES.md --- backends/your-backend/CAPABILITIES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/backends/your-backend/CAPABILITIES.md b/backends/your-backend/CAPABILITIES.md index d5f4d3f..b1f2b2d 100644 --- a/backends/your-backend/CAPABILITIES.md +++ b/backends/your-backend/CAPABILITIES.md @@ -10,7 +10,7 @@ It follows the generic MCP adapter principles defined in [CLAUDE.md](../../CLAUD These operations define the full surface area of the MCP specification for this backend integration. The MCP server MUST NOT introduce additional methods, rename existing ones, or change their semantics. -Each method maps directly to a backend API endpoint as described below. +Each method maps directly to a backend functionality, e.g. API endpoints as described below. --- From afc4264bbcb85480cabc9ae8f984eb819e9f2c7e Mon Sep 17 00:00:00 2001 From: Tim Dauer <59570228+timdauer@users.noreply.github.com> Date: Mon, 2 Mar 2026 09:49:45 +0100 Subject: [PATCH 4/5] Update .github/workflows/release.yml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index fc42cd5..ebc89b9 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -73,7 +73,7 @@ jobs: - name: Publish to NPM working-directory: server - run: npm publish --access public + run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} From 9529858956c88e268948a7e9ca64a4a411056b20 Mon Sep 17 00:00:00 2001 From: Tim Dauer <59570228+timdauer@users.noreply.github.com> Date: Mon, 2 Mar 2026 09:51:01 +0100 Subject: [PATCH 5/5] Update server/package.json Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- server/package.json | 3 --- 1 file changed, 3 deletions(-) diff --git a/server/package.json b/server/package.json index b933947..f04e808 100644 --- a/server/package.json +++ b/server/package.json @@ -73,9 +73,6 @@ "engines": { "node": ">=18.0.0" }, - "publishConfig": { - "access": "public" - }, "files": [ "dist", "schemas",