mcp-reference-server CLAUDE.md

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:

# 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/):

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