DealX

oficial

Servidor MCP para la plataforma DealX

GitHub

¿Qué puedes hacer con Deal X MCP?

Buscar anuncios por palabra clave — Encuentre listados en la plataforma DealX usando una consulta de texto a través de search_ads.
Ordenar y paginar resultados — Controle el orden de clasificación (por ejemplo, los más nuevos primero con -created), el desplazamiento de página y la cantidad de resultados.
Limitar la cantidad de resultados — Establezca un tamaño de página personalizado de hasta 100 anuncios por solicitud.

Documentación

@dealx/mcp-server

Este es un servidor del Protocolo de Contexto de Modelo (MCP) para la plataforma DealX. Permite que los LLM interactúen con la plataforma DealX, específicamente para buscar anuncios.

Despliegue Alojado

Hay un despliegue alojado disponible en Fronteir AI.

Descripción General

El Servidor MCP de DealX implementa el Protocolo de Contexto de Modelo para proporcionar una forma estandarizada de que los LLM interactúen con la plataforma DealX. Actualmente, soporta la búsqueda de anuncios, con planes de añadir más funcionalidades en el futuro.

¿Qué es MCP?

El Protocolo de Contexto de Modelo (MCP) es una forma estandarizada para que los LLM interactúen con sistemas externos. Proporciona una interfaz estructurada para que los LLM accedan a datos y realicen acciones en el mundo real. Este servidor implementa la especificación MCP para permitir que los LLM interactúen con la plataforma DealX.

Instalación

Requisitos Previos

Node.js (v20 o posterior)
npm (v11 o posterior)

Configuración MCP

Para usar este servidor con un LLM como Claude, necesitas añadirlo a la configuración MCP de tu LLM:

Abre el archivo de configuración MCP de tu LLM:
- Aplicación de Escritorio Claude:
  - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  - Windows: %APPDATA%\Claude\claude_desktop_config.json
  - Linux: ~/.config/Claude/claude_desktop_config.json
- Cline (Extensión de VS Code):
  - ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Añade el servidor MCP de DealX a la sección mcpServers:

{
  "mcpServers": {
    "dealx": {
      "command": "npx",
      "args": ["-y", "@dealx/mcp-server"],
      "env": {
        "DEALX_API_URL": "https://dealx.com.ua"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Instalación vía npm

La forma más fácil de instalar el Servidor MCP de DealX es a través de npm:

npm install -g @dealx/mcp-server

Instalación para Desarrollo

Si quieres modificar el servidor o contribuir a su desarrollo:

Clona el repositorio:

git clone <repository-url>
cd dealx/mcp

Instala las dependencias:
```
npm install
```
Crea un archivo .env basado en el archivo .env.example:
```
cp .env.example .env
```

Edita el archivo .env para establecer los valores apropiados:

# DealX API URL
DEALX_API_URL=http://localhost:3001

# Optional: Specify the port for the MCP server
MCP_SERVER_PORT=3100

# Optional: Log level (debug, info, warn, error)
LOG_LEVEL=info

Construye el servidor:
```
npm run build
```

Uso

Iniciar el Servidor

Puedes ejecutar el servidor de varias maneras:

Si está instalado globalmente:

node node_modules/@dealx/mcp-server/build/index.js

Usando npx sin instalación:
```
npx -y @dealx/mcp-server
```

Con variables de entorno:

DEALX_API_URL=https://dealx.com.ua npx -y @dealx/mcp-server

Para desarrollo:
```
npm start
```

Usar con un LLM

Una vez configurado en los ajustes MCP de tu LLM, puedes usar lenguaje natural para interactuar con la plataforma DealX.

Ejemplos de prompts:

"Busca anuncios en DealX con la consulta 'portátil'"
"Encuentra los 5 anuncios más nuevos de 'iPhone' en DealX"
"Busca en DealX apartamentos en Kyiv"

Herramientas Disponibles

search_ads

Busca anuncios en la plataforma DealX.

Parámetros:

query (string, opcional): Cadena de consulta de búsqueda
sort (string, opcional): Orden de clasificación (ej., "-created" para los más nuevos primero)
offset (number, opcional): Desplazamiento de paginación (empieza en 1, por defecto: 1)
limit (number, opcional): Número de resultados por página (máx. 100, por defecto: 30)

Ejemplo de Uso:

{
  "query": "laptop",
  "sort": "-created",
  "offset": 1,
  "limit": 10
}

Extender el Servidor

El servidor está diseñado para ser fácilmente extendido con herramientas adicionales. Aquí se muestra cómo añadir una nueva herramienta:

Define la herramienta en el objeto TOOLS en src/index.ts:

const TOOLS = {
  SEARCH_ADS: "search_ads",
  NEW_TOOL: "new_tool", // Add your new tool here
};

Crea un nuevo archivo en el directorio src/tools para la implementación de tu herramienta:

// src/tools/new-tool.ts
import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";

interface NewToolParams {
  // Define your tool parameters here
}

export async function newTool(params: NewToolParams) {
  try {
    // Implement your tool logic here

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  } catch (error) {
    // Handle errors
    // ...
  }
}

Añade la herramienta al manejador ListToolsRequestSchema en src/index.ts:

this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    // Existing tools...
    {
      name: TOOLS.NEW_TOOL,
      description: "Description of your new tool",
      inputSchema: {
        type: "object",
        properties: {
          // Define your tool parameters here
        },
        required: [], // List required parameters
      },
    },
  ],
}));

Añade la herramienta al manejador CallToolRequestSchema en src/index.ts:

this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  switch (name) {
    // Existing cases...
    case TOOLS.NEW_TOOL:
      return await newTool(args);
    default:
      throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
  }
});

Importa tu nueva herramienta en src/index.ts:

import { newTool } from "./tools/new-tool.js";

Herramientas Futuras Planeadas

Las siguientes herramientas están planeadas para implementación futura:

create_ad: Crear un nuevo anuncio en la plataforma DealX
edit_ad: Editar un anuncio existente
delete_ad: Eliminar un anuncio
get_threads: Obtener hilos de discusión para un anuncio
create_thread: Crear un nuevo hilo de discusión

Desarrollo

Estructura del Proyecto

mcp/
├── build/              # Compiled JavaScript files
├── src/                # TypeScript source files
│   ├── tools/          # Tool implementations
│   │   └── search-ads.ts
│   └── index.ts        # Main server implementation
├── .env                # Environment variables (not in git)
├── .env.example        # Example environment variables
├── package.json        # Project dependencies and scripts
├── tsconfig.json       # TypeScript configuration
└── README.md           # This file

Scripts de npm

npm run build - Compila TypeScript a JavaScript
npm start - Inicia el servidor usando el JavaScript compilado
npm run dev - Inicia el servidor en modo desarrollo con recarga en caliente
npm run lint - Analiza el código usando ESLint
npm run format - Formatea el código usando Prettier
npm test - Ejecuta pruebas

Solución de Problemas

Problemas Comunes

El Servidor No Inicia

Si el servidor no inicia, verifica lo siguiente:

Asegúrate de tener instalada la versión correcta de Node.js
Verifica que todas las dependencias estén instaladas
Verifica que el archivo .env exista y tenga los valores correctos
Revisa la salida de la consola en busca de mensajes de error

Problemas de Conexión

Si el LLM no puede conectarse al servidor:

Asegúrate de que el servidor esté en ejecución
Verifica que la configuración MCP en los ajustes del LLM sea correcta
Verifica que la ruta al ejecutable del servidor sea correcta
Verifica que las variables de entorno estén configuradas correctamente

Problemas de Conexión a la API

Si el servidor no puede conectarse a la API de DealX:

Asegúrate de que la API de DealX esté en ejecución
Verifica que la variable de entorno DEALX_API_URL esté configurada correctamente
Verifica que el endpoint de la API sea accesible desde el servidor

Obtener Ayuda

Si encuentras problemas no cubiertos aquí, por favor abre un issue en este repositorio de GitHub.