Dealx

@dealx/mcp-server

这是一个适用于 DealX 平台的 Model Context Protocol（MCP）服务。它允许大模型与 DealX 平台交互，具体用于搜索广告。

目录

• 概述
• 安装
• 使用方法
• 可用工具
• 扩展服务
• 开发
• 故障排除

托管部署

可通过 Fronteir AI使用托管部署。

概述

DealX MCP 服务实现了 Model Context Protocol，为大模型与 DealX 平台交互提供标准化方式。目前，它支持搜索广告，未来计划添加更多功能。

什么是 MCP？

Model Context Protocol（MCP）是一种供大模型与外部系统交互的标准化方式。它提供结构化接口，让大模型能够访问数据并在现实世界中执行操作。此服务实现了 MCP 规范，允许大模型与 DealX 平台交互。

安装

先决条件

• Node.js（v20 或更高版本）
• npm（v11 或更高版本）

MCP 配置

若要将此服务与 Claude 等大模型搭配使用，需要将其添加到大模型的 MCP 配置中：

1. 打开大模型的 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
   

与大模型搭配使用

在大模型的 MCP 设置中完成配置后，你可以使用自然语言与 DealX 平台交互。

提示词示例：

• “在 DealX 上搜索包含 ‘laptop’ 的广告”
• “在 DealX 上查找 ‘iPhone’ 最新的 5 条广告”
• “在 DealX 上搜索 Kyiv 的公寓”

可用工具

search_ads

在 DealX 平台上搜索广告。

参数：

• query（string，可选）：搜索查询字符串
• sort（string，可选）：排序方式（例如，"-created" 表示最新内容优先）
• offset（number，可选）：分页偏移量（从 1 开始，默认值：1）
• limit（number，可选）：每页结果数（最多 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 文件存在且包含正确的值
• 检查控制台输出中的错误消息

连接问题

如果大模型无法连接到服务：

• 确保服务正在运行
• 检查大模型设置中的 MCP 配置是否正确
• 确认服务可执行文件的路径是否正确
• 检查环境变量是否设置正确

API 连接问题

如果服务无法连接到 DealX API：

• 确保 DealX API 正在运行
• 检查 DEALX_API_URL 环境变量是否设置正确
• 确认服务可以访问该 API 端点

获取帮助

如果遇到此处未涵盖的问题，请在此 GitHub 仓库中提交 issue。