mcp-server

Purpose

@dealx/mcp-server is the Model Context Protocol (MCP) server for the DealX platform. By implementing the MCP specification, it provides LLMs with a standardized interface that enables them to interact with the DealX platform. Its current main function is searching ads, with more features planned for the future.

Main Capabilities

Currently only searching ads (search_ads) is supported, with parameters including: query (search string, optional), sort (sorting, e.g. "-created" means newest first, optional), offset (pagination offset, starting from 1, default 1), limit (number of results per page, maximum 100, default 30). Features planned for the future are: create_ad (create ad), edit_ad (edit ad), delete_ad (delete ad), get_threads (get ad discussion threads), create_thread (create discussion thread).

Usage

Environment Requirements

• Node.js (v20 or higher)
• npm (v11 or higher)

Installation

Can be installed via npm:npm install @dealx/mcp-server Or run directly with npx.

Integration Configuration with LLM

The server needs to be added to the LLM's MCP configuration file. For example, the configuration paths for 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 (VS Code extension): ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Add in the mcpServers section:

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

Development Installation

1. Clone the repository:git clone <repository-url> then cd dealx/mcp
2. Install dependencies:npm install
3. Create a .env file based on .env.example:cp .env.example .env
4. Edit the .env file to set appropriate values, for example:

DEALX_API_URL=http://localhost:3001
MCP_SERVER_PORT=3100
LOG_LEVEL=info

1. Build the server:npm run build

Starting the Server

• After global installation:node node_modules/@dealx/mcp-server/build/index.js
• Using npx:npx -y @dealx/mcp-server
• With environment variables:DEALX_API_URL=https://dealx.com.ua npx -y @dealx/mcp-server
• Development mode:npm start

Usage Examples

After configuration, you can interact in natural language, for example:

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

Applicable Scenarios

Suitable for scenarios that require giving LLMs access to ad data on the DealX platform, such as searching ads through an LLM or integrating into LLM applications that support MCP (e.g. Claude Desktop, Cline).

Limitations

Currently only ad search is supported, and other features have not yet been implemented. Requires Node.js v20+ and npm v11+. Requires configuring the DealX API URL. Managed deployment is available on Fronteir AI.

Extension and Contribution

The server is designed to be easy to extend. Steps to add a new tool: define the tool in the TOOLS object in src/index.ts; create a new file in the src/tools directory to implement the tool logic; add the tool in the ListToolsRequestSchema and CallToolRequestSchema handlers; import the new tool in src/index.ts.

Troubleshooting

• Server fails to start: check the Node.js version, dependency installation, .env file, and console errors
• LLM cannot connect: ensure the server is running, the MCP configuration is correct, the executable path is correct, and environment variables are set correctly
• Cannot connect to the DealX API: ensure the API is running, DEALX_API_URL is correct, and the API endpoint is accessible

If you encounter an issue not covered, you can submit an issue in the GitHub repository.