s4hanaopn_mcpserver by cjpark-sapcsa - MCP Server

Agentic AI for S/4HANA Sales Operations with MCP Server

Enterprise-grade agentic AI solution that empowers business users and sales teams to interact with SAP S/4HANA 2023 FPS02 through natural language conversations. Built on Model Context Protocol (MCP) with secure API Management gateway and intelligent approval workflows.

Overview

This repository provides an agentic AI platform for S/4HANA sales operations, connecting AI agents (Copilot Studio, GitHub Agents, M365 Copilot) directly to S/4HANA 2023 FPS02 via a secure MCP server.

Key Capabilities:

Natural Language Operations: "Show me orders for customer ABC" or "Create a sales order for 100 units"
Intelligent Approval Workflows: Automated routing with Teams integration for governance
Enterprise Security: APIM gateway with subscription keys and comprehensive monitoring
Production Ready: 2000+ lines of code with error handling and Azure Functions deployment

Business Impact:

🚀 Accelerated Processing: Natural language to S/4HANA sales orders instantly
🛡️ Governance & Compliance: Built-in approval workflows with audit trails
📱 Teams Integration: One-click approvals directly in Microsoft Teams

Features

Core Functionality:

Business Partner & Sales Order Management with approval workflows
Teams Integration with real-time notifications and approval buttons
MCP Protocol Support for Claude Desktop and AI agents
Enterprise Security with payload validation and governance controls

Technical Stack:

Azure Functions serverless architecture with auto-scaling
APIM Gateway for secure endpoint management and rate limiting
Azure Blob Storage for persistent approval tracking and audit trails

Technical Architecture

Core Stack (2000+ lines):

MCP Protocol Server with SSE communication
APIM Gateway for secure endpoint exposure
Azure Functions serverless MCP host with enterprise security
S/4HANA OData Integration with CSRF handling and approval workflows
Teams Integration via Power Automate webhooks and adaptive cards
Azure Blob Storage for persistent approval tracking with audit trails

Production Features:

14 Azure Function endpoints covering MCP, Copilot Studio, and approval workflows
Intelligent date parsing with S/4HANA OData format conversion
Complete payload cleanup preventing S/4HANA API errors
Environment-based security with externalized credentials

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐
│   MCP Clients   │    │   APIM Gateway   │    │   S/4HANA System    │
│ • M365 Copilot  │◄──►│                  │◄──►│   OData APIs        │
│ • GitHub Agent  │    │  ┌─────────────┐ │    │                     │
│ • Claude Desktop│    │  │Azure Functions│ │  │                     │
│                 │    │  │  MCP Host     │ │  │                     │
└─────────────────┘    │  └─────────────┘ │    └─────────────────────┘
                       └──────────────────┘
                                │
                                ▼
                       ┌─────────────────────────────────────────┐
                       │        Approval Workflow Engine         │
                       │                                         │
                       │  ┌─────────────┐   ┌─────────────────┐  │
                       │  │Azure Blob   │   │Power Automate   │  │
                       │  │Storage      │◄─►│Teams Workflow   │  │ 
                       │  │• Persistence│   │• YES/NO Buttons │  │
                       │  │• Audit Trail│   │• Adaptive Cards │  │
                       │  └─────────────┘   └─────────────────┘  │
                       │                                         │
                       │  ┌─────────────┐   ┌─────────────────┐  │
                       │  │HTTP Approval│   │Email Notifications │ 
                       │  │Endpoints    │   │• Request Alerts │  │
                       │  │• approve-req│   │• Status Updates │  │
                       │  │• reject-req │   │• Auto-routing   │  │
                       │  └─────────────┘   └─────────────────┘  │
                       └─────────────────────────────────────────┘

Power Automate Teams Approval Workflow

Complete Sales Order Creation Process (8 Steps)

🔍 Request Submission: AI assistant or user submits sales order creation request via MCP
🛡️ Automatic Interception: System intercepts ALL sales order creation attempts (governance enforcement)
💾 Persistent Storage: Request saved to Azure Blob Storage with unique request ID (SO-REQ-YYYYMMDDHHMMSS)
🚀 Power Automate Trigger: Teams workflow initiated with adaptive card containing YES/NO buttons
📱 Teams Notification: Approver receives interactive Teams message with:
- Complete sales order details
- YES button (approve-request endpoint)
- NO button (reject-request endpoint)
- Requester information and justification
⚡ Real-time Decision: Approver clicks YES/NO directly in Teams (no external navigation)
🎯 Automatic Processing:
- YES: Sales order automatically created in S/4HANA + success notifications
- NO: Request marked rejected + rejection notifications sent
📧 Status Notifications: All parties notified of final decision with audit trail

Governance Rules

🔒 No Direct Creation: All sales order creation must go through approval workflow
🧹 Payload Cleanup: Custom fields automatically removed before S/4HANA submission
📧 Audit Trail: All requests tracked with timestamps, approvers, and justifications
⚡ Real-time Notifications: Instant Teams and email alerts for all stakeholders

Power Automate Teams Integration Details

Teams Adaptive Card Features

Interactive YES/NO Buttons: Direct approval/rejection without leaving Teams
Complete Request Details: Full sales order information displayed in card
Requester Context: Shows who requested and why (justification field)
One-Click Actions: Buttons trigger HTTP GET requests to approval endpoints
Real-time Updates: Card updates automatically when decision is made

HTTP Approval Endpoints

/api/approve-request?request_id={id}: Approves pending request (triggered by YES button)
/api/reject-request?request_id={id}: Rejects pending request (triggered by NO button)
/api/create-so-request: Creates new approval request (triggered by MCP sales order creation)

Azure Blob Storage Integration

Persistent Request Storage: All approval requests survive function restarts/scaling
Automatic Status Updates: Request status updated in real-time (pending → approved/rejected)
Complete Audit Trail: Full history with timestamps, approvers, and justifications
Scalable Architecture: Handles concurrent approval requests efficiently

Email Notification System

Request Notifications: Sent when new approval request is created
Decision Notifications: Sent when request is approved/rejected
Status Updates: Real-time updates to all stakeholders
Automated Routing: Based on request type and business rules

Prerequisites

Development Environment

Python 3.11+ - Required for Azure Functions runtime
Azure Functions Core Tools - For local development and deployment
Visual Studio Code - IDE with GitHub Copilot integration

GitHub & AI Agent Access

GitHub Premium/Pro Account - Required for GitHub Agents with premium models
Claude Sonnet 4.0 Access - Premium AI model access through GitHub Agents
GitHub Copilot Chat - Integrated AI assistance in VS Code
MCP Client Support - VS Code extension for Model Context Protocol

Microsoft 365 & Azure Services

M365 Copilot License - For business user AI agent access
Azure Subscription - Required for all Azure services deployment
Azure Functions - Serverless compute platform
Azure API Management (APIM) - Gateway and security layer (Basic SKU or higher required for MCP server export)
Azure Blob Storage - Persistent approval request storage
Azure Application Insights - Monitoring and telemetry

Power Platform & Teams Integration

Power Automate Premium - Required for custom connectors and Teams workflows
Microsoft Teams - For approval workflow notifications
Teams Developer Mode - Enable custom app/connector uploads
Custom Connector Creation - Power Automate connector development access
Zip File Upload Capability - Teams admin permission for custom app deployment

SAP S/4HANA Access

SAP S/4HANA On-Premises System - With Gateway services and OData services enabled
S/4HANA Service Account - Technical user with Gateway service authorization
OData API Access - Business Partner and Sales Order APIs via Gateway services
Gateway Service Configuration - Services activated in SICF transaction
Network Connectivity - Azure to S/4HANA network access (typically port 8000 for Gateway)

Required Permissions & Licenses

Azure Contributor Role - For resource deployment and management
Teams Application Developer - For custom Teams app deployment
Power Automate Premium License - For advanced workflow features
APIM Developer Access - For API gateway configuration
S/4HANA Developer/Integration User - For OData API access

Installation

Build End-to-End Flow

The complete deployment follows this sequence:

Azure Functions Development → Local MCP server development and testing (Step 1-2)
Deployment to Azure Portal → Azure Functions deployment with environment configuration (Step 4)
APIM Import API → Import Azure Functions as backend API in API Management (Step 4)
Creation of MCP Server Under APIM → Export APIM API as MCP server endpoint (Step 4)
Export of OpenAPI v3 (YAML or JSON) → Generate API specification for Copilot Studio (Step 7)
Copilot Studio Creation of Agent → Create AI agent using OpenAPI specification (Step 6)
Creation of Custom Connector → Power Automate connector for Teams integration (Step 8)
Add Custom Connector as Tool in Copilot Studio → Integrate approval workflow in agent (Step 9)
Test run for MCP Tool Discovery → Validate complete end-to-end functionality (Step 10)
Publish into Copilot Agent → Deploy agent for business user access (Step 6)

Step 1: Environment Setup

Clone the repository:

git clone https://github.com/cjpark-sapcsa/s4hanaopn_mcpserver.git
cd s4hanaopn_mcpserver

Create and activate virtual environment:

# Windows
python -m venv .venv
.venv\Scripts\activate

# Linux/Mac
python3 -m venv .venv
source .venv/bin/activate

Install Python dependencies:

pip install -r requirements.txt

Install Azure Functions Core Tools:

# Windows (via npm)
npm install -g azure-functions-core-tools@4 --unsafe-perm true

# macOS (via Homebrew)
brew tap azure/functions
brew install azure-functions-core-tools@4

# Linux (via package manager)
curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
sudo mv microsoft.gpg /etc/apt/trusted.gpg.d/microsoft.gpg
sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-ubuntu-$(lsb_release -cs)-prod $(lsb_release -cs) main" > /etc/apt/sources.list.d/dotnetdev.list'
sudo apt-get update
sudo apt-get install azure-functions-core-tools-4

Step 2: Local Configuration

Create local settings file:

cp local.settings.json.template local.settings.json

Configure local.settings.json with your environment details:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "SAP_BASE_URL": "http://your-s4hana-server:8000",
    "SAP_USER": "your-service-account",
    "SAP_PASS": "your-service-password",
    "FUNCTION_APP_BASE_URL": "http://localhost:7071",
    "TEAMS_WEBHOOK_URL": "https://prod-xx.westus.logic.azure.com:443/workflows/...",
    "AZURE_STORAGE_CONNECTION_STRING": "your-storage-connection-string",
    "BLOB_STORAGE_ACCOUNT_URL": "https://yourstorageaccount.blob.core.windows.net",
    "BLOB_CONTAINER_NAME": "salesorderrequest"
  }
}

Create MCP client configuration:

mkdir -p .vscode

Create .vscode/mcp.json:

{
    "servers": {
        "s4hana-mcp-server-local": {
            "url": "http://localhost:7071/api/sse",
            "type": "http",
            "headers": {
                "Content-Type": "application/json"
            }
        }
    },
    "inputs": []
}

Step 3: Azure Resource Setup & APIM MCP Server Creation

Create Azure Resource Group:

az login
az group create --name rg-s4hana-mcp --location eastus

Create Azure Storage Account:

az storage account create \
  --name s4hanamcpstorage \
  --resource-group rg-s4hana-mcp \
  --location eastus \
  --sku Standard_LRS

Get Storage Connection String:

az storage account show-connection-string \
  --name s4hanamcpstorage \
  --resource-group rg-s4hana-mcp \
  --output tsv

Create Blob Container:

az storage container create \
  --name salesorderrequest \
  --account-name s4hanamcpstorage \
  --auth-mode login

Create API Management Service (Required for MCP Server):

az apim create \
  --resource-group rg-s4hana-mcp \
  --name your-s4hana-apim \
  --publisher-email admin@yourcompany.com \
  --publisher-name "Your Company" \
  --sku-name Basic \
  --location eastus

Note: APIM creation takes 30-45 minutes. Continue with other steps while it provisions.

Step 4: Azure Deployment & APIM MCP Server Setup

Create Azure Function App:

az functionapp create \
  --resource-group rg-s4hana-mcp \
  --consumption-plan-location eastus \
  --runtime python \
  --runtime-version 3.11 \
  --functions-version 4 \
  --name your-s4hana-mcp-app \
  --storage-account s4hanamcpstorage

Deploy to Azure:

func azure functionapp publish your-s4hana-mcp-app

Configure Application Settings:

az functionapp config appsettings set \
  --name your-s4hana-mcp-app \
  --resource-group rg-s4hana-mcp \
  --settings \
    SAP_BASE_URL="http://your-s4hana-server:8000" \
    SAP_USER="your-service-account" \
    SAP_PASS="your-service-password" \
    FUNCTION_APP_BASE_URL="https://your-s4hana-mcp-app.azurewebsites.net" \
    TEAMS_WEBHOOK_URL="https://your-teams-webhook-url" \
    BLOB_CONTAINER_NAME="salesorderrequest"

Import Azure Function into APIM:
- Navigate to Azure Portal → API Management → your-s4hana-apim
- Select APIs → Add API → Function App
- Choose your deployed Function App: your-s4hana-mcp-app
- Import all functions as API endpoints
Create MCP Server from APIM:

Microsoft Reference: Export a REST API from Azure API Management as an MCP server

In APIM → APIs → Select your imported Function App API
Click Export → Model Context Protocol (MCP)
Configure MCP server settings:
- Server Name: s4hana-mcp-server
- Description: S/4HANA Sales Operations MCP Server
- Endpoint: /mcp (auto-generated)
Generate subscription key for secure access

Get MCP Server Endpoint:
- MCP URL: https://your-s4hana-apim.azure-api.net/mcp
- Subscription Key: Copy from APIM → Subscriptions
- Backend: https://your-s4hana-mcp-app.azurewebsites.net

Step 5: Local Testing & Verification

Start Azure Functions locally:

func start

You should see output like:

Functions:
    sse: [GET,POST] http://localhost:7071/api/sse
    approve-request: [GET,POST] http://localhost:7071/api/approve-request
    reject-request: [GET,POST] http://localhost:7071/api/reject-request
    create-so-request: [POST] http://localhost:7071/api/create-so-request
    health: [GET] http://localhost:7071/api/health

Test health endpoint:

curl http://localhost:7071/api/health

Test MCP tools discovery (Local):

curl -X POST http://localhost:7071/api/sse \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Test Azure Functions endpoint (after deployment):

curl https://your-s4hana-mcp-app.azurewebsites.net/api/health

Test APIM MCP endpoint (production):

curl -X POST https://your-s4hana-apim.azure-api.net/mcp \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: your-subscription-key" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Step 6: Copilot Studio MCP Integration

Official Guide: Follow the Microsoft official documentation: Extend agent actions using Model Context Protocol (MCP)

Prerequisites for Copilot Studio MCP Integration

Copilot Studio License: Required for agent creation and MCP integration
APIM MCP Server: Your S/4HANA MCP server deployed via APIM (Step 4)
Admin Access: Copilot Studio environment admin permissions
Subscription Key: APIM subscription key for secure access

1. Prepare MCP Server Endpoint

Ensure your APIM MCP server is accessible:

# Verify your MCP server is accessible
curl -X POST https://your-s4hana-apim.azure-api.net/mcp \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: your-subscription-key" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

2. Create Agent in Copilot Studio

Navigate to Copilot Studio: https://copilotstudio.microsoft.com
Create New Agent:
- Select "Create" → "New agent"
- Choose "Skip to configure" for manual setup
- Name your agent: "S/4HANA Sales Assistant"
- Description: "Agent for S/4HANA sales order and business partner operations"

3. Add MCP Actions to Agent

Access Agent Actions:
- Open your created agent
- Navigate to "Actions" tab
- Select "Add an action" → "Model Context Protocol (MCP)"
Configure MCP Server Connection:
- Server URL: https://your-s4hana-apim.azure-api.net/mcp
- Connection Name: S4HANA-MCP-Server
- Authentication: Select "API key" and provide your APIM subscription key
- Test Connection: Verify connection works

4. Configure Available Actions

After connecting, Copilot Studio will discover available MCP tools:

Select S/4HANA Actions:
- ✅ query_s4hana - Query S/4HANA entities
- ✅ create_s4hana_entity - Create S/4HANA entities (with approval workflow)
- ✅ check_approval_status - Check sales order approval status
- ✅ check_and_create_sales_orders - Automated sales order workflow
Configure Action Parameters:
- Review each action's input/output schema
- Set parameter descriptions for better agent understanding
- Configure any required authentication or headers

5. Agent Configuration

Instructions: Add agent behavior instructions:

You are an S/4HANA sales assistant. You can help users:
- Query sales orders and business partner data
- Create new sales orders (requires approval workflow)
- Check approval status of pending requests

Always inform users that sales order creation requires approval and provide request IDs for tracking.

Knowledge Sources (Optional):
- Upload S/4HANA documentation
- Add business process guides
- Include approval workflow instructions

6. Test Agent Integration

Test in Copilot Studio:
- Use the "Test" panel
- Try queries like: "Show me recent sales orders"
- Test creation: "Create a sales order for customer USCU_L10"
- Verify approval workflow triggers

Sample Test Conversations:

User: "Show me sales orders for customer USCU_L10"
Agent: Uses query_s4hana action → Returns sales order data

User: "Create a sales order for customer USCU_L10"
Agent: Uses create_s4hana_entity → Triggers approval workflow → Returns request ID

7. Publish Agent

Save and Publish:
- Review agent configuration
- Click "Publish" to make available to users
- Configure user access permissions
Distribution:
- Share agent with business users
- Provide guidance on S/4HANA operations
- Explain approval workflow process

Step 7: Export OpenAPI v3 for Custom Connector

Export OpenAPI Specification from APIM:
- Navigate to Azure Portal → API Management → your-s4hana-apim
- Select APIs → Select your S/4HANA Function App API
- Click Export → OpenAPI v3 (YAML) or OpenAPI v3 (JSON)
- Download the specification file (e.g., s4hana-api-spec.yaml)

Validate OpenAPI Specification:

# Verify the downloaded specification contains required endpoints
# Key endpoints for Power Automate integration:
# - /api/create-so-request
# - /api/approve-request
# - /api/reject-request
# - /api/check-approval-status

Prepare for Custom Connector Creation:
- Ensure OpenAPI spec includes proper authentication (API key)
- Verify all required sales order endpoints are documented
- Check parameter definitions for Power Automate compatibility

Step 8: Power Automate & Teams Setup

Create Power Automate Flow:
- Go to Power Automate portal
- Create new automated flow
- Trigger: "When an HTTP request is received"
- Add "Post adaptive card in Teams" action
- Configure YES/NO buttons to call approve/reject endpoints
Enable Teams Developer Mode:
- Teams Admin Center → Teams apps → Setup policies
- Enable "Upload custom apps"
- Enable developer mode for target users
Create Custom Connector (if needed):
- Power Automate → Custom connectors
- Import OpenAPI definition from Step 7
- Configure authentication (API key)
- Test connector endpoints

Step 9: Add Custom Connector as Tool in Copilot Studio

Import Custom Connector into Copilot Studio:
- Navigate back to your S/4HANA Sales Assistant agent in Copilot Studio
- Go to Actions tab → Add an action → Custom connector
- Select the Power Automate custom connector created in Step 8
- Configure connector authentication and parameters
Configure Approval Workflow Actions:
- Enable Actions:
  - ✅ create-so-request - Submit sales orders for approval
  - ✅ approve-request - Approve pending requests
  - ✅ reject-request - Reject pending requests
  - ✅ check-approval-status - Query approval status

Update Agent Instructions:

You now have access to approval workflow actions. When users request sales order creation:
1. Use MCP actions for data queries and validation
2. Use custom connector actions for approval workflow management
3. Always provide request IDs for tracking
4. Explain the approval process to users

Test Integration:
- Test MCP + Custom Connector workflow
- Verify Teams notifications trigger properly
- Ensure approval buttons work correctly

Step 10: Verification

Test end-to-end flow:
- Use MCP client to query sales orders
- Create a sales order (should trigger approval)
- Check Teams for approval notification
- Click YES/NO buttons
- Verify S/4HANA creation or rejection
Monitor with Application Insights:
- Check function execution logs
- Monitor approval workflow metrics
- Verify Teams webhook delivery

Troubleshooting

Common Issues:

Function fails to start locally:

# Check Python version
python --version  # Should be 3.11+

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

S/4HANA connection issues:
- Verify network connectivity
- Check SAP user permissions
- Test OData endpoints manually
Teams webhook not working:
- Verify webhook URL in local.settings.json
- Test webhook with curl
- Check Power Automate flow configuration
APIM import fails:
- Validate OpenAPI YAML syntax
- Check backend URL configuration
- Verify subscription key setup

Configuration

Copy local.settings.json.template to local.settings.json
Update the configuration:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "SAP_BASE_URL": "http://your-s4hana-server:port",
    "SAP_USER": "your-sap-username",
    "SAP_PASS": "your-sap-password",
    "FUNCTION_APP_BASE_URL": "https://your-function-app.azurewebsites.net",
    "TEAMS_WEBHOOK_URL": "https://your-teams-webhook-url",
    "AZURE_STORAGE_CONNECTION_STRING": "your-azure-storage-connection-string",
    "BLOB_STORAGE_URL": "https://your-storage-account.blob.core.windows.net/salesorderrequest",
    "BLOB_STORAGE_ACCOUNT_URL": "https://your-storage-account.blob.core.windows.net",
    "BLOB_CONTAINER_NAME": "salesorderrequest"
  }
}

Environment Variables

SAP_BASE_URL: S/4HANA server base URL
SAP_USER: S/4HANA service account username
SAP_PASS: S/4HANA service account password
FUNCTION_APP_BASE_URL: Azure Function App base URL for API callbacks
TEAMS_WEBHOOK_URL: Microsoft Teams webhook for approval notifications
AZURE_STORAGE_CONNECTION_STRING: Azure Blob Storage connection string for approval persistence
BLOB_STORAGE_URL: Azure Blob Storage URL for approval requests
BLOB_STORAGE_ACCOUNT_URL: Azure Storage account URL (for managed identity authentication)
BLOB_CONTAINER_NAME: Blob container name for storing approval requests

Business User Transparency & MCP Workflow Visibility

Challenge: Hidden AI Decision-Making

Business users using Copilot Studio → MCP servers → M365 Copilot/Teams cannot see:

Which MCP functions were called
What data sources were accessed
How AI made decisions
What approval workflows were triggered

Solution: Enhanced Response Transparency

1. MCP Response Metadata (Implemented)

All MCP responses now include source attribution:

{
  "data": [...],
  "metadata": {
    "source": "SAP S/4HANA Sales Orders API",
    "mcp_function": "query_s4hana",
    "entity_queried": "salesorders", 
    "query_parameters": "$top=10&$filter=SoldToParty eq 'USCU_L10'",
    "timestamp": "2025-08-03T10:30:00Z",
    "approval_required": true,
    "request_id": "SO-REQ-20250803103000"
  }
}

2. Transparent Approval Notifications

Teams adaptive cards show complete workflow context:

Data Source: "Retrieved from S/4HANA via MCP Server"
Function Called: "create_s4hana_entity (salesorders)"
Governance Action: "Automatic approval routing enforced"
Request Origin: "AI Assistant via Copilot Studio"

3. Business User Response Format

Copilot Studio responses enhanced with transparency:

"Based on data retrieved from SAP S/4HANA (via MCP server query_s4hana function at 10:30 AM), 
here are the top 10 sales orders for customer USCU_L10. Since you requested to create a new 
sales order, this has been automatically routed through our approval workflow (request ID: 
SO-REQ-20250803103000). You'll receive a Teams notification when approved."

4. Audit Trail Visibility

Business users can check approval status and see complete audit trail:

MCP function calls and parameters
Data sources accessed
Approval workflow steps
Decision timestamps and approvers

Available Tools

Query Tools

query_s4hana: Query S/4HANA entities with OData parameters
check_approval_status: Check status of sales order approval requests

Create Tools

create_s4hana_entity: Create new entities in S/4HANA (enforces approval workflow for sales orders)

Workflow Tools

check_and_create_sales_orders: Automated sales order workflow with approval enforcement

Approval Workflow API Endpoints

Sales Order Approval Endpoints

Create Approval Request: /api/create-so-request - Submit sales order for approval
Approve Request: /api/approve-request?request_id={id} - Approve pending request
Reject Request: /api/reject-request?request_id={id} - Reject pending request
Check Status: Query approval status via MCP check_approval_status tool

Usage Examples

Query Sales Orders

# Query recent sales orders
response = await query_s4hana(
    entity="salesorders",
    query="$top=10&$orderby=CreationDate desc"
)

Create Sales Order with Approval Workflow

# Create sales order request (automatically routes through approval)
response = await create_s4hana_entity(
    entity="salesorders",
    payload={
        "SalesOrderType": "OR",
        "SoldToParty": "USCU_L10",
        "TransactionCurrency": "USD",
        "PurchaseOrderByCustomer": "PO-2025-001",
        "RequestedDeliveryDate": "/Date(1723680000000)/",
        "created_by": "Sarah_Sales",
        "justification": "Urgent customer requirement for Q2 production"
    }
)
# Returns: {"status": "approval_required", "request_id": "SO-REQ-20250730123456", ...}

Check Approval Status

# Check status of approval request
response = await check_approval_status(
    request_id="SO-REQ-20250730123456"
)
# Returns: {"status": "pending|approved|rejected", "created_by": "...", ...}

Approve Sales Order Request

# Approve via HTTP GET (typically triggered by Teams button)
curl "http://localhost:7071/api/approve-request?request_id=SO-REQ-20250730123456"

Deployment

Local Development & Testing

1. MCP Client Configuration for Localhost

Create/update .vscode/mcp.json for local testing:

{
    "servers": {
        "s4hana-mcp-server-local": {
            "url": "http://localhost:7071/api/sse",
            "type": "http",
            "headers": {
                "Content-Type": "application/json"
            }
        }
    },
    "inputs": []
}

2. Start Azure Functions Locally

# Start the MCP host locally
func start

# Should show:
# Functions:
#   sse: [GET,POST] http://localhost:7071/api/sse
#   approve-request: [GET,POST] http://localhost:7071/api/approve-request
#   reject-request: [GET,POST] http://localhost:7071/api/reject-request
#   create-so-request: [POST] http://localhost:7071/api/create-so-request

3. Test MCP Communication

# Test MCP tools discovery
curl -X POST http://localhost:7071/api/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

4. Test Teams Workflow (Localhost)

Update local.settings.json for localhost testing:

{
  "Values": {
    "FUNCTION_APP_BASE_URL": "http://localhost:7071",
    "TEAMS_WEBHOOK_URL": "https://your-teams-webhook-url",
    "SAP_BASE_URL": "http://your-s4hana-server:port"
  }
}

5. Complete Localhost Test Flow

Start Functions: func start
Configure MCP Client: Update .vscode/mcp.json to localhost:7071
Test Query: Use MCP client to query sales orders
Test Approval: Create sales order → triggers localhost approval workflow
Teams Integration: Approval buttons call localhost:7071/api/approve-request
Verify Flow: Check Azure Blob Storage and Teams notifications

6. Localhost to Azure Migration

When ready for production:

# Deploy to Azure
func azure functionapp publish your-function-app-name

# Configure APIM Gateway (mandatory for production)
az apim create --resource-group rg-s4hana-mcp --name your-s4hana-apim --sku-name Basic

# Update MCP client configuration
# FROM: "url": "http://localhost:7071/api/sse"
# TO:   "url": "https://your-s4hana-apim.azure-api.net/mcp"

Azure Deployment

func start

Azure Deployment

func azure functionapp publish your-function-app-name

APIM Gateway Configuration (Mandatory)

After Azure Functions deployment, the MCP server must be exposed through Azure API Management:

Azure Functions (MCP Host): https://your-function-app.azurewebsites.net
APIM Gateway (MCP Server): https://your-s4hana-apim.azure-api.net
MCP Endpoint: /mcp (using APIM's MCP server export feature)

Architecture Flow:

MCP Clients → APIM Gateway → Azure Functions → S/4HANA OData APIs

Benefits of APIM Gateway:

Enterprise Security: Subscription key authentication and OAuth integration
Rate Limiting: Request throttling and quota management
Monitoring: Comprehensive API analytics and usage tracking
Policy Enforcement: Custom policies for validation, transformation, and caching
MCP Protocol Support: Native MCP server export functionality

Production MCP Client Configuration

Update .vscode/mcp.json for production with APIM Gateway:

{
    "servers": {
        "s4hana-mcp-server": {
            "url": "https://your-s4hana-apim.azure-api.net/mcp",
            "type": "http",
            "headers": {
                "Content-Type": "application/json",
                "Ocp-Apim-Subscription-Key": "your-subscription-key"
            }
        }
    },
    "inputs": []
}

## API Endpoints

### MCP Protocol Endpoints
- SSE Endpoint: `/api/sse` - Server-Sent Events for MCP communication
- Tools Discovery: `/api/tools` - Available MCP tools

### Copilot Studio Compatible Endpoints
- Query Sales Orders: `/api/query-sales-orders` - Query sales orders (Copilot Studio format)
- Query Business Partners: `/api/query-business-partners` - Query business partners
- Create Sales Order: `/api/create-sales-order` - Create sales order with approval workflow

### Power Automate Teams Approval Workflow Endpoints
- Create Approval Request: `/api/create-so-request` - Submit sales order for approval
- Approve Request: `/api/approve-request?request_id={id}` - Approve pending request (YES button)
- Reject Request: `/api/reject-request?request_id={id}` - Reject pending request (NO button)

### Utility Endpoints
- Health Check: `/api/health` - Service health status and connectivity check

### Teams Webhook Integration Flow
1. MCP Request → `/api/sse` → Sales order creation intercepted
2. Approval Creation → `/api/create-so-request` → Azure Blob Storage + Teams notification
3. Teams Adaptive Card → YES button → `/api/approve-request?request_id=X`
4. Teams Adaptive Card → NO button → `/api/reject-request?request_id=X`
5. Automatic S/4HANA Creation → Upon approval → Direct OData API call
6. Status Notifications → Email + Teams updates to all stakeholders

## Supported S/4HANA Entities

### Business Partner API
- `businesspartners` - Business partner master data
- `businesspartneraddresses` - Partner addresses
- `businesspartnercontacts` - Partner contacts
- `customers` - Customer data
- `suppliers` - Supplier data

### Sales Order API
- `salesorders` - Sales order headers
- `salesorderitems` - Sales order line items
- `salesorderheaderpartners` - Header partner data
- `salesorderitempartners` - Item partner data
- `salesorderschedulelines` - Schedule lines
- `salesordertexts` - Header texts
- `salesorderitemtexts` - Item texts

## Security

- Approval Workflow Governance: All sales order creation enforced through approval process
- Payload Validation: Automatic removal of custom fields to prevent S/4HANA API errors
- Azure AD Authentication: Supported for enterprise integration
- Environment Variable Security: Sensitive credentials stored in environment variables
- Network Security: Azure private endpoints and VNet integration supported
- Audit Trail: All approval requests logged with timestamps and approvers
- Access Control: Role-based access to approval endpoints

## Monitoring

- Application Insights Integration: Comprehensive telemetry and performance monitoring
- Azure Monitor Metrics: Real-time health and performance metrics
- Custom Logging: Detailed approval workflow and S/4HANA integration logs
- Health Check Endpoints: Automated service health monitoring
- Approval Workflow Tracking: Complete audit trail of all approval requests
- Teams Notification Monitoring: Delivery status tracking for Teams messages
- S/4HANA Connectivity Monitoring: Real-time OData API connectivity checks

## Testing

### Test Environment Setup

#### Prerequisites for Testing
- Azure Function App deployed - MCP server running in Azure
- S/4HANA connectivity - Test system access configured
- Power Automate flow - Teams approval workflow active
- Azure Blob Storage - Container for approval requests
- MCP Client - VS Code with MCP extension or Copilot Studio agent

#### Test Data Requirements
- Test Customer: `USCU_L10` (or valid S/4HANA customer)
- Test Materials: Valid material numbers in S/4HANA
- Test Users: Approved sales users and approvers
- Teams Channels: Configured for approval notifications

### Unit Testing

#### 1. Health Check Tests
```bash
# Test basic connectivity
curl https://your-s4hana-mcp-app.azurewebsites.net/api/health

# Expected Response:
{
  "status": "healthy",
  "timestamp": "2025-08-03T10:30:00Z",
  "sap_connectivity": "ok",
  "blob_storage": "ok",
  "teams_webhook": "ok"
}

2. MCP Protocol Tests

# Test MCP tools discovery
curl -X POST https://your-s4hana-mcp-app.azurewebsites.net/api/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Expected: List of available MCP tools
# - query_s4hana
# - create_s4hana_entity  
# - check_approval_status
# - check_and_create_sales_orders

3. S/4HANA Connectivity Tests

# Test business partner query
curl -X POST https://your-s4hana-mcp-app.azurewebsites.net/api/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "query_s4hana",
      "arguments": {
        "entity": "businesspartners",
        "query": "$top=5"
      }
    }
  }'

# Expected: Business partner data from S/4HANA

Integration Testing

1. End-to-End Sales Order Creation Flow

Step 1: Submit Sales Order Request

curl -X POST https://your-s4hana-mcp-app.azurewebsites.net/api/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "create_s4hana_entity",
      "arguments": {
        "entity": "salesorders",
        "payload": {
          "SalesOrderType": "OR",
          "SoldToParty": "USCU_L10",
          "TransactionCurrency": "USD",
          "PurchaseOrderByCustomer": "TEST-PO-001",
          "created_by": "Test_User",
          "justification": "Integration test order"
        }
      }
    }
  }'

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "status": "approval_required",
    "request_id": "SO-REQ-20250803103000",
    "message": "Sales order request submitted for approval",
    "teams_notification": "sent",
    "metadata": {
      "source": "SAP S/4HANA Sales Orders API",
      "mcp_function": "create_s4hana_entity",
      "approval_required": true
    }
  }
}

Step 2: Verify Teams Notification

Check Teams channel for adaptive card
Verify YES/NO buttons are present
Confirm request details are displayed

Step 3: Test Approval Process

# Approve the request
curl "https://your-s4hana-mcp-app.azurewebsites.net/api/approve-request?request_id=SO-REQ-20250803103000"

# Expected: Sales order created in S/4HANA + success notifications

Step 4: Verify S/4HANA Creation

# Query created sales order
curl -X POST https://your-s4hana-mcp-app.azurewebsites.net/api/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "query_s4hana",
      "arguments": {
        "entity": "salesorders",
        "query": "$filter=SoldToParty eq '\''USCU_L10'\''&$orderby=CreationDate desc&$top=1"
      }
    }
  }'

2. Approval Rejection Flow

Test Rejection Process:

# Submit test order
# ... (same as Step 1 above)

# Reject the request
curl "https://your-s4hana-mcp-app.azurewebsites.net/api/reject-request?request_id=SO-REQ-20250803103001"

# Expected: Request marked as rejected, no S/4HANA creation

Verify Rejection:

# Check approval status
curl -X POST https://your-s4hana-mcp-app.azurewebsites.net/api/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "check_approval_status",
      "arguments": {
        "request_id": "SO-REQ-20250803103001"
      }
    }
  }'

Expected Response:

{
  "status": "rejected",
  "request_id": "SO-REQ-20250803103001",
  "created_by": "Test_User",
  "rejected_by": "Approver_User",
  "rejection_timestamp": "2025-08-03T10:35:00Z"
}

Copilot Studio Agent Testing

1. Agent Conversation Tests

Test Query Operations:

User: "Show me recent sales orders for customer USCU_L10"
Expected: Agent calls query_s4hana → Returns sales order data with metadata

Test Sales Order Creation:

User: "Create a sales order for customer USCU_L10 with material M001, quantity 10"
Expected: Agent calls create_s4hana_entity → Returns approval request ID

Test Approval Status Check:

User: "Check status of approval request SO-REQ-20250803103000"
Expected: Agent calls check_approval_status → Returns current status

2. Agent Response Validation

Verify Transparency Features:

Responses include MCP function names
Data source attribution is present
Approval workflow explanations are clear
Request IDs are provided for tracking

Performance Testing

1. Load Testing Scripts

Concurrent Query Test:

# Test 10 concurrent business partner queries
for i in {1..10}; do
  curl -X POST https://your-s4hana-mcp-app.azurewebsites.net/api/sse \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": '$i',
      "method": "tools/call",
      "params": {
        "name": "query_s4hana",
        "arguments": {
          "entity": "businesspartners",
          "query": "$top=5"
        }
      }
    }' &
done
wait

Approval Workflow Load Test:

# Test 5 concurrent approval requests
for i in {1..5}; do
  curl -X POST https://your-s4hana-mcp-app.azurewebsites.net/api/create-so-request \
    -H "Content-Type: application/json" \
    -d '{
      "SalesOrderType": "OR",
      "SoldToParty": "USCU_L10",
      "TransactionCurrency": "USD",
      "PurchaseOrderByCustomer": "LOAD-TEST-'$i'",
      "created_by": "Load_Test_User",
      "justification": "Load testing request '$i'"
    }' &
done
wait

2. Performance Benchmarks

Expected Response Times:

Health Check: < 500ms
MCP Tools List: < 1s
Business Partner Query: < 3s
Sales Order Query: < 3s
Approval Request Creation: < 5s
Teams Notification: < 10s

Error Handling Tests

1. Invalid Input Tests

Test Invalid Entity:

curl -X POST https://your-s4hana-mcp-app.azurewebsites.net/api/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "query_s4hana",
      "arguments": {
        "entity": "invalid_entity",
        "query": "$top=5"
      }
    }
  }'

# Expected: Error response with clear message

Test Missing Required Fields:

curl -X POST https://your-s4hana-mcp-app.azurewebsites.net/api/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "create_s4hana_entity",
      "arguments": {
        "entity": "salesorders",
        "payload": {
          "SalesOrderType": "OR"
        }
      }
    }
  }'

# Expected: Validation error for missing SoldToParty

2. S/4HANA Connectivity Tests

Test S/4HANA Unavailable:

Temporarily disable S/4HANA connectivity
Verify graceful error handling
Check retry mechanisms

Test Invalid Credentials:

Use incorrect SAP credentials
Verify authentication error handling
Ensure no credential exposure in logs

Security Testing

1. Authentication Tests

Test Unauthorized Access:

# Test without proper authentication
curl -X POST https://your-s4hana-mcp-app.azurewebsites.net/api/sse \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer invalid_token" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

# Expected: Authentication error (if auth is configured)

2. Input Validation Tests

Test SQL Injection Attempts:

curl -X POST https://your-s4hana-mcp-app.azurewebsites.net/api/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
      "name": "query_s4hana",
      "arguments": {
        "entity": "businesspartners",
        "query": "$filter=BusinessPartner eq '\'''; DROP TABLE--"
      }
    }
  }'

# Expected: Input sanitization, no security vulnerability

Monitoring & Observability Tests

1. Application Insights Validation

Verify Telemetry Collection:

Check Application Insights for request traces
Verify custom logging events
Confirm performance metrics collection

2. Error Tracking Tests

Trigger Known Errors:

Submit invalid approval request ID
Test with malformed JSON
Verify errors are properly logged and tracked

Test Results Documentation

Success Criteria

✅ All MCP protocol methods respond correctly
✅ S/4HANA integration works without errors
✅ Approval workflow completes successfully
✅ Teams notifications are delivered
✅ Performance benchmarks are met
✅ Security validations pass
✅ Error handling behaves as expected
✅ Monitoring and logging function properly

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the file for details.

Support

For support and questions:

Create an issue on GitHub
Contact: Microsoft Cloud AI Platform team

Changelog

v2.1.0 (Current)

NEW: Enhanced date formatting system with automatic S/4HANA OData date conversion (/Date(timestamp)/)
NEW: Azure Blob Storage integration for persistent approval request tracking
NEW: Comprehensive payload validation and cleanup for S/4HANA API compatibility
NEW: Advanced error handling with detailed logging and status tracking
NEW: Production-ready security with environment variable configuration
NEW: Multi-format date parsing supporting ISO 8601 and custom formats
ENHANCED: Complete approval workflow with blob storage persistence across function restarts
ENHANCED: Teams integration with real-time adaptive card notifications
ENHANCED: S/4HANA OData API integration with CSRF token handling
ENHANCED: Robust error recovery and retry mechanisms
ENHANCED: Security hardening - all credentials moved to environment variables

v2.0.0

NEW: Complete approval workflow implementation for sales order creation
NEW: Microsoft Teams integration with real-time notifications and approval buttons
NEW: Email notification system for approval requests and status updates
NEW: Payload cleanup functionality to prevent S/4HANA API errors
NEW: Governance controls - all sales order creation enforced through approval workflow
NEW: Copilot Studio compatible endpoints for enterprise integration
ENHANCED: Comprehensive audit trail and status tracking
ENHANCED: Error handling and validation for S/4HANA integration
ENHANCED: Security controls and access management

v1.0.0

Initial release
Basic S/4HANA integration
MCP protocol support
Azure Functions deployment

Approval Workflow Features

✅ Fully Implemented Features

✅ Automatic sales order approval routing - All sales order creation enforced through approval workflow
✅ Azure Blob Storage persistence - Approval requests survive function restarts and scaling
✅ Teams webhook integration - Real-time adaptive card notifications with approval buttons
✅ Email notification system - Automated alerts for approval requests and status updates
✅ Advanced payload cleanup - Intelligent removal of custom fields for S/4HANA compatibility
✅ S/4HANA date formatting - Automatic conversion to /Date(timestamp)/ format for OData APIs
✅ Comprehensive status tracking - Complete audit trail with timestamps and approver details
✅ HTTP approval endpoints - GET/POST APIs for Teams integration and external systems
✅ Security enforcement - No direct sales order creation allowed, all requests routed through approval
✅ Enterprise error handling - Detailed logging, retry mechanisms, and graceful failure recovery
✅ Multi-format date parsing - Support for ISO 8601, custom formats with intelligent conversion
✅ Production security - All credentials externalized, managed identity support

🔄 Future Enhancements

Multi-level approval workflows with role-based routing
Advanced analytics and reporting dashboard with Power BI integration
Integration with Azure Active Directory for enhanced security
Automated testing framework with comprehensive unit and integration tests
Performance optimization with caching and connection pooling