DealX

官方

DealX 平台的 MCP 伺服器

GitHub
2

你可以用 Deal X MCP 做什麼？

  • 依關鍵字搜尋廣告 — 透過 search_ads 使用文字查詢在 DealX 平台上尋找刊登項目。
  • 排序與分頁結果 — 控制排序順序（例如使用 -created 以最新優先）、頁面偏移量及結果數量。
  • 限制結果數量 — 設定自訂頁面大小，每次請求最多可顯示 100 則廣告。

文件

@dealx/mcp-server

這是一個用於 DealX 平台 的模型上下文協定 (Model Context Protocol, MCP) 伺服器。它允許 LLM 與 DealX 平台互動，特別是搜尋廣告。

目錄

託管部署

Fronteir AI 上提供託管部署。

概覽

DealX MCP 伺服器實作了 模型上下文協定，為 LLM 提供與 DealX 平台 互動的標準化方式。目前支援搜尋廣告，未來計劃加入更多功能。

什麼是 MCP？

模型上下文協定 (MCP) 是 LLM 與外部系統互動的標準化方式。它提供了一個結構化的介面，讓 LLM 能夠存取資料並在現實世界中執行動作。此伺服器實作了 MCP 規範，允許 LLM 與 DealX 平台互動。

安裝

先決條件

  • Node.js (v20 或更新版本)
  • npm (v11 或更新版本)

MCP 設定

若要將此伺服器與 Claude 等 LLM 搭配使用，您需要將其新增至 LLM 的 MCP 設定中：

  1. 開啟 LLM 的 MCP 設定檔：

    • 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 (VS Code 擴充功能)：
      • ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

  2. 將 DealX MCP 伺服器新增至 mcpServers 區段：

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

透過 npm 安裝

安裝 DealX MCP 伺服器最簡單的方式是透過 npm：

npm install -g @dealx/mcp-server

開發用安裝

如果您想修改伺服器或為其開發做出貢獻：

  1. 複製儲存庫：

    git clone <repository-url>
cd dealx/mcp

  2. 安裝相依套件：

    npm install

  3. 根據 .env.example 檔案建立一個 .env 檔案：

    cp .env.example .env

  4. 編輯 .env 檔案以設定適當的值：

    # 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. 建置伺服器：

    npm run build

使用方式

啟動伺服器

您可以透過多種方式執行伺服器：

  1. 若已全域安裝：

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

  2. 使用 npx 而無需安裝：

    npx -y @dealx/mcp-server

  3. 搭配環境變數：

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

  4. 開發用途：

    npm start

與 LLM 搭配使用

在 LLM 的 MCP 設定中完成設定後，您可以使用自然語言與 DealX 平台互動。

提示範例：

  • "在 DealX 上搜尋 '筆記型電腦' 的廣告"
  • "在 DealX 上尋找最新的 5 則 'iPhone' 廣告"
  • "在 DealX 上搜尋基輔的公寓"

可用工具

search_ads

在 DealX 平台上搜尋廣告。

參數：

  • query (字串，選用)：搜尋查詢字串
  • sort (字串，選用)：排序順序 (例如 "-created" 表示最新優先)
  • offset (數字，選用)：分頁偏移量 (從 1 開始，預設值：1)
  • limit (數字，選用)：每頁結果數量 (最多 100，預設值：30)

使用範例：

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

擴充伺服器

伺服器設計為易於使用額外工具進行擴充。以下是新增工具的步驟：

  • 在 src/index.ts 的 TOOLS 物件中定義工具：

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

  • 在 src/tools 目錄中為您的工具實作建立一個新檔案：

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

  • 將工具新增至 src/index.ts 中的 ListToolsRequestSchema 處理常式：

    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
      },
    },
  ],
}));

  • 將工具新增至 src/index.ts 中的 CallToolRequestSchema 處理常式：

    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}`);
  }
});

  • 在 src/index.ts 中匯入您的新工具：

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

計劃中的未來工具

以下工具計劃在未來實作：

  • create_ad：在 DealX 平台 上建立新廣告
  • edit_ad：編輯現有廣告
  • delete_ad：刪除廣告
  • get_threads：取得廣告的討論串
  • create_thread：建立新的討論串

開發

專案結構

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

npm 指令稿

  • npm run build - 將 TypeScript 編譯為 JavaScript
  • npm start - 使用編譯後的 JavaScript 啟動伺服器
  • npm run dev - 以開發模式啟動伺服器並支援熱重載
  • npm run lint - 使用 ESLint 檢查程式碼
  • npm run format - 使用 Prettier 格式化程式碼
  • npm test - 執行測試

疑難排解

常見問題

伺服器無法啟動

如果伺服器無法啟動，請檢查以下事項：

  • 確保已安裝正確的 Node.js 版本
  • 檢查所有相依套件是否已安裝
  • 驗證 .env 檔案是否存在且具有正確的值
  • 檢查主控台輸出中的錯誤訊息

連線問題

如果 LLM 無法連線到伺服器：

  • 確保伺服器正在執行
  • 檢查 LLM 設定中的 MCP 設定是否正確
  • 驗證伺服器執行檔的路徑是否正確
  • 檢查環境變數是否設定正確

API 連線問題

如果伺服器無法連線到 DealX API：

  • 確保 DealX API 正在執行
  • 檢查 DEALX_API_URL 環境變數是否設定正確
  • 驗證是否可以從伺服器存取 API 端點

取得協助

如果您遇到此處未涵蓋的問題，請在此 GitHub 儲存庫中開啟一個 issue。