Metadata-Version: 2.4
Name: kt-mcp-bc
Version: 0.3.0
Summary: Buyer-scoped MCP server for Keitaro Tracker — analytics-only access (clicks, conversions, reports) filtered by sub_id_3 = buyer_id.
Author-email: Leximo <alekseykosenko@gmail.com>
License: Proprietary
Project-URL: Homepage, https://github.com/okosenko-commits/kt-mcp-buyercentric
Keywords: mcp,keitaro,tracker,affiliate,analytics,buyer-scoped
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Other Audience
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Keitaro MCP — Buyer Edition

MCP-сервер для доступа к **твоей** аналитике в Keitaro Tracker из Claude Code и Claude Desktop. Видишь только данные своего трафика (по `sub_id_3 = buyer_id`), чужие кампании и конфиг трекера недоступны.

## Что получишь

Четыре инструмента в Claude:

| Инструмент | Что делает |
|---|---|
| `keitaro_list_instances` | список подключённых трекеров |
| `keitaro_build_report` | аналитические отчёты (метрики × дименшины × фильтры) |
| `keitaro_get_clicks` | сырые клики |
| `keitaro_get_conversions` | сырые конверсии |

Все запросы автоматически фильтруются по твоему `buyer_id`. Подмена `sub_id_3` блокируется до выхода на wire.

---

## 1. Что подготовить (один раз)

### 1.1 Установить uv

[uv](https://docs.astral.sh/uv/) — менеджер Python-окружений, нужен для запуска сервера.

```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Проверь: `uv --version` должно отдать номер версии.

### 1.2 Получить у админа трекера 4 значения

| Переменная | Что это | Где взять |
|---|---|---|
| `KEITARO_URL` | URL трекера, без слэша в конце | у админа, пример: `https://tracker.example.com` |
| `KEITARO_API_KEY` | твой API-ключ | админ создаёт в **Maintenance → Users → твой логин → API keys** |
| `KEITARO_LOGIN` | твой логин в Keitaro **в точности как в колонке "Логін"** (со всеми пробелами и пайпами) | у админа в Users, пример: `TEAM \| FB1 \| ivanov` |
| `KEITARO_BUYER_ID` | значение, которое летит в `sub_id_3` на твоём трафике | у админа |

### 1.3 Скачать MCP-сервер

```bash
git clone https://github.com/okosenko-commits/kt-mcp-buyercentric.git ~/kt-mcp-buyercentric
cd ~/kt-mcp-buyercentric
uv sync
```

Папка может быть любой, главное запомни абсолютный путь — он понадобится дальше.

---

## 2. Подключение к Claude Code (терминал)

В любой папке выполни:

```bash
claude mcp add keitaro -s user \
  -e "KEITARO_URL=https://tracker.example.com" \
  -e "KEITARO_API_KEY=<твой_ключ>" \
  -e "KEITARO_LOGIN=<твой_логин_как_в_keitaro>" \
  -e "KEITARO_BUYER_ID=<твой_buyer_id>" \
  -- uv --directory ~/kt-mcp-buyercentric run python -m keitaro_mcp
```

> Флаг `-s user` сохранит конфиг в `~/.claude.json` — он будет доступен из любой cwd.
> Если хочешь поднять только в конкретном проекте — замени на `-s project` и запусти команду из корня проекта (запишется в `<project>/.mcp.json`).

Проверь подключение:

```bash
claude mcp get keitaro
```

Ожидаемый вывод:
```
Status: ✓ Connected
```

**Перезапусти Claude Code** (если был запущен) — новые MCP-сервера подхватываются только при старте сессии. Теперь в чате можно писать естественным языком:

> Покажи мои кампании за последнюю неделю с группировкой по странам, сортировка по revenue

Claude сам вызовет нужный инструмент.

---

## 3. Подключение к Claude Desktop (приложение)

Открой config-файл:

**macOS:**
```bash
open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
```

**Windows:**
```cmd
notepad %APPDATA%\Claude\claude_desktop_config.json
```

**Linux:**
```bash
nano ~/.config/Claude/claude_desktop_config.json
```

Если файл пустой — вставь полностью:

```json
{
  "mcpServers": {
    "keitaro": {
      "command": "uv",
      "args": [
        "--directory", "/АБСОЛЮТНЫЙ/путь/к/kt-mcp-buyercentric",
        "run", "python", "-m", "keitaro_mcp"
      ],
      "env": {
        "KEITARO_URL": "https://tracker.example.com",
        "KEITARO_API_KEY": "<твой_ключ>",
        "KEITARO_LOGIN": "<твой_логин_как_в_keitaro>",
        "KEITARO_BUYER_ID": "<твой_buyer_id>"
      }
    }
  }
}
```

Если уже есть другие MCP-сервера — добавь блок `"keitaro": { ... }` внутрь существующего `mcpServers`.

> ⚠️ Путь должен быть **абсолютный**. `~` в JSON не раскрывается. На macOS обычно `/Users/<имя>/kt-mcp-buyercentric`.

**Сохрани файл и полностью выйди из Claude Desktop** (Cmd+Q на macOS / закрыть через трей на Windows). Запусти заново. В чате должны появиться `keitaro_*` инструменты.

---

## 4. Где хранятся твои креденшалы

| Клиент | Файл | Формат |
|---|---|---|
| Claude Code | `~/.claude.json` | plain JSON |
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` | plain JSON |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` | plain JSON |
| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` | plain JSON |

**Ключи лежат в открытом виде** на твоём диске. Никаких облаков, шифрования или Keychain. Файлы доступны только твоему системному пользователю (права 600/644). Если делишь компьютер с кем-то — учти.

В памяти процесса MCP api_key хранится только в одном объекте `KeitaroClient` и никогда не возвращается через `keitaro_list_instances` — наружу видны `name / url / login / buyer_id / description`.

---

## 5. Что MCP видит и не видит

✅ **Видит:**
- Клики и конверсии с `sub_id_3` равным твоему `buyer_id`
- Все стандартные метрики Keitaro: `clicks, conversions, revenue, profit, roi, cr, epc, cpc, cpa, leads, sales, bot_share` и др.
- Все дименшины: `campaign, offer, landing, country, device_type, browser, os, day, hour, sub_id_1..30` и др.

🚫 **Не видит / не может:**
- Данные других buyer-ов
- Конфигурацию трекера: список всех кампаний / офферов / лендингов / доменов / трафик-источников
- Создание / редактирование / удаление чего-либо

> Если попросишь "покажи все кампании трекера" — Claude вернёт ошибку. Спроси иначе: **"покажи мои кампании за неделю"** — он сделает отчёт с группировкой по `campaign`, и ты увидишь только те, где был твой трафик.

---

## 6. Troubleshooting

### `Status: ✗ Failed to connect`

Запусти сервер вручную в терминале и посмотри лог:

```bash
KEITARO_URL=https://... \
KEITARO_API_KEY=... \
KEITARO_LOGIN="..." \
KEITARO_BUYER_ID=... \
uv --directory ~/kt-mcp-buyercentric run python -m keitaro_mcp
```

Чтобы выйти — Ctrl+C.

Что искать в выводе:

| Сообщение | Что значит | Что делать |
|---|---|---|
| `Missing required env vars: ...` | пропущена переменная | проверь все 4 |
| `HTTP 401 ... Invalid API key` | ключ битый или истёк | взять у админа новый |
| `Login '...' not found among Keitaro users` | логин не совпал с тем что в трекере | проверь точное написание (пробелы, пайпы) |
| `api_key OK \| login NOT verified` | **это не ошибка** — у тебя user-level ключ, MCP не может строго сверить логин, но ключ работает | продолжай работать |
| `[<name>] login OK: <login> (USER/ADMIN)` | строгая проверка прошла, всё ок | продолжай работать |

### "uv: command not found"

uv не в PATH. На macOS добавь в `~/.zshrc`:
```bash
export PATH="$HOME/.local/bin:$PATH"
```
И перезапусти терминал.

### Claude Code не видит keitaro-тулы

Перезапусти сессию (`exit` → `claude` снова, или Ctrl+C если открыт интерактивный режим). MCP-сервера подхватываются только при старте.

### "Claude говорит что не может вызвать `keitaro_list_campaigns`"

By design. В buyer-edition доступны только 4 аналитических инструмента. Все запросы на конфиг трекера и CRUD блокируются. Если нужно «список кампаний» — спроси `"кампании по которым у меня шёл трафик"` — Claude использует `keitaro_build_report` с группировкой по `campaign`.

---

## 7. Несколько трекеров (опционально)

Если работаешь с двумя+ трекерами, замени env-vars на путь к JSON-файлу:

```bash
claude mcp add keitaro -s user \
  -e "KEITARO_CONFIG_FILE=$HOME/keitaro-instances.json" \
  -- uv --directory ~/kt-mcp-buyercentric run python -m keitaro_mcp
```

Файл `~/keitaro-instances.json`:

```json
[
  {
    "name": "main",
    "url": "https://main.tracker.com",
    "api_key": "...",
    "login": "...",
    "buyer_id": "...",
    "description": "Основной"
  },
  {
    "name": "test",
    "url": "https://test.tracker.com",
    "api_key": "...",
    "login": "...",
    "buyer_id": "...",
    "description": "Тестовый"
  }
]
```

В чате после этого можно явно указывать: *"отчёт из инстанса test за вчера"*.

---

## 8. Обновление

```bash
cd ~/kt-mcp-buyercentric
git pull
```

Перезапусти Claude Code/Desktop — он автоматически подхватит новый код. Переустанавливать ничего не надо.

---

## 9. Удаление

**Claude Code:**
```bash
claude mcp remove keitaro -s user
```

**Claude Desktop:** удали блок `"keitaro": { ... }` из `claude_desktop_config.json` и перезапусти приложение.

Папку `~/kt-mcp-buyercentric` можно потом просто стереть.
