📊 TikTok Research MCP Server

MCP Server для анализа трендов TikTok с поддержкой x402 (Coinbase Commerce) платежей.

Используется с Claude Desktop для создания отчетов о хештегах, создателях, звуках и трендах на TikTok.

🚀 Быстрый Старт (5 минут)

1️⃣ Установка

cd tiktok-research-mcp
npm install
npm run build

2️⃣ Конфигурация

Создай .env файл (копируй из .env.example):

BACKEND_URL=http://localhost:3000
LOG_LEVEL=info

3️⃣ Запуск

npm run dev -- --svm-private-key <SVM_PRIVATE_KEY>              # Development
npm start -- --svm-private-key <SVM_PRIVATE_KEY>                # Production
docker-compose up -d     # Docker

🎯 Встроенные Инструменты

| Инструмент | Функция | Пример | | ------------------------ | ----------------------- | ---------------------------- | | create_report | Создать отчет о трендах | "Создай отчет по запросу" | | check_report_status | Проверить статус | "Какой статус у report-123?" | | get_report_result | Получить результаты | "Покажи результаты отчета" | | get_pricing | Получить цены | "Сколько стоит отчет?" | | list_available_reports | Список типов отчетов | "Какие типы доступны?" |

⚙️ Конфигурация

Обязательно:

• BACKEND_URL - адрес backend API (default: http://localhost:3000)

Опционально:

• LOG_LEVEL - debug|info|warn|error (default: info)

CLI параметры (обязательно хотя бы один):

• --svm-private-key - приватный ключ Solana (base58 или JSON-массив)
• --evm-private-key - приватный ключ EVM (hex)

Примеры .env:

Dev:

BACKEND_URL=http://localhost:3000
LOG_LEVEL=debug

Prod:

BACKEND_URL=https://api.tiktok-research.com
LOG_LEVEL=warn

🔌 Backend API Требования

Server ожидает эти endpoints на backend:

| Endpoint | Метод | Назначение | | --------------------- | ----- | ----------------- | | /report | POST | Создать отчет | | /report/list | GET | Список отчетов | | /report/{id} | GET | Получить отчет | | /report/{id}/stream | SSE | Стрим статуса | | /auth/wallet/nonce | GET | Получить nonce | | /auth/wallet/verify | POST | Проверить подпись |

📖 Примеры

Пример 1: Создание отчета

User: "Сделай базовый отчет по #viral"

Claude:
1. Вызывает create_report(type: "basic", sources: [{type: "hashtag", value: "#viral", count: 30}])
2. Получает reportId: "report-12345"
3. Проверяет статус через check_report_status(reportId)

Пример 2: Отчет о профиле

User: "Дай анализ профиля @tiktok_user"

Claude:
1. Создает отчет: create_report(type: "deep", sources: [{type: "profile", value: "@tiktok_user", count: 100}])
2. Проверяет статус: check_report_status(reportId)
3. После завершения: get_report_result(reportId)
4. Показывает результаты

🌐 Интеграция с Claude Desktop

1️⃣ Найди конфиг Claude

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

2️⃣ Добавь MCP Server

{
    "mcpServers": {
        "tiktok-research": {
            "command": "node",
            "args": [
                "/path/to/tiktok-research-mcp/dist/index.js",
                "--svm-private-key",
                "<SVM_PRIVATE_KEY>"
            ],
            "env": {
                "BACKEND_URL": "http://localhost:3000",
                "LOG_LEVEL": "info"
            }
        }
    }
}

3️⃣ Перезагрузи Claude

Закрой и открой Claude Desktop заново.

4️⃣ Проверь подключение

Claude: "Какие типы отчетов доступны?"

Должно вернуть список (если backend запущен).

🔍 Логирование

Server использует структурированное логирование в формате JSON.

Уровни:

• debug - все операции, реквесты, ответы
• info - важные события (создание отчета, оплата)
• warn - предупреждения (таймауты, ошибки валидации)
• error - критические ошибки (сбой backend, платежа)

Настройка:

LOG_LEVEL=debug npm run dev   # Максимально подробные логи
LOG_LEVEL=error npm start      # Только ошибки

Пример лога:

{
    "level": "info",
    "timestamp": "2024-01-15T10:30:45.123Z",
    "tool": "create_report",
    "message": "Creating report",
    "type": "hashtag",
    "query": "#viral"
}

🐛 Troubleshooting

❌ "Backend недоступен"

# Проверь, запущен ли backend
curl http://localhost:3000/health

# Или проверь BACKEND_URL в .env
echo $BACKEND_URL

❌ "MCP Server не загружается"

# Проверь логи Claude
npm run dev  # Выполни в console - должны быть ошибки

# Перепроверь path в claude_desktop_config.json
# Убедись что path абсолютный

❌ "Отчет зависает на processing"

# Проверь логи backend
# Если timeout - увеличь timeout в config или попробуй позже
# Если ошибка в backend - исправь backend и пересоздай отчет

🚀 Развертывание

Docker

# Build
docker build -t tiktok-research-mcp .

# Run
docker run -e BACKEND_URL=http://backend:3000 tiktok-research-mcp

Docker Compose

docker-compose up -d

PM2 (Production)

npm install -g pm2
pm2 start dist/index.js --name "tiktok-mcp"
pm2 save
pm2 startup

Systemd (Linux)

sudo tee /etc/systemd/system/tiktok-mcp.service > /dev/null <<EOF
[Unit]
Description=TikTok Research MCP Server
After=network.target

[Service]
Type=simple
User=app
WorkingDirectory=/opt/tiktok-research-mcp
ExecStart=/usr/bin/node dist/index.js
Restart=always
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable tiktok-mcp
sudo systemctl start tiktok-mcp

📁 Структура Проекта

├── src/
│   ├── index.ts              # MCP Server (точка входа)
│   ├── config.ts             # Загрузка конфига из .env
│   ├── logger.ts             # Структурированное логирование
│   ├── client/
│   │   └── backend.ts        # HTTP клиент для backend API
│   ├── handlers/
│   │   ├── report.ts         # create_report, check_report_status, list_available_reports
│   │   └── pricing.ts        # get_pricing
│   └── types.ts              # TypeScript типы
├── dist/                     # Скомпилированный JS
├── package.json
├── tsconfig.json
├── .env                      # Конфиг (НЕ коммитить!)
├── .env.example             # Пример конфига
└── README.md                # Этот файл

🛠️ Разработка

Установка Dependencies

npm install

Локальный запуск

npm run dev

Компиляция TypeScript

npm run build

Тестирование

npm run test

Проверка типов

npx tsc --noEmit

Форматирование кода

npm run format

📚 Дополнительная Документация

• INSTALLATION.md - Детальная инструкция установки
• EXAMPLES.md - Расширенные примеры использования
• DEVELOPER_GUIDE.md - Гайд для разработчиков (расширение функционала)

🤝 Поддержка

• 📧 Email: [email protected]
• 🐛 Issues: https://github.com/your-org/tiktok-research-mcp/issues
• 💬 Discussions: https://github.com/your-org/tiktok-research-mcp/discussions

📄 Лицензия

MIT

2. Вернет информацию о цене
3. Создаст платеж через x402
4. После подтверждения запустит обработку

Пример 2: Проверка статуса

Проверь статус отчета report_12345

Архитектура

src/
├── index.ts              # Entry point
├── server.ts             # MCP Server setup
├── handlers/             # Tool handlers
│   ├── report.ts         # Report creation & status
│   └── pricing.ts        # Pricing information
├── client/               # Backend HTTP client
├── types.ts              # TypeScript definitions
└── config.ts             # Configuration management

Разработка

# Установка зависимостей
npm install

# Запуск в режиме разработки
npm run dev

# Сборка
npm run build

# Тесты
npm run test

Лицензия

MIT