Ops Lense

Ops Lense — это удаленно размещенный сервер Model Context Protocol (MCP) для операций электронной коммерции. Он помогает специалисту по операциям расследовать зависшие заказы, понять, что пошло не так, и выполнить следующее безопасное действие без необходимости привлекать инженера для каждого инцидента.

Данное задание намеренно фокусируется на одном рабочем процессе в глубину: расследование и исправление зависших заказов по заказам, платежам, запасам и выполнению.

Что он демонстрирует

Оператор может задать AI-клиенту с поддержкой MCP вопросы, такие как:

Почему этот оплаченный заказ все еще завис?

AI может использовать Ops Lense, чтобы:

1. найти заказ;

2. изучить его операционную временную шкалу;

3. диагностировать вероятный сбой на основе данных бэкенда;

4. определить, насколько безопасно можно выполнить предлагаемое действие;

5. предварительно просмотреть и выполнить ограниченное исправление после подтверждения оператора; или

6. отправить действие высокого риска в очередь ручной проверки вместо его выполнения.

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

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

Не все операции электронной коммерции должны иметь одинаковый уровень автономии AI. Ops Lense разделяет действия на три категории.

Процесс подтверждения

resync_inventory_reservation — это защищенная операция записи.

Первый вызов:

confirmed=false

Сервер проверяет заказ и возвращает предполагаемый эффект без изменения базы данных.

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

confirmed=true

Затем сервер выполняет ограниченную мутацию и записывает запись аудита.

Процесс ручной проверки

Критические действия намеренно недоступны как прямые мутации MCP. request_manual_review создает запись аудита pending_review вместо этого.

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

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

Ресурс MCP

Ops Lense предоставляет один операционный ресурс:

ops://action-policy

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

Я выбрал ресурс вместо подсказки MCP, потому что это стабильная операционная политика, которая должна быть доступна независимо от того, как пользователь формулирует свой запрос. Выделенная подсказка добавила бы мало ценности этому намеренно узкому рабочему процессу.

Пример сквозного рабочего процесса

Типичный инцидент — заказ, в котором платеж был успешно захвачен, но этап резервирования запасов отсутствует.

1. Оператор спрашивает, почему заказ завис.

2. AI использует search_orders, если ему нужно найти заказ.

3. Он вызывает get_order_timeline, чтобы проверить, что произошло.

4. Он вызывает diagnose_order, чтобы сопоставить платеж и операционное состояние.

5. Диагностика определяет INVENTORY_RESERVATION_MISSING и рекомендует resync_inventory_reservation.

6. AI вызывает инструмент с confirmed=false и показывает предлагаемое исправление оператору.

7. Оператор одобряет его.

8. AI снова вызывает инструмент с confirmed=true.

9. MCP выполняет исправление и записывает запись аудита.

10. AI снова вызывает get_order_timeline, чтобы проверить итоговое состояние.

Запрос высокого риска следует по другому пути. Например, если оператор запрашивает возврат средств, MCP создает запрос на ручную проверку, а не изменяет состояние платежа. Затем запрос можно проверить с помощью list_manual_reviews.

Это дает демо одну связную историю, охватывающую расследование → диагностику → подтверждение человеком → мутацию → проверку → эскалацию.

Архитектура

MCP-enabled AI client
        |
        | Streamable HTTP
        v
   Ops Lense MCP
        |
        +-- Investigation tools
        +-- Diagnostic logic
        +-- Safety / action policy
        +-- Guarded actions
        |
        v
   Neon PostgreSQL
   synthetic commerce data

Технологии:

• TypeScript

• Bun для локальной разработки и скриптов

• Node.js 24 на Heroku

• Пакеты сервера Model Context Protocol

• Транспорт Express HTTP

• Neon PostgreSQL

• Проверка входных данных Zod

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

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

Предварительные требования

Вам понадобятся:

• Bun

• база данных PostgreSQL; Neon хорошо подходит для размещенного демо

1. Установка зависимостей

bun install

2. Настройка переменных окружения

Создайте файл .env в корне проекта:

DATABASE_URL=postgresql://YOUR_DATABASE_URL
MCP_AUTH_TOKEN=YOUR_STRONG_RANDOM_TOKEN
PORT=3000

3. Создание синтетической базы данных

bun scripts/setup-db.ts

Эта команда удаляет и заново создает таблицы задания. Не запускайте ее для базы данных, содержащей данные, которые вам нужно сохранить.

4. Загрузка демо-данных

bun scripts/seed-db.ts

Все загруженные записи клиентов, заказов, платежей, запасов и выполнения являются синтетическими.

5. Сборка и запуск сервера MCP

bun run build
bun run start

bun run build компилирует TypeScript в dist/. Затем команда запуска запускает скомпилированный сервер с Node, соответствующий пути выполнения Heroku.

Локальная конечная точка MCP:

http://localhost:3000/mcp

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

Репозиторий содержит Procfile, который запускает веб-динозавр с npm start. Heroku собирает проект TypeScript и запускает скомпилированный сервер Node.js.

1. Создание приложения Heroku

heroku create YOUR_APP_NAME

2. Настройка базы данных

Установите строку подключения PostgreSQL и надежный маркер носителя, используемый для защиты конечной точки MCP:

heroku config:set DATABASE_URL="YOUR_DATABASE_URL" MCP_AUTH_TOKEN="YOUR_STRONG_RANDOM_TOKEN" -a YOUR_APP_NAME

Heroku предоставляет PORT автоматически, поэтому вам не нужно настраивать его вручную.

3. Развертывание

git push heroku HEAD:main

Во время развертывания Heroku устанавливает зависимости Node и запускает скрипт build. Затем запускается веб-динозавр:

node dist/index.js

Размещенная конечная точка MCP будет:

https://YOUR_APP_NAME.herokuapp.com/mcp

Если ваше приложение Heroku использует пользовательский домен, используйте этот домен с /mcp.

4. Проверка развертывания

heroku logs --tail -a YOUR_APP_NAME

Вы должны увидеть, как сервер MCP запускается и привязывается к назначенному порту Heroku.

Синтетическую базу данных можно инициализировать перед развертыванием с вашей локальной машины, используя ту же DATABASE_URL, или запустив сценарии установки и заполнения как одноразовые команды Heroku, если Bun доступен в этой среде. Для самого простого пути развертывания инициализируйте и заполните Neon локально перед развертыванием сервера.

Подключение от AI-клиента

Ops Lense использует удаленную конечную точку HTTP MCP. В клиенте MCP, поддерживающем удаленные/потоковые HTTP-серверы, добавьте конечную точку и маркер носителя:

{
  "serverUrl": "http://localhost:3000/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_STRONG_RANDOM_TOKEN"
  }
}

Для развернутого экземпляра замените локальный URL на размещенный URL MCP и используйте тот же маркер, который настроен как MCP_AUTH_TOKEN на сервере.

После подключения клиент должен автоматически обнаружить инструменты и ресурс ops://action-policy.

Затем вы можете начать естественно, например:

Show me recent orders that may need attention.

Why is this order stuck? Investigate it and tell me what we can safely do.

Show me all actions currently waiting for manual review.

Для операций, требующих подтверждения, AI должен представить предварительный просмотр оператору и получить явное одобрение перед выполнением второго вызова инструмента с confirmed=true.

Подключение с помощью MCP Inspector

MCP Inspector полезен для тестирования сервера независимо от чат-клиента.

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

npx @modelcontextprotocol/inspector

В Inspector подключитесь к:

http://localhost:3000/mcp

Затем вы можете проверить обнаруженные инструменты/ресурс и вызвать рабочий процесс вручную.

Проверка

Проверьте типы проекта с помощью:

npm run typecheck

Запустите целенаправленный набор интеграционных тестов Vitest для настроенной синтетической базы данных:

npm test

Тесты в tests/operations.test.ts создают изолированные временные записи, выполняют реальные функции инструментов для PostgreSQL и удаляют эти записи после завершения. Они проверяют:

• захваченный платеж с отсутствующим резервированием приводит к INVENTORY_RESERVATION_MISSING;

• терминальные заказы не диагностируются как активные сбои запасов;

• confirmed=false не выполняет мутации;

• confirmed=true выполняет ограниченное исправление запасов и записывает запись аудита;

• повторение уже завершенной повторной синхронизации является безопасным холостым действием;

• запрос на возврат средств ставится в очередь на проверку без изменения состояния платежа;

• дублирующиеся запросы на ожидающую проверку подавляются.

Набор в настоящее время содержит 8 интеграционных тестов. Успешный запуск сообщает 8 passed.

Эти тесты намеренно сфокусированы на рабочем процессе и границах безопасности, а не на широких показателях охвата.

Ключевые продуктовые решения

Сохраняйте рабочий процесс узким

Задание не пытается создать полный бэкенд электронной коммерции. Операции с зависшими заказами были выбраны, потому что они предоставляют компактный рабочий процесс, включающий несколько систем, диагностику, исправление, безопасность и проверку.

Дайте AI полезную автономию, а не неограниченный доступ на запись

Если сделать каждую операцию только для чтения, оператор будет зависеть от другой системы для решения даже простых инцидентов. Разрешение всех мутаций создало бы ненужный операционный риск.

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

Критические действия не должны выполняться через MCP

Возвраты и аналогичные операции технически могут быть представлены как мутации базы данных в этом синтетическом проекте, но это демонстрировало бы неправильное производственное поведение. Вместо этого MCP создает запрос на проверку и делает границу явной.

Поддерживайте небольшую поверхность MCP

Каждый открытый инструмент имеет четкую роль в выбранном рабочем процессе. Цель состоит в том, чтобы AI-клиент надежно выбирал инструменты, а не в максимизации количества доступных инструментов.

Объем и допущения

Включено:

• синтетические данные электронной коммерции

• расследование заказов

• детерминированная диагностика поддерживаемого условия зависшего заказа

• защищенное исправление запасов

• ведение журнала аудита

• очередь ручной проверки

• удаленно доступный интерфейс MCP

Намеренно исключено:

• интерфейс/панель администратора

• реальные данные клиентов

• производственные платежные или складские учетные данные

• учетные записи пользователей, сессии, OAuth и управление доступом на основе ролей

• прямое выполнение возврата

• интерфейс одобрения/выполнения ручной проверки

• полный бэкенд электронной коммерции

• широкие рабочие процессы возвратов, мошенничества, каталога и поддержки клиентов

Сервер заданий, размещённый на хостинге, использует единый bearer-токен, чтобы не раскрывать MCP публично. Для производственной системы потребовалось бы добавить аутентификацию с учётом личности, авторизацию/RBAC, ротацию секретов, более строгий контроль параллелизма, интеграции с конкретными провайдерами, наблюдаемость и полный процесс рецензирования.

Структура репозитория

src/
  index.ts
  db.ts
  resources.ts
  tools/
    diagnose-order.ts
    get-stats.ts
    get-timeline.ts
    list-manual-reviews.ts
    request-manual-review.ts
    resync-inventory.ts
    search-orders.ts
scripts/
  setup-db.ts
  seed-db.ts
tests/
  operations.test.ts
vitest.config.ts

Журнал работы ИИ

Этот раздел должен содержать фактическое использование ИИ из задания до сдачи:

• Инструменты для написания кода с ИИ и точные использованные модели

• Почему каждая модель была выбрана для своей задачи

• Как работа была спланирована и декомпозирована

• Обязанности, взятые на себя ИИ по сравнению с разработчиком

• Важные промпты/контекст, предоставленные ИИ

• Как минимум одно предложение ИИ, которое было отклонено или существенно изменено

• Как код, созданный ИИ, проверялся и верифицировался

• Оставшиеся риски или незавершённая работа

Одно из продуктовых решений, которое изменилось в ходе разработки, — это обработка важных операций. Вместо того чтобы выставлять возвраты средств и аналогичные критические действия как исполняемые инструменты MCP, они были перемещены в очередь ручного рецензирования. Это сохраняет полезную автономию ИИ, оставляя финансово или операционно значимые решения за пределами прямого выполнения моделью.

Сдача

Финальная сдача должна включать:

• URL размещённого MCP

• URL репозитория исходного кода

• этот README

• проверки/тесты для важного поведения рабочего процесса

• заполненный журнал работы ИИ

• асинхронную демонстрацию на 4–5 минут

Демонстрация должна отдавать приоритет фактическому рабочему процессу продукта, а не обзору кода: исследовать заказ, диагностировать его, предпросмотреть безопасное исправление, подтвердить его, проверить результат, а затем показать, как критическое действие направляется на ручное рецензирование.