mcp-testaserver 0.1.3

MCP Server for ERP integration

ERP MCP Server

Servidor MCP (Model Context Protocol) para conectar asistentes de IA con tu ERP empresarial. Este servidor permite a Claude, Cursor y otros clientes MCP consultar información de clientes, proveedores y documentos a través de la API de tu ERP.

✨ Características

• Buscar clientes por nombre y obtener su código
• Buscar proveedores por nombre y obtener su código
• Consultar documentos de clientes (por nombre o código)
• Consultar documentos de proveedores (por nombre o código)
• Resolución automática de nombres a códigos
• Manejo de múltiples resultados con sugerencias
• Formato de respuesta claro y estructurado

📋 Requisitos

• Python 3.9 o superior
• Acceso a la API del ERP
• Token de autenticación del ERP
• IP y puerto del servidor ERP

🔧 Instalación

1. Clonar el repositorio

git clone https://github.com/tu-usuario/erp-mcp-server.git
cd erp-mcp-server

2. Crear entorno virtual (recomendado)

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

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

3. Instalar dependencias

pip install -r requirements.txt

4. Configurar variables de entorno

Crea un archivo .env en la raíz del proyecto:

#OPCION 1: TOKEN
TOKEN=token

#OPCION 2: ERP_USER
ERP_USER=usuario
ERP_PSWD=password
ERP_EMGES=empresa
ERP_APL=aplicacion
ERP_EMP=ejercicio

ERP_APLICACION=aplicacion_mcp
ERP_IP=ip_servidor
ERP_PORT=puerto_servidor
ERP_TIMEOUT=30
ERP_SSL_VERIFY=False

Variable	Descripción	Ejemplo
TOKEN	Token de autenticación del ERP	token
ERP_IP	IP del servidor ERP	ip_servidor
ERP_PORT	Puerto del servidor ERP	puerto_servidor
ERP_USER	Usuario para la API del ERP	usuario
ERP_PSWD	Contraseña para la API del ERP	password
ERP_EMGES	Código de empresa/gestión (EMGES)	empresa
ERP_APL	Aplicación específica (APL)	aplicacion
ERP_EMP	Código de empresa (EMP)	ejercicio
ERP_APLICACION	Nombre de la aplicación (APLICACION)	aplicacion_mcp
ERP_TIMEOUT	Timeout en segundos (opcional)	30
ERP_SSL_VERIFY	Verificar SSL (opcional)	False

🚀 Cómo Ejecutar el Servidor

Ejecución directa

python server.py

Verás un mensaje como:

INFO:erp-mcp-server:Servidor MCP ERP inicializado. Conectando a: http://192.168.1.100:8080/api

Ejecución con el inspector MCP (para pruebas)

mcp dev server.py

🔌 Configuración con Clientes MCP

Claude Desktop

Edita el archivo de configuración de Claude Desktop:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-testaserver": {
      "command": "uvx",
      "args": [
        "mcp-testaserver"
      ],
      "env": {
        "ERP_USER": "usuario",
        "ERP_PSWD": "password",
        "ERP_EMGES": "empresa",
        "ERP_APL": "aplicacion",
        "ERP_EMP": "ejercicio",
        "ERP_APLICACION": "aplicacion_mcp",
        "ERP_IP": "ip_servidor",
        "ERP_PORT": "puerto_servidor"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-testaserver": {
      "command": "uvx",
      "args": [
        "mcp-testaserver"
      ],
      "env": {
        "TOKEN": "token",
        "ERP_APLICACION": "aplicacion_mcp"
      }
    }
  }
}

Cursor

En Cursor, ve a Settings > MCP Servers y añade:

{
  "command": "uv",
  "args": ["run", "--mcp", "mcp-testaserver"]
}

VS Code con extensión MCP

Añade a tu configuración de VS Code:

{
  "mcp.servers": {
    "mcp-testaserver": {
      "command": "uv",
      "args": ["run", "mcp-testaserver"]
    }
  }
}

🛠️ Herramientas Disponibles

El servidor expone las siguientes herramientas MCP:

1. buscar_cliente

Busca clientes por nombre y devuelve sus códigos.

Parámetros:

• nombre (string, requerido): Nombre del cliente a buscar

Ejemplo:

buscar_cliente(nombre="Martínez")

2. buscar_proveedor

Busca proveedores por nombre y devuelve sus códigos.

Parámetros:

• nombre (string, requerido): Nombre del proveedor a buscar

Ejemplo:

buscar_proveedor(nombre="Proveedor SA")

3. buscar_documentos_cliente

Busca documentos de un cliente. Si se proporciona un nombre, primero resuelve el código.

Parámetros:

• identificador (string, requerido): Nombre o código del cliente
• es_codigo (boolean, opcional): true si el identificador es código, false si es nombre

Ejemplos:

# Por nombre (resuelve automáticamente el código)
buscar_documentos_cliente(identificador="García")

# Por código (más rápido si ya conoces el código)
buscar_documentos_cliente(identificador="CLI001", es_codigo=true)

4. buscar_documentos_proveedor

Busca documentos de un proveedor. Si se proporciona un nombre, primero resuelve el código.

Parámetros:

• identificador (string, requerido): Nombre o código del proveedor
• es_codigo (boolean, opcional): true si el identificador es código, false si es nombre

Ejemplos:

# Por nombre
buscar_documentos_proveedor(identificador="Distribuciones")

# Por código
buscar_documentos_proveedor(identificador="PROV001", es_codigo=true)

📝 Ejemplos de Uso

Una vez configurado, puedes hacer consultas como:

Buscar un cliente

Usuario: "Busca el cliente García y dime su código"

Asistente: 🔍 Clientes encontrados para 'García':

1. García Hermanos S.L.
   • Código: CLI-123
   • Email: [e-mail]
   • Teléfono: 912345678

2. María García López
   • Código: CLI-456
   • Email: [e-mail]

Documentos de un cliente por nombre

Usuario: "Muéstrame los documentos del cliente Martínez"

Asistente: 📄 Documentos de Martínez Importaciones (código CLI-789):

1. FACTURA F2024-001
   • Fecha: 2024-01-15
   • Importe: 1.234,56 €
   • Estado: Pagada

2. PEDIDO P2024-089
   • Fecha: 2024-02-20
   • Importe: 3.450,00 €
   • Estado: Pendiente

Documentos de proveedor con múltiples resultados

Usuario: "Busca documentos del proveedor 'Distribuciones'"

Asistente: ⚠️ Se encontraron múltiples proveedores con ese nombre:

• Distribuciones Martínez (Código: PROV-001)
• Distribuciones García (Código: PROV-002)
• Distribuciones del Norte (Código: PROV-003)

Por favor, especifica usando el código con es_codigo=True

🔧 Adaptación a tu ERP

Este servidor está diseñado para ser adaptado a cualquier ERP. Necesitarás modificar:

1. Endpoints de la API (en erp_client.py)

# Adapta estos endpoints según tu ERP
result = self._request("GET", "clientes/search", ...)  # ← Cambia 'clientes/search'
result = self._request("GET", f"clientes/{codigo}/documentos", ...)  # ← Cambia la ruta

2. Estructura de respuestas

# Adapta según la estructura JSON de tu ERP
datos = result.get("data", result.get("clientes", []))  # ← Ajusta las claves
codigo = item.get("codigo", item.get("id", ""))  # ← Ajusta los nombres de campo

3. Modelos de datos

Si tu ERP usa nombres de campos diferentes, ajusta los dataclasses en erp_client.py:

@dataclass
class Cliente:
    codigo: str  # ← Cómo se llama en tu ERP: "id", "code", "customerId"?
    nombre: str  # ← "name", "razonSocial", "fullName"?
    email: Optional[str] = None
    telefono: Optional[str] = None

🐛 Depuración

Ver logs del servidor

# Ejecuta con logging detallado
python server.py --debug

Probar la conexión al ERP

Crea un script test_connection.py:

from erp_client import ERPClient

client = ERPClient()
print(f"Conectando a: {client.base_url}")

# Prueba búsqueda
clientes = client.buscar_clientes("test")
print(f"Clientes encontrados: {len(clientes)}")
for c in clientes:
    print(f"  - {c.nombre} (código: {c.codigo})")

Usar el inspector MCP

mcp inspect server.py

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama (git checkout -b feature/mejora)
3. Commit tus cambios (git commit -am 'Añade nueva funcionalidad')
4. Push a la rama (git push origin feature/mejora)
5. Abre un Pull Request

📄 Licencia

MIT License - ver archivo LICENSE para más detalles.

⚠️ Solución de Problemas

Error: "No module named 'mcp'"

pip install -r requirements.txt

Error de conexión al ERP

• Verifica que el ERP sea accesible desde tu red
• Comprueba token, IP y puerto en el archivo .env
• Prueba la conectividad con ping o telnet

Múltiples resultados inesperados

Usa el parámetro es_codigo=True cuando ya conozcas el código exacto.

Timeout en las peticiones

Aumenta ERP_TIMEOUT en el archivo .env si el ERP es lento.

📞 Soporte

Si encuentras algún problema o tienes preguntas:

• Abre un issue
• Consulta la documentación de MCP

---

Desarrollado con ❤️ usando Model Context Protocol