DealX

resmi

Server MCP untuk platform DealX

GitHub
2

Apa yang bisa Anda lakukan dengan Deal X MCP?

  • Cari iklan berdasarkan kata kunci — Temukan daftar di platform DealX menggunakan kueri teks melalui search_ads.
  • Urutkan dan paginasi hasil — Kontrol urutan pengurutan (misalnya, yang terbaru terlebih dahulu dengan -created), offset halaman, dan jumlah hasil.
  • Batasi jumlah hasil — Tetapkan ukuran halaman kustom hingga 100 iklan per permintaan.

Dokumentasi

@dealx/mcp-server

Ini adalah server Model Context Protocol (MCP) untuk platform DealX. Server ini memungkinkan LLM berinteraksi dengan platform DealX, khususnya untuk mencari iklan.

Daftar Isi

Deployment Terhosting

Deployment terhosting tersedia di Fronteir AI.

Gambaran Umum

DealX MCP Server mengimplementasikan Model Context Protocol untuk menyediakan cara standar bagi LLM dalam berinteraksi dengan platform DealX. Saat ini, server mendukung pencarian iklan, dengan rencana penambahan fungsionalitas lainnya di masa mendatang.

Apa itu MCP?

Model Context Protocol (MCP) adalah cara standar bagi LLM untuk berinteraksi dengan sistem eksternal. Protokol ini menyediakan antarmuka terstruktur bagi LLM untuk mengakses data dan melakukan tindakan di dunia nyata. Server ini mengimplementasikan spesifikasi MCP untuk memungkinkan LLM berinteraksi dengan platform DealX.

Instalasi

Prasyarat

  • Node.js (v20 atau lebih baru)
  • npm (v11 atau lebih baru)

Konfigurasi MCP

Untuk menggunakan server ini dengan LLM seperti Claude, Anda perlu menambahkannya ke konfigurasi MCP LLM Anda:

  1. Buka file konfigurasi MCP LLM Anda:

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

  2. Tambahkan server MCP DealX ke bagian mcpServers:

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

Instalasi melalui npm

Cara termudah untuk menginstal DealX MCP Server adalah melalui npm:

npm install -g @dealx/mcp-server

Instalasi untuk Pengembangan

Jika Anda ingin memodifikasi server atau berkontribusi pada pengembangannya:

  1. Kloning repositori:

    git clone <repository-url>
cd dealx/mcp

  2. Instal dependensi:

    npm install

  3. Buat file .env berdasarkan file .env.example:

    cp .env.example .env

  4. Edit file .env untuk menetapkan nilai yang sesuai:

    # 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. Build server:

    npm run build

Penggunaan

Memulai Server

Anda dapat menjalankan server dengan beberapa cara:

  1. Jika diinstal secara global:

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

  2. Menggunakan npx tanpa instalasi:

    npx -y @dealx/mcp-server

  3. Dengan variabel lingkungan:

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

  4. Untuk pengembangan:

    npm start

Menggunakan dengan LLM

Setelah dikonfigurasi di pengaturan MCP LLM Anda, Anda dapat menggunakan bahasa alami untuk berinteraksi dengan platform DealX.

Contoh prompt:

  • "Cari iklan di DealX dengan kueri 'laptop'"
  • "Temukan 5 iklan terbaru untuk 'iPhone' di DealX"
  • "Cari apartemen di Kyiv di DealX"

Alat yang Tersedia

search_ads

Mencari iklan di platform DealX.

Parameter:

  • query (string, opsional): String kueri pencarian
  • sort (string, opsional): Urutan pengurutan (misalnya, "-created" untuk terbaru terlebih dahulu)
  • offset (number, opsional): Offset paginasi (dimulai dari 1, default: 1)
  • limit (number, opsional): Jumlah hasil per halaman (maks 100, default: 30)

Contoh Penggunaan:

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

Memperluas Server

Server dirancang agar mudah diperluas dengan alat tambahan. Berikut cara menambahkan alat baru:

  • Definisikan alat di objek TOOLS di src/index.ts:

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

  • Buat file baru di direktori src/tools untuk implementasi alat Anda:

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

  • Tambahkan alat ke handler ListToolsRequestSchema di 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
      },
    },
  ],
}));

  • Tambahkan alat ke handler CallToolRequestSchema di 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}`);
  }
});

  • Impor alat baru Anda di src/index.ts:

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

Alat Masa Depan yang Direncanakan

Alat-alat berikut direncanakan untuk implementasi di masa depan:

  • create_ad: Membuat iklan baru di platform DealX
  • edit_ad: Mengedit iklan yang sudah ada
  • delete_ad: Menghapus iklan
  • get_threads: Mendapatkan utas diskusi untuk sebuah iklan
  • create_thread: Membuat utas diskusi baru

Pengembangan

Struktur Proyek

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

Skrip npm

  • npm run build - Kompilasi TypeScript ke JavaScript
  • npm start - Mulai server menggunakan JavaScript yang telah dikompilasi
  • npm run dev - Mulai server dalam mode pengembangan dengan hot reloading
  • npm run lint - Lint kode menggunakan ESLint
  • npm run format - Format kode menggunakan Prettier
  • npm test - Jalankan pengujian

Pemecahan Masalah

Masalah Umum

Server Tidak Mau Mulai

Jika server gagal dimulai, periksa hal berikut:

  • Pastikan Anda telah menginstal versi Node.js yang benar
  • Periksa apakah semua dependensi telah diinstal
  • Verifikasi bahwa file .env ada dan memiliki nilai yang benar
  • Periksa output konsol untuk pesan kesalahan

Masalah Koneksi

Jika LLM tidak dapat terhubung ke server:

  • Pastikan server sedang berjalan
  • Periksa apakah konfigurasi MCP di pengaturan LLM sudah benar
  • Verifikasi bahwa path ke server yang dapat dieksekusi sudah benar
  • Periksa apakah variabel lingkungan telah diatur dengan benar

Masalah Koneksi API

Jika server tidak dapat terhubung ke API DealX:

  • Pastikan API DealX sedang berjalan
  • Periksa apakah variabel lingkungan DEALX_API_URL telah diatur dengan benar
  • Verifikasi bahwa endpoint API dapat diakses dari server

Mendapatkan Bantuan

Jika Anda mengalami masalah yang tidak tercakup di sini, silakan buka isu di repositori GitHub ini.