Skip to content

overview.md

Latest commit

 

History

History
374 lines (289 loc) · 10.7 KB

overview.md

File metadata and controls

374 lines (289 loc) · 10.7 KB
Raw

Architecture Overview

System Design

The Order Network eXchange standard defines a three-layer architecture that separates concerns and enables flexible implementation:

┌─────────────────────────────────────────────────────────────┐
│                     AI Agents / Clients                      │
│         (Claude, ChatGPT, Gemini, Custom Agents)            │
└─────────────────┬───────────────────────────────────────────┘
                  │ MCP Protocol
                  ▼
┌─────────────────────────────────────────────────────────────┐
│                  Order Network eXchange MCP Server                    │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                  Protocol Handler                    │   │
│  │   • Message parsing  • Request routing              │   │
│  │   • Validation       • Response formatting          │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                    Tool Registry                     │   │
│  │   • Tool discovery   • Parameter validation         │   │
│  │   • Error handling   • Response transformation      │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────┬───────────────────────────────────────────┘
                  │ Adapter Interface
                  ▼
┌─────────────────────────────────────────────────────────────┐
│              Fulfillment Backend (Your Implementation)               │
│                                                               │
│   • Existing Fulfillment    • ERP Systems    • WMS/3PL             │
│   • Custom Logic    • Databases      • External APIs        │
└───────────────────────────────────────────────────────────────┘

Core Concepts

1. Tools

Tools are callable functions that perform operations. They represent actions that change state or retrieve information.

interface Tool {
  name: string; // Unique identifier
  description: string; // Human-readable purpose
  parameters: Schema; // JSON Schema for inputs
  returns: Schema; // JSON Schema for outputs
}

2. Transport

The protocol supports multiple transport mechanisms:

  • stdio (Current): Standard input/output for local execution
  • HTTP (Future): REST-style endpoints for remote access
  • WebSocket (Future): Real-time bidirectional communication

3. Message Flow

1. Discovery
   Client: "What tools are available?"
   Server: Lists all implemented tools

2. Invocation
   Client: "Call create-sales-order with {...}"
   Server: Processes and returns result

3. Response
   Server: Success/failure with data
   Client: Handles response

Implementation Layers

Layer 1: MCP Protocol

Handles the low-level protocol mechanics:

class MCPProtocolHandler {
  // Parse incoming JSON-RPC messages
  parseMessage(input: string): Message;

  // Format outgoing responses
  formatResponse(result: any): string;

  // Handle protocol-level errors
  handleError(error: Error): ErrorResponse;
}

Layer 2: Tool Implementation

Your business logic for each operation:

class OrderTools {
  @tool({
    name: 'create-sales-order',
    description: 'Create a new order',
  })
  async createSalesOrder(params: OrderInput): Promise<OrderOutput> {
    // Your implementation
    return await this.fulfillment.createOrder(params);
  }
}

Layer 3: Fulfillment Adapter

Connects to your actual backend systems:

interface FulfillmentAdapter {
  // Abstract interface
  createSalesOrder(order: Order): Promise<Result>;
  cancelOrder(orderId: string): Promise<Result>;
  // ... other methods
}

class YourFulfillmentAdapter implements FulfillmentAdapter {
  // Your specific implementation
  async createSalesOrder(order: Order) {
    return await yourAPI.post('/orders', order);
  }
}

Data Flow Patterns

Synchronous Operations

Most tools follow a request-response pattern:

AI Agent                MCP Server              Fulfillment Backend
    │                        │                        │
    ├──── create-sales-order▶│                        │
    │                        ├──── validateOrder ────▶│
    │                        │◀──── validation OK ────┤
    │                        ├──── createOrder ──────▶│
    │                        │◀──── orderCreated ─────┤
    │◀──── success ─────────┤                        │

Asynchronous Operations

Long-running operations can return immediately:

AI Agent                MCP Server              Fulfillment Backend
    │                        │                        │
    ├──── fulfill-order ────▶│                        │
    │◀──── accepted ─────────┤                        │
    │                        ├──── processFulfillment▶│
    │                        │         (async)        │
    ├──── get-fulfillments ─▶│                        │
    │◀──── status: shipped ──┤◀──── completed ───────┤

Security Model

Authentication (Future)

interface Authentication {
  type: 'oauth2' | 'api-key' | 'jwt';
  credentials: Credentials;
  scopes: string[];
}

Authorization

interface Authorization {
  tool: string;
  principal: Principal;
  context: Context;
  decision: 'allow' | 'deny' | 'prompt';
}

Audit Trail

interface AuditLog {
  timestamp: ISO8601;
  tool: string;
  parameters: any;
  principal: Principal;
  result: 'success' | 'failure';
  metadata: Record<string, any>;
}

Error Handling

Error Categories

Code Range Category Description
1000-1999 Protocol MCP protocol errors
2000-2999 Validation Parameter validation
3000-3999 Business Business rule violations
4000-4999 System System-level failures
5000-5999 Fulfillment-Specific Custom Fulfillment errors

Error Response Format

interface ErrorResponse {
  code: number;
  message: string;
  details?: {
    field?: string;
    reason?: string;
    suggestion?: string;
  };
  retryable: boolean;
}

For authoritative codes, retryability, and best practices, see the canonical Error Model: Error Model.

Extensibility

Custom Tools

Add domain-specific operations:

// Standard tools
tool: 'create-sales-order';
tool: 'cancel-order';

// Your custom tools
tool: 'apply-discount';
tool: 'schedule-delivery';
tool: 'gift-wrap';

Vendor Extensions

Add vendor-specific data:

interface OrderExtensions {
  standard: StandardOrder;
  extensions: {
    'x-vendor-field': any;
    'x-custom-data': any;
  };
}

Version Management

interface Version {
  protocol: '1.0';
  implementation: '1.2.3';
  capabilities: string[];
}

Performance Considerations

Optimization Strategies

  1. Connection Pooling: Reuse connections to backend systems
  2. Caching: Cache frequently accessed data
  3. Batch Operations: Group multiple operations when possible
  4. Async Processing: Don't block on long operations

Benchmarks

Operation Target Response Time
Query operations < 200ms
Simple mutations < 500ms
Complex operations < 2000ms
Batch operations < 5000ms

Deployment Models

Local Development

cd mcp-reference-server/server
npm install
npm run dev

Production Deployment

Containerized

FROM node:18
COPY . /app
CMD ["npm", "start"]

Serverless

export const handler = async (event) => {
  return mcpServer.handle(event);
};

Edge Functions

export default {
  async fetch(request) {
    return mcpServer.handleRequest(request);
  },
};

Monitoring & Observability

Key Metrics

  • Request Rate: Tools invoked per second
  • Error Rate: Percentage of failed operations
  • Latency: P50, P95, P99 response times
  • Throughput: Orders processed per hour

Logging Strategy

logger.info('Tool invoked', {
  tool: 'create-sales-order',
  duration: 234,
  success: true,
});

Health Checks

interface HealthCheck {
  status: 'healthy' | 'degraded' | 'unhealthy';
  checks: {
    protocol: boolean;
    backend: boolean;
    database: boolean;
  };
  version: string;
  uptime: number;
}

Conclusion

The Order Network eXchange Standard architecture provides:

  • Separation of Concerns: Clean layers with defined responsibilities
  • Flexibility: Multiple implementation options
  • Scalability: From local development to global deployment
  • Extensibility: Add custom capabilities while maintaining compatibility
  • Reliability: Built-in error handling and monitoring

This architecture ensures that any Fulfillment can become AI-ready without major restructuring, while any AI can gain commerce capabilities without custom integrations.

Continue to: Tools Reference →