secureFlows MCP Server

Облачный MCP-сервер, который оборачивает поверхность OpenAPI secureFlows, помеченную тегами ai-safe и ai-optional.

Этот репозиторий — публичное зеркало, публикуемое периодически из приватного монорепозитория secureFlows, где на самом деле ведётся разработка. Issues и PR приветствуются; крупные изменения могут сначала пройти цикл релиза в основном репозитории.

Что такое MCP-сервер?

MCP-сервер — это небольшой HTTP-сервис, который предоставляет набор «инструментов», которые ИИ-клиент может вызывать стандартным способом.

В этом репозитории:

• secureFlows MCP-сервер предоставляет инструменты, автоматически сгенерированные из ваших YAML-спецификаций OpenAPI.

• Когда клиент вызывает инструмент, MCP-сервер пересылает вызов на ваш реальный бэкенд secureFlows (connection.host) и возвращает ответ в нормализованном виде результата инструмента.

Это позволяет ИИ-клиенту:

• обнаруживать доступные операции secureFlows через listTools

• вызывать их через callTool

• без жёсткого кодирования поверхности API или ручной настройки аутентификации/заголовков

Что он делает

Два вида инструментов, зарегистрированных вместе в src/server.ts:

Сгенерированные инструменты (src/tools/build-tools.ts) — по одному на каждую операцию OpenAPI:

• Загружает:

  • docs/openapi/session/secure-flows-session-api.yaml

  • docs/openapi/user/secure-flows-user-api.yaml

  • docs/openapi/docs/secure-flows-docs-api.yaml

• Предоставляет только операции, помеченные ai-safe или ai-optional, как MCP-инструменты

• Пересылает запросы на указанный вызывающей стороной хост secureFlows — тонкая универсальная HTTP-обёртка без специфичной для secureFlows логики. Каждый из них требует действующий токен auth.*, поэтому они полезны только после того, как сессия уже существует (см. Модель выполнения ниже).

• Сопоставляет заголовки аутентификации secureFlows из входных данных MCP-инструмента:

  • auth.firebaseToken

  • auth.sessionToken

  • auth.userToken

Статические инструменты (src/tools/static-tools.ts) — написанные вручную, не сгенерированные из спецификации:

• secureflows_build_login_url / secureflows_build_logout_url — корректно строят URL для хостингового входа и перенаправления при выходе (всегда /app/sessions/login, никогда устаревший /app/login; отклоняют redirect_uri после выхода, указывающий на /callback или раскрывающий session_token). Токен secureFlows не требуется.

• secureflows_lint_integration — проверяет сгенерированный исходный код приложения на соответствие правилам интеграции и сообщает структурированные результаты вместо того, чтобы оставлять их в виде текста, который агент должен сам контролировать. Токен secureFlows не требуется. Два вида результатов:

  • scope: "file" — запрещённая конструкция присутствует в точном месте file:line: константы конфигурации из переменных окружения, токен в localStorage, устаревший /app/login, выход через fetch/XHR, декодирование JWT на клиенте, отзыв при выходе, пустой catch {}, восстановление setSession(null) при ошибках, не связанных с аутентификацией, CTA «Продолжить», ограниченный условием session === null, …

  • scope: "project" — требуемая обработка отсутствует во всех переданных файлах: обнаружение 401/410, но токен никогда не очищается, отсутствие обработки 403 или обработка 403 без исключения BILLING_GRACE_LOCK.

  Проверки отсутствия существуют, потому что шаблонные правила структурно не могли выявить класс дефектов, который доминирует в реальных сгенерированных приложениях. Измерено: в реальном приложении пробной версии, которое LLM-судья оценочного стенда оценил в 4/10 — ссылаясь на «устаревший токен, никогда не очищаемый при выходе», «необработанные варианты 403», «отсутствие обработки ошибок» — одни только шаблонные правила дали ноль результатов, потому что каждая из этих ошибок является отсутствием, а регулярное выражение может видеть только то, что присутствует. С проверками отсутствия он выдаёт 3 результата, включая ошибку уровня error об очистке токена. Оба вида проверок проверяются на каноническом стартовом шаблоне templates/web-app-secureflows, который должен оставаться с нулевым количеством результатов.

  Это всё ещё эвристический текстовый анализ, а не парсер или проверка типов: он пропускает то, для чего у него нет правила, проектная проверка может быть удовлетворена правильным ключевым словом в неправильном месте, и он не может покрыть проверки, требующие работающего приложения (гонки при монтировании auth-guard, проверка свежей перезагрузки). Быстрый первый проход — не замена чек-листу реализации агента в SKILL.md.

Эти статические инструменты существуют, потому что сгенерированные инструменты не могут помочь с частью интеграции, которая происходит до создания сессии — создание кода перенаправления/обратного вызова/жизненного цикла токена — а именно здесь происходит большинство ошибок интеграции secureFlows.

Использует транспорт MCP без сохранения состояния по HTTP, поэтому сервер не сохраняет конфигурацию тенанта или секреты.

Модель выполнения

Каждый вызов инструмента получает:

• connection.host: базовый URL secureFlows

• connection.workspaceName: необязательное рабочее пространство по умолчанию

• connection.appId: необязательный идентификатор приложения по умолчанию

• auth.*: токен, необходимый выбранной конечной точке

workspaceName и appId рассматриваются как стабильная конфигурация приложения. Сервер внедряет их в известные формы запросов secureFlows, если вызывающая сторона их не указала.

Для агентов (единственный поддерживаемый путь клиента)

Укажите MCP-клиенту хостинговый URL — тот же хост, что и у продукта, путь /mcp (не поддомен):

{
  "mcpServers": {
    "secureflows": {
      "url": "https://www.secure-flows.com/mcp"
    }
  }
}

Не говорите агентам запускать npx или использовать localhost — это разделяет историю и ломает тех, кто никогда не запускает локальный процесс. Встроено в веб-Docker-образ (Node на 127.0.0.1:8787, nginx location = /mcp; см. docs/ROUTING.md). Node-процесс устанавливает обработчики uncaughtException / unhandledRejection, чтобы один плохой запрос не завершал процесс; docker/entrypoint.sh также перезапускает MCP, если процесс всё же завершается.

Локальная разработка (мейнтейнеры этого пакета)

cd mcp-server
npm install
npm run build
npm test
npm run dev

Сервер по умолчанию запускается на http://0.0.0.0:8787 (POST /mcp, GET /health). Это для изменения самого MCP-сервера — а не путь, который должны настраивать агенты продукта.

Переменные окружения

• PORT: HTTP-порт, по умолчанию 8787 (в веб-контейнере entrypoint устанавливает PORT=8787 только для дочернего процесса MCP, чтобы nginx сохранял публичный $PORT Render)

• HOST: адрес привязки, по умолчанию 0.0.0.0 (веб-контейнер использует 127.0.0.1)

• ALLOWED_HOSTS: необязательный список разрешённых хостов через запятую для проверки заголовка Host MCP

• MCP_ALLOWED_HOSTS: переопределение ALLOWED_HOSTS в entrypoint при запуске процесса внутри образа

Конечные точки

• POST /mcp: конечная точка MCP Streamable HTTP

• GET /health: проверка здоровья (публично доступна как GET /mcp/health через nginx)

Встраивание secureFlows в приложение

Продуктовые приложения интегрируются напрямую с HTTP API secureFlows и хостинговым входом. Начните с:

• docs/integration/quickstart.md — подготовка (рабочее пространство + приложение) и хостинговый вход во время выполнения

• docs/integration/CONCEPT.md — базовый порядок: вход → создание рабочего пространства перед расширенными функциями

• docs/openapi/integration-auth.yaml — /app/sessions/login (приложения с сессиями) против /app/login (устаревший/консольный)

Продуктовые приложения по-прежнему интегрируются напрямую с указанными выше HTTP API, а не через этот сервер. Сгенерированные инструменты здесь предназначены для агентов/автоматизации, у которых уже есть токен (тестирование, скриптовая проверка). Статические инструменты (secureflows_build_login_url, secureflows_build_logout_url, secureflows_lint_integration) не требуют токена и предназначены для вызова кодирующим агентом, пока он ещё создаёт интеграцию — см. Что он делает выше.

Тестирование этого MCP-сервера

1. npm test в mcp-server/ — модульные тесты плюс HTTP-дымовой тест (test/http-smoke.test.ts): запускает Express-приложение на эфемерном порту, проверяет GET /health, GET /mcp → 405 и реальный клиент Streamable-HTTP listTools + callTool(secureflows_build_login_url).

2. После развёртывания: Playwright tests/smoke/mcp-health.spec.ts обращается к публичным GET /mcp/health и GET /mcp на целевом хосте (продакшн-дымовая задача).

3. Локальный цикл мейнтейнера: npm run dev, затем curl -sS http://127.0.0.1:8787/health.

4. Опционально: MCP-клиент против POST /mcp с connection.host + auth.* для сгенерированных инструментов.

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

Поставляется внутри веб-Docker-образа и проксируется на /mcp на www.secure-flows.com / стейджинге (см. Для агентов выше). Без отдельного поддомена.

npm-пакет secureflows-mcp-server — это то, как CI публикует версионированный артефакт (и как можно собрать автономный контейнер из mcp-server/Dockerfile); это не путь настройки для агентов. Публикация по тегам v*.*.* через .github/workflows/publish-secureflows-mcp-server.yml.

docker build -f mcp-server/Dockerfile -t secureflows-mcp-server .
docker run --rm -p 8787:8787 secureflows-mcp-server

Примечания

• Конечные точки хостингового входа / перенаправления доступны только в том случае, если они помечены ai-safe или ai-optional в спецификациях OpenAPI.

• Поиск по документации (get_docs_search) — ai-safe, не требует никакого auth.* — только connection.host и параметр запроса q.

• Консольные API только для людей-администраторов намеренно исключены.

• Полезная нагрузка ответа каждого инструмента включает:

  • status

  • ok

  • url

  • headers

  • data