Sora (空)

Self-hosted MCP-/REST-Integrationsserver für die Nutzung des japanischen Webs durch KI-Agenten
All-in-One, Zero-Middleware Web Scraping & Japanese Life Infrastructure Engine for AI Agents

Sora ist ein All-in-One-MCP-/REST-Server, der es LLMs und KI-Agenten (Claude Desktop, Cursor, Cline, OpenCodeInterpreter, Dify usw.) ermöglicht, den japanischen Webraum und die alltägliche Infrastruktur frei und sicher zu erkunden und zu bedienen.

Ohne externe Datenbanken (Redis / PostgreSQL) oder Message Queues ist keinerlei zusätzliche Infrastruktur nötig: Schon ein einziger Container / ein einzelnes Binary – mit Headless-Chromium und japanischen CJK-Schriften inklusive – läuft sofort auf einem VPS für 800 Yen pro Monat.

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

⚡ Schnellstart in 5 Sekunden (Claude Desktop / Cursor / Cline)

Fügen Sie einfach die folgenden Zeilen in die Konfigurationsdatei Ihres KI-Agenten (z. B. claude_desktop_config.json) ein, um die 16 leistungsstarken Tools sofort zu aktivieren.

Remote-MCP-Verbindung (HTTP / SSE)

Geben Sie die URL bei laufendem Sora-Container an:

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

Ein-Befehl-Start mit Docker / Podman

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

Related MCP server: Agent Toolbox

🌟 Hauptfunktionen und Vorteile (Why Sora?)

1. 🗾 Vollständige Abdeckung des japanischen Alltags und der Web-Erkundung:

   • In einem einzigen MCP werden „Yahoo! 知恵袋", „X (Twitter) Realtime-Meldungen", „direkte Anbindung an die offiziellen Open Data und 気象庁 (automatische Auswahl der 1.805 Städte und Gemeinden Japans)" sowie „Zugverbindungsauskunft" bereitgestellt – Dinge, die ausländische Tools wie Firecrawl / Tavily nicht abdecken können.

2. ⚡ Überragende Millisekunden-Antwortzeiten und minimaler Speicherverbrauch:

   • Durch nativen Bun-Komplex liegt die API-Antwort bei 1,5 ms; der belegte Speicher liegt bei JS-Heap ~32 MB / gesamt ~140 MB. Dadurch wird die Wartezeit für KI-Aggressagen minimiert.

3. 📦 Vollständig All-in-One & Zero-Middleware:

   • Redis, PostgreSQL, externe Worker-Queues usw. werden vollständig entfernt. Ein einzelnes Binary / ein einzelner Container genügt für den sofortigen Betrieb.

4. 🛡️ Distroless (ohne Shell) und strikte Sicherheit:

   • Als Basis-Image wird gcr.io/distroless/cc-debian12 verwendet. Da im Container kein /bin/sh, bash, curl usw. vorhanden ist, werden RCE-Angriffe (unerlaubte Code-Ausführung) unwirksam.

   • SSRF-/DNS-Rebinding-Blockade, Schutz vor Timing-Angriffen durch Konstant-Zeit-Vergleich, Trennung der Browser-Session-Besitzverhältnisse und DoS-Schutz (Body-Limit 10 MB) sind serienmäßig.

5. 🕹️ DSL für statusbasierte Browser-Operationen:

   • Direkte Steuerung AWS Aktionen open → fill → click → screenshot Library → evaluate über mehrere Runden interaktiver Browser-Sessions per API / MCP.

📊 Performance- und Architekturvergleich

⏱️ Gemessene Antwortzeiten der Endpunkte (Measured Latency: Cold vs Cached)

Hier sind die gemessenen Latenzen beim ersten Abruf (ohne Cache) und bei Cache-Treff auf einem echten lokalen Server. Im Vergleich zur Zeit, die ein KI-Agent für Denken und Text** (1–3 Sekunden) braucht, antwortet Sora extrem schnell .

⚡ Messzeiten der internen Anreicherungs-/KI-Optimierung (In-Memory Latency)

Diese Prozesse laufen vollständig über Bun-Native und optimierte Algorithmen – in unter 1 ms – ohne externe LLM-API.

🏛️ Design-Philosophie (Design Principles & Principles – Prinzipien)

1. ✂️ Occam's Razor (Occam's Razor-Prinzip) / Zero-Middleware:

   • „Wenn du nicht nötig bist, solltest du nicht viele Dinge setzen. Die einfachste Konfiguration, die die Anforderungen erfüllt , ist die beste."

   • Verzicht ohne Redis, PostgreSQL, externe Queues und Mini-Dienste. Nur ein einzelner Container / ein einzelnes Binary funktioniert. Läuft selakt auf einem VPSNode (800 EUR/Monat) sowie in der Cloud mit 100k Anfragen, ohne auszuhalten.

2. 🛡️ Stealth and Return-Rate Pareto-Optimum (Stealth & Pareto Optimum):

   • Bei einem „0-ms mechanischer Zugriff"" wird eine IP meist von WAF / Cloudflare gebannt; die Erfolgsquote fällt auf 0 %.

   • Bei aufeinanderfolgenden Aufrufen zur selben Hostname 150 ms + Jitter (0–100 ms) und für Tipp-Eingaben 15–0–30 ms humane Verzögerung automatisch mit ein. Zulasten der empfandenen Werkt? – garantiert: „Return-Rate" = Sie bringen die Daten zuverlässig mit.

3. 🔒 Starkes Sicherheit durch Distroless (Distroless by Design):

   • Da /bin/sh, bash, curl, apt im Container nicht existieren, gibt es selbst bei unbekannter Lücke für Angreifer keine Wege, eine Code-Ausführung (RCE) zu erzielen. Immer non-root und starker SSRF-Eck-** block.

4. 🗾 Direkte-Bindung an öffentliche Open Data &Sustainability:

   • Der Wetterbericht greift auf die offizielle CDN-Open-Data von 気象庁 ( jmpa.go.jp ). Die 1.805 japanischen Cities/Voide werden per 30-Minute LRU-Cached, und das System: Läuft dauerhaft ohne die Lastquotes auf Gegenstelle zu erhöhen.

1. Quickstart mit 1

1.1 Container starten (Docker / Podman)

Sohne Endlosschleife: von der 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-Klienten selbst einrichten (Claude Desktop / Cursor / Cline / Windsurf)

Streamable HTTP-Connection (empfohlen, Stand)

Ergänzung in der Datei claude_desktop_config.json oder Cursor MCP-Config:

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

SSE-Verbindung (für ältere SSE-Clients)

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

(Wenn kein API-Key eingestellt ist, kann headers weggelassen werden.)

2. Bereitgestellte MCP-Werkzeuge (alle 16 Tools / 4 Module)

Sora ist in **jeweiliges 4 log- wise **Modules aufgeteilt. Über ENABLED_MODULES (Standardgröße:all, oder web,browser,yahoo,life) können Sie die aktiveModule frei konfigurieren.

┌──────────────────────────────────────────────────────────────────────────┐
│                         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│                │
└─────────────────┴───────────────────┴──────────────────┴─────────────────┘

🌐 Module 1: Core Web & Crawling (ENABLED_MODULES=web)

Web-Suche und Text-Text-Scraping, paralleler Sammelaufruf, tiefe integrierte Suche, Sitemap-Parsing, rekursiver Crawler.

💡 Best Practices für die LLM-/Agent-Integration & Leitfaden zur limit-Anpassung

Wenn Sie Websuche, Scraping und Crawling in Agenten- oder RAG-Anwendungen nutzen, ändern sich Latenz und Antwortqualität je nach Einstellung der Abrufmenge (limit) erheblich.

1. Vor- und Nachteile einer höheren Abrufmenge

2. Best Practices für den effektivsten LLM-Einsatz

[!TIP] Effektiverer Ansatz:

1. Getrennte Verwendung von Snippets und Volltext: Die Such-Snippets (search_web) selbst sollten 10–20 Treffer zurückgeben, um einen breiten Überblick zu erhalten, während die Volltext-Scraping-Ziele (search_deep mit limit) auf die obersten 3–5 Treffer begrenzt werden sollten – das ist am schnellsten und präzisesten.

2. Kombinierte Highlight-Extraktion: Durch Aktivierung von extractHighlights: true (mit query-Angabe) kann die Structure & Proximity-Aware BM25+-Engine (Überschriften-Kontextvererbung, exakter Phrasenabgleich, Proximity-Scoring, KWIC-Snippet-Generierung) dem LLM ermöglichen, sich statt der gesamten langen Seite nur auf die wichtigsten Absätze und Sätze zu konzentrieren, die für die Abfrage relevant sind. Dadurch werden Halluzinationen verhindert und der Token-Verbrauch um 70–90 % reduziert (kein externes LLM erforderlich, läuft lokal in 0,3 ms).

3. Gemeinsame Metadaten für alle Endpunkte (Firecrawl / Tavily-kompatibel): publishedTime (Veröffentlichungs-/Aktualisierungszeitpunkt), author (Autorenname) und siteName (Seitenname) werden automatisch aus OGP / JSON-LD / HTML-Meta-Tags extrahiert und in Frontmatter sowie JSON-Antworten eingefügt. Das LLM kann so die Aktualität von Informationen (Faktencheck) sofort beurteilen.

4. Beibehaltung der GFM-Syntaxhervorhebungs-Sprachen: Programmiersprachennamen werden aus <pre><code class="language-python"> usw. präzise identifiziert und in der Markdown-Ausgabe als ```python reproduziert.

5. Automatische Token-Kompression & Rauschunterdrückung: Leere Links, ungültige JavaScript-Links und unnötige doppelte Leerzeilen werden automatisch bereinigt (cleanMarkdownTokens), und Cookie-Einwilligungsbanner (OneTrust / Cookiebot usw.) werden vollständig entfernt, sodass der LLM-Kontext stets sauber bleibt.

6. Automatische robots.txt-Sitemap-Erkennung: Unregelmäßig platzierte Sitemap-URLs werden automatisch aus /robots.txt erkannt, und Sitemap-Indizes werden rekursiv bis zu maximal 1.000 Einträgen durchsucht.

7. Streaming beim Crawlen: Beim Durchlaufen vieler Seiten kann POST /crawl/stream (SSE) verwendet werden, um jede Seite unmittelbar nach Abschluss des Abrufs sequenziell zu empfangen und zu verarbeiten. So können Zwischenantworten sofort an Benutzer oder LLM zurückgegeben werden, ohne auf den Abschluss des gesamten Vorgangs warten zu müssen.

3. Gemessene Benchmarks und Skalierbarkeitseigenschaften (lokale Messwerte)

🤖 Modul 2: Browser-Aktionen & Automatisierung (ENABLED_MODULES=browser)

Formulareingaben, Button-Klicks, Bildschirm-Scrolling, JavaScript-Ausführung, Screenshot-Aufnahme, Multi-Turn-Dialog-Sitzungen.

🇯🇵 Modul 3: Yahoo! JAPAN-Dienste (ENABLED_MODULES=yahoo)

Eine Suchgruppe, die vollständig auf japanische Medien, Q&A, Trends und Echtzeitinformationen spezialisiert ist.

🗾 Modul 4: Japan Alltag & Verkehr (ENABLED_MODULES=life)

Lebensinfrastruktur-Funktionen mit direkter Anbindung an japanische öffentliche Verkehrsmittel und offizielle offene Daten der Japan Meteorological Agency.

3. REST-API-Spezifikation

Basis-URL: http://localhost:3016 (oder die Domain-URL des Deployment-Ziels)

3.1 Health-Check & Metriken

GET /health

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

GET /metrics (Betriebsstatistiken, Cache-Trefferquote, Ressourcennutzung)

{
  "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 oder Accept: text/plain (Metriken für Prometheus-Überwachung)

Gibt im Standard-Textformat aus, das direkt in einen Grafana-/Prometheus-Überwachungsstack übernommen werden kann.

# 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 Einzel-URL-/PDF-Scraping (POST /scrape)

• Anfrage:

{
  "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": "新機能 リリース"
}

• Beispielantwort:

{
  "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] 🇯🇵 Automatische Unterstützung für japanische Legacy-Websites: Auch Websites mit Shift_JIS (CP932) oder EUC-JP werden durch automatische Erkennung des Zeichensatzes dekodiert. Keine Sorge um Zeichensalat (Mojibake).

📄 Erweiterte PDF-Extraktion: Mehrseitige PDF-Dokumente werden als strukturiertes Markdown mit Seitenzahl-Trennern wie <!-- Page 1 -->\n## Page 1 ausgegeben, und Metadaten wie totalPages oder der Autor werden automatisch extrahiert.

✂️ Syntaxsichere Kürzung & Token-Schätzung: Auch bei einer Zeichenbegrenzung durch maxChars werden geöffnete Codeblöcke (```) oder Tabellen automatisch sicher korrigiert bzw. geschlossen. Zudem wird der geschätzte LLM-Token-Anzahl estimatedTokens in der Antwort mitgeliefert.

🧩 RAG-optimiertes semantisches Chunking (chunkMarkdown: true): Es werden automatisch chunks: [{ index, heading, content, estimatedTokens }] generiert, die ohne Beschädigung der Überschriftenhierarchie (H1–H4) oder von Absätzen und Codeblöcken sinnvoll aufgeteilt sind und sofort in Vektorsuche oder RAG eingespeist werden können.

🖼️ Bild-Metadaten & Caption-Extraktion (formats: ["images"]): Für jedes Bild werden zusätzlich zur URL die Beschreibung aus <figcaption> (caption), width/height sowie die Erkennung des Hauptbildes (isMainImage) automatisch extrahiert.

🔗 Prüfung der Integrität & Erreichbarkeit interner Links (validateLinks: true): Links innerhalb der Seite werden einer leichten parallelen Validierung unterzogen, und HTTP-Status sowie Gültigkeit werden als linksWithStatus: [{ url, status, ok }] zurückgegeben.

📚 Strukturierte Extraktion von Quellen- und Zitatlinks (extractCitations: true): Externe Links und Referenzen im Text werden automatisch mit Kontextsatz als citations: [{ text, url, context }] extrahiert.

⏱️ Lesezeit & Zeichen-/Wortstatistik: Aus dem Text werden automatisch characterCount, wordCount sowie die geschätzte Lesezeit readingTimeMin (in Minuten) basierend auf den Spracheigenschaften berechnet und hinzugefügt.

🔔 Asynchroner Webhook-Callback (webhookUrl): Bei langwierigen Batch-Verarbeitungen oder Abschluss großer Crawls wird das Ergebnis-Payload per HTTP POST asynchron an den angegebenen Endpunkt gesendet.

🛡️ Automatische PII-Maskierung (maskPii: true): Vertrauliche Informationen wie E-Mail-Adressen, japanische Telefonnummern und Kreditkartennummern (Luhn-Prüfung) werden automatisch zu [EMAIL], [PHONE], [CREDIT_CARD] maskiert, um die Übertragung an LLMs zu schützen.

📡 Echtzeit-Fortschritts-SSE-Streaming (POST /scrape/stream): Die Fortschrittsereignisse der einzelnen Phasen start → fetch → render → enrich → done können in Echtzeit über Server-Sent Events empfangen werden.

🎬 YouTube / Video-Media-Metadaten & Kapitel-Extraktion (media): Aus Videoseiten werden automatisch Wiedergabedauer, Thumbnails und eine Kapitelliste (Inhaltsverzeichnis mit Zeitstempeln) strukturiert extrahiert.

🤖 Automatische LLM-optimierte Prompt-XML-Generierung (formatAsPrompt: true): Es wird automatisch ein standardisierter Kontext-Wrapper promptContext im <web_page url="..." title="...">...</web_page>-Format generiert, den Claude / GPT / Gemini am besten verstehen.

🖍️ Automatische Hervorhebung von Suchbegriffen im Text (highlightMatches: true): Der Inhalt highlightedContent kann abgerufen werden, in dem die Schlüsselwörter der angegebenen query im Markdown-Text als <mark>Schlüsselwort</mark> hervorgehoben sind.

📊 Strukturierte JSON-Extraktion von Tabellen (formats: ["tables"]): Die Tabellen (<table>) der Seite können direkt als strukturiertes JSON-Array im Format { caption, headers, rows } abgerufen werden.

⚡ Blitzschnelle extraktive automatische Zusammenfassung (extractSummary: true): Ohne Aufruf einer externen LLM-API werden mit einem internen Algorithmus in Millisekunden wichtige Sätze (TL;DR-Zusammenfassung) als summary: string[] automatisch generiert.

🎯 Deduplizierung von Suchergebnissen (dedup: true): Bei Nachrichten- oder Echtzeitsuchen werden kopierte Beiträge oder weiterverbreitete Artikel automatisch per Ähnlichkeitsprüfung ausgeschlossen, sodass nur einzigartige Informationen ausgewählt werden.

🔄 Automatische Wiederholungsrichtlinie (retries & retryDelayMs): Bei Verbindungsfehlern oder 429/503-Fehlern wird mit exponentiellem Backoff automatisch erneut versucht, was die Ausfallsicherheit erhöht.

📸 Elementbezogener Screenshot (clipSelector): Durch Angabe eines bestimmten Elements (z. B. clipSelector: "#stock-chart") kann ein Base64-PNG nur dieses Elements ausgeschnitten abgerufen werden.

🍪 Benutzerdefinierte Header & Cookie-Injektion (headers / cookies): Für Mitgliederseiten, Sprachangaben (Accept-Language) oder Altersverifikations-Cookies können transparent gesendet werden.

🧹 Entfernung benutzerdefinierter Rausch-Selektoren (removeSelectors): Mit removeSelectors: [".ad", ".comments", "#related-articles"] können bestimmte Blöcke vor der Markdown-Konvertierung gründlich entfernt werden.

📖 Interaktive API-Dokumentation (GET /docs): Wenn Sie im Browser http://localhost:3016/docs aufrufen, können Sie alle APIs direkt über die Swagger UI testen (Try it out).

3.2.1 Batch-Scraping mehrerer URLs parallel (POST /scrape/batch)

Geben Sie mehrere Webseiten-URLs an, und sie werden serverseitig mit hoher Geschwindigkeit parallel abgerufen, wobei das Domain-spezifische Throttling beibehalten wird.

• Anfrage (POST):

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

• Beispielantwort:

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

3.3 Interaktive Browser-Automatisierung (POST /browser/action oder POST /action)

Öffnet eine Webseite und führt nacheinander eine Reihe von Aktionen wie Klicken, Texteingabe, Scrollen, Warten und Screenshot-Aufnahme aus, um das Endergebnis zu erhalten. Unterstützt sowohl die Einmal-Ausführung als auch zustandsbehaftete Multi-Turn-Dialog-Sitzungen (sessionId) für die interaktive Steuerung im Chat.

① Einmal-Ausführung (einmalig abgeschlossen)

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

• Beispielantwort:

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

② Zustandsbehaftete Multi-Turn-Dialog-Sitzung (für interaktiven Chat)

• Turn 1 (Sitzung erstellen & Bildschirm öffnen):

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

(In der Antwort wird "sessionId": "sess_a1b2c3d4" zurückgegeben)

• Turn 2 (Weiter mit der geöffneten Ansicht arbeiten):

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

• Turn 3 (Sitzung beenden & aufräumen):

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

(※ Wenn die Bedienung 5 Minuten lang unterbrochen wird, wird der Speicher durch automatisches Timeout sicher freigegeben)

3.4 Integrierte Tiefensuche (POST /search) & Websuche (POST /search/web)

• Tiefensuch-Anfrage (POST /search):

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

• Bei Abruf im HTML-Format:

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

• Bei Extraktion nur der wichtigen Hervorhebungen (Token-Sparmodus):

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

• Websuch-Anfrage (POST /search/web):

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

3.4.1 Sitemap-Erkundung (POST /map)

Durchsucht die sitemap.xml oder interne Links der angegebenen Domain und extrahiert eine Liste aller URLs innerhalb der Website.

• Anfrage:

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

3.4.2 Rekursives Crawlen von Unterseiten (POST /crawl & POST /crawl/stream)

Durchsucht ausgehend von der angegebenen URL rekursiv die darunterliegenden Seiten und sammelt Markdown/HTML/Bilder/strukturierte Daten mehrerer Seiten in einem Rutsch. Unterstützt Glob-Wildcard-Filterung über includePatterns / excludePatterns.

• Anfrage (Batch-Abruf):

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

• SSE-Streaming (POST /crawl/stream): Sobald eine Seite abgerufen wird, werden Server-Sent Events (start -> page -> done) in Echtzeit gesendet.

3.5 Bild-, Video-, Nachrichten-, Chiebukuro- und Vorschlags-Suche

• Bildersuche (POST /search/image): { "query": "Fuji", "limit": 10 }

• Videosuche (POST /search/video): { "query": "einfaches Rezept", "limit": 10 }

• Nachrichtensuche (POST /search/news): { "query": "KI Roboter", "limit": 10 }

• Chiebukuro Q&A (POST /search/chiebukuro): { "query": "Programmierung Anfänger", "limit": 10, "status": "solved" }

• Schlüsselwort-Vervollständigung (POST /search/suggest): { "query": "Wetter", "limit": 10 }

3.6 Zugverbindungsauskunft (POST /transit/route)

• Anfrage:

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

• Beispielantwort:

{
  "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 Wettervorhersage für ganz Japan (POST /weather / GET /weather / GET /weather/:city)

Analysiert direkt die offiziellen Open-Data-APIs der Japan Meteorological Agency (JMA) (sowie das livedoor-Wetter-kompatible Format) und ruft vollständig autonom detaillierte Wetterdaten für heute, morgen und übermorgen in ganz Japan ab.

Vorteile dieser Funktion (Features & Advantages)

• Vollständig autonom & offiziell angebunden (Null-Abhängigkeit): Ruft Wetterdaten direkt vom offiziellen CDN der JMA (jma.go.jp) ab und parst sie.

• Intelligente automatische Auflösung aller 1.805 Städte und Gemeinden Japans: Die offizielle Gebietsdefinition der JMA (area.json) ist integriert. Aus Städtenamen und bekannten Ortsnamen wie „Tendo", „Karuizawa", „Hakone", „Urayasu" oder „Beppu" wird die Stations-ID der zuständigen Wetterwarte in 0 ms automatisch ausgewählt. Auch Eingaben ohne Präfekturnamen werden unterstützt.

• KI-Agenten-freundliche strukturierte Daten: Wetterbeschreibungen für 3 Tage, Wind und Wellen, voraussichtliche Höchst-/Tiefsttemperaturen (°C), Niederschlagswahrscheinlichkeit nach Zeitfenster (0–6 Uhr, 6–12 Uhr, 12–18 Uhr, 18–24 Uhr) sowie die von der Wetterwarte veröffentlichten allgemeinen Wetterlageberichte (Überschrift und Text) werden in einem sauberen JSON abgerufen.

• Höchstgeschwindigkeit durch LRU-Cache: Ein In-Memory-LRU-Cache für 30 Minuten ist standardmäßig integriert und verhindert unnötige doppelte Zugriffe auf die JMA-Server.

• Anfrage (POST):

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

• GET-Anfrage: GET /weather?city=Karuizawa&days=2 oder GET /weather/Hakone

• Beispielantwort:

{
  "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 Echtzeitsuche & Trends (POST /search/realtime / POST /search/trend)

• Echtzeitsuche (POST /search/realtime): { "query": "Veranstaltungsname", "sort": "popular", "limit": 20, "page": 1 }

  • sort: "recent" (neueste zuerst, Standard) oder "popular" (nach Beliebtheit / Engagement)

  • Jeder Beitrag erhält automatisch publishedTime (ISO-8601-String), author (Benutzername + @Kontoname) und siteName: "X (Twitter)" in einem einheitlichen Format.

• Trends im Aufwind (POST /search/trend): { "limit": 20 }

3.9 Sitemap & Crawl (POST /map / POST /crawl)

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

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

4. Sicherheit & Architektur

4.1 Distroless-Container-Design

• Basis-Image: gcr.io/distroless/cc-debian12

• Keine Shell, kein Paketmanager: Im Container existieren weder /bin/sh noch apt oder curl. Ein Angreifer hat keine Möglichkeit, eine Shell zu übernehmen.

• Prinzip der geringsten Rechte: Unterstützt die Ausführung ohne Root-Rechte und kann sicher in Standard-Containerumgebungen wie Docker / Podman / Kubernetes isoliert und ausgeführt werden.

4.2 Sicherheits- & Leistungsfunktionen

• 🛡️ Mehrfacher SSRF- & DNS-Rebinding-Schutz:

  • Interne Zugriffe auf private IPs (z. B. 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), spezielle IPv6-Adressen und Cloud-Metadaten-IPs (169.254.169.254) werden blockiert.

  • Eine vorherige Namensauflösung über dns.promises.lookup wird durchgeführt, und DNS-Rebinding-Angriffe durch Domain-Täuschung werden ebenfalls vor der Verbindung sofort blockiert.

• ⚡ Single-Flight-Cache (In-flight-Deduplizierung):

  • Bei parallelen Anfragen an dieselbe URL wird das Promise geteilt und auf eine einzige externe Kommunikation reduziert. Dies verhindert Thundering Herd (Cache-Stampede) und schützt externe Server und lokale Ressourcen.

• 🚦 Browser-Concurrency-Limit (Concurrency Control):

  • Mit SimpleSemaphore wird die Anzahl gleichzeitig laufender Chromium-Prozesse (MAX_CONCURRENT_BROWSERS, Standard 5) sicher gesteuert. Dies verhindert die Erschöpfung von CPU/Arbeitsspeicher des Servers.

• 🔒 Timing-sichere Authentifizierung & Zuordnung des Browser-Session-Eigentums:

  • Für den API-Key-Abgleich wird crypto.timingSafeEqual + SHA-256 (Konstantzeitvergleich) verwendet, um Timing-Angriffe zu verhindern.

  • Multi-Turn-Browser-Sitzungen (sessionId) werden kryptografisch mit dem Ersteller-Token verknüpft, um die Übernahme der Sitzung durch andere zu verhindern.

• 🛡️ Sicherer Steuerschalter für beliebige JavaScript-Ausführung (ALLOW_BROWSER_EVALUATE):

  • Durch die Umgebungsvariable ALLOW_BROWSER_EVALUATE=false oder SAFE_BROWSER_MODE=true kann die Ausführung von evaluate-Skripten in /browser/action sofort deaktiviert und gesperrt werden.

• 📐 Gemeinsames Zod-Schema & vollständige automatische OpenAPI-3.0-Generierung:

  • Die Eingabevalidierung wird sowohl für REST als auch für MCP über Zod-Schemata vereinheitlicht.

  • /openapi.json generiert die OpenAPI-3.0-Spezifikation zu 100 % dynamisch aus den Zod-Schemata des Codes und verhindert so vollständig Abweichungen in der Dokumentation.

  • Fehlerantworten sind so strukturiert, dass KI-Agenten sie leicht selbst reparieren und autonom entscheiden können, z. B. { "error": "...", "code": "SSRF_BLOCKED", "status": 403, "retryable": false }.

• ⏱️ Jitter-Throttling & echter LRU-Cache:

  • Übermäßige aufeinanderfolgende Zugriffe auf dieselbe Domain werden automatisch mit 150 ms + Jitter (0–100 ms Schwankung) gedrosselt.

  • Ein echter LRU-Cache (Aktualisierung bei Zugriff) für 15–30 Minuten und ein regelmäßiger TTL-Sweep alle 10 Minuten verhindern Speicherlecks vollständig.

5. Danksagungen (Acknowledgments)

Sora wird von den hervorragenden Beiträgen der folgenden Open-Source-Projekte, öffentlichen Dienste, öffentlichen offenen Daten und Bibliotheksautoren unterstützt. Wir danken Ihnen von Herzen.

🗾 Datenquellen & Inspirationen (Data Sources & Inspirations)

• Offene Daten der Japan Meteorological Agency (JMA): jma.go.jp

  • Wir danken Ihnen zutiefst für die öffentliche Bereitstellung hochpräziser Wettervorhersage- und Katastrophenschutzdaten für ganz Japan sowie der Gebietsdefinitionsdaten für über 1.800 Regionen.

• Design-Inspiration für die Wettervorhersage-API (livedoor-Wetter-kompatibel): tsukumijima/weather-api / weather.tsukumijima.net

  • Wir danken für das verständliche Schema-Design des livedoor-Wetter-kompatiblen Formats und den langjährigen Beitrag zur Community.

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

  • Wir danken für die MCP-Implementierung der Bild-, Video-, Nachrichten-, Chiebukuro- und Vorschlags-Suche von Yahoo! JAPAN.

• norikae-mcp: tysonwu/norikae-mcp

  • Wir danken für das Design und die Implementierung der Verbindungsauskunftslogik durch Scraping der Yahoo!-Routeninformationen.

🛠️ Grundlegende Open-Source-Bibliotheken & Ökosystem (Core Libraries & Ecosystem)

• Hono (@yusukebe) — Hochgeschwindigkeits-Web-API-Framework & MCP-Integration

• Puppeteer (Google Chrome Team) — Headless-Chromium-Steuerung & Stealth-Operationen

• Readability (Mozilla) — Reader-Mode-Artikeltext-Extraktionsengine

• Cheerio (cheeriojs team) — Schnelle DOM-Analyse & Metadaten-Extraktion

• Turndown (Dom Christie) — HTML-zu-Markdown-Konverter

• LinkeDOM (Andrea Giammarchi) — Extrem leichtgewichtige In-Memory-DOM-Engine

• unpdf (UnJS Team) — Schnelle, leichte PDF-Text-Extraktion

• Model Context Protocol SDK (Anthropic / MCP Team) — Nächste-Generation-AI-Tool-Verbindungsstandard

6. Haftungsausschluss (Disclaimer)

• Inoffizielles Drittanbieter-Tool:

  • Diese Software ist ein inoffizielles (Drittanbieter-)Tool, das für die persönliche Entwicklung, akademische Forschung und den internen Gebrauch im eigenen Unternehmen entwickelt wurde.

• Zu Marken:

  • „Yahoo!“, „Yahoo! JAPAN“ und die einzelnen Dienstnamen sind Marken oder eingetragene Marken der LINE Yahoo Corporation. Dieses Projekt steht in keiner Beziehung zur LINE Yahoo Corporation.

• Einhaltung von Nutzungsbedingungen und Gesetzen:

  • Beim Zugriff auf die einzelnen externen Dienste (Yahoo! JAPAN, JMA usw.) müssen die Nutzungsbedingungen, Richtlinien, robots.txt und geltenden Gesetze des jeweiligen Dienstes eingehalten werden. Die Nutzung erfolgt in der Verantwortung des Nutzers, ohne übermäßige Last zu erzeugen.

• Haftungsbeschränkung:

  • Für jegliche Schäden, die durch die Nutzung dieser Software entstehen (einschließlich Zugriffsbeschränkungen durch den jeweiligen Dienst, Integrität, Genauigkeit und Aktualität der Daten), übernehmen die Entwickler dieses Projekts keinerlei Haftung.

7. Lizenz (License)

Diese Software wird unter der Business Source License 1.1 (BSL 1.1 / BUSL-1.1) veröffentlicht.

• Kostenlose Nutzung für folgende Zwecke:

  • Persönliche Entwicklung, akademische Forschung, nicht-kommerzielle Nutzung

  • Selbsthosting für eigene Systeme innerhalb von Unternehmen/Organisationen (als internes Backend für eigene Produkte oder interne Tools)

  • Änderung, Forking und interne Weitergabe des Quellcodes

• Einschränkungen (Restriction):

  • Die Bereitstellung oder der Weiterverkauf dieser Software (oder ihrer Derivate) als „kostenpflichtiger Cloud-Dienst“, „kostenpflichtiger Scraping-/Such-API-Dienst“ oder „verwalteter Dienst“ für Dritte ist untersagt.

• Change Date (Datum der Open-Source-Konvertierung):

  • Am 1. August 2030 (oder früher) wird die Software automatisch in eine vollständige MIT-Lizenz umgewandelt.

Weitere Details finden Sie in der LICENSE.

Copyright (c) 2026 ikeno