Toss Place MCP

Спрашивайте Codex о продажах Toss Place POS в реальном времени, заказах, доступности позиций меню, столах, платежах и об остатках, отслеживаемых в POS.

Toss Place MCP — это открытая самостоятельно размещаемая интеграция. Небольшой плагин работает внутри Toss POS и безопасно синхронизирует читаемые данные POS с вашим бриджем. Codex подключается через стандартный локальный MCP-процесс или Streamable HTTP-эндпоинт бриджа.

[!IMPORTANT] Этот проект интегрирует Toss Place POS, а не Toss Payments. Toss Payments — это отдельный будущий провайдер с другими API и авторизацией.

О чём можно спрашивать

• «Сколько мы продали сегодня вечером, не считая открытых чеков?»

• «Какие напитки были самыми продаваемыми с 8 вечера до полуночи?»

• «Сравни эту пятницу с прошлой пятницей.»

• «Покажи почасовые продажи и скажи, когда нам стоит поставить ещё одного бармена.»

• «Какие товары закончились или их осталось меньше 10 единиц?»

• «Разбей платежи по картам, наличным и внешним оплатам.»

• «За какими столиками сейчас открыты чеки?»

• «Дай исходный заказ Toss, стоящий за этим номером.»

Сервер предоставляет как инструменты для работы с исходными данными POS, так и аналитику с заданной логикой. Открытые чеки всегда указываются отдельно от проведённых продаж.

Related MCP server: lightspeed-x

Как это работает

Toss POS plugin ──signed HTTPS──▶ self-hosted bridge + database
                                      │
                         ┌────────────┴────────────┐
                         ▼                         ▼
                 local stdio MCP          Streamable HTTP MCP
                         │                         │
                         └──────────▶ Codex ◀─────┘

Такое разделение важно, когда Toss POS работает на iPad или на стационарном компьютере магазина, а Codex — на другом компьютере. Docker — лишь удобный способ развернуть бридж; он не является частью протокола MCP и не обязателен для локальной разработки.

Текущий статус поддержки платформ

• Канал данных основан на SDK плагина Toss Place POS, успешно применённом в реальной настольной песочнице.

• Полный путь для настольной версии — активация мерчанта, установка POS, одноразовое сопряжение, первичная синхронизация и MCP-запросы по продажам и остаткам — проверен на тестовом мерчанте Toss в macOS.

• SDK заявляет поддержку платформ устройств Windows, macOS, Android и iOS. Этот проект ещё не проверял полный процесс установки на iPad-экземпляре Toss POS.

• Домены самостоятельно размещаемого бриджа обычно нужно добавлять в HTTP allowlist/ACL плагина разработчика Toss. Это основной ручной шаг онбординга; Toss Place в настоящее время не предоставляет эту интеграцию в виде обычного OAuth для мерчантов.

• Мерчант в настоящее время не может самостоятельно установить GitHub-репозиторий в Toss POS. Человек с требуемым доступом к порталу разработчика Toss должен создать/распространить worker-плагин, назначить терминал и мерчанта и ввести сервисный код на POS. После такой ручной установки Codex может провести сопряжение и настройку MCP.

• Данные о количестве на остатках доступны, только когда мерчант включил отслеживание запасов Toss для соответствующей позиции каталога. В противном случае MCP может сообщать только о доступности и статусе «распродано».

Требования

• Node.js 22 или новее

• Стабильный HTTPS URL, доступный с устройства Toss POS при использовании на разных устройствах

• Доступ для создания или установки плагина разработчика Toss Place

• Docker и Docker Compose — только если вы выберете развёртывание в контейнере

Быстрый старт

1. Клонирование и инициализация

git clone https://github.com/danyay/toss-place-mcp.git
cd toss-place-mcp
npm install
npm run build:all
node dist/cli.js init

Сгенерированный .env имеет режим доступа 0600 и игнорируется Git. Установите TOSS_MCP_PUBLIC_URL в стабильный HTTPS URL, доступный устройству POS.

2. Запуск бриджа

Локально:

npm run bridge

Или с помощью Docker:

docker compose up -d --build

Перед установкой плагина POS присвойте бриджу стабильное HTTPS-имя хоста. Рекомендуемый путь — Docker вместе с Caddy; за NAT полезен постоянный Cloudflare Tunnel. Инструкции по DNS, межсетевому экрану, Caddyfile, туннелю, проверке и перезапуску см. в docs/deployment.md. Не передавайте трафик сопряжения или POS по публичному незашифрованному HTTP.

3. Сборка и установка плагина Toss POS

npm run build:plugin
npm run zip --workspace plugin

Артефакт для загрузки — plugin/place-mcp-bridge.zip; внутри ZIP точка входа Toss находится в dist/main.js.

Этот раздел требует участия человека с доступом к порталу разработчика Toss. На портале разработчика Toss:

1. Создайте приложение worker-плагина POS с точкой входа POS_BACKGROUND_WORKER. Идентификатор пакета должен совпадать с загружаемым бандлом (place-mcp-bridge для этого репозитория).

2. Добавьте origin вашего бриджа, например https://toss-mcp.example.com, в HTTP ACL/allowlist приложения.

3. Загрузите plugin/place-mcp-bridge.zip на development/test-трек, затем распространите или разверните эту версию на тестовом треке. Только загрузки недостаточно.

4. Зарегистрируйте POS-терминал в настройках тестовых терминалов приложения. Используйте серийный номер, указанный в Toss POS, в разделе Настройки → Информация о POS/программном обеспечении.

5. Откройте Управление тестовыми мерчантами, выберите мерчанта, найдите Place MCP Bridge в таблице Приложения и переключите его в ВКЛ. Убедитесь, что Toss сообщает об успешном обновлении.

6. Полностью завершите работу Toss POS и перезапустите его.

7. В Toss POS откройте Настройки → Интеграция сервисов → Подключение по сервисному коду, введите сервисный код, показанный для приложения разработчика, и убедитесь, что Place MCP Bridge отображается как Используется.

Требуются и регистрация тестового терминала, и переключатель Application → ON для каждого мерчанта. Распознавание сервисного кода не означает, что worker авторизован для этого мерчанта. Включайте его только для мерчанта, владелец которого одобрил постоянное read-only подключение к данным.

Полный пошаговый чек-лист, ожидаемый результат после каждого этапа, диагностику сбоев и ограничения публичного онбординга мерчантов см. в docs/toss-developer-setup.md.

4. Сопряжение с POS

При запущенном бридже:

npm run pair

Введите отображаемый URL бриджа и одноразовый код в настройках плагина Toss POS. Код действует 15 минут и может быть использован один раз. Полученный секрет подключения хранится в защищённом хранилище Toss; запросы плагина содержат метку времени, защищены одноразовым nonce и подписаны HMAC.

Поля находятся в разделе Настройки → Интеграция сервисов → Place MCP Bridge. Сохраните их, затем полностью перезапустите Toss POS один раз, чтобы фоновый worker загрузился и выполнил первичную синхронизацию.

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

npm run doctor

При первом подключении ретроспективно загружаются заказы за 90 дней. Крупные мерчанты могут позже запросить другие диапазоны через MCP-инструмент refresh_pos_data.

5. Подключение Codex

Для локального MCP-сервера stdio:

codex mcp add toss-place \
  --env TOSS_MCP_BRIDGE_URL=http://127.0.0.1:8787 \
  --env TOSS_MCP_ACCESS_TOKEN=YOUR_LOCAL_ENV_TOKEN \
  -- npx -y toss-place-mcp mcp

Пока пакет не опубликован в npm, замените команду после -- на путь к собранному репозиторию:

node /absolute/path/to/toss-place-mcp/dist/cli.js mcp

Для удалённого Streamable HTTP добавьте это в ~/.codex/config.toml:

[mcp_servers.toss_place]
url = "https://toss-mcp.example.com/mcp"
bearer_token_env_var = "TOSS_MCP_ACCESS_TOKEN"
default_tools_approval_mode = "writes"

Затем экспортируйте TOSS_MCP_ACCESS_TOKEN в окружении, из которого запускается Codex. Клиенты Codex desktop, CLI и IDE на одном хосте совместно используют эту конфигурацию. См. официальную документацию Codex MCP.

Передайте этот репозиторий Codex

Вот как выглядит предполагаемый онбординг для неразработчиков:

Установите MCP-сервер Toss Place из этого репозитория. Не храните учётные данные в git. Разверните бридж локально или с помощью Docker, помогите мне назначить стабильный HTTPS URL, соберите ZIP-плагин Toss POS и остановитесь, когда мне нужно будет одобрить или выполнить действия на портале разработчика Toss. Создайте одноразовый код сопряжения, проверьте, что POS синхронизируется, добавьте MCP в мою конфигурацию Codex, затем покажите сегодняшние проведённые продажи отдельно от открытых чеков.

Codex может выполнить локальную установку и проверку. Человек всё равно должен выполнить шаги на портале/устройстве Toss, когда этого требует учётная запись.

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

MCP также публикует ресурсы toss-place://capabilities и toss-place://data-dictionary, а также промпт daily-sales-review.

Это не все вызываемые пространства имён в Toss Place SDK. Он охватывает только читаемые данные мерчанта, необходимые для типового анализа продаж, заказов, платежей, меню, столов и остатков. Состояние KDS, живые черновики заказов, управление устройством/интерфейсом и все мутации исключены из v1. Матрица покрытия SDK различает полную, частичную, внутреннюю и недодерживаемую поверхности.

Модель безопасности

Эта версия ориентирована в первую очердь на аналитику и является read-only. Базовый SDK Toss включат мутации заказов, платежей, кассовых чеков и черновиков заказов, но они намеренно не предоставляются как MCP-инструменты. Случайная отмена открытого чека недопустима как возможность по умолчанию для сервера анализа продаж.

• API бриджа и удалённый MCP требуют длинного bearer-токена.

• Запросы синхронизации POS используют HMAC-SHA256, метки времени и одноразовые nonce.

• Коды сопряжения хэшируются, действуют недолго и являются одноразовыми.

• Секреты исключены с помощью .gitignore; примеры содержат только заполнители.

• Бридж по умолчанию привязывается к 127.0.0.1.

• Журналы намеренно не содержат токены доступа и секреты плагина.

Прочтите SECURITY.md, прежде чем открывать доступ к бриджу из интернета.

Данные и метрики

Границы суток по умолчанию задаются часовым поясом Asia/Seoul. «Проведённые продажи» — это сумма Toss chargePrice.chargePriceValue по завершённым, не отменённым заказам. Текущие чеки за столиками показываются отдельно, даже если чек был открыт до запрошенного диапазона продаж; они никогда не учитываются как проведённые продажи. Исходные знаковые поля скидок сохраняются, поскольку возвраты и сторнирования могут влиять на их знак.

См. docs/api-coverage.md и docs/architecture.md.

База данных

По умолчанию используется SQLite:

TOSS_MCP_DATABASE_URL=sqlite:./data/toss-place.sqlite

PostgreSQL использует тот же репозиторий:

TOSS_MCP_DATABASE_URL=postgresql://user:password@localhost:5432/toss_mcp

База данных содержит данные о продажах мерчанта и секреты подключения для шифрованного транспорта. Защищайте её как другие производственные данные POS и создавайте резервные копии в соответствии с собственной политикой хранения.

Разработка

npm install
npm run check
npm run build:all

Тесты используют синтетические фикстуры. Боевые учётные данные для интеграции должны передаваться только через игнорируемые переменные окружения и никогда не требуются для обычного набора тестов.

Тестовое приложение песочницы macOS и все локальные данные POS исключены из Git. Никогда не копируйте в коммит URL бриджа мерчанта, токен доступа, код сопряжения, базу данных или пакет приложения Toss POS.

План развития

• Проверить и задокументировать развёртывание на iPad у реального мерчанта

• Онбординг плагина, проверенный/опубликованный Toss, если платформа это допускает

• Настраиваемое хранение и инкрементальные контрольные точки длительной ретроспективной загрузки

• Интеграционное тестирование PostgreSQL в CI

• Опциональный OAuth для удалённого MCP-эндпоинта

• Отдельный провайдер Toss Payments

• Осторожно ограниченные операционные инструменты — только после появления явной модели одобрения и аудита

Лицензия и товарные знаки

MIT. Toss и Toss Place являются товарными знаками соответствующих владельцев. Этот проект сообщества не связан с Toss и не одобрен им, если не указано иное.

Toss Place MCP

Codex можно спрашивать о продажах Toss Place POS в реальном времени, заказах, доступности блюд в меню, столах, платежах и об остатках, отслеживаемых в POS.

Toss Place MCP — это инструмент интеграции с открытым исходным кодом, размещаемый самостоятельно. Небольшой плагин запускается внутри Toss POS и безопасно синхронизирует доступные для чтения данные POS с вашим бриджем. Codex подключается через стандартный локальный MCP-процесс или Streamable HTTP-эндпоинт бриджа.

[!IMPORTANT] Этот проект интегрирует Toss Place POS, а не Toss Payments. Toss Payments — это отдельный будущий провайдер с другими API и методом авторизации.

О чём можно спрашивать

• «Сколько составит выручка за сегодняшний вечер без учёта неоплаченных заказов?»

• «Какой алкоголь продавался лучше всего с 20:00 до полуночи?»

• «Сравни эту пятницу с прошлой пятницей.»

• «Покажи выручку по часам и подскажи, когда нужно поставить ещё одного бармена.»

• «Какие товары распроданы или осталось меньше 10 единиц?»

• «Покажи разбивку по картам, наличным и внешним платежам.»

• «За какими столами сейчас числятся неоплаченные заказы?»

• «Покажи исходные заказы Toss, на основе которых получены эти цифры.»

Сервер предоставляет как низкоуровневые инструменты POS, так и аналитические инструменты с чёткими критериями. Текущие неоплаченные заказы всегда сообщаются отдельно от подтверждённой выручки.

Как это работает

Toss POS 플러그인 ──서명된 HTTPS──▶ 셀프 호스팅 브리지 + 데이터베이스
                                            │
                              ┌─────────────┴─────────────┐
                              ▼                           ▼
                       로컬 stdio MCP             Streamable HTTP MCP
                              │                           │
                              └──────────▶ Codex ◀────────┘

Toss POS может работать на iPad или настольном компьютере заведения, а Codex — на другом компьютере, поэтому такое разделение важно. Docker — это лишь удобный способ развернуть мост, он не является частью протокола MCP и не обязателен для локальной разработки.

Текущее состояние платформы

• Путь данных реализован на основе плагинного SDK Toss Place POS, который успешно интегрирован с реальной песочницей для настольных компьютеров.

• Полный путь для настольных компьютеров — активация мерчанта, установка POS, одноразовое сопряжение, первичная синхронизация, MCP-запросы выручки/остатков — проверен на тестовом мерчанте Toss в macOS.

• SDK объявляет платформы Windows, macOS, Android и iOS. В этом проекте полный процесс установки на iPad Toss POS ещё не проверен.

• Как правило, в HTTP-список разрешённых/ACL плагина разработчика Toss нужно добавить домен самостоятельно размещённого моста. Это самый важный ручной шаг онбординга; Toss Place сейчас не предоставляет эту интеграцию через обычный OAuth для мерчантов.

• Сейчас мерчант не может установить Toss POS напрямую только из GitHub-репозитория. Тот, у кого есть необходимые права в портале разработчика Toss, должен создать/развернуть фоновый плагин, назначить терминалы и мерчанта, а затем ввести код услуги в POS. После завершения установки человеком Codex может провести сопряжение и настройку MCP.

• Остатки предоставляются только в том случае, если мерчант включил отслеживание остатков Toss для соответствующих позиций каталога. В противном случае MCP может сообщать только о доступности к продаже и статусе «распродано».

Требования

• Node.js 22 или новее

• Стабильный HTTPS URL, доступный с устройства Toss POS, если POS и мост находятся на разных машинах

• Права на создание/установку плагина разработчика Toss Place

• Docker и Docker Compose только в случае выбора контейнерного развёртывания

Быстрый старт

1. Клонирование и инициализация

git clone https://github.com/danyay/toss-place-mcp.git
cd toss-place-mcp
npm install
npm run build:all
node dist/cli.js init

Созданный .env имеет режим доступа 0600 и игнорируется Git. Установите TOSS_MCP_PUBLIC_URL в стабильный HTTPS URL, доступный с устройства POS.

2. Запуск моста

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

npm run bridge

Запуск через Docker:

docker compose up -d --build

Перед установкой плагина POS укажите мосту стабильное HTTPS-имя хоста. Рекомендуется связка Docker и Caddy; за NAT удобен постоянный Cloudflare Tunnel. Следуйте docs/deployment.md по DNS, файрволу, Caddyfile, туннелю, проверке и перезапуску. Не передавайте сопряжение или трафик POS через публичный обычный HTTP.

3. Сборка и установка плагина Toss POS

npm run build:plugin
npm run zip --workspace plugin

Загружаемый файл — plugin/place-mcp-bridge.zip, точка входа Toss внутри ZIP — dist/main.js.

Этот шаг должен выполнять человек с правами в портале разработчика Toss. На портале разработчика Toss:

1. Создайте приложение-плагин POS worker с точкой входа POS_BACKGROUND_WORKER. Идентификатор пакета должен совпадать с загружаемым бандлом. В этом репозитории это place-mcp-bridge.

2. Добавьте origin моста, например https://toss-mcp.example.com, в HTTP ACL/список разрешённых приложения.

3. Загрузите plugin/place-mcp-bridge.zip в трек разработки/тестирования, затем разверните эту версию в тестовый трек. Только загрузки недостаточно.

4. Зарегистрируйте POS-терминал в настройках тестового термінала приложения. Используйте серийный номер, отображаемый в Toss POS в разделе Настройки → Информация о POS/ПО.

5. Откройте Управление тестовыми мерчантами, выберите мерчанта, затем в таблице Приложения найдите Place MCP Bridge и переключите в ON. Убедитесь, что Toss показывает, что изменение успешно.

6. Полностью закройте Toss POS и запустите его снова.

7. В Toss POS откройте Настройки → Интеграция услуг → Подключение по коду услуги, введите код услуги из приложения разработчика и убедитесь, что Place MCP Bridge отображается как Используется.

Нужны и регистрация тестового терминала, и переключатель Приложения → ON для мерчанта. Распознавание кода услуги не означaет, что worker одобрен для этого мерчанта. Включайте постоянное read-only подключение к данным только с согласия владельца мерчанта.

Полний пошаговый чек-лист, ожидаемые результаты на каждом шаге, диагностику неполадок и ограничения онбординга обычных мерчантов см. в docs/toss-developer-setup.md.

4. Сопряжение POS

При запущенном мосте выполните:

npm run pair

Введите отображаемый URL моста и одноразовый код в настройки плагина Toss POS. Код истекает через 15 минут и может быть использован только один раз. Созданный секретный ключ соединения хранится в защищённом хранилище Toss. Запросы плагина содержат метку времени и nonce для защиты от повтора и подписаны HMAC.

Поля ввода находятся в разделе Настройки → Интеграция услуг → Place MCP Bridge. После сохранеия полностью перезапустите Toss POS один раз, чтобы фоновый worker загрузился и выполнил первичную синхронизацию.

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

npm run doctor

Первичное подключение обратным заполнением подтягивает заказы за период до 90 дней. Крупные мерчанты позже могут запросить другой период с помощью MCP-инструмента refresh_pos_data.

5. Подключение Codex

Локальный stdio MCP-сервер:

codex mcp add toss-place \
  --env TOSS_MCP_BRIDGE_URL=http://127.0.0.1:8787 \
  --env TOSS_MCP_ACCESS_TOKEN=YOUR_LOCAL_ENV_TOKEN \
  -- npx -y toss-place-mcp mcp

Пока пакет не опубликован в npm, замените команду после -- на путь к собранному репозиторию.

node /absolute/path/to/toss-place-mcp/dist/cli.js mcp

Для удалённого Streamable HTTP добавьте в ~/.codex/config.toml:

[mcp_servers.toss_place]
url = "https://toss-mcp.example.com/mcp"
bearer_token_env_var = "TOSS_MCP_ACCESS_TOKEN"
default_tools_approval_mode = "writes"

Затем экспортируйте TOSS_MCP_ACCESS_TOKEN в окружение, где запускается Codex. Настольный клиент Codex, CLI и IDE-клиенты на одном хосте используют эту настройку совместно. См. официальную документацию Codex MCP.

Поручение этого репозитория Codex

Ниже — способ онбординга, предназначенный для нетехнических пользователей.

«Установи MCP-сервер Toss Place из этого репозитория. Не включай учётные данные в Git. Разверни мост локально или в Docker, помоги указать стабильный HTTPS URL и собери ZIP-плагин Toss POS. Останавливайся на шагах, которые требуют моего одобрения или ручных действий в портале разработчика Toss. Сгенерируй одноразовый код сопряжения, проверь, что POS синхронизируется, и добавь MCP в мою конфигурацию Codex. В конце покажи отдельно подтверждённую выручку за сегодня и текущие неоплаченные заказы.»

Codex может выполнить локальную установку и проверку. Шаги с порталом Toss и оборудованием, требуемые от аккаунта, человек должен выполнить самостоятельно.

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

MCP также предоставляет ресурсы toss-place://capabilties, toss-place://data-dictionary и промпт daily-sales-review.

Этот проект не предоставляет все пространства имён, которые можно вызвать в Toss Place SDK. Он поддерживает read-only данные мерчанта, необходимые для типового анализа выручки, заказов, платежей, меню, столов и остатков. Статусы KDS, реальные временные заказы, управление оборудованием/интерфейсом и все операции изменения данных в v1 исключены. В таблице покрытия SDK разграничены полностью поддерживаемые, частично поддерживаемые, внутренние и неподдерживаемые поверхности.

Модель безопасности

Этота версия — read-only сервис с приоритетом аналитики. В Toss SDK есть функци изменения заказов, платежей, чеков и временных заказов, но они намеренно не предоставляются в качестве MCP-инструментов. Сервер аналитики выручки не должен случайно отменить реальный неоплаченный заказ.

• Bridge API и удалённый MCP требуют длиный Bearer-токен.

• Запросы синхронизации POS используют HMAC-SHA256, метку времени и одноразовый nonce.

• Коды сопряжения хранятся в хешированном виде, живут недолго и могут быть использованы только один раз.

• Секреты исключаются через .gitingore; в примерах только плейсхолдеры.

• Мост по умолчанию привязывается к 127.0.0.1.

• Журналы намеренно не записывают токены доступа или секретные ключи плагина.

Прежде чем открывать мост в интернет, прочтите SECURITY.md.

Данные и метрики

Граница суток по умолчанию использует часовой пояс Asia/Seoul. «Подтверждённая выручка» — это сумма Toss chargePrice.chargePriceValue по завершённым и не отменённым заказам. Текущие заказы за столами показываются отдельно и не включаются в подтверждённую выручку, даже если начались раньше запрошенного периода выручки. Мы сохраняем знак исходных полей скидок, поскольку возвраты и отмены могут влиять на знак.

См. docs/api-coverge.md и docs/architectore.md.

База данных

База данных по умолчанию — SQLite.

TOSS_MCP_DATABASE_URL=sqlite:./data/toss-place.sqlite

PostgreSQL также доступен в этом же репозитории.

TOSS_MCP_DATABASE_URL=postgresql://user:password@localhost:5432/toss_mcp

В баже данных хранятся данные о выручке мерчанта и зашифрованные секретные ключи транспортного соединения. Защищайте её так же, как другие операционные данные POS, и делайте резервные копии в соответствии с собственной политикой хранения.

Разработка

npm install
npm run check
npm run build:all

Тесты используют синтетические фикстуры. Реальные интеграционные учётные данные должны передаваться только через переменные окружения, игнорируемые Git, и не требуются для обычного набора тестов.

Тестовое приложение песочницы macOS и все локальные данные POS исключены из Git. Не копируйте в коммиты URL моста мерчанта, токены доступа, коды сопряжения, базы данных или бандлы приложения Toss POS.

Дорожная карта

• Проверка и документирование развёртывания на iPad у реального мерчанта

• Онбординг через проверенный/публичный плагин Toss, если платформа позволяет

• Настраиваемый срок хранения и инкрементальные контрольные точки длительного обратного заполнения

• Интеграционные тесты PostgreSQL в CI

• Опциональный OAuth для удалённой MCP-точки

• Отдельный провайдер Toss Payments

• Аккуратно ограниченные операционные инструменты — только после явной модели одобрений и аудита

Лицензия и товарные знаки

Лицензия MIT. Toss и Toss Place — товарные знаки соответствующих владельцев. Если не указано иное, этот общественный проект не аффилирован с Toss и не получает одобрения Toss.