MCP 服务器

@dealx/mcp-server

Enables LLMs to search ads on the DealX platform through the Model Context Protocol.

README

@dealx/mcp-server

This is a Model Context Protocol (MCP) server for the DealX platform. It allows LLMs to interact with the DealX platform, specifically to search for ads.

Overview
Installation
Usage
Available Tools
Extending the Server
Development
Troubleshooting

Overview

The DealX MCP Server implements the Model Context Protocol to provide a standardized way for LLMs to interact with the DealX platform. Currently, it supports searching for ads, with plans to add more functionality in the future.

What is MCP?

The Model Context Protocol (MCP) is a standardized way for LLMs to interact with external systems. It provides a structured interface for LLMs to access data and perform actions in the real world. This server implements the MCP specification to allow LLMs to interact with the DealX platform.

Installation

Prerequisites

Node.js (v20 or later)
npm (v11 or later)

MCP Configuration

To use this server with an LLM like Claude, you need to add it to your LLM's MCP configuration:

Open your LLM's MCP configuration file:
- 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

Add the DealX MCP server to the mcpServers section:

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

Installation via npm

The easiest way to install the DealX MCP Server is via npm:

npm install -g @dealx/mcp-server

Installation for Development

If you want to modify the server or contribute to its development:

Clone the repository:

git clone <repository-url>
cd dealx/mcp

Install dependencies:
```
npm install
```
Create a .env file based on the .env.example file:
```
cp .env.example .env
```

Edit the .env file to set the appropriate values:

# 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

Build the server:
```
npm run build
```

Usage

Starting the Server

You can run the server in several ways:

If installed globally:

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

Using npx without installation:
```
npx -y @dealx/mcp-server
```

With environment variables:

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

For development:
```
npm start
```

Using with an LLM

Once configured in your LLM's MCP settings, you can use natural language to interact with the DealX platform.

Example prompts:

"Search for ads on DealX with the query 'laptop'"
"Find the newest 5 ads for 'iPhone' on DealX"
"Search DealX for apartments in Kyiv"

Available Tools

search_ads

Search for ads on the DealX platform.

Parameters:

query (string, optional): Search query string
sort (string, optional): Sort order (e.g., "-created" for newest first)
offset (number, optional): Pagination offset (starts at 1, default: 1)
limit (number, optional): Number of results per page (max 100, default: 30)

Example Usage:

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

Extending the Server

The server is designed to be easily extended with additional tools. Here's how to add a new tool:

Define the tool in the TOOLS object in src/index.ts:

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

Create a new file in the src/tools directory for your tool implementation:

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

Add the tool to the ListToolsRequestSchema handler in 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
      },
    },
  ],
}));

Add the tool to the CallToolRequestSchema handler in 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}`);
  }
});

Import your new tool in src/index.ts:

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

Planned Future Tools

The following tools are planned for future implementation:

create_ad: Create a new ad on the DealX platform
edit_ad: Edit an existing ad
delete_ad: Delete an ad
get_threads: Get discussion threads for an ad
create_thread: Create a new discussion thread

Development

Project Structure

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