npm package: @n0ml1/tiktokr-mcp
Description: MCP Server for TikTok Research API with x402 payment integration
Author: Crypto-AI-Media
Latest version: 0.1.1

# 📊 TikTok Research MCP Server

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

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

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

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

```bash
cd tiktok-research-mcp
npm install
npm run build
```

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

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

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

### 3️⃣ Запуск

```bash
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:

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

Prod:

```bash
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

```json
{
    "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, платежа)

**Настройка:**

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

**Пример лога:**

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

---

## 🐛 Troubleshooting

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

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

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

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

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

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

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

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

---

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

### Docker

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

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

### Docker Compose

```bash
docker-compose up -d
```

### PM2 (Production)

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

### Systemd (Linux)

```bash
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

```bash
npm install
```

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

```bash
npm run dev
```

### Компиляция TypeScript

```bash
npm run build
```

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

```bash
npm run test
```

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

```bash
npx tsc --noEmit
```

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

```bash
npm run format
```

---

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

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

---

## 🤝 Поддержка

- 📧 Email: support@tiktok-research.com
- 🐛 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
```

## Разработка

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

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

# Сборка
npm run build

# Тесты
npm run test
```

## Лицензия

MIT