Dealx

@dealx/mcp-server

これはDealX platform向けのModel Context Protocol（MCP）サーバーです。LLMがDealXプラットフォームと連携して、特に広告を検索できるようにします。

目次

• 概要
• インストール
• 使い方
• 利用可能なツール
• サーバーの拡張
• 開発
• トラブルシューティング

ホスト型デプロイ

Fronteir AIでホスト型デプロイを利用できます。

概要

DealX MCP ServerはModel Context Protocolを実装し、LLMがDealX platformと連携するための標準化された方法を提供します。現在は広告検索に対応しており、今後さらに機能を追加する予定です。

MCPとは？

Model Context Protocol（MCP）は、LLMが外部システムと連携するための標準化された方法です。LLMがデータにアクセスし、現実世界でアクションを実行するための構造化されたインターフェースを提供します。このサーバーはMCP仕様を実装し、LLMがDealXプラットフォームと連携できるようにします。

インストール

前提条件

• Node.js（v20以降）
• npm（v11以降）

MCPの設定

ClaudeなどのLLMでこのサーバーを使用するには、LLMのMCP設定に追加する必要があります。

1. 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

2. mcpServersセクションにDealX MCPサーバーを追加します。

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

npm経由でのインストール

DealX MCP Serverをインストールする最も簡単な方法は、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
   

LLMでの使用

LLMのMCP設定に追加すると、自然言語を使ってDealXプラットフォームを操作できます。

プロンプトの例：

• 「DealXでクエリ'laptop'を使って広告を検索」
• 「DealXで'iPhone'の最新広告を5件検索」
• 「DealXでKyivのアパートを検索」

利用可能なツール

search_ads

DealXプラットフォームで広告を検索します。

パラメーター：

• query（string、任意）：検索クエリ文字列
• sort（string、任意）：並べ替え順（例：新しい順の場合は"-created"）
• offset（number、任意）：ページネーションのオフセット（1から開始、デフォルト：1）
• limit（number、任意）：1ページあたりの結果数（最大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 platformに新しい広告を作成します
• 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 ファイルが存在し、正しい値が設定されていることを確認します
• コンソール出力にエラーメッセージがないか確認します

接続の問題

LLM がサーバーに接続できない場合は、以下を確認してください。

• サーバーが実行中であることを確認します
• LLM の設定にある MCP 構成が正しいことを確認します
• サーバー実行ファイルへのパスが正しいことを確認します
• 環境変数が正しく設定されていることを確認します

API 接続の問題

サーバーが DealX API に接続できない場合は、以下を確認してください。

• DealX API が稼働していることを確認します
• DEALX_API_URL 環境変数が正しく設定されていることを確認します
• サーバーから API エンドポイントにアクセスできることを確認します

サポートを受ける

ここに記載されていない問題が発生した場合は、この GitHub リポジトリに Issue を作成してください。