DealX

chính thức

Máy chủ MCP cho nền tảng DealX

GitHub
2

Bạn có thể làm gì với Deal X MCP?

  • Tìm kiếm quảng cáo theo từ khóa — Tìm danh sách trên nền tảng DealX bằng truy vấn văn bản qua search_ads.
  • Sắp xếp và phân trang kết quả — Kiểm soát thứ tự sắp xếp (ví dụ: mới nhất trước với -created), độ lệch trang và số lượng kết quả.
  • Giới hạn số lượng kết quả — Đặt kích thước trang tùy chỉnh lên đến 100 quảng cáo mỗi yêu cầu.

Tài liệu

@dealx/mcp-server

Đây là một máy chủ Model Context Protocol (MCP) dành cho nền tảng DealX. Nó cho phép các LLM tương tác với nền tảng DealX, cụ thể là để tìm kiếm quảng cáo.

Mục lục

Triển khai được lưu trữ

Một bản triển khai được lưu trữ có sẵn trên Fronteir AI.

Tổng quan

Máy chủ DealX MCP triển khai Model Context Protocol để cung cấp một cách chuẩn hóa cho các LLM tương tác với nền tảng DealX. Hiện tại, nó hỗ trợ tìm kiếm quảng cáo, với kế hoạch bổ sung thêm chức năng trong tương lai.

MCP là gì?

Model Context Protocol (MCP) là một cách chuẩn hóa để các LLM tương tác với các hệ thống bên ngoài. Nó cung cấp một giao diện có cấu trúc để LLM truy cập dữ liệu và thực hiện các hành động trong thế giới thực. Máy chủ này triển khai đặc tả MCP để cho phép các LLM tương tác với nền tảng DealX.

Cài đặt

Điều kiện tiên quyết

  • Node.js (v20 trở lên)
  • npm (v11 trở lên)

Cấu hình MCP

Để sử dụng máy chủ này với một LLM như Claude, bạn cần thêm nó vào cấu hình MCP của LLM:

  1. Mở tệp cấu hình MCP của LLM:

    • Ứng dụng Claude Desktop:
      • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
      • Windows: %APPDATA%\Claude\claude_desktop_config.json
      • Linux: ~/.config/Claude/claude_desktop_config.json
    • Cline (Tiện ích mở rộng VS Code):
      • ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

  2. Thêm máy chủ DealX MCP vào phần mcpServers:

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

Cài đặt qua npm

Cách dễ nhất để cài đặt Máy chủ DealX MCP là qua npm:

npm install -g @dealx/mcp-server

Cài đặt để phát triển

Nếu bạn muốn sửa đổi máy chủ hoặc đóng góp vào quá trình phát triển của nó:

  1. Sao chép kho lưu trữ:

    git clone <repository-url>
cd dealx/mcp

  2. Cài đặt các phụ thuộc:

    npm install

  3. Tạo một tệp .env dựa trên tệp .env.example:

    cp .env.example .env

  4. Chỉnh sửa tệp .env để đặt các giá trị phù hợp:

    # 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. Xây dựng máy chủ:

    npm run build

Sử dụng

Khởi động máy chủ

Bạn có thể chạy máy chủ theo một số cách:

  1. Nếu được cài đặt toàn cục:

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

  2. Sử dụng npx mà không cần cài đặt:

    npx -y @dealx/mcp-server

  3. Với các biến môi trường:

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

  4. Để phát triển:

    npm start

Sử dụng với một LLM

Sau khi được cấu hình trong cài đặt MCP của LLM, bạn có thể sử dụng ngôn ngữ tự nhiên để tương tác với nền tảng DealX.

Ví dụ về lời nhắc:

  • "Tìm kiếm quảng cáo trên DealX với từ khóa 'laptop'"
  • "Tìm 5 quảng cáo mới nhất cho 'iPhone' trên DealX"
  • "Tìm kiếm căn hộ ở Kyiv trên DealX"

Công cụ có sẵn

search_ads

Tìm kiếm quảng cáo trên nền tảng DealX.

Tham số:

  • query (chuỗi, tùy chọn): Chuỗi truy vấn tìm kiếm
  • sort (chuỗi, tùy chọn): Thứ tự sắp xếp (ví dụ: "-created" cho mới nhất trước)
  • offset (số, tùy chọn): Độ lệch phân trang (bắt đầu từ 1, mặc định: 1)
  • limit (số, tùy chọn): Số lượng kết quả mỗi trang (tối đa 100, mặc định: 30)

Ví dụ sử dụng:

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

Mở rộng máy chủ

Máy chủ được thiết kế để dễ dàng mở rộng với các công cụ bổ sung. Dưới đây là cách thêm một công cụ mới:

  • Định nghĩa công cụ trong đối tượng TOOLS trong src/index.ts:

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

  • Tạo một tệp mới trong thư mục src/tools cho việc triển khai công cụ của bạn:

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

  • Thêm công cụ vào trình xử lý ListToolsRequestSchema trong 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
      },
    },
  ],
}));

  • Thêm công cụ vào trình xử lý CallToolRequestSchema trong 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}`);
  }
});

  • Nhập công cụ mới của bạn trong src/index.ts:

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

Các công cụ dự kiến trong tương lai

Các công cụ sau đây được lên kế hoạch triển khai trong tương lai:

  • create_ad: Tạo một quảng cáo mới trên nền tảng DealX
  • edit_ad: Chỉnh sửa một quảng cáo hiện có
  • delete_ad: Xóa một quảng cáo
  • get_threads: Lấy các luồng thảo luận cho một quảng cáo
  • create_thread: Tạo một luồng thảo luận mới

Phát triển

Cấu trúc dự án

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

Các tập lệnh npm

  • npm run build - Biên dịch TypeScript sang JavaScript
  • npm start - Khởi động máy chủ bằng JavaScript đã biên dịch
  • npm run dev - Khởi động máy chủ ở chế độ phát triển với tính năng tải lại nóng
  • npm run lint - Kiểm tra mã bằng ESLint
  • npm run format - Định dạng mã bằng Prettier
  • npm test - Chạy kiểm thử

Khắc phục sự cố

Các vấn đề thường gặp

Máy chủ không khởi động

Nếu máy chủ không khởi động được, hãy kiểm tra những điều sau:

  • Đảm bảo bạn đã cài đặt đúng phiên bản Node.js
  • Kiểm tra xem tất cả các phụ thuộc đã được cài đặt chưa
  • Xác minh rằng tệp .env tồn tại và có các giá trị chính xác
  • Kiểm tra đầu ra bảng điều khiển để tìm thông báo lỗi

Sự cố kết nối

Nếu LLM không thể kết nối với máy chủ:

  • Đảm bảo máy chủ đang chạy
  • Kiểm tra xem cấu hình MCP trong cài đặt của LLM có chính xác không
  • Xác minh rằng đường dẫn đến tệp thực thi máy chủ là chính xác
  • Kiểm tra xem các biến môi trường đã được đặt đúng chưa

Sự cố kết nối API

Nếu máy chủ không thể kết nối với API DealX:

  • Đảm bảo API DealX đang chạy
  • Kiểm tra xem biến môi trường DEALX_API_URL đã được đặt đúng chưa
  • Xác minh rằng điểm cuối API có thể truy cập được từ máy chủ

Nhận trợ giúp

Nếu bạn gặp sự cố không được đề cập ở đây, vui lòng mở một vấn đề trên kho lưu trữ GitHub này.