MCP 服务器

@dealx/mcp-server

DealX平台的MCP服务器

DealExpress

开发者工具

访问服务器

README

@dealx/mcp-server

这是一个用于 DealX 平台的模型上下文协议 (MCP) 服务器。它允许 LLM 与 DealX 平台交互，特别是搜索广告。

概述

DealX MCP 服务器实现了模型上下文协议，为 LLM 提供了一种与 DealX 平台交互的标准化方式。目前，它支持搜索广告，并计划在未来添加更多功能。

什么是 MCP？

模型上下文协议 (MCP) 是 LLM 与外部系统交互的一种标准化方式。它为 LLM 提供了一个结构化的接口，用于访问数据并在现实世界中执行操作。此服务器实现了 MCP 规范，以允许 LLM 与 DealX 平台交互。

安装

前提条件

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

MCP 配置

要将此服务器与像 Claude 这样的 LLM 一起使用，您需要将其添加到 LLM 的 MCP 配置中：

打开 LLM 的 MCP 配置文件：
- Claude Desktop App:
  - 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 Extension):
  - ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

将 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

开发安装

如果您想修改服务器或为其开发做出贡献：

克隆存储库：

git clone <repository-url>
cd dealx/mcp

安装依赖项：
```
npm install
```
基于 .env.example 文件创建一个 .env 文件：
```
cp .env.example .env
```

编辑 .env 文件以设置适当的值：

# DealX API URL
DEALX_API_URL=http://localhost:3001

# 可选：指定 MCP 服务器的端口
MCP_SERVER_PORT=3100

# 可选：日志级别 (debug, info, warn, error)
LOG_LEVEL=info

构建服务器：
```
npm run build
```

使用

启动服务器

您可以通过几种方式运行服务器：

如果全局安装：

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

使用 npx 无需安装：
```
npx -y @dealx/mcp-server
```

使用环境变量：

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

用于开发：
```
npm start
```

与 LLM 一起使用

在 LLM 的 MCP 设置中配置后，您可以使用自然语言与 DealX 平台交互。

示例提示：

"在 DealX 上搜索查询为 'laptop' 的广告"
"在 DealX 上查找最新的 5 个 'iPhone' 广告"
"在 DealX 上搜索基辅的公寓"

可用工具

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", // 在此处添加您的新工具
};

在 src/tools 目录中为您的工具实现创建一个新文件：

// src/tools/new-tool.ts
import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";

interface NewToolParams {
  // 在此处定义您的工具参数
}

export async function newTool(params: NewToolParams) {
  try {
    // 在此处实现您的工具逻辑

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  } catch (error) {
    // 处理错误
    // ...
  }
}

将该工具添加到 src/index.ts 中的 ListToolsRequestSchema 处理程序：

this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    // 现有工具...
    {
      name: TOOLS.NEW_TOOL,
      description: "您的新工具的描述",
      inputSchema: {
        type: "object",
        properties: {
          // 在此处定义您的工具参数
        },
        required: [], // 列出必需的参数
      },
    },
  ],
}));

将该工具添加到 src/index.ts 中的 CallToolRequestSchema 处理程序：

this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  switch (name) {
    // 现有案例...
    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/              # 编译后的 JavaScript 文件
├── src/                # TypeScript 源代码文件
│   ├── tools/          # 工具实现
│   │   └── search-ads.ts
│   └── index.ts        # 主要服务器实现
├── .env                # 环境变量 (不在 git 中)
├── .env.example        # 环境变量示例
├── package.json        # 项目依赖项和脚本
├── tsconfig.json       # TypeScript 配置
└── README.md           # 此文件