# 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`:
```bash
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:
```bash
pip install -r requirements.txt
```

4. Ejecutar servidor:
```bash
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](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent)

###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:
```bash
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:
```bash
./deploy-azure.ps1
```

###Docker

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

##Ejemplo de Uso

###Crear Sales Order
```json
{
  "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
```json
{
  "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

```bash
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`:

```bash
cp .env.example .env
```

Completa las variables:

```env
# 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

```bash
# Instalar dependencias
pip install -r requirements.txt

# Ejecutar servidor
python server.py
```

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

###3. Probar Localmente

```bash
# 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

```powershell
# 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

```bash
# 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

```json
{
  "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

```json
{
  "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()`:
```python
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()`:
```python
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

```bash
# 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)](https://modelcontextprotocol.io/)
- [SAP Business One Service Layer API](https://help.sap.com/docs/SAP_BUSINESS_ONE/68a2e87fb29941b5bf959a184d9c6727/16f20002dd5645ad84f3853d08e76a0f.html)
- [Microsoft Copilot Studio Custom Connectors](https://docs.microsoft.com/en-us/connectors/custom-connectors/)
- [Azure Container Apps](https://docs.microsoft.com/en-us/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](https://github.com/NXr10/MCP-SAP/issues)
- **Documentación**: [Wiki del proyecto](https://github.com/NXr10/MCP-SAP/wiki)
- **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

```bash
# 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

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

###Verificar conectividad

```bash
# 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

```bash
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:

```bash
# 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
```