SAP Business One Service Layer MCP Server

A professional TypeScript MCP (Model Context Protocol) server that integrates with SAP Business One Service Layer API. This server provides efficient, session-managed access to SAP B1 data through a comprehensive set of MCP tools.

Features

• Session Management: Intelligent session handling with automatic renewal to avoid repeated logins
• Comprehensive API Coverage: Support for business partners, items, sales orders, invoices, and custom queries
• Multiple Transport Options: STDIO, HTTP, and Streaming HTTP (SSE) with API key authentication
• Production Ready: Professional error handling, logging, and configuration management
• Type Safe: Full TypeScript implementation with comprehensive type definitions
• Efficient: Reuses sessions and implements proper caching strategies

Prerequisites

• Bun >= 1.0.0 (Install Bun)
• Node.js >= 18 (for Node.js compatibility mode)
• SAP Business One with Service Layer enabled

Quick Start

1. Installation

bun install
bun run build

2. Configuration

Set up your SAP B1 connection using environment variables:

export SAP_B1_SERVER_URL="https://your-sap-server:50000/b1s/v1"
export SAP_B1_DATABASE="YOUR_COMPANY_DB"
export SAP_B1_USERNAME="manager"
export SAP_B1_PASSWORD="your-password"
export SAP_B1_SESSION_TIMEOUT="30"

Or create a config.json file (see Configuration section below).

3. Run the Server

STDIO Transport (default for MCP clients):

bun start

🔥 Streaming HTTP Transport (production HTTP with full MCP support + API key auth):

export MCP_TRANSPORT=streaming-http
export MCP_API_KEY="your-secure-api-key"
bun start

Basic HTTP Transport (health monitoring only):

export MCP_TRANSPORT=http
bun start

Docker Deployment

Quick Docker Start

# Build the optimized Docker image
bun run docker:build

# Configure environment
cp .env.docker .env
# Edit .env with your SAP B1 credentials

# Run with Docker Compose (recommended)
bun run docker:compose:up

The Docker image is highly optimized (~50-80MB) using Alpine Linux and Bun runtime. See DOCKER.md for complete Docker deployment guide.

Docker Features

• Minimal size: Multi-stage build with Alpine base
• Security hardened: Non-root user, read-only filesystem
• Health checks: Built-in container health monitoring
• Resource optimized: Memory and CPU limits
• Production ready: Kubernetes and Docker Compose configs

🔥 Streaming HTTP Transport (NEW!)

Full production-ready HTTP transport with complete MCP protocol support:

Key Features:

• ✅ Full MCP Protocol: All 14 tools work over HTTP
• 🔐 API Key Authentication: Secure access with configurable keys
• 📡 Server-Sent Events (SSE): Real-time streaming communication
• 🛡️ Production Security: CORS, request validation, connection management
• 📊 Monitoring: Health checks, connection stats, performance metrics

Quick Start:

# Configure streaming HTTP
export MCP_TRANSPORT=streaming-http
export MCP_API_KEY=your-secure-api-key-here
bun start

# Test the API
curl -H "X-API-Key: your-key" http://localhost:3000/mcp/auth

Complete Documentation: See STREAMING-HTTP.md for full API documentation, examples, and integration guides.

Configuration

The server supports configuration through environment variables or a JSON configuration file.

Environment Variables

| Variable | Required | Description | Default | |----------|----------|-------------|---------| | SAP_B1_SERVER_URL | ✅ | SAP B1 Service Layer URL | - | | SAP_B1_DATABASE | ✅ | Company database name | - | | SAP_B1_USERNAME | ✅ | SAP B1 username | - | | SAP_B1_PASSWORD | ✅ | SAP B1 password | - | | SAP_B1_SESSION_TIMEOUT | ❌ | Session timeout in minutes | 30 | | MCP_TRANSPORT | ❌ | Transport type (stdio or http) | stdio | | MCP_HTTP_PORT | ❌ | HTTP server port | 3000 | | MCP_HTTP_HOST | ❌ | HTTP server host | localhost | | LOG_LEVEL | ❌ | Log level (ERROR, WARN, INFO, DEBUG) | INFO | | NODE_ENV | ❌ | Environment (development, production, test) | development |

Configuration File

Create a config.json file in the project root:

{
  "serverUrl": "https://your-sap-server:50000/b1s/v1",
  "database": "YOUR_COMPANY_DB",
  "username": "manager",
  "password": "your-password",
  "sessionTimeout": 30
}

Run with configuration file:

bun start config.json

Available Tools

Authentication & Session Management

sap_login

Establish a new session with SAP Business One.

Parameters:

• force (boolean, optional): Force new login even if session exists

Example:

{
  "force": false
}

sap_logout

Terminate the current SAP Business One session.

sap_session_status

Check the validity and details of the current session.

Master Data Operations

sap_get_business_partners

Retrieve customers/vendors with optional filtering.

Parameters:

• filter (string): OData $filter expression
• select (string): Fields to select
• orderby (string): Sort expression
• top (number): Max records
• skip (number): Skip records
• cardType (string): Filter by type (cCustomer, cSupplier, cLid)

Examples:

{
  "filter": "CardType eq 'cCustomer'",
  "select": "CardCode,CardName,EmailAddress",
  "top": 10
}

{
  "cardType": "cCustomer",
  "filter": "CardName contains 'Microsoft'",
  "orderby": "CardName asc"
}

sap_create_business_partner

Create a new business partner.

Example:

{
  "CardName": "New Customer Corp",
  "CardType": "cCustomer",
  "EmailAddress": "[email protected]",
  "Phone1": "555-0123",
  "Address": "123 Business St",
  "ZipCode": "12345"
}

sap_update_business_partner

Update an existing business partner.

Example:

{
  "CardCode": "C20000",
  "updates": {
    "Phone1": "555-9999",
    "EmailAddress": "[email protected]"
  }
}

sap_get_items

Retrieve items with optional filtering.

Example:

{
  "filter": "SalesItem eq 'tYES' and QuantityOnStock gt 0",
  "select": "ItemCode,ItemName,QuantityOnStock,Price",
  "orderby": "ItemName asc"
}

sap_create_item

Create a new item.

Example:

{
  "ItemName": "New Product",
  "SalesItem": "tYES",
  "PurchaseItem": "tYES",
  "InventoryItem": "tYES"
}

Document Operations

sap_get_orders

Retrieve sales orders with optional filtering.

Example:

{
  "filter": "DocDate ge '2024-01-01' and CardCode eq 'C20000'",
  "expand": "DocumentLines",
  "orderby": "DocDate desc"
}

sap_create_order

Create a new sales order.

Example:

{
  "CardCode": "C20000",
  "DocDate": "2024-01-15",
  "DocDueDate": "2024-02-15",
  "Comments": "Urgent order",
  "DocumentLines": [
    {
      "ItemCode": "A00001",
      "Quantity": 5,
      "Price": 100.00
    },
    {
      "ItemCode": "A00002", 
      "Quantity": 2,
      "Price": 250.00
    }
  ]
}

sap_get_invoices

Retrieve invoices with optional filtering.

sap_create_invoice

Create a new invoice.

Example:

{
  "CardCode": "C20000",
  "DocDate": "2024-01-15",
  "DocumentLines": [
    {
      "BaseType": 17,
      "BaseEntry": 123,
      "BaseLine": 0,
      "Quantity": 5
    }
  ]
}

Query Operations

sap_query

Execute custom OData queries against any SAP B1 entity.

Parameters:

• entityType (string): Entity to query (e.g., BusinessPartners, Items, Orders)
• filter, select, expand, orderby, top, skip: OData query options

Example:

{
  "entityType": "Orders",
  "filter": "DocTotal gt 1000 and DocDate ge '2024-01-01'",
  "select": "DocEntry,DocNum,CardCode,DocTotal,DocDate",
  "expand": "DocumentLines",
  "orderby": "DocTotal desc",
  "top": 50
}

sap_cross_join

Execute cross-join queries for complex data relationships.

Example:

{
  "entities": ["BusinessPartners", "Orders"],
  "filter": "BusinessPartners/CardCode eq Orders/CardCode",
  "select": "BusinessPartners/CardName,Orders/DocTotal"
}

Usage Examples

Basic Customer Lookup

# Using with Claude or other MCP clients
{
  "tool": "sap_get_business_partners",
  "arguments": {
    "cardType": "cCustomer",
    "filter": "CardName contains 'Tech'",
    "select": "CardCode,CardName,Phone1,EmailAddress",
    "top": 10
  }
}

Creating a Sales Order

{
  "tool": "sap_create_order",
  "arguments": {
    "CardCode": "C20000",
    "Comments": "Monthly recurring order",
    "DocumentLines": [
      {
        "ItemCode": "SERVICE-01",
        "Quantity": 1,
        "Price": 1500.00,
        "ItemDescription": "Monthly Service Package"
      }
    ]
  }
}

Complex Query

{
  "tool": "sap_query",
  "arguments": {
    "entityType": "Orders",
    "filter": "DocStatus eq 'bost_Open' and DocDate ge '2024-01-01'",
    "select": "DocEntry,DocNum,CardCode,CardName,DocTotal,DocDate",
    "expand": "DocumentLines($select=ItemCode,Quantity,Price,LineTotal)",
    "orderby": "DocDate desc,DocTotal desc",
    "top": 25
  }
}

Architecture

src/
├── index.ts              # Main server entry point
├── transports/
│   ├── http.ts          # HTTP transport implementation  
│   └── stdio.ts         # STDIO transport implementation
├── sap/
│   ├── client.ts        # SAP B1 API client
│   ├── session.ts       # Session management
│   └── types.ts         # SAP B1 TypeScript types
├── tools/
│   ├── auth.ts          # Authentication tools
│   ├── master-data.ts   # Master data tools
│   ├── documents.ts     # Document tools
│   └── queries.ts       # Query tools
└── utils/
    ├── config.ts        # Configuration management
    └── logger.ts        # Logging utilities

Error Handling

The server provides comprehensive error handling:

• SAP API Errors: Wrapped with meaningful messages
• Session Management: Automatic renewal on expiration
• Network Issues: Retry logic for transient failures
• Validation: Input validation with clear error messages
• Logging: Structured logging for debugging

Security Considerations

• Passwords and session IDs are masked in logs
• Input sanitization prevents injection attacks
• Session cookies are handled securely
• HTTPS is supported for production deployments

Development

Building

bun run build

Development Mode (with hot reload)

bun run dev

Type Checking

bun run typecheck

Docker Commands

# Build Docker image
bun run docker:build

# Run with HTTP transport
bun run docker:run

# Run with STDIO transport  
bun run docker:run:stdio

# Docker Compose operations
bun run docker:compose:up    # Start services
bun run docker:compose:down  # Stop services
bun run docker:compose:logs  # View logs

# Health check
bun run docker:health

Production Deployment

1. Set Production Environment:

   export NODE_ENV=production
   export LOG_LEVEL=INFO

2. Use HTTPS for SAP Connection:

   export SAP_B1_SERVER_URL="https://your-sap-server:50000/b1s/v1"

3. Configure Session Timeout:

   export SAP_B1_SESSION_TIMEOUT=60  # Longer timeout for production

4. Run with Process Manager:

   Docker (Recommended):

   # Production with Docker Compose
   bun run docker:compose:up
      
   # Or Kubernetes deployment
   kubectl apply -f k8s-deployment.yaml

   Traditional Process Managers:

   # Using PM2 with Bun
   pm2 start --interpreter bun dist/index.js --name sap-mcp-server
      
   # Or run directly with Bun
   bun start
      
   # Or using systemd service
   systemctl start sap-mcp-server

HTTP Transport Usage

When using HTTP transport, the server provides additional endpoints:

• GET /health - Health check
• GET /info - Server information
• POST /message - MCP message endpoint

Client connection URL: http://localhost:3000/message

Troubleshooting

Common Issues

1. Connection Refused: Check SAP B1 Service Layer URL and network connectivity
2. Authentication Failed: Verify username, password, and database name
3. Session Expired: The server auto-renews sessions, but manual login may be needed
4. OData Errors: Check filter syntax and field names

Debug Logging

export LOG_LEVEL=DEBUG
bun start

Health Check

curl http://localhost:3000/health  # For HTTP transport

License

MIT

Support

For issues and feature requests, please check the repository documentation or contact the development team.