Машинний переклад, не перевірений носієм мови. Еталоном є англійська версія.

API та інтеграціїРедагувати на GitHubДжерело: docs/deploy/mcp-http.md

Запуск kshana-mcp через HTTP (самостійне розміщення)

Фрагмент, що називає сторонніх клієнтів ШІ, тут пропущено; він є в docs/deploy/mcp-http.md на GitHub.

Kshana не розміщує жодної кінцевої точки. Немає спільного сервера kshana, на який можна спрямувати клієнт. Ви запускаєте його на власній машині, в контейнері чи хмарному проєкті та самі відповідаєте за контроль доступу й вартість. Сервер 0.40.0 — це той, що в цьому репозиторії: його показники мають позначки VALIDATED або MODELLED точно так само, як через stdio.

Безпечні типові налаштування#

Засіб контролю Поведінка
Адреса прив'язки Лише loopback (127.0.0.1, ::1). Голий порт (--http 8080) означає 127.0.0.1:8080.
Non-loopback Потрібні --allow-remote і токен-носій у змінній середовища KSHANA_MCP_HTTP_TOKEN (16 символів або більше). Без обох сервер відмовляється запускатися. З обома він виводить попередження, що слухає поза межами цієї машини.
Автентифікація Authorization: Bearer <token> у кожному запиті, коли задано токен (його можна задати й на loopback). Порівнюється за сталий час. Відсутній або хибний: 401.
Файлова система Нічого. Інструменти файлів IQ (iq_*) вимкнені в режимі HTTP що б не казало KSHANA_MCP_IQ_DIR; кожен інший інструмент приймає свій сценарій у тілі та відхиляє той, що називає файл. Жоден аргумент інструмента не читає й не записує шлях.
Розмір тіла --max-body-bytes, типово 5 MiB (обмеження сценарію — 4 MiB). Понад це: 413, чи то довжину оголошено, чи тіло передається частинами.
Час відповіді --request-timeout-secs, типово 120. Понад це: 408. Це обмежує, як довго чекає викликач, а не роботу: прогін, що вже триває, не можна зупинити, тож він іде далі після 408 і завершується у фоні.
Паралелізм --max-concurrent, типово 8. Понад це запит одразу отримує 503 із Retry-After; жоден не стає в чергу.
Пул роботи Кожен виклик інструмента виконується в блокувальному потоці всередині пулу з --max-concurrent слотів, ніколи в асинхронних робітниках, тож тривалий прогін не може завадити серверу відповідати. Слот звільняється лише тоді, коли закінчується сам прогін, а не коли викликач здається: тому покинуті прогони не можуть накопичуватися понад розмір пулу, а виклик, що застає пул повним, відхиляється як зайнятий.
Бюджет роботи Сценарій, що вимагає значно більше, ніж вбудовані приклади, відхиляється до запуску: понад 1000 реалізацій Монте-Карло (runs), сітка параметрів із понад 1000 вузлів, понад 5000 запусків-членів (вузли сітки, помножені на реалізації) або часова сітка з понад 2 мільйонів епох. Помилка називає поле, яке слід зменшити. Той самий бюджет застосовується через stdio; командний рядок kshana його не має.
CORS Заголовок Access-Control-* ніколи не надсилається. Запит із заголовком Origin відхиляється (403), якщо його не названо через --allow-origin <scheme://host[:port]>; * не приймається.
Заголовок Host Перевіряється щодо імен loopback або адреси прив'язки плюс кожен --allowed-host. За проксі чи на URL платформи передайте --allowed-host your.domain. Усе інше: 403.
Сесії Немає. Кожен POST отримує відповідь JSON; таблиця сесій і потік server-sent-event не тримаються відкритими.

TLS не завершується в kshana-mcp. Коли він доступний поза межами однієї машини, поставте перед ним HTTPS (TLS вашої платформи або зворотний проксі) і тримайте токен у таємниці; токен-носій через звичайний HTTP можна прочитати в каналі.

Локально#

kshana-mcp --http 127.0.0.1:8080

Конфігурація клієнта (клієнт на URL; додавайте заголовок лише тоді, коли задано токен):

{ "mcpServers": { "kshana": { "url": "http://127.0.0.1:8080/mcp",
    "headers": { "Authorization": "Bearer ${KSHANA_MCP_HTTP_TOKEN}" } } } }

Docker#

export KSHANA_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8080:8080 -e KSHANA_MCP_HTTP_TOKEN \
  ghcr.io/ashfordeou/kshana-mcp:0.40.0 \
  --http 0.0.0.0:8080 --allow-remote --allowed-host localhost:8080 --allowed-host 127.0.0.1:8080

Усередині контейнера сервер має слухати 0.0.0.0, тож йому потрібні --allow-remote і токен. Публікація порту як 127.0.0.1:8080:8080 тримає його на вашій машині; прибирайте 127.0.0.1: лише тоді, коли маєте на меті його відкрити, і тоді завершуйте TLS перед ним. docker compose і шаблони для Fly.io та Cloud Run є в mcp-http/.

Шаблони (ви розгортаєте їх самі; Kshana не запускає жодного)#

Кожен запускає опублікований образ, задає --allowed-host на ім'я хоста платформи, яке ви підставляєте у файл, і покладається на платформу щодо HTTPS.

Задайте обмеження ЦП і пам'яті на платформі#

Тайм-аут, пул і бюджет обмежують, скільки роботи допускається, але один допущений виклик усе ще може довго використовувати ядро, а великий результат може використати сотні мегабайтів. Поставте жорсткий ліміт і на контейнер: шаблони просять 2 ЦП і 1 GiB (cpus і mem_limit у Compose, [[vm]] у Fly, resources.limits у Cloud Run). Тримайте --max-concurrent не вище за кількість ЦП.

Чим він не є#

  • Не багатокористувацька служба. Будь-хто, хто має токен, запускає симуляції на вашому обладнанні; поза наведеними вище обмеженнями квот для користувачів немає.
  • Лише консультативно, не навігаційне обладнання із затвердженням типу: відповідальність за навігацію залишається на операторі. Виходи симулятора — це обчислені за моделлю або перевірені за зовнішнім еталоном показники для аналізу, як і скрізь у Kshana.