SAP Business One MCP Server

SAP Business One MCP Server

Servidor MCP (Model Context Protocol) para integrar SAP Business One con Microsoft Copilot Studio.

##Características

-## Configuración

1. Variables de Entorn## Despliegue en AzureConexión ## Integración con Copilot St## Pruebas del Protocolo MCPdioersistente*## Estructura del Proyecto a SAP Business## TroubleshootingOne Service Layer API

• Creación de Sales Orders con validación completa
• Protocolo MCP Streamable compatible con Microsoft Copilot Studio
• Deployment en Azure Container Apps listo para producción

##Herramientas Disponibles

1. sap_connect - Conectar a SAP Business One
2. sap_status - Verificar estado de conexión
3. sap_create_sales_order - Crear Sales Orders

##Requisitos

• Python 3.11+
• SAP Business One con Service Layer habilitado
• Variables de entorno configuradas

##Configuración

1. Copiar .env.example a .env:

cp .env.example .env

2. Configurar variables de entorno en .env:

SAP_BASE_URL=https://your-sap-server:50000/b1s/v2
SAP_COMPANY_DB=YOUR_DB
SAP_USERNAME=your_user
SAP_PASSWORD=your_password

3. Instalar dependencias:

pip install -r requirements.txt

4. Ejecutar servidor:

python server.py

##Integración con Microsoft Copilot Studio

###1. Schema File Usar sap-mcp-schema.yaml como archivo de schema OpenAPI en Copilot Studio.

###2. Crear Custom Connector

1. En Copilot Studio, ir a Tools → Add a tool → New tool → Custom connector
2. Seleccionar Import OpenAPI file
3. Subir el archivo sap-mcp-schema.yaml
4. Completar la configuración siguiendo la documentación oficial

###3. Configurar Host Actualizar el host en sap-mcp-schema.yaml:

• Para desarrollo local: localhost:8000
• Para producción: your-domain.azurecontainerapps.io

##Deployment

###Azure Container Apps

1. Configurar variables de entorno en Azure:

az containerapp env set-vars --name myapp-env --resource-group myresourcegroup --vars SAP_BASE_URL=https://your-sap-server:50000/b1s/v2 SAP_COMPANY_DB=YOUR_DB SAP_USERNAME=your_user SAP_PASSWORD=your_password

2. Deploy usando el script:

./deploy-azure.ps1

###Docker

docker build -t sap-mcp-server .
docker run -p 8000:8000 --env-file .env sap-mcp-server

##Ejemplo de Uso

###Crear Sales Order

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "sap_create_sales_order",
    "arguments": {
      "CardCode": "CUSTOMER_CODE",
      "DocDueDate": "YYYYMMDD",
      "DocCurrency": "USD",
      "DocRate": 1.0,
      "DocumentLines": [
        {
          "ItemCode": "ITEM_CODE",
          "Quantity": "1",
          "TaxCode": "TAX_CODE",
          "UnitPrice": "100.00"
        }
      ]
    }
  }
}

###Respuesta

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Sales Order creada exitosamente:
{
  \"status\": \"success\",
  \"DocEntry\": 12345,
  \"DocNum\": 1001,
  \"CardCode\": \"CUSTOMER_CODE\",
  \"CardName\": \"Customer Name\",
  \"DocTotal\": 1000.0,
  \"DocCurrency\": \"USD\",
  \"DocRate\": 1.0
}"
      }
    ]
  }
}

##Health Check

curl http://localhost:8000/health

##Licencia

MIT License

##Contribuir

1. Fork el proyecto
2. Crear feature branch (git checkout -b feature/AmazingFeature)
3. Commit cambios (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Abrir Pull Request

##Objetivo

Exponer herramientas de SAP Business One Service Layer API mediante el protocolo MCP streamable para que Microsoft Copilot Studio pueda consumirlas como un custom connector.

##Arquitectura

Microsoft Copilot Studio
    ↓ (HTTPS/JSON-RPC)
Azure Container Apps (Public Endpoint)
    ↓ (Service Layer API)
SAP Business One Server

##� Características

###Herramientas MCP Disponibles

• sap_connect: Conectar a SAP Business One
• sap_status: Verificar estado de conexión
• sap_create_sales_order: Crear Sales Orders con validación completa

###Recursos MCP Disponibles

• sap://status: Estado actual de la conexión SAP

###Endpoints HTTP

• POST /mcp: Endpoint principal para protocolo MCP streamable
• GET /health: Verificación de salud del servidor

##🛠️ Configuración

###1. Variables de Entorno

Crea un archivo .env basado en .env.example:

cp .env.example .env

Completa las variables:

# SAP Business One Service Layer
SAP_BASE_URL=https://your-sap-server:50000/b1s/v1
SAP_COMPANY_DB=YOUR_COMPANY_DB
SAP_USERNAME=your_username
SAP_PASSWORD=your-password

###2. Desarrollo Local

# Instalar dependencias
pip install -r requirements.txt

# Ejecutar servidor
python server.py

El servidor estará disponible en http://localhost:8000

###3. Probar Localmente

# Verificar salud del servidor
curl http://localhost:8000/health

# Probar herramientas MCP
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

##☁️ Despliegue en Azure

###Prerequisitos

• Azure CLI instalado y configurado
• Azure Container Registry creado
• Permisos para crear Container Apps

###Despliegue Automatizado

# Ejecutar script de despliegue
.\deploy-azure.ps1 -ResourceGroupName "rg-mcp-sap" `
                   -ContainerAppEnvironmentName "cae-mcp-sap" `
                   -ContainerAppName "app-sap-mcp" `
                   -ContainerRegistryName "acrmcpsap" `
                   -VNetName "vnet-mcp-sap" `
                   -SubnetName "subnet-container-apps"

###Configurar Secrets en Azure

# Variables de entorno en Container App
az containerapp secret set --name app-sap-mcp --resource-group rg-mcp-sap \
  --secrets sap-base-url="https://your-sap:50000/b1s/v1" \
            sap-company-db="YOUR_COMPANY_DB" \
            sap-username="your_username" \
            sap-password="your-password"

##🔌 Integración con Copilot Studio

###1. Crear Custom Connector

1. Ir a Power Platform Admin Center
2. Seleccionar Custom Connectors → New custom connector → Import from OpenAPI file
3. Subir el archivo sap-mcp-schema.yaml
4. Configurar la URL del host con tu Container App:

   https://app-sap-mcp-test.bravewater-b67ade29.eastus.azurecontainerapps.io
   

###2. Configurar en Copilot Studio

1. Abrir Copilot Studio
2. Ir a Settings → Generative AI → Custom Actions
3. Agregar el custom connector creado
4. Las herramientas SAP aparecerán automáticamente como acciones disponibles

###3. Ejemplo de Uso en Copilot

Usuario: "Conecta a SAP y crea una orden de venta"

Copilot ejecutará:
1. sap_connect() - para conectar
2. sap_create_sales_order(CardCode="CUSTOMER", DocumentLines=[...]) - para crear la orden

##🧪 Pruebas del Protocolo MCP

###Ejemplo de Solicitud MCP

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "sap_create_sales_order",
    "arguments": {
      "CardCode": "CUSTOMER_CODE",
      "DocumentLines": [
        {
          "ItemCode": "ITEM_CODE",
          "Quantity": "1",
          "UnitPrice": "100.00"
        }
      ]
    }
  },
  "id": 1
}

###Ejemplo de Respuesta MCP

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Sales Order creada exitosamente: DocEntry 12345"
      }
    ]
  }
}

##📁 Estructura del Proyecto

MCP-SAP-main/
├── server.py               # Servidor MCP principal con FastAPI
├── sap_client.py           # Cliente para SAP Business One Service Layer
├── sap-mcp-schema.yaml     # Schema OpenAPI para Custom Connector
├── deploy-azure.ps1        # Script de despliegue en Azure
├── Dockerfile              # Imagen de contenedor
├── requirements.txt        # Dependencias Python
├── .env.example           # Plantilla de configuración
├── azure-container-app.yaml # Configuración de Container App
└── README.md              # Este archivo

Desarrollo

###Agregar Nueva Herramienta

1. Definir en handle_list_tools():

Tool(
    name="nueva_herramienta",
    description="Descripción de la herramienta",
    inputSchema={
        "type": "object",
        "properties": {
            "param1": {"type": "string", "description": "Parámetro"}
        },
        "required": ["param1"]
    }
)

2. Implementar en handle_call_tool():

elif name == "nueva_herramienta":
    # Lógica de la herramienta
    return [TextContent(type="text", text="Resultado")]

##🔍 Troubleshooting

###Problemas Comunes

1. Error de conexión SAP:

   • Verificar variables de entorno
   • Comprobar conectividad de red
   • Validar credenciales

2. Container App no responde:

   • Verificar logs: az containerapp logs show --name app-sap-mcp --resource-group rg-mcp-sap
   • Comprobar variables de entorno en Azure

3. Copilot Studio no encuentra herramientas:

   • Verificar schema OpenAPI
   • Comprobar URL del host en custom connector
   • Validar protocolo mcp-streamable-1.0

###Logs y Debugging

# Ver logs locales
python server.py  # Logs aparecen en consola

# Ver logs en Azure
az containerapp logs show --name app-sap-mcp --resource-group rg-mcp-sap --follow

# Probar endpoints manualmente
curl https://your-container-app.azurecontainerapps.io/health
curl -X POST https://your-container-app.azurecontainerapps.io/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Referencias

• Model Context Protocol (MCP)
• SAP Business One Service Layer API
• Microsoft Copilot Studio Custom Connectors
• Azure Container Apps

Contribución

1. Fork el repositorio
2. Crear rama feature: git checkout -b feature/nueva-caracteristica
3. Commit cambios: git commit -am 'Agregar nueva característica'
4. Push a la rama: git push origin feature/nueva-caracteristica
5. Crear Pull Request

##📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver archivo LICENSE para más detalles.

##🆘 Soporte

• Issues: GitHub Issues
• Documentación: Wiki del proyecto
• Contacto: Crear un issue para soporte técnico --secrets "sap-username=tu-usuario" "sap-password=tu-password"

##🔧 Configuración Manual

###Crear VNet y Subnet (si no existe)

```bash
# Crear VNet
az network vnet create \
    --resource-group $ResourceGroupName \
    --name $VNetName \
    --address-prefix 10.0.0.0/16 \
    --subnet-name $SubnetName \
    --subnet-prefix 10.0.1.0/24

# Delegación para Container Apps
az network vnet subnet update \
    --resource-group $ResourceGroupName \
    --vnet-name $VNetName \
    --name $SubnetName \
    --delegations Microsoft.App/environments

###Configurar NSG para SAP

# Crear regla para permitir tráfico a SAP
az network nsg rule create \
    --resource-group $ResourceGroupName \
    --nsg-name nsg-containers \
    --name AllowSAP \
    --priority 100 \
    --direction Outbound \
    --access Allow \
    --protocol Tcp \
    --destination-port-ranges 50000 \
    --destination-address-prefixes 10.0.0.0/16

##📊 Verificación

###Ver logs de la aplicación

az containerapp logs show \
    --name $ContainerAppName \
    --resource-group $ResourceGroupName \
    --follow

###Verificar conectividad

# Entrar al contenedor para debug
az containerapp exec \
    --name $ContainerAppName \
    --resource-group $ResourceGroupName

# Verificar variables de entorno
echo $SAP_BASE_URL

##🔐 Seguridad

###Variables de entorno configuradas:

• SAP_BASE_URL: URL de tu SAP Business One API
• SAP_COMPANY_DB: Base de datos de la compañía
• SAP_USERNAME: Usuario SAP
• SAP_PASSWORD: Contraseña SAP (almacenada como secreto)

###Mejores prácticas:

• Credenciales almacenadas como secretos de Container Apps
• VNet isolation para comunicación privada con SAP
• Contenedor ejecutándose con usuario no-root
• Recursos limitados (CPU/Memory)

##🛠️ Troubleshooting

###Error de conectividad a SAP

1. Verificar que SAP esté ejecutándose
2. Verificar NSG rules
3. Verificar que las IPs sean correctas
4. Verificar credenciales

###Error de despliegue

1. Verificar permisos en Azure
2. Verificar que el nombre del Container Registry sea único
3. Verificar que la VNet exista

###Ver logs detallados

az containerapp logs show \
    --name $ContainerAppName \
    --resource-group $ResourceGroupName \
    --type console

##📞 Soporte

Para problemas específicos:

1. Revisar logs de Container Apps
2. Verificar conectividad de red
3. Probar credenciales SAP desde Postman
4. Verificar configuración de secretos

##🔄 Actualizaciones

Para actualizar la aplicación:

# Rebuild y redeploy
az acr build --registry $ContainerRegistryName --image "sap-mcp-server:latest" .

# Restart container app
az containerapp revision restart \
    --name $ContainerAppName \
    --resource-group $ResourceGroupName