Sora (空)

Servidor MCP / REST autoalojado para que los agentes de IA accedan a la Web japonesa
Motor integral de scraping web y de infraestructura de la vida cotidiana japonesa para agentes de IA: todo en uno, sin middleware

Sora es un servidor MCP / REST todo en uno que permite a los LLM y agentes de IA (Claude Desktop, Cursor, Cline, OpenCodeInterpreter, Dify, etc.) explorar y operar el espacio web japonés y la infraestructura cotidiana de forma libre y segura.

No requiere ninguna base de datos externa (Redis / PostgreSQL) ni colas de mensajes: basta con un único contenedor / un único binario que incluye Chromium sin interfaz y fuentes CJK japonesas para empezar a funcionar al instante desde un VPS de 800 yenes al mes.

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

⚡ Guía de inicio rápido en 5 segundos (Claude Desktop / Cursor / Cline)

Solo tienes que añadir lo siguiente al archivo de configuración de tu agente de IA (por ejemplo, claude_desktop_config.json) y se activarán al instante 16 potentes herramientas.

① Conexión MCP remota (HTTP / SSE)

Con el contenedor de Sora en marcha, especifica la URL:

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

② Arranque con un solo comando en Docker / Podman

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

Related MCP server: Agent Toolbox

🌟 Características y ventajas principales (¿Por qué Sora?)

1. 🗾 Cobertura completa de la infraestructura cotidiana japonesa y exploración web:

   • Herramientas que las soluciones extranjeras (Firecrawl / Tavily) no pueden ofrecer: «Yahoo! Chiebukuro», «X (Twitter) noticias en tiempo real», «conexión directa con los datos abiertos oficiales de la Agencia Meteorológica de Japón (selección automática de los 1.805 municipios de todo el país)» y «búsqueda de rutas de tren» en un único MCP.

2. ⚡ Respuesta en milisegundos y consumo de memoria ultrabajo:

   • Gracias a la compilación nativa de Bun, la respuesta de la API es de 1,5 ms y la memoria residente es de ~32 MB de heap JS / ~140 MB en total. Reduce al mínimo el tiempo de espera de los agentes de IA.

3. 📦 Totalmente todo en uno y cero middleware:

   • No se necesita Redis, PostgreSQL ni colas de trabajadores externas. Basta con un único binario / un único contenedor.

4. 🛡️ Distroless (sin shell) y seguridad estricta:

   • La imagen base es gcr.io/distroless/cc-debian12. No hay /bin/sh, bash ni curl en el contenedor, lo que neutraliza los ataques RCE (ejecución de código arbitrario).

   • Bloqueo de SSRF / DNS Rebinding, prevención de ataques de temporización mediante comparación en tiempo constante, separación de la propiedad de las sesiones del navegador y defensa contra DoS (límite de cuerpo de 10 MB) de serie.

5. 🕹️ DSL de operación del navegador con estado:

   • Control directo de sesiones de navegador interactivas de varios turnos (open → fill → click → screenshot → evaluate) desde la API / MCP.

📊 Comparación de rendimiento y arquitectura

⏱️ Velocidad de respuesta medida de cada endpoint (Latencia medida: frío vs. caché)

Lista de latencias medidas en un servidor local real para «primera obtención (sin caché)» y «cuando hay acierto de caché». Responde de forma abrumadoramente más rápida en comparación con el tiempo que tarda un agente de IA en pensar y generar (1-3 segundos).

⚡ Velocidad medida de los procesos internos de enriquecimiento y optimización para IA (Latencia en memoria)

Todo se completa en menos de 1 milisegundo (< 1 ms) gracias a los algoritmos nativos y optimizados de Bun, sin pasar por APIs de LLM externas.

🏛️ Filosofía de diseño (Principios y filosofía de diseño)

Sora se ha construido sobre los siguientes 4 principios de diseño fundamentales:

1. ✂️ La navaja de Occam (Occam's Razor y cero middleware):

   • «No se deben afirmar más cosas de las necesarias. La configuración más simple que cumpla los requisitos es la mejor configuración.»

   • Se eliminan por completo Redis, PostgreSQL, colas externas y pesados conjuntos de microservicios. Funciona con «un único contenedor y un único binario» y permanece estable desde un VPS de 800 yenes al mes o una Raspberry Pi hasta una nube con decenas de miles de peticiones.

2. 🛡️ Óptimo de Pareto entre sigilo y tasa de supervivencia (Stealth y Pareto Optimum):

   • Si simplemente se accede mecánicamente con «0 ms», el WAF o Cloudflare del servidor de destino bloqueará la IP inmediatamente y la tasa de éxito caerá al 0%.

   • Se inserta automáticamente un retraso de 150 ms + jitter (fluctuación de 0-100 ms) en los accesos consecutivos al mismo dominio, y se añade un retraso humano de 15-40 ms a la escritura. Se da prioridad absoluta a la tasa de supervivencia para traer los datos de vuelta de forma fiable sin perjudicar la velocidad percibida por la IA.

3. 🔒 Seguridad robusta gracias a Distroless (Distroless by Design):

   • Como no hay /bin/sh, bash, curl ni apt en el contenedor, aunque exista una vulnerabilidad desconocida, el atacante no tiene espacio para tomar el control del shell (RCE: ejecución de código arbitrario) por principio. La ejecución no root y el bloqueo estricto de SSRF son estándar.

4. 🗾 Conexión directa con datos abiertos públicos, sostenibilidad (Sostenible y autónomo):

   • La previsión meteorológica se obtiene accediendo directamente al CDN de datos abiertos oficiales de la Agencia Meteorológica (jma.go.jp). La resolución automática en cero milisegundos de los 1.805 municipios de todo el país y la caché LRU de 30 minutos minimizan la carga en el servidor de destino mientras se mantiene un funcionamiento autónomo permanente.

1. Inicio rápido

1.1 Arranque del contenedor (Docker / Podman)

Puedes arrancarlo al instante con un solo comando desde el Registro de Contenedores de GitHub (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 Configuración del cliente MCP (Claude Desktop / Cursor / Cline / Windsurf, etc.)

Conexión Streamable HTTP (recomendada y estándar)

Añade lo siguiente al archivo de configuración (por ejemplo, claude_desktop_config.json o la configuración MCP de Cursor):

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

Conexión SSE (para clientes SSE heredados)

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

(※ Si no se ha configurado la clave de API, se puede omitir headers)

2. Lista de herramientas MCP proporcionadas (16 herramientas en total / 4 módulos)

Sora se compone de 4 módulos lógicos según el propósito. Puedes personalizar libremente las categorías activadas con la variable de entorno ENABLED_MODULES (por defecto: all, o 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│                │
└─────────────────┴───────────────────┴──────────────────┴─────────────────┘

🌐 Módulo 1: Core Web y rastreo (ENABLED_MODULES=web)

Búsqueda web y scraping del cuerpo del texto, obtención paralela masiva, búsqueda integrada profunda, análisis de sitemaps y rastreo recursivo.

💡 Prácticas recomendadas para la integración con LLM / Agent y guía de ajuste de limit

Al utilizar la búsqueda web, el raspado y el rastreo en agentes o aplicaciones RAG, la configuración del número de resultados (limit) afecta significativamente a la latencia y a la calidad de las respuestas.

1. Ventajas y desventajas de aumentar el número de resultados

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] 🇯🇵 Compatibilidad automática con sitios japoneses heredados: Los sitios web con Shift_JIS (CP932) o EUC-JP también se decodifican mediante detección automática del juego de caracteres. No hay que preocuparse por caracteres corruptos.

📄 Extracción de PDF mejorada: Los documentos PDF de varias páginas se generan como Markdown estructurado con separadores de número de página, como <!-- Page 1 -->\n## Page 1, y también se extraen automáticamente metadatos como totalPages o el autor.

✂️ Recorte seguro con sintaxis válida y estimación de tokens: Incluso cuando se limita el número de caracteres con maxChars, los bloques de código abiertos ( ```) o las tablas se corrigen y cierran automáticamente de forma segura. Además, la respuesta incluye el número estimado de tokens de LLM estimatedTokens.

🧩 Fragmentación semántica optimizada para RAG (chunkMarkdown: true): Se generan automáticamente chunks: [{ index, heading, content, estimatedTokens }] divididos correctamente sin romper la jerarquía de encabezados (H1-H4), párrafos o bloques de código, listos para su uso inmediato en búsqueda vectorial o RAG.

🖼️ Metadatos de imagen y extracción de pies de foto (formats: ["images"]): Para cada imagen, además de la URL, se extraen automáticamente la descripción de <figcaption> (caption), width/height y la detección de imagen principal (isMainImage).

🔗 Verificación de integridad y accesibilidad de enlaces internos (validateLinks: true): Se realiza una verificación paralela ligera de los enlaces de la página y se devuelve el estado HTTP y la validez en linksWithStatus: [{ url, status, ok }].

📚 Extracción estructurada de fuentes y citas (extractCitations: true): Los enlaces externos y referencias del texto se extraen automáticamente con su contexto en citations: [{ text, url, context }].

⏱️ Tiempo de lectura y estadísticas de caracteres y palabras: Se calculan y añaden automáticamente characterCount, wordCount y el tiempo de lectura estimado readingTimeMin (en minutos) según las características del idioma.

🔔 Callback asíncrono por Webhook (webhookUrl): Cuando se completan procesos por lotes de larga duración o rastreos a gran escala, se envía una notificación HTTP POST asíncrona con el payload de resultados al endpoint especificado.

🛡️ Enmascaramiento automático de PII (maskPii: true): Información confidencial como direcciones de correo electrónico, números de teléfono japoneses y números de tarjeta de crédito (validación de Luhn) se enmascara automáticamente como [EMAIL], [PHONE], [CREDIT_CARD] para proteger el envío al LLM.

📡 Transmisión SSE de progreso en tiempo real (POST /scrape/stream): Se pueden recibir en tiempo real los eventos de progreso de cada etapa (start → fetch → render → enrich → done) mediante Server-Sent Events.

🎬 Metadatos de YouTube / medios de video y extracción de capítulos (media): Se extraen automáticamente de las páginas de video la duración, la miniatura y la lista de capítulos (índice con marcas de tiempo).

🤖 Generación automática de XML de prompt optimizado para LLM (formatAsPrompt: true): Se genera automáticamente un contenedor de contexto promptContext en el formato estándar <web_page url="..." title="...">...</web_page> que Claude / GPT / Gemini entienden más fácilmente.

🖍️ Resaltado automático de palabras clave de búsqueda en el texto (highlightMatches: true): Se puede obtener highlightedContent con las palabras clave de la query especificada resaltadas como <mark>palabra clave</mark> en el Markdown del texto.

📊 Extracción JSON estructurada de tablas (formats: ["tables"]): Las tablas (<table>) de la página se pueden obtener directamente como una matriz JSON estructurada { caption, headers, rows }.

⚡ Resumen automático de extracción ultrarrápido (extractSummary: true): Sin llamar a una API LLM externa, se generan automáticamente frases importantes (resumen TL;DR) summary: string[] en milisegundos mediante un algoritmo interno.

🎯 Deduplicación de resultados de búsqueda (dedup: true): En búsquedas de noticias o búsquedas en tiempo real, las publicaciones copiadas o los artículos republicados se eliminan automáticamente mediante la detección de similitud, seleccionando solo información única.

🔄 Política de reintentos automáticos (retries y retryDelayMs): En caso de fallos de conexión o errores 429/503, se reintenta automáticamente con retroceso exponencial para mejorar la tolerancia a fallos.

📸 Captura de pantalla de elemento específico (clipSelector): Al especificar un elemento concreto (por ejemplo, clipSelector: "#stock-chart"), se puede obtener un PNG Base64 recortado solo de ese elemento.

🍪 Inyección de encabezados personalizados y cookies (headers / cookies): Se pueden enviar de forma transparente a sitios de membresía, especificación de idioma (Accept-Language), cookies de verificación de edad, etc.

🧹 Eliminación de selectores de ruido especificados por el usuario (removeSelectors): Se puede especificar removeSelectors: [".ad", ".comments", "#related-articles"] para purgar por completo bloques específicos antes de la conversión a Markdown.

📖 Documentación de API interactiva (GET /docs): Al acceder desde el navegador a http://localhost:3016/docs, se pueden probar y ejecutar directamente todas las API desde Swagger UI (Try it out).

3.2.1 Scraping paralelo por lotes de múltiples URL (POST /scrape/batch)

Especifica varias URL de páginas web y las obtiene de forma masiva con un fetch paralelo rápido en el servidor, manteniendo la limitación de velocidad por dominio.

• Solicitud (POST):

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

• Ejemplo de respuesta:

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

3.3 Operación automática del navegador interactivo (POST /browser/action o POST /action)

Abre una página web y ejecuta secuencialmente una serie de acciones como clics, entrada de texto, desplazamiento, espera y captura de pantalla para obtener el resultado final. Admite tanto la ejecución de una sola vez como la sesión de diálogo interactivo de múltiples turnos con estado (sessionId) para operar mientras se conversa en el chat.

① Ejecución de una sola vez (completada en una sola vez)

• Solicitud (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
}

• Ejemplo de respuesta:

{
  "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
}

② Sesión de diálogo interactivo con estado (para chat interactivo)

• Turno 1 (creación de sesión y apertura de pantalla):

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

(En la respuesta se devuelve "sessionId": "sess_a1b2c3d4")

• Turno 2 (continuar operando en la pantalla abierta):

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

• Turno 3 (fin de sesión y limpieza):

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

(※ Si la operación se interrumpe durante 5 minutos, también se libera la memoria de forma segura mediante un tiempo de espera automático)

3.4 Búsqueda profunda integrada (POST /search) y búsqueda web (POST /search/web)

• Solicitud de búsqueda profunda (POST /search):

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

• Para obtener en formato HTML:

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

• Para extraer solo los aspectos más destacados importantes (modo de ahorro de tokens):

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

• Solicitud de búsqueda web (POST /search/web):

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

3.4.1 Exploración del mapa del sitio (POST /map)

Explora el sitemap.xml o los enlaces internos del dominio especificado y extrae la lista de todas las URL del sitio.

• Solicitud:

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

3.4.2 Rastreo recursivo de subpáginas (POST /crawl y POST /crawl/stream)

Recorre de forma recursiva las páginas descendientes desde la URL especificada y recopila de forma masiva Markdown/HTML/imágenes/datos estructurados de varias páginas. Admite el filtrado con comodines Glob mediante includePatterns / excludePatterns.

• Solicitud (obtención masiva):

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

• Streaming SSE (POST /crawl/stream): Se transmiten en tiempo real Server-Sent Events (start -> page -> done) cada vez que se obtiene una página.

3.5 Búsqueda de imágenes, vídeos, noticias, Chiebukuro y sugerencias

• Búsqueda de imágenes (POST /search/image): { "query": "Monte Fuji", "limit": 10 }

• Búsqueda de vídeos (POST /search/video): { "query": "receta fácil", "limit": 10 }

• Búsqueda de noticias (POST /search/news): { "query": "robot IA", "limit": 10 }

• Preguntas y respuestas de Chiebukuro (POST /search/chiebukuro): { "query": "programación principiante", "limit": 10, "status": "solved" }

• Autocompletado de palabras clave (POST /search/suggest): { "query": "clima", "limit": 10 }

3.6 Indicaciones de transbordo de trenes (POST /transit/route)

• Solicitud:

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

• Ejemplo de respuesta:

{
  "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 Pronóstico del tiempo para todo Japón (POST /weather / GET /weather / GET /weather/:city)

Analiza directamente la API oficial de datos abiertos de la Agencia Meteorológica de Japón (y el formato compatible con livedoor weather) y obtiene de forma totalmente autónoma los datos meteorológicos detallados de hoy, mañana y pasado mañana para todo Japón.

Ventajas de esta función (Features & Advantages)

• Totalmente autónomo y conectado directamente a la fuente oficial (cero dependencias): Obtiene y analiza los datos meteorológicos directamente desde el CDN oficial de la Agencia Meteorológica de Japón (jma.go.jp).

• Resolución automática inteligente de los 1.805 municipios de Japón: Incluye la definición de áreas oficial de la Agencia Meteorológica de Japón (area.json). Selecciona automáticamente en 0 ms el ID de punto de la estación meteorológica responsable para nombres de municipios y lugares famosos como "Tendō", "Karuizawa", "Hakone", "Urayasu" o "Beppu". También admite entradas sin nombre de prefectura.

• Datos estructurados aptos para agentes de IA: Obtiene en un solo JSON limpio los titulares meteorológicos de 3 días, viento y olas, temperaturas máximas/mínimas previstas (°C), probabilidad de precipitación por franja horaria (0-6 h, 6-12 h, 12-18 h, 18-24 h) y el texto de la situación meteorológica general publicado por la estación meteorológica (título y cuerpo).

• Respuesta ultrarrápida con caché LRU: Incluye de serie una caché LRU en memoria de 30 minutos para evitar automáticamente accesos duplicados innecesarios al servidor de la Agencia Meteorológica.

• Solicitud (POST):

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

• Solicitud GET: GET /weather?city=Karuizawa&days=2 o GET /weather/Hakone

• Ejemplo de respuesta:

{
  "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 Búsqueda en tiempo real y tendencias de Yahoo (POST /search/realtime / POST /search/trend)

• Búsqueda en tiempo real (POST /search/realtime): { "query": "nombre del evento", "sort": "popular", "limit": 20, "page": 1 }

  • sort: "recent" (por orden de novedad, predeterminado) o "popular" (por orden de popularidad / participación)

  • A cada publicación se le añaden automáticamente publishedTime (cadena ISO 8601), author (nombre de usuario + @nombre de cuenta) y siteName: "X (Twitter)" en un formato unificado.

• Tendencias en aumento (POST /search/trend): { "limit": 20 }

3.9 Mapa del sitio y rastreo (POST /map / POST /crawl)

• Mapa del sitio (POST /map): { "url": "https://example.com", "limit": 200 }

• Rastreo recursivo (POST /crawl): { "url": "https://example.com/docs", "maxPages": 10 }

4. Seguridad y arquitectura

4.1 Diseño de contenedor sin distribución (Distroless)

• Imagen base: gcr.io/distroless/cc-debian12

• Sin shell ni gestor de paquetes: En el contenedor no existe /bin/sh, apt ni curl, por lo que el atacante no tiene ninguna posibilidad de hacerse con un shell.

• Diseño de privilegios mínimos: Admite la ejecución sin root y se puede aislar y ejecutar de forma segura en entornos de contenedores estándar como Docker / Podman / Kubernetes.

4.2 Funciones de seguridad y rendimiento

• 🛡️ Defensa múltiple contra SSRF y DNS Rebinding:

  • Bloquea el acceso interno a IPs privadas (como 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), direcciones especiales IPv6 y la IP de metadatos de la nube (169.254.169.254).

  • Realiza una resolución previa de nombres con dns.promises.lookup y bloquea inmediatamente antes de la conexión los ataques de DNS Rebinding mediante suplantación de dominio.

• ⚡ Caché de vuelo único (deduplicación en vuelo):

  • Cuando se producen solicitudes paralelas a la misma URL, se comparte la Promise y se agrupan en una sola comunicación externa. Evita el efecto rebaño (estampida de caché) y protege los servidores externos y los recursos locales.

• 🚦 Límite de ejecución simultánea del navegador (Control de concurrencia):

  • SimpleSemaphore controla de forma segura el número de procesos Chromium simultáneos (MAX_CONCURRENT_BROWSERS, por defecto 5), evitando el agotamiento de CPU/memoria del servidor.

• 🔒 Autenticación Timing-Safe y vinculación de propiedad de la sesión del navegador:

  • Para la verificación de la clave API se utiliza crypto.timingSafeEqual + SHA-256 (comparación en tiempo constante) para defenderse de los ataques de temporización.

  • Las sesiones de navegador de múltiples turnos (sessionId) se vinculan criptográficamente al token del creador, evitando que otros tomen el control de la sesión.

• 🛡️ Interruptor de control seguro para la ejecución de JavaScript arbitrario (ALLOW_BROWSER_EVALUATE):

  • Con la variable de entorno ALLOW_BROWSER_EVALUATE=false o SAFE_BROWSER_MODE=true, se puede desactivar y bloquear inmediatamente la ejecución de scripts evaluate en /browser/action.

• 📐 Esquema Zod común y generación automática completa de OpenAPI 3.0:

  • Se unifica la validación de entrada mediante esquemas Zod tanto en REST como en MCP.

  • /openapi.json genera dinámicamente al 100% la especificación OpenAPI 3.0 a partir de los esquemas Zod del código, evitando por completo la divergencia de la documentación.

  • Las respuestas de error proporcionan una estructura fácil de auto-reparar y decidir de forma autónoma para los agentes de IA, como { "error": "...", "code": "SSRF_BLOCKED", "status": 403, "retryable": false }.

• ⏱️ Limitación de velocidad con jitter y caché LRU real:

  • Suprime automáticamente el acceso excesivo y continuo al mismo dominio con 150 ms + Jitter (fluctuación de 0 a 100 ms).

  • Con una caché LRU real (actualización en el momento del acceso) de 15 a 30 minutos y un barrido periódico de TTL cada 10 minutos, se evita por completo la fuga de memoria.

5. Agradecimientos y créditos

Sora se apoya en las excelentes contribuciones de los siguientes proyectos de código abierto, servicios públicos, datos abiertos públicos y autores de bibliotecas. Les estamos profundamente agradecidos.

🗾 Fuentes de datos e inspiración

• Datos abiertos de la Agencia Meteorológica de Japón (JMA): jma.go.jp

  • Agradecemos profundamente la publicación abierta de los datos meteorológicos y de prevención de desastres de alta precisión de todo Japón, así como los datos de definición de más de 1.800 áreas.

• Inspiración de diseño de la API de pronóstico del tiempo (compatible con livedoor): tsukumijima/weather-api / weather.tsukumijima.net

  • Agradecemos el diseño de esquema claro del formato compatible con livedoor y su contribución a la comunidad durante muchos años.

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

  • Agradecemos la implementación MCP de la búsqueda de imágenes, vídeos, noticias, Chiebukuro y sugerencias de Yahoo! JAPAN.

• norikae-mcp: tysonwu/norikae-mcp

  • Agradecemos el diseño e implementación de la lógica de indicaciones de transbordo mediante el scraping de la información de rutas de Yahoo!

🛠️ Código abierto y bibliotecas base (Core Libraries & Ecosystem)

• Hono (@yusukebe) — Framework de API web ultrarrápido e integración MCP

• Puppeteer (Google Chrome Team) — Control de Chromium sin interfaz y operación sigilosa

• Readability (Mozilla) — Motor de extracción del texto del artículo en modo lector

• Cheerio (cheeriojs team) — Análisis DOM rápido y extracción de metadatos

• Turndown (Dom Christie) — Conversor de HTML a Markdown

• LinkeDOM (Andrea Giammarchi) — Motor DOM en memoria ultraligero

• unpdf (UnJS Team) — Extracción de texto PDF rápida y ligera

• Model Context Protocol SDK (Anthropic / MCP Team) — Estándar de conexión de herramientas de IA de próxima generación

6. Descargo de responsabilidad

• Herramienta no oficial de terceros:

  • Este software es una herramienta no oficial (de terceros) desarrollada con fines de desarrollo personal, investigación académica y uso interno de la empresa.

• Sobre las marcas comerciales:

  • «Yahoo!», «Yahoo! JAPAN» y los nombres de cada servicio son marcas comerciales o marcas registradas de LINE Yahoo Corporation. Este proyecto no tiene ninguna relación con LINE Yahoo Corporation.

• Cumplimiento de los términos de uso y las leyes:

  • Al acceder a cada servicio externo (Yahoo! JAPAN, Agencia Meteorológica de Japón, etc.), cumple con los términos de uso, las directrices, el robots.txt y las leyes aplicables del servicio de destino, y úsalo bajo tu propia responsabilidad para no sobrecargarlo.

• Limitación de responsabilidad:

  • Los desarrolladores de este proyecto no asumen ninguna responsabilidad por cualquier daño que pueda surgir del uso de este software (incluyendo la restricción de acceso del servicio de destino, la integridad, exactitud o actualidad de los datos).

7. Licencia

Este software se publica bajo la Business Source License 1.1 (BSL 1.1 / BUSL-1.1).

• Usos permitidos de forma libre y gratuita:

  • Desarrollo personal, investigación académica, uso no comercial

  • Uso de autoalojamiento para sistemas propios dentro de la empresa u organización (funcionar como backend interno que respalda productos propios o herramientas internas)

  • Modificación, bifurcación y uso compartido interno del código fuente

• Restricción:

  • Proporcionar o revender este software (o sus derivados) como «servicio en la nube de pago», «servicio de scraping / API de búsqueda de pago» o «servicio gestionado» para terceros.

• Fecha de cambio (fecha de conversión a código abierto):

  • Se convertirá automáticamente a una licencia MIT completa el 1 de agosto de 2030 (o antes).

Para más detalles, consulta LICENSE.

Copyright (c) 2026 ikeno