odata-mcp-proxy: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Install dependencies
npm install

# Development with hot reload
npm run dev

# Build TypeScript to dist/
npm run build

# Run built server (HTTP transport, default)
npm start

# Run with stdio transport (for Claude Desktop)
npm run start:stdio

# Run tests (node:test via tsx; builds first — the e2e test boots dist/index.js)
npm test

# Deploy to SAP BTP
npm run build:btp    # Build MTA archive
npm run deploy:btp   # Deploy via CF CLI

Tests live in test/ (unit tests for the UI layer and destination fallback, plus a stdio end-to-end test against a stub config in test/fixtures/).

Architecture

This is an MCP (Model Context Protocol) server that bridges AI assistants with SAP Cloud Integration (CPI) OData V2 APIs. It runs as either a stdio server (local Claude Desktop) or an HTTP server (SAP BTP Cloud Foundry deployment).

Transport Modes

• stdio (MCP_TRANSPORT=stdio): For Claude Desktop integration. Reads/writes over standard I/O.
• HTTP (MCP_TRANSPORT=http, default): Express-based server on port 4004. Uses Streamable HTTP with SSE (GET /mcp) for notifications, POST /mcp for requests, DELETE /mcp for session teardown. Session state maintained in-memory.

Request Flow

AI Assistant → MCP Protocol → McpServer (tool registry) → ODataClient → Destination Service → SAP CPI OData APIs

1. AI sends tool call (e.g. IntegrationPackages_list)
2. Tool handler in src/tools/registry.ts constructs an OData request
3. ODataClient (src/client/odata-client.ts) resolves the destination and executes the HTTP request via SAP Cloud SDK
4. resolveDestination() (src/client/destination-service.ts) returns credentials:
   • BTP mode: Uses @sap-cloud-sdk/connectivity with bound VCAP_SERVICES
   • Local mode: Uses env vars (SAP_CPI_BASE_URL, SAP_CPI_CLIENT_ID, SAP_CPI_CLIENT_SECRET, SAP_CPI_TOKEN_URL) for direct OAuth2