Sora (空)

Self-hosted MCP / REST интеграционный сервер для использования японского веба из AI-агентов
All-in-One, Zero-Middleware Web Scraping & Japanese Life Infrastructure Engine for AI Agents

Sora — это универсальный MCP / REST сервер, который позволяет LLM и AI-агентам (Claude Desktop, Cursor, Cline, OpenCodeInterpreter, Dify и др.) свободно и безопасно исследовать и использовать японское веб-пространство и повседневную инфраструктуру.

Для работы не требуются внешние БД (Redis / PostgreSQL) или очереди сообщений: достаточно одного контейнера / одного бинарного файла со встроенным headless Chromium и японскими CJK-шрифтами — и сервер мгновенно запускается на VPS за 800 иен в месяц.

flowchart LR
    subgraph Clients["AI Clients / Agents"]
        Claude["Claude Desktop / Cursor"]
        Agents["LangChain / AutoGen / Dify"]
    end

    subgraph Sora["Sora All-in-One (Distroless / Bun)"]
        direction TB
        MCP["MCP Server (Streamable HTTP / SSE)"]
        REST["Hono REST API (OpenAPI 3.0)"]
        Auth["Timing-Safe Auth & SSRF Guard"]
        LRU["True LRU In-Memory Cache"]
        
        subgraph Engine["Dual Scrape Engine"]
            Fast["Static Fetch + Readability + AI Chunker"]
            Browser["Stealth Chromium + Browser DSL (Tabs/Clicks)"]
        end

        subgraph JP["Japan Life Infrastructure"]
            JMA["気象庁 1,805自治体 天気予報"]
            Transit["Yahoo! 路線乗換・IC運賃"]
            Yahoo["Yahoo! リアルタイム(X)/知恵袋/ニュース/画像/動画"]
        end
    end

    subgraph Web["Public Internet"]
        Sites["Web Sites / PDFs / SPAs"]
        PublicData["気象庁 / Yahoo / X"]
    end

    Clients <-->|MCP / REST| Sora
    Fast --> Sites
    Browser --> Sites
    JP --> PublicData

⚡ Quickstart за 5 секунд (Claude Desktop / Cursor / Cline)

Просто добавьте следующее в файл конфигурации вашего AI-агента (например, claude_desktop_config.json) — и набор из 16 мощных инструментов сразу же станет доступен.

① Подключение Remote MCP (HTTP / SSE)

Запустите контейнер Sora и укажите URL:

{
  "mcpServers": {
    "sora": {
      "url": "http://localhost:3016/mcp"
    }
  }
}

② Запуск одной командой в Docker / Podman

docker run -d -p 3016:8000 --name sora ghcr.io/ikenokazuki/sora:latest

Related MCP server: Agent Toolbox

🌟 Основные характеристики и преимущества (Why Sora?)

1. 🗾 Полный охват повседневной инфраструктуры Японии и веб-поиска:

   • Предоставляет в одном MCP то, что недоступно зарубежным инструментам (Firecrawl / Tavily): «Yahoo! 知恵袋», «X (Twitter) в реальном времени», «прямое подключение к официальным открытым данным Метеорологического агентства Японии (автоматический выбор из 1 805 муниципалитетов по всей стране)», «поиск маршрутов электропоездов».

2. ⚡ Потрясающий отклик в миллисекундах и сверхнизкое энергопотребление:

   • Благодаря нативной компиляции Bun: ответ API 1,5 мс, резидентная память JS-куча ~32 МБ / всего ~140 МБ. Время ожидания AI-агента сведено к абсолютному минимуму.

3. 📦 Полностью «всё в одном» и ноль промежуточного ПО:

   • Не нужны Redis, PostgreSQL, внешние очереди задач и т. д. Достаточно одного бинарного файла / одного контейнера.

4. 🛡️ Distroless (без оболочки) и строгая безопасность:

   • В качестве базового образа используется gcr.io/distroless/cc-debian12. В контейнере отсутствуют /bin/sh, bash, curl и т. д., что нейтрализует RCE-атаки (выполнение произвольного кода).

   • Встроены: блокировка SSRF / DNS Rebinding, защита от Timing Attack с помощью сравнения за константное время, изоляция владения сессиями браузера, защита от DoS (лимит тела 10 МБ).

5. 🕹️ DSL для управления состоянием браузера:

   • Управляйте многошаговыми интерактивными сессиями браузера open → fill → click → screenshot → evaluate напрямую через API / MCP.

📊 Сравнение производительности и архитектуры

⏱️ Фактическая скорость ответа каждой конечной точки (Measured Latency: Cold vs Cached)

Список фактических задержек «первого получения (без кэша)» и «при попадании в кэш» на реальном локальном сервере. Ответ происходит значительно быстрее по сравнению со временем размышления и генерации AI-агента (1–3 секунды).

⚡ Фактическая скорость внутреннего обогащения и AI-оптимизации (In-Memory Latency)

Все операции выполняются менее чем за 1 миллисекунду (< 1 мс) с помощью нативных и оптимизированных алгоритмов Bun, без обращения к внешним LLM API.

🏛️ Философия дизайна (Design Philosophy & Principles)

Sora построен на следующих 4 основных принципах проектирования:

1. ✂️ Бритва Оккама (Occam's Razor & Zero-Middleware):

   • «Не следует утверждать лишнего, если в этом нет необходимости. Самая простая конфигурация, удовлетворяющая требованиям, — лучшая конфигурация.»

   • Полностью исключены Redis, PostgreSQL, внешние очереди и громоздкие микросервисы. Работает на «одном контейнере и одном бинарном файле», стабильно функционируя как на VPS за 800 иен в месяц или Raspberry Pi, так и в облаке с десятками тысяч запросов.

2. 🛡️ Парето-оптимум скрытности и выживаемости (Stealth & Pareto Optimum):

   • Если просто «получить доступ механически за 0 мс», WAF или Cloudflare на стороне сервера немедленно забанит IP, и вероятность успеха упадет до 0%.

   • При последовательных запросах к одному и тому же домену автоматически вставляется 150 мс + Jitter (колебания 0–100 мс), а к вводу добавляется человеческая задержка 15–40 мс. Приоритет отдается проценту выживания — гарантированному получению данных без ущерба для воспринимаемой скорости ИИ.

3. 🔒 Надежная безопасность благодаря Distroless (Distroless by Design):

   • Поскольку в контейнере нет /bin/sh, bash, curl, apt, даже при обнаружении неизвестной уязвимости у злоумышленника в принципе нет возможности получить оболочку (RCE: выполнение произвольного кода). Встроены запуск от непривилегированного пользователя и строгая блокировка SSRF.

4. 🗾 Прямое подключение к государственным открытым данным, устойчивость (Sustainable & Autonomous):

   • Прогноз погоды получается напрямую с официального CDN открытых данных Метеорологического агентства Японии (jma.go.jp). Благодаря автоматическому разрешению названий всех 1 805 муниципалитетов за ноль миллисекунд и 30-минутному LRU-кэшу система работает автономно вечно, сводя к минимуму нагрузку на сторонние серверы.

1. Быстрый старт

1.1 Запуск контейнера (Docker / Podman)

Мгновенный запуск одной командой из GitHub Container Registry (GHCR):

docker run -d \
  --name sora \
  -p 3016:8000 \
  -e API_KEY="your-secret-api-key" \
  -e ENABLED_MODULES="all" \
  ghcr.io/ikenokazuki/sora:latest

1.2 Настройка MCP-клиента (Claude Desktop / Cursor / Cline / Windsurf и др.)

Подключение Streamable HTTP (рекомендуется, стандарт)

Добавьте следующее в файл конфигурации (например, claude_desktop_config.json или настройки MCP в Cursor):

{
  "mcpServers": {
    "sora": {
      "url": "http://localhost:3016/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-api-key"
      }
    }
  }
}

Подключение SSE (для устаревших SSE-клиентов)

{
  "mcpServers": {
    "sora": {
      "url": "http://localhost:3016/sse",
      "headers": {
        "Authorization": "Bearer your-secret-api-key"
      }
    }
  }
}

(※ Если API-ключ не задан, headers можно опустить)

2. Список предоставляемых MCP-инструментов (всего 16 инструментов / 4 модуля)

Sora состоит из 4 логических модулей в зависимости от назначения. Категории можно свободно настраивать с помощью переменной окружения ENABLED_MODULES (по умолчанию: all или web,browser,yahoo,life).

┌──────────────────────────────────────────────────────────────────────────┐
│                         Sora - Modular MCP                               │
├─────────────────┬───────────────────┬──────────────────┬─────────────────┤
│ 🌐 Core Web     │ 🤖 Browser Action │ 🇯🇵 Yahoo Services │ 🗾 Daily Life   │
│ (`web`)         │ (`browser`)       │ (`yahoo`)        │ (`life`)        │
│ ・search_web    │ ・browser_action  │ ・search_image   │ ・search_route  │
│ ・scrape        │   (クリック/入力/ │ ・search_video   │   (乗換案内)    │
│ ・scrape_batch  │    スクショ/JS実行│ ・search_news    │ ・get_weather   │
│ ・search_deep   │    セッション保持)│ ・search_chiebukuro│ (気象庁天気)  │
│ ・map_site      │                   │ ・search_realtime│                 │
│ ・crawl_site    │                   │ ・search_trend   │                 │
│                 │                   │ ・suggest_keywords│                │
└─────────────────┴───────────────────┴──────────────────┴─────────────────┘

🌐 Модуль 1: Core Web & Crawling (ENABLED_MODULES=web)

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

💡 Рекомендации по интеграции с LLM / Agent и руководство по настройке limit

При использовании веб-поиска, скрейпинга и обхода в агентах или RAG-приложениях настройка количества получаемых элементов (limit) существенно влияет на задержку и качество ответов.

1. Преимущества и недостатки увеличения количества получаемых элементов

2. 最も高精度な LLM 活用のベストプラクティス

[!TIP] より効果的なアプローチ:

1. スニペットと全文の使い分け: 検索スニペット（search_web）自体は 10〜20 件 返して概要を広く把握しつつ、全文スクレイプ対象（search_deep の limit）は 上位 3〜5 件に絞る のが最も高速かつ高精度です。

2. ハイライト抽出の併用: extractHighlights: true（query 指定）を有効化すると、Structure & Proximity-Aware BM25+ エンジン（見出し文脈継承・フレーズ完全一致・近接度スコアリング・KWICスニペット生成）により、LLM は長いページ全体を読む代わりにクエリに関連する最も重要な段落・センテンスのみを集中して読めるため、ハルシネーションを防止しつつトークン消費を 70〜90% 削減できます（外部 LLM 不要、0.3ms でローカル動作）。

3. 全エンドポイント共通メタデータ (Firecrawl / Tavily 互換): publishedTime（公開日時/更新日時）、author（著者名）、siteName（サイト名）を OGP / JSON-LD / HTML メタタグから自動抽出し、Frontmatter および JSON レスポンスに付与。LLM が情報の鮮度（ファクトチェック）を瞬時に判定可能。

4. GFM シンタックスハイライト言語の保持: <pre><code class="language-python"> 等からプログラミング言語名を正確に識別し、Markdown 出力時に ```python として再現。

5. 自動トークン圧縮 & ノイズ除去: 空リンク、無効な JavaScript リンク、不要な重複空行を自動クレンジング（cleanMarkdownTokens）し、Cookie 同意バナー（OneTrust / Cookiebot 等）も完全パージするため、LLM コンテキストを常にクリーンに保ちます。

6. robots.txt サイトマップ自動発見: /robots.txt から変則配置された Sitemap URL を自動検出し、Sitemap Index を最大 1,000 件まで再帰走査。

7. クロール時のストリーミング: 多数のページを巡回する際は、POST /crawl/stream（SSE）を利用して 1 ページ取得完了ごとに逐次受信・処理することで、全体の完了を待たずに即座にユーザーや LLM へ中間応答を返せます。

3. 実測ベンチマークとスケーラビリティ特性 (ローカル実測値)

🤖 Module 2: Browser Actions & Automation (ENABLED_MODULES=browser)

フォーム入力、ボタンクリック、画面スクロール、JavaScript 実行、スクリーンショット撮影、マルチターン対話セッション。

🇯🇵 Module 3: Yahoo! JAPAN Services (ENABLED_MODULES=yahoo)

日本のメディア・Q&A・トレンド・リアルタイム情報に完全特化した検索群。

🗾 Module 4: Japan Daily Life & Transit (ENABLED_MODULES=life)

日本の公共交通・気象庁公式オープンデータに直結した生活インフラ機能。

3. REST API 仕様

ベース URL: http://localhost:3016 (またはデプロイ先のドメイン URL)

3.1 ヘルスチェック & メトリクス

GET /health

{
  "status": "ok",
  "service": "sora",
  "cachedEntries": 0,
  "chromiumAvailable": true,
  "yahooMcpAvailable": true,
  "mcpConnected": true,
  "timestamp": "2026-08-21T05:54:26.782Z"
}

GET /metrics (運用統計・キャッシュヒット率・リソース使用量)

{
  "status": "ok",
  "service": "sora",
  "uptimeSeconds": 1420,
  "cache": {
    "size": 42,
    "maxSize": 3000,
    "hits": 156,
    "misses": 48,
    "hitRatio": 0.7647
  },
  "activeSessions": 2,
  "chromium": {
    "available": true,
    "sharedConnected": true
  },
  "memory": {
    "rssMb": 86,
    "heapUsedMb": 34,
    "heapTotalMb": 58
  },
  "timestamp": "2026-08-22T04:20:00.000Z"
}

GET /metrics?format=prometheus または Accept: text/plain (Prometheus 監視用メトリクス)

Grafana / Prometheus 監視スタックにそのまま取り込める標準テキスト形式で出力します。

# HELP sora_uptime_seconds Process uptime in seconds
# TYPE sora_uptime_seconds gauge
sora_uptime_seconds 1420
# HELP sora_memory_rss_bytes Resident set size in bytes
# TYPE sora_memory_rss_bytes gauge
sora_memory_rss_bytes 90177536
# HELP sora_cache_hits_total Total cache hits
# TYPE sora_cache_hits_total counter
sora_cache_hits_total 156
# HELP sora_cache_hit_rate Cache hit rate
# TYPE sora_cache_hit_rate gauge
sora_cache_hit_rate 0.7647
# HELP sora_active_browser_sessions Active browser sessions count
# TYPE sora_active_browser_sessions gauge
sora_active_browser_sessions 2

3.2 単一 URL / PDF スクレイプ (POST /scrape)

• リクエスト:

{
  "url": "https://example.com/article",
  "maxChars": 30000,
  "mode": "auto",
  "formats": ["markdown", "jsonLd", "images", "links"],
  "onlyMainContent": true,
  "selectors": {
    "productName": "h1.product-title",
    "price": ".price-value",
    "buyLink": "a.btn-buy@href",
    "thumbnail": "img.main-photo@src"
  },
  "extractHighlights": true,
  "query": "新機能 リリース"
}

• レスポンス例:

{
  "url": "https://example.com/article",
  "title": "最新アップデートのお知らせ",
  "content": "---\ntitle: \"最新アップデートのお知らせ\"\nurl: \"https://example.com/article\"\npublishedTime: \"2026-08-22T10:00:00Z\"\nauthor: \"開発チーム\"\nsiteName: \"Tech Blog\"\n---\n\n...",
  "isTruncated": false,
  "contentType": "text/html",
  "source": "web",
  "renderedWithBrowser": false,
  "publishedTime": "2026-08-22T10:00:00Z",
  "author": "開発チーム",
  "siteName": "Tech Blog",
  "extracted": {
    "productName": "Sora プレミアムキーボード",
    "price": "¥24,800",
    "buyLink": "https://example.com/cart/add?id=123",
    "thumbnail": "https://example.com/images/feature.png"
  },
  "jsonLd": [
    {
      "@context": "https://schema.org",
      "@type": "NewsArticle",
      "headline": "最新アップデートのお知らせ"
    }
  ],
  "images": [
    {
      "url": "https://example.com/images/feature.png",
      "alt": "新機能の画面イメージ"
    }
  ],
  "highlights": [
    "本日より新機能の提供を開始いたします。"
  ]
}

[!TIP] 🇯🇵 Автоматическая поддержка японских легаси-сайтов: Веб-сайты в кодировках Shift_JIS (CP932) и EUC-JP также автоматически определяются и декодируются. Не нужно беспокоиться о кракозябрах.

📄 Расширенное извлечение PDF: Многостраничные PDF-документы выводятся в структурированном Markdown с разделителями номеров страниц, например <!-- Page 1 -->\n## Page 1, а также автоматически извлекаются метаданные, такие как totalPages и автор.

✂️ Синтаксически безопасная обрезка и оценка токенов: Даже при ограничении длины через maxChars открытые блоки кода ( ```) и таблицы автоматически безопасно корректируются и закрываются. Кроме того, в ответ добавляется оценочное количество LLM-токенов estimatedTokens.

🧩 RAG-оптимизированная семантическая чанкинг (chunkMarkdown: true): Автоматически генерируются правильно разделённые chunks: [{ index, heading, content, estimatedTokens }] без нарушения иерархии заголовков (H1–H4), абзацев и блоков кода — готовые для немедленного использования в векторном поиске и RAG.

🖼️ Извлечение метаданных изображений и подписей (formats: ["images"]): Для каждого изображения автоматически извлекаются URL, описание из <figcaption> (caption), width/height, а также определение главного изображения (isMainImage).

🔗 Проверка работоспособности и доступности внутренних ссылок (validateLinks: true): Выполняется лёгкая параллельная проверка ссылок на странице с возвратом HTTP-статуса и валидности linksWithStatus: [{ url, status, ok }].

📚 Структурированное извлечение источников и цитат (extractCitations: true): Внешние ссылки и библиографические ссылки в тексте автоматически извлекаются с контекстом как citations: [{ text, url, context }].

⏱️ Время чтения и статистика символов/слов: Автоматически рассчитываются и добавляются characterCount, wordCount и оценочное время чтения readingTimeMin (в минутах) с учётом языковых особенностей.

🔔 Асинхронный Webhook-колбэк (webhookUrl): При завершении длительных пакетных операций или масштабного обхода выполняется асинхронная HTTP POST-отправка полезной нагрузки результата на указанную конечную точку.

🛡️ Автоматическое маскирование PII (maskPii: true): Конфиденциальная информация, такая как адреса электронной почты, японские номера телефонов и номера кредитных карт (с проверкой Луна), автоматически заменяется на [EMAIL], [PHONE], [CREDIT_CARD] для защиты при отправке в LLM.

📡 Потоковая передача прогресса в реальном времени через SSE (POST /scrape/stream): События прогресса каждого этапа start → fetch → render → enrich → done можно получать в реальном времени через Server-Sent Events.

🎬 Извлечение метаданных и глав YouTube / видеомедиа (media): Со страниц с видео автоматически структурированно извлекаются длительность, миниатюра и список глав (оглавление с временными метками).

🤖 Автоматическая генерация XML-промпта, оптимизированного для LLM (formatAsPrompt: true): Автоматически генерируется обёртка контекста promptContext в стандартном формате <web_page url="..." title="...">...</web_page>, который легче всего понимают Claude / GPT / Gemini.

🖍️ Автоматическое выделение поисковых ключевых слов в тексте (highlightMatches: true): Можно получить highlightedContent, где ключевые слова указанного query выделены в Markdown-тексте как <mark>ключевое слово</mark>.

📊 Структурированное извлечение таблиц в JSON (formats: ["tables"]): Таблицы (<table>) на странице можно напрямую получить как структурированный JSON-массив { caption, headers, rows }.

⚡ Сверхбыстрое экстрактивное автоматическое резюмирование (extractSummary: true): Без вызова внешних LLM API, с помощью внутреннего алгоритма за миллисекунды автоматически генерируются ключевые предложения (TL;DR-резюме) summary: string[].

🎯 Дедупликация результатов поиска (dedup: true): При поиске новостей или в реальном времени автоматически исключаются скопированные посты и перепечатанные статьи на основе определения схожести, отбирается только уникальная информация.

🔄 Политика автоматических повторных попыток (retries и retryDelayMs): При сбоях подключения или ошибках 429/503 выполняется автоматический повтор с экспоненциальной задержкой, повышая отказоустойчивость.

📸 Скриншот указанного элемента (clipSelector): Указав конкретный элемент (например, clipSelector: "#stock-chart"), можно получить Base64 PNG с вырезанным только этим элементом.

🍪 Пользовательские заголовки и внедрение Cookie (headers / cookies): Можно прозрачно отправлять заголовки для сайтов с членством, указание языка (Accept-Language), Cookie возрастной верификации и т. д.

🧹 Удаление указанных пользователем шумовых селекторов (removeSelectors): Указав removeSelectors: [".ad", ".comments", "#related-articles"], можно полностью удалить определённые блоки перед преобразованием в Markdown.

📖 Интерактивная документация API (GET /docs): При доступе из браузера к http://localhost:3016/docs можно напрямую тестировать все API (Try it out) через Swagger UI.

3.2.1 Пакетный параллельный скрейпинг нескольких URL (POST /scrape/batch)

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

• Запрос (POST):

{
  "urls": [
    "https://example.com/page1",
    "https://example.com/page2",
    "https://example.com/page3"
  ],
  "concurrency": 3,
  "maxChars": 10000,
  "mode": "auto",
  "formats": ["markdown", "jsonLd"]
}

• Пример ответа:

{
  "total": 3,
  "successful": 3,
  "failed": 0,
  "results": [
    {
      "url": "https://example.com/page1",
      "title": "Page 1 Title",
      "content": "...",
      "estimatedTokens": 450
    }
  ],
  "errors": []
}

3.3 Интерактивное автоматическое управление браузером (POST /browser/action или POST /action)

Открывается веб-страница, последовательно выполняются серии действий, таких как клик, ввод текста, прокрутка, ожидание, создание скриншота, и получается конечный результат. Поддерживаются как одноразовое выполнение, так и многоходовые диалоговые сессии с сохранением состояния (sessionId), где операции выполняются в интерактивном режиме в чате.

① Одноразовое выполнение (завершается за один раз)

• Запрос (POST):

{
  "url": "https://example.com/search",
  "actions": [
    { "type": "fill", "selector": "input[name='q']", "text": "Sora" },
    { "type": "click", "text": "検索" },
    { "type": "wait", "selector": ".results-container", "ms": 5000 },
    { "type": "scroll", "direction": "down", "distance": 1000 }
  ],
  "extract": {
    "markdown": true,
    "screenshot": true,
    "html": false
  },
  "timeout": 30000
}

• Пример ответа:

{
  "source": "browser",
  "url": "https://example.com/search?q=Sora",
  "title": "検索結果 - Sora",
  "content": "---\ntitle: \"検索結果 - Sora\"\nurl: \"https://example.com/search?q=Sora\"\n---\n\n# 検索結果\n...",
  "screenshot": "iVBORw0KGgoAAAANSUhEUgA...",
  "actionLogs": [
    { "step": 1, "type": "fill", "target": "input[name='q']", "success": true, "elapsedMs": 42 },
    { "step": 2, "type": "click", "target": "検索", "success": true, "elapsedMs": 115 },
    { "step": 3, "type": "wait", "target": ".results-container", "success": true, "elapsedMs": 620 },
    { "step": 4, "type": "scroll", "target": undefined, "success": true, "elapsedMs": 510 }
  ],
  "renderedWithBrowser": true
}

② Многоходовая диалоговая сессия с сохранением состояния (для интерактивного чата)

• Ход 1 (создание сессии и открытие экрана):

{
  "url": "https://example.com/login",
  "createSession": true,
  "actions": [
    { "type": "fill", "selector": "#username", "text": "myuser" }
  ],
  "extract": { "screenshot": true }
}

(В ответе возвращается "sessionId": "sess_a1b2c3d4")

• Ход 2 (продолжение операций на уже открытом экране):

{
  "sessionId": "sess_a1b2c3d4",
  "actions": [
    { "type": "fill", "selector": "#password", "text": "mypassword" },
    { "type": "click", "text": "ログイン" },
    { "type": "wait", "selector": "#dashboard" }
  ],
  "extract": { "markdown": true }
}

• Ход 3 (завершение сессии и очистка):

{
  "sessionId": "sess_a1b2c3d4",
  "closeSession": true
}

(※ Если операции прерываются на 5 минут, память также безопасно освобождается автоматическим тайм-аутом)

3.4 Интегрированный углублённый поиск (POST /search) и веб-поиск (POST /search/web)

• Запрос углублённого поиска (POST /search):

{
  "query": "2026年 AI 最新トレンド",
  "limit": 5,
  "scrapeContent": true,
  "includeRealtime": true,
  "updated": "week",
  "formats": ["markdown"]
}

• При получении в формате HTML:

{
  "query": "React 19 新機能",
  "formats": ["html"]
}

• При извлечении только важных выделений (режим экономии токенов):

{
  "query": "React 19 新機能 変更点",
  "extractHighlights": true
}

• Запрос веб-поиска (POST /search/web):

{
  "query": "新商品 発売情報",
  "includeDomains": ["example.com", "news.example.org"],
  "excludeDomains": ["spam.example.com"],
  "updated": "week"
}

3.4.1 Обход карты сайта (POST /map)

Выполняется поиск sitemap.xml и внутренних ссылок указанного домена, извлекается список всех URL на сайте.

• Запрос:

{
  "url": "https://example.com",
  "limit": 200,
  "includeSubdomains": false
}

3.4.2 Рекурсивный обход подстраниц (POST /crawl и POST /crawl/stream)

Рекурсивно обходятся страницы ниже указанного URL, пакетно собираются Markdown/HTML/изображения/структурированные данные нескольких страниц. Поддерживается фильтрация по Glob-шаблонам через includePatterns / excludePatterns.

• Запрос (пакетное получение):

{
  "url": "https://example.com/docs",
  "maxPages": 20,
  "maxDepth": 2,
  "includePatterns": ["/docs/**", "/guide/*"],
  "excludePatterns": ["/tag/**", "*.pdf"],
  "formats": ["markdown", "jsonLd", "images"]
}

• SSE-поток (POST /crawl/stream): При каждом получении страницы в реальном времени через Server-Sent Events доставляются события (start -> page -> done).

3.5 Поиск изображений, видео, новостей, Chiebukuro и подсказок

• Поиск изображений (POST /search/image): { "query": "富士山", "limit": 10 }

• Поиск видео (POST /search/video): { "query": "簡単 レシピ", "limit": 10 }

• Поиск новостей (POST /search/news): { "query": "AI ロボット", "limit": 10 }

• Q&A Chiebukuro (POST /search/chiebukuro): { "query": "プログラミング 初心者", "limit": 10, "status": "solved" }

• Автодополнение ключевых слов (POST /search/suggest): { "query": "天気", "limit": 10 }

3.6 Маршруты поездов (POST /transit/route)

• Запрос:

{
  "from": "東京",
  "to": "新宿",
  "sortBy": "time"
}

• Пример ответа:

{
  "source": "transit",
  "from": "東京",
  "to": "新宿",
  "count": 3,
  "routes": [
    {
      "rank": 1,
      "summary": {
        "departureTime": "09:30",
        "arrivalTime": "09:44",
        "durationMinutes": 14,
        "transferCount": 0,
        "fare": {
          "ic": 209,
          "ticket": 210
        },
        "flags": {
          "isFastest": true,
          "isCheapest": true,
          "isEasiest": true
        }
      },
      "sections": [
        {
          "type": "move",
          "line": "ＪＲ中央線快速・高尾行",
          "from": "東京",
          "departureTime": "09:30",
          "to": "新宿",
          "arrivalTime": "09:44"
        }
      ]
    }
  ]
}

3.7 Прогноз погоды по всей Японии (POST /weather / GET /weather / GET /weather/:city)

Напрямую анализируются официальные открытые данные API Метеорологического агентства Японии (а также совместимый формат livedoor weather), полностью автономно получаются подробные метеорологические данные на сегодня, завтра и послезавтра по всей Японии.

Преимущества данной функции (Features & Advantages)

• Полная автономность и прямое подключение к официальному источнику (нулевая зависимость): Метеорологические данные получаются и парсятся напрямую с официального CDN Метеорологического агентства (jma.go.jp).

• Умное автоматическое разрешение для 1 805 муниципалитетов по всей стране: Встроено официальное определение районов Метеорологического агентства (area.json). Из названий муниципалитетов и известных мест, таких как «Тендо», «Каруидзава», «Хаконе», «Ураясу», «Беппу», ID пункта ответственной метеорологической обсерватории автоматически определяется за 0 мс. Поддерживается ввод без названия префектуры.

• Структурированные данные, удобные для AI-агентов: За один раз в чистом JSON получаются телетекст погоды на 3 дня, ветер и волны, прогнозируемые максимальные/минимальные температуры (℃), вероятность осадков по временным интервалам (0–6 ч, 6–12 ч, 12–18 ч, 18–24 ч), а также текст общего обзора погоды от метеорологической обсерватории (заголовок и основной текст).

• Сверхбыстрый ответ с LRU-кэшем: Стандартно встроен кэш LRU в памяти на 30 минут, автоматически предотвращающий ненужные повторные обращения к серверам Метеорологического агентства.

• Запрос (POST):

{
  "city": "天童市",
  "days": 3
}

• GET-запрос: GET /weather?city=軽井沢&days=2 или GET /weather/箱根

• Пример ответа:

{
  "source": "weather",
  "cityId": "060010",
  "title": "村山 の天気",
  "publishedTime": "2026-08-21T17:00:00+09:00",
  "publicTime": "2026-08-21T17:00:00+09:00",
  "publishingOffice": "山形地方気象台",
  "location": {
    "area": "東北",
    "prefecture": "山形県",
    "city": "天童市"
  },
  "overview": "前線が、日本海から東北地方を通って、日本の東にのびています。村山地方では、夜遅くにかけて雷を伴い激しい雨が降る所がある見込みです。",
  "description": {
    "headline": "",
    "body": "前線が、日本海から東北地方を通って、日本の東にのびています...",
    "text": "..."
  },
  "forecasts": [
    {
      "date": "2026-08-21",
      "dateLabel": "今日",
      "telop": "曇り",
      "detail": {
        "weather": "くもり　所により　夕方　雨　で　雷を伴い　激しく　降る",
        "wind": "北の風　後　南東の風",
        "wave": null
      },
      "temperature": {
        "min": "22℃",
        "max": "31℃"
      },
      "chanceOfRain": {
        "T00_06": "30%",
        "T06_12": "0%",
        "T12_18": "0%",
        "T18_24": "30%"
      },
      "image": "https://www.jma.go.jp/bosai/forecast/img/200.svg"
    }
  ]
}

3.8 Поиск в реальном времени и тренды Yahoo (POST /search/realtime / POST /search/trend)

• Поиск в реальном времени (POST /search/realtime): { "query": "イベント名", "sort": "popular", "limit": 20, "page": 1 }

  • sort: "recent" (по новизне, по умолчанию) или "popular" (по популярности / вовлечённости)

  • Каждому посту автоматически присваиваются publishedTime (строка ISO 8601), author (имя пользователя + @имя аккаунта), siteName: "X (Twitter)" в едином формате.

• Растущие тренды (POST /search/trend): { "limit": 20 }

3.9 Карта сайта и обход (POST /map / POST /crawl)

• Карта сайта (POST /map): { "url": "https://example.com", "limit": 200 }

• Рекурсивный обход (POST /crawl): { "url": "https://example.com/docs", "maxPages": 10 }

4. Безопасность и архитектура

4.1 Дизайн контейнера Distroless

• Базовый образ: gcr.io/distroless/cc-debian12

• Без оболочки и менеджера пакетов: В контейнере полностью отсутствуют /bin/sh, apt и curl — у злоумышленника нет возможности захватить оболочку.

• Принцип минимальных привилегий: Поддерживается запуск от непривилегированного пользователя, возможна безопасная изоляция и запуск в стандартных контейнерных средах, таких как Docker / Podman / Kubernetes.

4.2 Функции безопасности и производительности

• 🛡️ Многоуровневая защита от SSRF и DNS Rebinding:

  • Блокируется внутренний доступ к частным IP-адресам (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8 и т. д.), CGNAT (100.64.0.0/10), специальным IPv6-адресам, IP-адресам метаданных облака (169.254.169.254).

  • Выполняется предварительное разрешение имён через dns.promises.lookup, атаки DNS Rebinding с подменой доменов также немедленно блокируются до установления соединения.

• ⚡ Single-Flight Cache (дедупликация в полёте):

  • При параллельных запросах к одному и тому же URL Promise разделяется, и внешняя связь объединяется в один запрос. Предотвращается Thundering Herd (кэш-стампед), защищаются внешние серверы и локальные ресурсы.

• 🚦 Ограничение параллельного выполнения браузера (Concurrency Control):

  • С помощью SimpleSemaphore безопасно контролируется количество одновременно выполняемых процессов Chromium (MAX_CONCURRENT_BROWSERS, по умолчанию 5). Предотвращается истощение CPU/памяти сервера.

• 🔒 Timing-Safe аутентификация и привязка владения Browser Session:

  • Для проверки API-ключа используется crypto.timingSafeEqual + SHA-256 (сравнение за постоянное время), защищающее от Timing Attack.

  • Многоходовые браузерные сессии (sessionId) криптографически привязываются к токену создателя, предотвращая захват сессии другими лицами.

• 🛡️ Безопасный переключатель управления произвольным выполнением JavaScript (ALLOW_BROWSER_EVALUATE):

  • С помощью переменной окружения ALLOW_BROWSER_EVALUATE=false или SAFE_BROWSER_MODE=true можно немедленно отключить и заблокировать выполнение скриптов evaluate в /browser/action.

• 📐 Общая схема Zod и полная автоматическая генерация OpenAPI 3.0:

  • Проверка входных данных унифицирована через схему Zod как для REST, так и для MCP.

  • /openapi.json на 100% динамически автоматически генерирует спецификацию OpenAPI 3.0 из схемы Zod на стороне кода, полностью предотвращая расхождение документации.

  • Ответы об ошибках предоставляют структуру, удобную для самостоятельного восстановления и автономного принятия решений AI-агентами, например { "error": "...", "code": "SSRF_BLOCKED", "status": 403, "retryable": false }.

• ⏱️ Троттлинг с джиттером и настоящий LRU-кэш:

  • Чрезмерные последовательные обращения к одному домену автоматически ограничиваются задержкой 150 мс + Jitter (колебание 0–100 мс).

  • Настоящий LRU-кэш (обновление при обращении) на 15–30 минут и периодическая очистка TTL каждые 10 минут полностью предотвращают утечки памяти.

5. Благодарности (Acknowledgments)

Sora поддерживается выдающимся вкладом следующих отличных проектов с открытым исходным кодом, публичных сервисов, официальных открытых данных и авторов библиотек. Выражаем искреннюю благодарность.

🗾 Источники данных и вдохновение (Data Sources & Inspirations)

• Открытые данные Метеорологического агентства Японии (JMA): jma.go.jp

  • Глубоко благодарим за открытую публикацию высокоточных метеорологических прогнозов, данных о стихийных бедствиях и определений более чем 1 800 районов по всей Японии.

• Дизайн-вдохновение API прогноза погоды (совместимый с livedoor weather): tsukumijima/weather-api / weather.tsukumijima.net

  • Благодарим за понятный дизайн схемы в формате, совместимом с livedoor weather, и многолетний вклад в сообщество.

• Yahoo Japan Search MCP: mouseos/Yahoo-Japan-Search-MCP

  • Благодарим за реализацию MCP для поиска изображений, видео, новостей, Chiebukuro и подсказок Yahoo! JAPAN.

• norikae-mcp: tysonwu/norikae-mcp

  • Благодарим за дизайн и реализацию логики маршрутов поездов на основе скрейпинга информации о маршрутах Yahoo!

🛠️ Базовые проекты с открытым исходным кодом и библиотеки (Core Libraries & Ecosystem)

• Hono (@yusukebe) — сверхбыстрый веб-API-фреймворк и интеграция MCP

• Puppeteer (Google Chrome Team) — управление headless Chromium, скрытые операции

• Readability (Mozilla) — движок извлечения основного текста статей в режиме чтения

• Cheerio (команда cheeriojs) — быстрый разбор DOM и извлечение метаданных

• Turndown (Dom Christie) — конвертер HTML в Markdown

• LinkeDOM (Andrea Giammarchi) — сверхлёгкий DOM-движок в памяти

• unpdf (команда UnJS) — быстрое и лёгкое извлечение текста из PDF

• Model Context Protocol SDK (Anthropic / команда MCP) — стандарт подключения AI-инструментов следующего поколения

6. Отказ от ответственности (Disclaimer)

• Неофициальный сторонний инструмент:

  • Данное программное обеспечение является неофициальным (сторонним) инструментом, разработанным для личной разработки, академических исследований и внутреннего использования в компаниях.

• О товарных знаках:

  • «Yahoo!», «Yahoo! JAPAN» и названия каждого сервиса являются товарными знаками или зарегистрированными товарными знаками LINE Yahoo Corporation. Данный проект никак не связан с LINE Yahoo Corporation.

• Соблюдение условий использования и законодательства:

  • При доступе к каждому внешнему сервису (Yahoo! JAPAN, Метеорологическое агентство и т. д.) пользователь обязан соблюдать условия использования, руководства, robots.txt и применимое законодательство соответствующего сервиса и использовать его под свою ответственность, не создавая чрезмерной нагрузки.

• Ограничение ответственности:

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

7. Лицензия (License)

Данное программное обеспечение опубликовано под лицензией Business Source License 1.1 (BSL 1.1 / BUSL-1.1).

• Свободное и бесплатное использование разрешено для:

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

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

  • Изменения исходного кода, форков и внутреннего обмена

• Ограничения (Restriction):

  • Запрещается предоставлять или перепродавать данное программное обеспечение (или его производные) третьим лицам в качестве «платного облачного сервиса», «платного сервиса скрейпинга / поискового API» или «управляемого сервиса».

• Change Date (дата перехода в открытый исходный код):

  • 1 августа 2030 года (или ранее) автоматически произойдёт полный переход на лицензию MIT License.

Подробности см. в LICENSE.

Copyright (c) 2026 ikeno