MCP_BusinessCentral - Servidor Model Context Protocol 🚀

Este proyecto implementa un servidor MCP para Microsoft Business Central, usando FastMCP y FastAPI, integrable con Claude Desktop y otros clientes AI.

🌐 Servidor Online Disponible

🎉 El servidor está desplegado y operativo en Azure App Service:

• URL: https://mcp-bc-javi-chb7bue4evbkeyb0.westeurope-01.azurewebsites.net
• Documentación API: https://mcp-bc-javi-chb7bue4evbkeyb0.westeurope-01.azurewebsites.net/docs
• Estado: ✅ 100% funcional con datos reales de Business Central
• Endpoints disponibles: GET /customers, /items, /orders, POST /customers

📋 Para usar el servidor desplegado: Consulta el archivo `test-mcp-api.http` con ejemplos de todas las operaciones.

📋 ¿Qué es MCP?

El Model Context Protocol (MCP) es un estándar abierto que permite a clientes AI acceder a herramientas, datos y servicios externos de forma segura y estructurada. MCP define una arquitectura cliente-servidor donde:

• MCP Host: Cliente AI (Claude, Copilot, etc.)
• MCP Client: Conector MCP en el host
• MCP Server: Este proyecto (Python) expone herramientas y lógica de negocio
• Transporte: JSON-RPC sobre stdin/stdout (local) o HTTP/SSE (remoto)

Más información: MCP servers en Microsoft Learn

🔒 Autenticación y Seguridad

• Se recomienda usar Microsoft Entra ID (Azure AD) y OAuth2 para entornos de producción.
• Consulta la guía de autenticación para Business Central.

Ejemplo: Autenticación OAuth2 con Entra ID

import httpx

def get_bc_token(tenant_id, client_id, client_secret, scope):
    url = f"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token"
    data = {
        "grant_type": "client_credentials",
        "client_id": client_id,
        "client_secret": client_secret,
        "scope": scope
    }
    response = httpx.post(url, data=data)
    response.raise_for_status()
    return response.json()["access_token"]

Más información: Guía de autenticación

⚠️ Manejo de límites y errores

• Business Central impone límites de uso (rate limits) en sus APIs. Si recibes errores 429 (Too Many Requests) o 504 (Gateway Timeout), implementa lógica de reintentos y backoff.
• Más información: Límites de API en Business Central.

Ejemplo: Manejo de errores 429 y 504 en llamadas a la API

import httpx
import time

def call_bc_api_with_retry(url, headers, max_retries=5):
    retries = 0
    backoff = 2
    while retries < max_retries:
        response = httpx.get(url, headers=headers)
        if response.status_code == 429:
            wait = backoff ** retries
            print(f"Rate limit alcanzado. Reintentando en {wait}s...")
            time.sleep(wait)
            retries += 1
        elif response.status_code == 504:
            print("Timeout de la API. Reintentando...")
            time.sleep(backoff)
            retries += 1
        else:
            return response
    raise Exception("No se pudo completar la petición tras varios intentos")

Más información: Límites de API en Business Central

🏅 Buenas prácticas de integración

• Usa siempre los endpoints REST oficiales de Business Central para la integración.
• Desacopla la lógica de negocio del transporte MCP.
• Documenta claramente las herramientas expuestas y sus parámetros siguiendo el estándar MCP.
• Consulta la documentación de APIs REST de Business Central.

🏗️ Estructura del Proyecto

📁 MCP_BusinessCentral/
├── requirements.txt            # Dependencias Python
├── README.md                   # Documentación principal
├── .env                        # Variables de entorno (no se incluye en repo)
├── .venv/                      # Entorno virtual Python
├── .github/copilot-instructions.md
├── .vscode/tasks.json          # Tareas de VS Code
├── task1.txt                   # (Ejemplo o pruebas)
└── 📁 bc_server/                # Paquete principal
    ├── BusinessCentralMCP.py   # Servidor MCP (JSON-RPC) para BC
    ├── http_server.py          # API REST (FastAPI) con OpenAPI/Swagger
    ├── setup_guide.py          # Script de validación de entorno y credenciales
    ├── client.py               # Cliente HTTP para la API de BC
    ├── config.py               # Carga y validación de configuración
    └── __init__.py

🎯 Servidores y APIs Implementados

1. BusinessCentralMCP.py - Servidor MCP (JSON-RPC)

Expone herramientas para interactuar con Business Central vía JSON-RPC:

• get_customers(limit): Lista clientes
• get_customer_details(customer_id): Detalle de un cliente
• get_items(limit): Lista artículos
• get_sales_orders(limit): Lista órdenes de venta
• create_customer(...): Crea un nuevo cliente

2. http_server.py - API REST (FastAPI)

Expone los mismos métodos anteriores vía HTTP REST, con documentación Swagger/OpenAPI.

3. setup_guide.py - Validación de entorno

Script para comprobar variables de entorno y conectividad con Azure AD y Business Central.

🛠️ Tecnologías Utilizadas

• FastMCP: Framework para servidores MCP (JSON-RPC)
• FastAPI: API REST moderna con documentación automática
• httpx: Cliente HTTP asíncrono
• Pydantic: Validación y serialización de datos
• python-dotenv: Gestión de variables de entorno

🚀 Instalación y Puesta en Marcha

💻 Entorno Local

1. Crear entorno virtual

python -m venv .venv
.venv\Scripts\Activate.ps1

2. Instalar dependencias

pip install -r requirements.txt

3. Validar entorno y credenciales

python bc_server/setup_guide.py

4. Lanzar el servidor MCP (JSON-RPC)

python -m bc_server.BusinessCentralMCP

5. Lanzar la API REST (FastAPI)

uvicorn bc_server.http_server:app --reload --host 0.0.0.0 --port 8000

Accede a la documentación interactiva en: http://localhost:8000/docs

☁️ Despliegue en Azure App Service

¿Quieres el servidor disponible online? Consulta la **Guía Completa de Despliegue** que incluye:

• Proceso paso a paso para Azure App Service
• Solución a todos los problemas encontrados
• Configuración de variables de entorno
• Scripts de automatización
• Suite de testing completa

Resultado: Servidor 100% operativo en Azure con integración real a Business Central.

🧪 Testing del Servidor Desplegado

El archivo `test-mcp-api.http` contiene una suite completa de tests para validar todas las funcionalidades:

### Health Check
GET https://mcp-bc-javi-chb7bue4evbkeyb0.westeurope-01.azurewebsites.net/health

### Listar Clientes
GET https://mcp-bc-javi-chb7bue4evbkeyb0.westeurope-01.azurewebsites.net/customers?limit=5

### Crear Cliente
POST https://mcp-bc-javi-chb7bue4evbkeyb0.westeurope-01.azurewebsites.net/customers
Content-Type: application/json

{
  "displayName": "Cliente Test",
  "email": "test@example.com"
}

Usar REST Client extension de VS Code para ejecutar los tests directamente desde el editor.

🔧 Integración con Claude Desktop

1. Localiza el archivo de configuración de Claude Desktop:

2. Añade una entrada para el servidor MCP de Business Central, por ejemplo:

{
     "mcpServers": {
       "businesscentral-mcp": {
         "command": "C:/ruta/completa/.venv/Scripts/python.exe",
         "args": ["-m", "bc_server.BusinessCentralMCP"]
       }
     }
   }

3. Reinicia Claude Desktop para que detecte el nuevo servidor MCP.

🛠️ Herramientas Disponibles (BusinessCentralMCP)

Consulta la documentación Swagger en `/docs` si usas la API REST.

🧪 Testing y Desarrollo

• Claude Desktop: Configura el archivo de Claude Desktop y reinicia para probar las herramientas MCP.
• Modo desarrollo: Usa los scripts de la carpeta `bc_server` para pruebas y debugging.
• API REST: Ejecuta `uvicorn bc_server.http_server:app --reload` y prueba los endpoints en `http://localhost:8000/docs`.
• VS Code Task: Usa la tarea "Run Python Script" para lanzar scripts rápidamente.

🎯 Casos de Uso Demostrados

• Integración MCP con Business Central
• Exposición de datos de clientes, artículos y órdenes
• Creación de clientes desde herramientas AI
• API REST y JSON-RPC para integración flexible

📚 Referencias oficiales y recursos útiles

📖 Documentación del Proyecto

🌐 Enlaces Oficiales de Microsoft

• MCP servers en Microsoft Learn
• APIs REST de Business Central
• Desarrollar apps conectadas a Business Central
• Límites de API en Business Central
• Documentación MCP Oficial
• FastMCP GitHub
• Claude Desktop
• Pydantic Docs
• Blog TechSphereDynamics

¡Desarrollado con visión y buen rollo! 😉

Para cualquier duda, revisa los comentarios en el código o consulta la documentación oficial de MCP.