sap-sales-order-mcp

Production-ready MCP server for SAP S/4HANA Sales Order Management. Sandbox-first, offline-testable, built on FastMCP.

A reference implementation showing how to build a maintainable, testable MCP server that connects Claude (or any MCP client) to an enterprise system. Uses the public SAP API Business Hub sandbox — no on-prem SAP install needed.

Why this repo exists: most MCP + SAP examples show a toy server with one tool and no error handling. This one applies the patterns from Anthropic's Claude Certified Architect (Foundations) curriculum — boundary descriptions, structured errors, offline mocks, and a tool-selection reliability harness — to a real (public) SAP API.

5-Minute Quickstart

# 1. Clone + install
git clone https://github.com/coding-with-abbi/sap-sales-order-mcp.git
cd sap-sales-order-mcp
pip install -e .

# 2. Smoke-test all 4 tools offline (no API key needed)
python mcp_server.py --selftest

# 3. Add your SAP API key (get it free at api.sap.com)
cp .env.example .env
# Edit .env: SAP_API_KEY=<your key>

# 4. Verify live connection
LIVE_TESTS=1 python -m pytest tests/test_integration_live.py

Add to Claude Desktop (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "sap-sales-orders": {
      "command": "python",
      "args": ["/absolute/path/to/sap-sales-order-mcp/mcp_server.py"],
      "env": {
        "SAP_API_KEY": "your_key_here"
      }
    }
  }
}

Restart Claude Desktop, then ask: "Show me all open sales orders for customer 17100001."

Related MCP server: odata-mcp-proxy

Tools

Four tools, each with boundary descriptions (USE WHEN / DO NOT use) that guide Claude to pick the right one on ambiguous requests. See docs/ARCHITECTURE.md for the design rationale.

Full contracts (docstrings): src/sap_sales_mcp/tools.py. More prompts + responses: docs/EXAMPLES.md.

Architecture Highlights

• Offline-first. Unit tests + --selftest run against a MockSAPClient with realistic OData v2 fixtures. No API key, no network. Live tests are opt-in via LIVE_TESTS=1.

• Structured errors. Every failure returns a ToolError with errorCategory (transient|validation|business|permission) + isRetryable — never a bare "failed" string. Claude can act on them.

• Boundary descriptions. Each tool's docstring explicitly states USE WHEN and DO NOT use for, with cross-references. A tool-selection-reliability harness empirically verifies that these descriptions guide the model correctly on ambiguous requests.

• Retry policy. Bounded exponential backoff (1s/2s/4s) on transient HTTP errors only. Never on validation, business, or permission errors.

• Lazy imports. The offline codepath is stdlib-only — httpx, mcp, python-dotenv are imported lazily in live functions. Unit tests run without them.

• Path-scoped rules. .claude/rules/python.md and .claude/rules/mcp-tool-design.md load only when editing matching files — root CLAUDE.md stays lean.

Testing

# Unit tests (offline, always safe)
python -m pytest

# Tool-selection harness (deterministic proxy for LLM tool-picking)
python tool_selection_harness.py

# Integration tests against real SAP sandbox
LIVE_TESTS=1 python -m pytest tests/test_integration_live.py

Current status: 53 passed + 5 skipped (5 skipped = live tests, opt-in).

Documentation

• docs/SETUP.md — Full setup guide (SAP API Hub, Claude Desktop, troubleshooting)

• docs/ARCHITECTURE.md — Design decisions + CCA-F pattern rationale

• docs/EXAMPLES.md — 10 prompt/response examples

• docs/NEXT-STEPS.md — v2 ideas (create-order with approval gate, OAuth, more domains)

• CONTRIBUTING.md — How to contribute

Positioning

Built by Jacob Abb — AI Consultant & Engineer specialising in Enterprise-AI (RAG, Voicebots, SAP+GenAI). This project is part of a public reference portfolio; adapt it for your own SAP system or use it as a template for other SAP domains (Business Partner, Purchase Order, Materials).

Related: the patterns here (boundary descriptions, structured errors, tool-selection harness) come directly from Anthropic's Claude Certified Architect – Foundations curriculum.

Credits

• SAP — API Business Hub for the sandbox

• Anthropic — MCP protocol + Claude Certified Architect curriculum

• FastMCP — the Python MCP framework this server is built on

License

MIT — use freely, adapt for your production SAP systems, fork it for other domains. PRs welcome (see CONTRIBUTING.md).