DealX

공식

DealX 플랫폼용 MCP 서버

GitHub
2

Deal X MCP(으)로 무엇을 할 수 있나요?

  • 키워드로 광고 검색 — 텍스트 쿼리를 사용하여 search_ads를 통해 DealX 플랫폼에서 목록을 찾습니다.
  • 결과 정렬 및 페이지 매기기 — 정렬 순서(예: -created로 최신순), 페이지 오프셋 및 결과 개수를 제어합니다.
  • 결과 수 제한 — 요청당 최대 100개의 광고로 사용자 지정 페이지 크기를 설정합니다.

문서

@dealx/mcp-server

이것은 DealX 플랫폼을 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. LLM이 DealX 플랫폼과 상호 작용할 수 있도록 하며, 특히 광고 검색 기능을 제공합니다.

목차

호스팅 배포

Fronteir AI에서 호스팅 배포를 이용할 수 있습니다.

개요

DealX MCP 서버는 모델 컨텍스트 프로토콜을 구현하여 LLM이 DealX 플랫폼과 상호 작용할 수 있는 표준화된 방법을 제공합니다. 현재는 광고 검색을 지원하며, 향후 더 많은 기능을 추가할 계획입니다.

MCP란 무엇인가요?

모델 컨텍스트 프로토콜(MCP)은 LLM이 외부 시스템과 상호 작용할 수 있는 표준화된 방법입니다. LLM이 데이터에 접근하고 실제 세계에서 작업을 수행할 수 있도록 구조화된 인터페이스를 제공합니다. 이 서버는 MCP 사양을 구현하여 LLM이 DealX 플랫폼과 상호 작용할 수 있도록 합니다.

설치

사전 요구 사항

  • Node.js (v20 이상)
  • npm (v11 이상)

MCP 구성

Claude와 같은 LLM에서 이 서버를 사용하려면 LLM의 MCP 구성에 추가해야 합니다:

  1. LLM의 MCP 구성 파일을 엽니다:

    • Claude 데스크톱 앱:
      • 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 확장):
      • ~/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 서버를 설치하는 가장 쉬운 방법은 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에서 '노트북' 쿼리로 광고 검색해 줘"
  • "DealX에서 'iPhone'에 대한 최신 광고 5개 찾아 줘"
  • "DealX에서 키이우의 아파트 검색해 줘"

사용 가능한 도구

search_ads

DealX 플랫폼에서 광고를 검색합니다.

매개변수:

  • query (문자열, 선택 사항): 검색 쿼리 문자열
  • sort (문자열, 선택 사항): 정렬 순서 (예: 최신순은 "-created")
  • offset (숫자, 선택 사항): 페이지네이션 오프셋 (1부터 시작, 기본값: 1)
  • limit (숫자, 선택 사항): 페이지당 결과 수 (최대 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 플랫폼에 새 광고 생성
  • 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 저장소에 이슈를 등록해 주세요.