Business Central MCP Server

# 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](https://learn.microsoft.com/en-us/azure/api-management/export-rest-mcp-server#about-mcp-servers) ## 🔒 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](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-develop-connect-apps). ### Ejemplo: Autenticación OAuth2 con Entra ID ```python 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](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-develop-connect-apps) ## ⚠️ 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](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/dynamics-rate-limits). ### Ejemplo: Manejo de errores 429 y 504 en llamadas a la API ```python 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](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/dynamics-rate-limits) ## 🏅 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](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/api-overview). ## 🏗️ 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 ```powershell python -m venv .venv .venv\Scripts\Activate.ps1 ``` ### 2. Instalar dependencias ```powershell pip install -r requirements.txt ``` ### 3. Validar entorno y credenciales ```powershell python bc_server/setup_guide.py ``` ### 4. Lanzar el servidor MCP (JSON-RPC) ```powershell python -m bc_server.BusinessCentralMCP ``` ### 5. Lanzar la API REST (FastAPI) ```powershell 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](./DEPLOYMENT_GUIDE.md)** 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: ```http ### 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: - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` 2. Añade una entrada para el servidor MCP de Business Central, por ejemplo: ```json { "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) | Herramienta | Descripción | Parámetros principales | |--------------------------|---------------------------------------------|---------------------------------------| | get_customers | Lista clientes de Business Central | limit (int) | | get_customer_details | Detalle de un cliente por ID | customer_id (str) | | get_items | Lista artículos | limit (int) | | get_sales_orders | Lista órdenes de venta | limit (int) | | create_customer | Crea un nuevo cliente | displayName, email, ... (ver código) | 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 | Recurso | Descripción | |---------|-------------| | [Guía de Despliegue Azure](./DEPLOYMENT_GUIDE.md) | Proceso completo para llevar el servidor a producción | | [Suite de Tests](./test-mcp-api.http) | Validación completa de endpoints con REST Client | | [Configuración MCP](./bc_server/BusinessCentralMCP.py) | Servidor JSON-RPC para integración con AI clients | | [API REST](./bc_server/http_server.py) | Endpoints HTTP con documentación OpenAPI | ### 🌐 Enlaces Oficiales de Microsoft - [MCP servers en Microsoft Learn](https://learn.microsoft.com/en-us/azure/api-management/export-rest-mcp-server#about-mcp-servers) - [APIs REST de Business Central](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/api-overview) - [Desarrollar apps conectadas a Business Central](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-develop-connect-apps) - [Límites de API en Business Central](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/dynamics-rate-limits) - [Documentación MCP Oficial](https://modelcontextprotocol.io/llms-full.txt) - [FastMCP GitHub](https://github.com/jlowin/fastmcp) - [Claude Desktop](https://claude.ai/desktop) - [Pydantic Docs](https://docs.pydantic.dev/) - [Blog TechSphereDynamics](https://techspheredynamics.com) | Recurso | Enlace | |--------------------------------------------|------------------------------------------------------------------------| | MCP servers en Microsoft Learn | https://learn.microsoft.com/en-us/azure/api-management/export-rest-mcp-server#about-mcp-servers | | APIs REST de Business Central | https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/api-overview | | Autenticación y apps conectadas | https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-develop-connect-apps | | Límites de API | https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/dynamics-rate-limits | | Documentación MCP Oficial | https://modelcontextprotocol.io/llms-full.txt | | FastMCP GitHub | https://github.com/jlowin/fastmcp | | Claude Desktop | https://claude.ai/desktop | | Pydantic Docs | https://docs.pydantic.dev/ | | Blog TechSphereDynamics | https://techspheredynamics.com | --- **¡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.