DealX MCP Interfacing Service (@dealx/mcp-server)

This repository houses the Model Context Protocol (MCP) service designed to bridge Large Language Models (LLMs) with the proprietary data ecosystem of the DealX platform. Its primary function is to enable AI agents to perform sophisticated searches against the platform's classified advertisements.

Table of Contents

• Introduction
• Setup and Deployment
• Operational Guide
• Exposed Capabilities
• Architecture Extension
• Development Workflow
• Debugging and Support

Introduction

The DealX MCP Gateway conforms to the Model Context Protocol specification, establishing a standardized conduit for LLMs to query and manipulate data pertaining to DealX listings. Currently, the primary supported capability is ad retrieval, with a roadmap for incorporating further platform integrations.

Understanding MCP

The Model Context Protocol (MCP) is a standard interface enabling AI systems to reliably access external data sources and execute real-world operations. This implementation adheres to the protocol to grant LLMs structured access to DealX resources.

Setup and Deployment

Prerequisites

Ensure the following runtime environment is present:

• Node.js (version 20 or newer)
• npm (version 11 or newer)

LLM Configuration Integration

To activate this service for an LLM client (e.g., Claude), integrate the following configuration snippet into the client's MCP settings file:

1. Locate Configuration File:
2. Claude Desktop App: Path varies by OS (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json on macOS).

3. Cline (VS Code Extension): Specific path within VS Code's global storage.

4. Register Server Entry: Add the service configuration to the mcpServers array:

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

Installation via Package Manager

The simplest method for deployment is global installation:

npm install -g @dealx/mcp-server

Local Development Setup

For source code modification or contribution:

1. Clone Repository: shell git clone <repository-url> cd dealx/mcp

2. Dependency Resolution: shell npm install

3. Environment Initialization: Create and populate the .env file from the example template: shell cp .env.example .env

4. **Configuration Tuning (in .env): ```shell # Endpoint for the DealX backend service DEALX_API_URL=http://localhost:3001

# Optional: Port binding for the MCP listener MCP_SERVER_PORT=3100

# Logging verbosity control LOG_LEVEL=info ```

1. Compilation: shell npm run build

Operational Guide

Initiating the Service

Execution methods include:

1. Globally Installed: shell node node_modules/@dealx/mcp-server/build/index.js

2. On-Demand Execution (No Global Install): shell npx -y @dealx/mcp-server

3. With Custom Environment Variables: shell DEALX_API_URL=https://dealx.com.ua npx -y @dealx/mcp-server

4. Development Mode Startup: shell npm start

LLM Interaction

Once the service is configured in the LLM settings, interaction occurs via natural language instructions targeting the exposed capabilities.

Illustrative Prompts:

• "Retrieve listings from DealX matching the keyword 'high-performance workstation'."
• "Show the ten most recent advertisements for 'vacation properties' on DealX, starting from the second page."
• "What are the current listings for real estate in the capital city on the DealX marketplace?"

Exposed Capabilities

search_ads

Functionality to query the DealX advertisement database.

Arguments:

• query (String, Optional): The textual criterion for filtering advertisements.
• sort (String, Optional): Specification for result ordering (e.g., "-created" for reverse chronological order).
• offset (Number, Optional): Index indicating the starting position of the result set (1-based indexing; default: 1).
• limit (Number, Optional): Maximum number of records returned per invocation (Constraint: maximum 100; default: 30).

Invocation Example:

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

Architecture Extension

The framework prioritizes ease of integration for new platform functionalities. To integrate a novel tool:

• Tool Definition: Register the new operation identifier within the central TOOLS map in src/index.ts (e.g., NEW_FUNCTIONALITY: "new_functionality").

• Implementation File: Develop the core logic in a dedicated file within the src/tools directory (e.g., src/tools/new-functionality.ts). The function must accept parsed parameters and return a structured MCP response object.

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

interface NewFuncParams { / Define schema inputs here / }

export async function newFunctionality(params: NewFuncParams) { try { // Core business logic implementation

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify(execution_result, null, 2),
      },
    ],
  };
} catch (e) {
  // Robust error handling
  throw new McpError(ErrorCode.InternalError, "Operation failed.");
}

} ```

• Schema Registration (ListToolsRequestSchema): Update the manifest returned by the service to describe the new tool, including its name and input schema validation rules:

typescript this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ // ... Existing definitions ... { name: TOOLS.NEW_FUNCTIONALITY, description: "A concise summary of what the new tool accomplishes.", inputSchema: { /* JSON Schema definition for parameters */ }, }, ], }));

• Dispatch Registration (CallToolRequestSchema): Implement the routing logic to execute the newly defined function upon receiving a call request:

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

switch (name) {
  // ... Existing cases ...
  case TOOLS.NEW_FUNCTIONALITY:
    return await newFunctionality(args);
  default:
    throw new McpError(ErrorCode.MethodNotFound, `Unrecognized operation: ${name}`);
}

}); ```

• Import: Ensure the function is imported into src/index.ts for use in the handler.

Future Roadmap

Future enhancements slated for integration include:

• place_listing: Functionality to submit a new classified ad to DealX.
• update_listing: Modifying parameters of an existing advertisement.
• retract_listing: Removing an advertisement from publication.
• fetch_correspondence: Retrieving associated discussion threads for a specific listing.
• initiate_dialog: Creating a new communication thread.

Development

Directory Layout

mcp/
├── build/              # Output directory for compiled ES modules
├── src/                # Primary source code (TypeScript)
│   ├── tools/          # Isolated implementation modules for each capability
│   │   └── search-ads.ts
│   └── index.ts        # Service bootstrap and request routing
├── .env                # Runtime configurations (not tracked by version control)
├── .env.example        # Template for environment settings
├── package.json        # Project metadata, scripts, and dependencies
├── tsconfig.json       # TypeScript compiler directives
└── README.md           # Documentation

Available npm Scripts

• npm run build: Transpiles TypeScript source files into JavaScript.
• npm start: Launches the service using the compiled artifacts.
• npm run dev: Starts the service with a watch process for live reloading during development.
• npm run lint: Executes code quality checks via ESLint.
• npm run format: Applies automated code style corrections via Prettier.
• npm test: Executes automated unit and integration tests.

Troubleshooting

Common Operational Obstacles

Service Fails to Initiate

Verify the following points in sequence:

• Compatibility check: Ensure Node.js meets the minimum version requirement.
• Dependency integrity: Confirm all required packages are installed correctly.
• Configuration validity: Inspect the .env file for errors or omissions.
• Output review: Examine console output for explicit error messages during startup.

Connectivity Failures (LLM to Server)

If the controlling LLM cannot engage the service:

• Confirm the service process is actively running.
• Cross-reference the LLM's MCP settings against the service configuration (address, port, command).
• Validate the executable path specified in the LLM configuration.
• Check the environment variables supplied to the server process.

DealX Backend Communication Errors

If the server cannot reach the target API:

• Confirm the DealX API service is operational.
• Validate the integrity of the DEALX_API_URL environment setting.
• Ensure network accessibility from the server environment to the API endpoint.

Seeking Assistance

If standard diagnostics do not resolve the issue, please submit a detailed report as an issue on the project's official GitHub repository.