# Tokopedia Personal MCP

Локальный MCP для работы с загруженными данными покупателя Tokopedia:
заказами, доставками, платежами, перепиской и товарами.

## Возможности

- Импорт структурированных снимков заказов, доставок, платежей, чатов и товаров.
- Поиск по загруженным данным с фильтрами и пагинацией.
- История изменений каждой записи.
- Подготовка черновиков сообщений продавцам.
- Подготовка планов покупок с расчётом стоимости товаров и сравнением с бюджетом.

Суммы хранятся в целых индонезийских рупиях (IDR). Каждая запись содержит время
наблюдения `observedAt`; результаты чтения имеют `provenance: manual_import`.
Черновики возвращаются со статусом `DRAFT_NOT_SENT`, планы — `PLAN_NOT_ORDERED`.

## Установка

Нужен Node.js >=24.

```sh
git clone https://github.com/alexfisenkov/tokopedia-personal-mcp.git
cd tokopedia-personal-mcp
npm ci --ignore-scripts
npm run build
```

Регистрация в Codex из каталога проекта:

```sh
codex mcp add tokopedia_personal -- "$(command -v node)" "$PWD/dist/index.js"
codex mcp get tokopedia_personal
```

После регистрации откройте новый чат, чтобы использовать инструменты.

## Инструменты

| Инструмент | Назначение |
|---|---|
| `status` | Состояние сервера и загруженного набора данных |
| `import_records` | Импорт структурированных снимков |
| `list_orders` | Поиск и фильтрация заказов |
| `get_order` | Чтение заказа по ID |
| `list_shipments` | Поиск доставок, в том числе по ID заказа |
| `list_transactions` | Поиск платежей и возвратов |
| `list_chats` | Поиск переписки |
| `get_chat` | Чтение загруженного диалога |
| `search_products` | Поиск загруженных товаров |
| `record_history` | История версий записи |
| `prepare_message` | Подготовка черновика сообщения |
| `prepare_purchase` | Расчёт плана покупки и сравнение с бюджетом |

## Импорт

Передайте `import_records` объект с массивом `records`.
[Полный синтетический пример](examples/synthetic.json) включает все пять типов.

```json
{
  "records": [
    {
      "kind": "order",
      "id": "example-order",
      "observedAt": "2026-10-01T08:00:00Z",
      "status": "Dikirim",
      "totalIdr": 50000,
      "items": [{ "title": "Example USB cable", "quantity": 2, "unitPriceIdr": 25000 }]
    }
  ]
}
```

Один импорт принимает до 100 записей и 2 MiB. Весь пакет записывается атомарно.
Повтор того же снимка идемпотентен. Новые версии сохраняются с историей;
старые и конфликтующие снимки отклоняются. Схемы находятся в [src/domain.ts](src/domain.ts).
Каждая запись — полный снимок сущности: массивы сообщений и событий доставки
содержат её состояние на `observedAt`. Новая версия заменяет текущий снимок,
а предыдущие версии доступны через `record_history`.
Хранилище проверяет сохранение уже известных сообщений и событий доставки.

## Хранение

База: `~/.local/share/tokopedia-personal-mcp/records.sqlite`.
Переменная `TOKOPEDIA_DB_PATH` задаёт другой абсолютный путь в выделенном
приватном каталоге. Каталог имеет права 0700, файл базы — 0600.

## Проверка

```sh
npm run check
npm test
npm run build
npm run smoke
```

Smoke-проверка запускает MCP-клиент по stdio и проверяет все 12 инструментов
на синтетических данных во временной базе.

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

Исходники и дальнейшие изменения ведутся в этом репозитории.
Карта слоёв — [docs/АРХИТЕКТУРА.md](docs/АРХИТЕКТУРА.md).

[MIT License](LICENSE).