mcp-testaserver 0.1.3
MCP Server for ERP integration
Requires Python: >=3.10

# 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

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

### 2. Crear entorno virtual (recomendado)

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

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

### 3. Instalar dependencias

```bash
pip install -r requirements.txt
```

### 4. Configurar variables de entorno

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

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

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

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

```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"
      }
    }
  }
}
```


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

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

### VS Code con extensión MCP

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

```json
{
  "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: info@garciahermanos.es
   • Teléfono: 912345678

2. María García López
   • Código: CLI-456
   • Email: maria.garcia@email.com
```

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

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

```python
# 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`:

```python
@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

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

### Probar la conexión al ERP

Crea un script `test_connection.py`:

```python
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

```bash
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'"

```bash
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](https://github.com/tu-usuario/erp-mcp-server/issues)
- Consulta la [documentación de MCP](https://modelcontextprotocol.io)

---

Desarrollado con ❤️ usando [Model Context Protocol](https://modelcontextprotocol.io)