DealX

@dealx/mcp-server

Este é um servidor Model Context Protocol (MCP) para a plataforma DealX. Ele permite que LLMs interajam com a plataforma DealX, especificamente para buscar anúncios.

Sumário

• Visão Geral
• Instalação
• Uso
• Ferramentas Disponíveis
• Estendendo o Servidor
• Desenvolvimento
• Solução de Problemas

Implantação hospedada

Uma implantação hospedada está disponível no Fronteir AI.

Visão Geral

O Servidor MCP DealX implementa o Model Context Protocol para fornecer uma maneira padronizada de LLMs interagirem com a plataforma DealX. Atualmente, ele suporta a busca de anúncios, com planos de adicionar mais funcionalidades no futuro.

O que é MCP?

O Model Context Protocol (MCP) é uma forma padronizada de LLMs interagirem com sistemas externos. Ele fornece uma interface estruturada para que LLMs acessem dados e realizem ações no mundo real. Este servidor implementa a especificação MCP para permitir que LLMs interajam com a plataforma DealX.

Instalação

Pré-requisitos

• Node.js (v20 ou superior)
• npm (v11 ou superior)

Configuração MCP

Para usar este servidor com um LLM como o Claude, você precisa adicioná-lo à configuração MCP do seu LLM:

1. Abra o arquivo de configuração MCP do seu LLM:

   • Aplicativo Desktop 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 (Extensão VS Code):
     • ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

2. Adicione o servidor MCP DealX à seção mcpServers:

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

Instalação via npm

A maneira mais fácil de instalar o Servidor MCP DealX é via npm:

npm install -g @dealx/mcp-server

Instalação para Desenvolvimento

Se você deseja modificar o servidor ou contribuir para o seu desenvolvimento:

1. Clone o repositório:

   git clone <repository-url>
   cd dealx/mcp
   

2. Instale as dependências:

   npm install
   

3. Crie um arquivo .env baseado no arquivo .env.example:

   cp .env.example .env
   

4. Edite o arquivo .env para definir os valores apropriados:

   # 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
   

5. Compile o servidor:

   npm run build
   

Uso

Iniciando o Servidor

Você pode executar o servidor de várias maneiras:

1. Se instalado globalmente:

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

2. Usando npx sem instalação:

   npx -y @dealx/mcp-server
   

3. Com variáveis de ambiente:

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

4. Para desenvolvimento:

   npm start
   

Usando com um LLM

Uma vez configurado nas definições MCP do seu LLM, você pode usar linguagem natural para interagir com a plataforma DealX.

Exemplos de prompts:

• "Busque anúncios no DealX com a consulta 'laptop'"
• "Encontre os 5 anúncios mais novos para 'iPhone' no DealX"
• "Busque no DealX apartamentos em Kyiv"

Ferramentas Disponíveis

search_ads

Busca anúncios na plataforma DealX.

Parâmetros:

• query (string, opcional): String de consulta de busca
• sort (string, opcional): Ordem de classificação (ex., "-created" para mais recentes primeiro)
• offset (number, opcional): Deslocamento de paginação (começa em 1, padrão: 1)
• limit (number, opcional): Número de resultados por página (máx. 100, padrão: 30)

Exemplo de Uso:

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

Estendendo o Servidor

O servidor foi projetado para ser facilmente estendido com ferramentas adicionais. Veja como adicionar uma nova ferramenta:

• Defina a ferramenta no objeto TOOLS em src/index.ts:

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

• Crie um novo arquivo no diretório src/tools para a implementação da sua ferramenta:

  // 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
      // ...
    }
  }
  

• Adicione a ferramenta ao manipulador ListToolsRequestSchema em 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
        },
      },
    ],
  }));
  

• Adicione a ferramenta ao manipulador CallToolRequestSchema em 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}`);
    }
  });
  

• Importe sua nova ferramenta em src/index.ts:

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

Ferramentas Futuras Planejadas

As seguintes ferramentas estão planejadas para implementação futura:

• create_ad: Criar um novo anúncio na plataforma DealX
• edit_ad: Editar um anúncio existente
• delete_ad: Excluir um anúncio
• get_threads: Obter threads de discussão para um anúncio
• create_thread: Criar uma nova thread de discussão

Desenvolvimento

Estrutura do Projeto

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 npm

• npm run build - Compila TypeScript para JavaScript
• npm start - Inicia o servidor usando o JavaScript compilado
• npm run dev - Inicia o servidor em modo de desenvolvimento com recarga automática
• npm run lint - Analisa o código usando ESLint
• npm run format - Formata o código usando Prettier
• npm test - Executa testes

Solução de Problemas

Problemas Comuns

Servidor Não Inicia

Se o servidor falhar ao iniciar, verifique o seguinte:

• Certifique-se de ter a versão correta do Node.js instalada
• Verifique se todas as dependências estão instaladas
• Verifique se o arquivo .env existe e possui os valores corretos
• Verifique a saída do console para mensagens de erro

Problemas de Conexão

Se o LLM não conseguir se conectar ao servidor:

• Certifique-se de que o servidor está em execução
• Verifique se a configuração MCP nas definições do LLM está correta
• Verifique se o caminho para o executável do servidor está correto
• Verifique se as variáveis de ambiente estão definidas corretamente

Problemas de Conexão com a API

Se o servidor não conseguir se conectar à API DealX:

• Certifique-se de que a API DealX está em execução
• Verifique se a variável de ambiente DEALX_API_URL está definida corretamente
• Verifique se o endpoint da API está acessível a partir do servidor

Obtendo Ajuda

Se você encontrar problemas não cobertos aqui, por favor, abra uma issue neste repositório GitHub.