Sora (空)

일본 웹을 AI 에이전트에서 이용하기 위한 Self-hosted MCP / REST 통합 서버
All-in-One, Zero-Middleware Web Scraping & Japanese Life Infrastructure Engine for AI Agents

Sora는 LLM이나 AI 에이전트(Claude Desktop, Cursor, Cline, OpenCodeInterpreter, Dify 등)가 일본의 웹 공간과 일상 인프라를 자유롭고 안전하게 탐색·조작하기 위한 All-in-One MCP / REST 서버입니다.

외부 DB(Redis / PostgreSQL)나 메시지 큐를 전혀 필요로 하지 않고, 헤드리스 Chromium과 일본어 CJK 폰트를 내장한 단일 컨테이너 / 단일 바이너리만으로 월 800엔 VPS에서 즉시 가동합니다.

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

⚡ 5초 만에 연결되는 Quickstart (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에서 1 커맨드 기동

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

Related MCP server: Agent Toolbox

🌟 주요 특징과 강점 (Why Sora?)

1. 🗾 일본 일상 인프라 & 웹 탐색의 완전 포괄:

   • 해외제 도구(Firecrawl / Tavily)로는 대응할 수 없는 「Yahoo! 지식백과」「X (Twitter) 실시간 속보」「기상청 공식 오픈데이터 직결(전국 1,805개 시구정촌 자동 선정)」「전철 환승 안내」를 단일 MCP로 제공.

2. ⚡ 압도적인 밀리초 응답 & 초저전력 메모리:

   • Bun 네이티브 컴파일로 API 응답 1.5ms, 상주 메모리 JS 힙 ~32MB / 전체 ~140MB. AI 에이전트의 대기 시간을 극한까지 단축.

3. 📦 완전 올인원 & 제로 미들웨어:

   • Redis, PostgreSQL, 외부 워커 큐 등은 전혀 불필요. 단일 바이너리 / 단일 컨테이너만으로 즉시 완결.

4. 🛡️ Distroless(셸 없음) & 엄격한 보안:

   • 베이스 이미지에 gcr.io/distroless/cc-debian12를 채택. 컨테이너 내에 /bin/sh, bash, curl 등이 존재하지 않아 RCE(임의 코드 실행) 공격을 무력화.

   • SSRF / DNS Rebinding 차단, 상수 시간 비교에 의한 Timing Attack 방지, 브라우저 세션 소유권 분리, DoS 방어(Body Limit 10MB)를 표준 장비.

5. 🕹️ 스테이트풀 브라우저 조작 DSL:

   • open → fill → click → screenshot → evaluate의 복수 턴 대화형 브라우저 세션을 API / MCP에서 직접 제어.

📊 성능 & 아키텍처 비교

⏱️ 각 엔드포인트의 실측 응답 속도 (Measured Latency: Cold vs Cached)

실기 로컬 서버에서의 「최초 취득(비캐시 시)」과 「캐시 히트 시」의 실측 레이턴시 목록입니다. AI 에이전트가 사고·생성하는 시간(1〜3초)과 비교해 압도적으로 빠르게 응답합니다.

⚡ 내부 엔리치먼트·AI 최적화 처리의 실측 속도 (In-Memory Latency)

외부 LLM API를 거치지 않고, 모든 Bun 네이티브 및 최적화 알고리즘으로 1밀리초 미만(< 1ms) 으로 완결됩니다.

🏛️ 설계 사상 (Design Philosophy & Principles)

Sora는 다음 4가지 코어 설계 원칙에 기반해 구축되었습니다:

1. ✂️ 오컴의 면도날(Occam's Razor & Zero-Middleware):

   • "필요가 없다면 많은 것을 정립해서는 안 된다. 요건을 충족하는 가장 단순한 구성이 최선의 구성이다."

   • Redis, PostgreSQL, 외부 큐, 중후한 마이크로서비스군을 전부 배제. 「단일 컨테이너·단일 바이너리」 만으로 동작하며, 월 800원 VPS나 Raspberry Pi에서 수만 리퀘스트 클라우드까지 고장 없이 상주합니다.

2. 🛡️ 스텔스와 생환율의 파레토 최적(Stealth & Pareto Optimum):

   • 단순히 「0ms로 기계적 액세스」를 하면 상대 서버의 WAF나 Cloudflare에 즉시 IP가 BAN되어 성공률은 0%로 떨어집니다.

   • 동일 도메인에 연속 액세스 시 150ms + Jitter(0〜100ms 요동) 을 자동 삽입하고, 타이핑에도 15〜40ms의 인간적 지연을 부여. AI에서 본 체감 속도를 손상시키지 않으면서 확실히 데이터를 가져오는 생환율을 최우선으로 합니다.

3. 🔒 디스트로레스에 의한 견고한 보안(Distroless by Design):

   • 컨테이너 내에 /bin/sh, bash, curl, apt가 존재하지 않으므로, 만에 하나 미지의 취약성이 있어도 공격자가 셸을 탈취할 여지(RCE: 임의 코드 실행)가 원리적으로 없습니다. 비root 실행 및 엄격한 SSRF 차단을 표준 장착.

4. 🗾 공적 오픈데이터 직결·지속 가능성(Sustainable & Autonomous):

   • 날씨 예보는 기상청 공식 오픈데이터 CDN(jma.go.jp)에 직접 액세스. 전국 1,805개 시구촌명의 제로 밀리초 자동 해결과 30분 LRU 캐시로 상대 서버에 대한 부하를 최소화하면서 영구히 자율 가동합니다.

1. 퀵스타트

1.1 컨테이너 기동 (Docker / Podman)

GitHub Container Registry (GHCR)에서 1 커맨드로 즉시 기동할 수 있습니다:

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이나 Cursor의 MCP 설정)에 다음을 추가합니다:

{
  "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│                │
└─────────────────┴───────────────────┴──────────────────┴─────────────────┘

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

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)하고, 쿠키 동의 배너(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 문서는 <!-- Page 1 -->\n## Page 1처럼 페이지 번호 구분으로 구조화된 Markdown 출력되며, totalPages나 작성자 등의 메타데이터도 자동 추출됩니다.

✂️ 구문 안전 트리밍 & 토큰 견적: maxChars로 문자 수가 제한된 경우에도 열린 코드 블록(```)이나 테이블을 자동으로 안전하게 보정·폐쇄합니다. 또한 응답에는 추정 LLM 토큰 수 estimatedTokens가 부여됩니다.

🧩 RAG 최적화 시맨틱 청킹 (chunkMarkdown: true): 제목 계층(H1~H4)이나 문단·코드 블록을 깨지 않게 적절히 분할된 chunks: [{ index, heading, content, estimatedTokens }]를 자동 생성하여 벡터 검색이나 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): 이메일 주소, 일본 전화번호, 신용카드 번호(Luhn 검증) 등의 민감 정보를 자동으로 [EMAIL], [PHONE], [CREDIT_CARD]로 비식별화하여 LLM으로의 전송을 보호합니다.

📡 진행 상황 실시간 SSE 스트리밍 (POST /scrape/stream): start → fetch → render → enrich → done 각 스테이지 진행 이벤트를 실시간으로 Server-Sent Events로 수신할 수 있습니다.

🎬 YouTube / 동영상 미디어 메타데이터 & 챕터 추출 (media): 동영상 페이지에서 재생 시간, 썸네일, 챕터 목록(타임스탬프 포함 목차)을 자동 구조화 추출합니다.

🤖 LLM 최적화 프롬프트 XML 자동 생성 (formatAsPrompt: true): Claude / GPT / Gemini가 가장 이해하기 쉬운 표준 <web_page url="..." title="...">...</web_page> 형식의 컨텍스트 래퍼 promptContext를 자동 생성합니다.

🖍️ 검색 키워드 본문 자동 강조 (highlightMatches: true): 지정한 query의 키워드를 본문 Markdown 내에서 <mark>키워드</mark>로 강조 표시한 highlightedContent를 얻을 수 있습니다.

📊 테이블 구조화 JSON 추출 (formats: ["tables"]): 페이지 내 표(<table>)를 { caption, headers, rows }의 구조화 JSON 배열로 직접 획득할 수 있습니다.

⚡ 초고속 추출형 자동 요약 (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에 접속하면 Swagger UI에서 전체 API를 직접 테스트 실행(Try it out)할 수 있습니다.

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) 모두 지원합니다.

① 원샷 실행(1회 완결)

• 요청 (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
}

② 스테이트풀·멀티턴 대화 세션(대화형 채팅용)

• Turn 1 (세션 생성 & 화면 오픈):

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

(응답에서 "sessionId": "sess_a1b2c3d4"가 반환됩니다)

• Turn 2 (열린 화면에서 계속 조작):

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

• Turn 3 (세션 종료 & 클린업):

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

(※ 조작이 5분간 끊긴 경우에도 자동 타임아웃으로 안전하게 메모리가 해제됩니다)

3.4 통합 심층 검색 (POST /search) & Web 검색 (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
}

• Web 검색 요청 (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/이미지/구조화 데이터를 일괄 수집합니다. includePatterns / excludePatterns에 의한 Glob 와일드카드 필터링을 지원합니다.

• 요청 (일괄 획득):

{
  "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 이미지·동영상·뉴스·지식인·추천 검색

• 이미지 검색 (POST /search/image): { "query": "富士山", "limit": 10 }

• 동영상 검색 (POST /search/video): { "query": "簡単 レシピ", "limit": 10 }

• 뉴스 검색 (POST /search/news): { "query": "AI ロボット", "limit": 10 }

• 지식인 Q&A (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 날씨 호환 형식)를 직접 해석하여 일본 전국의 오늘·내일·모레 상세 기상 데이터를 완전 자율로 획득합니다.

본 기능의 장점 (Features & Advantages)

• 완전 자율·공식 직결(제로 의존): 기상청 공식 CDN(jma.go.jp)에서 직접 기상 데이터를 획득·파싱.

• 전국 1,805개 시구정촌 스마트 자동 해결: 기상청 공식 에어리어 정의(area.json)를 내장. "天童市""軽井沢""箱根""浦安""別府" 등의 시구정촌명·유명 지명에서 담당 기상대의 지점 ID를 0ms로 자동 선정. 현명 없는 입력에도 대응.

• AI 에이전트 친화적 구조화 데이터: 3일간 날씨 자막, 바람·파도, 예상 최고/최저 기온(℃), 시간대별 강수 확률(0-6시, 6-12시, 12-18시, 18-24시), 기상대 발표 날씨 개황문(제목·본문)을 깨끗한 JSON으로 일괄 획득.

• LRU 캐시에 의한 초고속 응답: 30분간 인메모리 LRU 캐시를 기본 탑재하여 기상청 서버로의 불필요한 중복 액세스를 자동 방지.

• 요청 (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은 전혀 존재하지 않아 공격자가 셸을 탈취할 여지가 없습니다.

• 최소 권한 설계: 비 root 실행을 지원하며 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 (In-flight Deduplication):

  • 동일 URL로의 병렬 요청 발생 시 Promise를 공유하여 1회의 외부 통신으로 집약. Thundering Herd(캐시 스탬피드)를 방지하고 외부 서버와 로컬 리소스를 보호.

• 🚦 브라우저 동시 실행 제한 (Concurrency Control):

  • SimpleSemaphore로 Chromium 프로세스의 동시 실행 수(MAX_CONCURRENT_BROWSERS, 기본값 5)를 안전하게 제어. 서버의 CPU/메모리 고갈을 방지.

• 🔒 Timing-Safe 인증 & Browser Session 소유권 연결:

  • API 키 대조에는 crypto.timingSafeEqual + SHA-256(상수 시간 비교)을 채택하여 Timing Attack을 방어.

  • Multi-turn 브라우저 세션(sessionId)을 작성자 토큰과 암호학적으로 연결하여 타인의 세션 탈취를 방지.

• 🛡️ 임의 JavaScript 실행의 안전 제어 스위치 (ALLOW_BROWSER_EVALUATE):

  • 환경 변수 ALLOW_BROWSER_EVALUATE=false 또는 SAFE_BROWSER_MODE=true로 /browser/action에서의 evaluate 스크립트 실행을 즉시 무효화·락다운 가능.

• 📐 공통 Zod 스키마 & OpenAPI 3.0 완전 자동 생성:

  • REST / MCP 양쪽에서 Zod 스키마에 의한 입력 검증을 통일.

  • /openapi.json은 코드 측 Zod 스키마에서 OpenAPI 3.0 사양을 100% 동적으로 자동 생성하여 문서의 괴리를 완전 방지.

  • 오류 응답은 { "error": "...", "code": "SSRF_BLOCKED", "status": 403, "retryable": false }처럼 AI 에이전트가 자기 수복·자율 판단하기 쉬운 구조를 제공.

• ⏱️ Jitter 스로틀링 & 진정한 LRU 캐시:

  • 동일 도메인으로의 과도한 연속 액세스를 150ms + Jitter(0~100ms 변동)로 자동 억제.

  • 15~30분간의 진정한 LRU(액세스 시 최신화) 캐시와 10분마다의 정기 TTL 스윕으로 메모리 누수를 완전 방지.

5. 감사의 말·크레딧 (Acknowledgments)

Sora는 아래의 훌륭한 오픈소스 프로젝트, 공개 서비스, 공공 오픈데이터, 그리고 라이브러리 작성자 여러분의 훌륭한 기여에 힘입어 있습니다. 진심으로 감사드립니다.

🗾 데이터 소스 & 착상원 (Data Sources & Inspirations)

• 기상청(JMA) 오픈데이터: jma.go.jp

  • 일본 전국의 고정밀 기상 예보·방재 데이터 및 전국 1,800개 이상의 에어리어 정의 데이터의 공개에 깊이 감사드립니다.

• 날씨 예보 API(livedoor 날씨 호환) 설계 착상: tsukumijima/weather-api / weather.tsukumijima.net

  • livedoor 날씨 호환 포맷의 알기 쉬운 스키마 설계와 오랜 커뮤니티 기여에 감사드립니다.

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

  • Yahoo! JAPAN의 이미지·동영상·뉴스·지식인·추천 검색의 MCP 구현에 감사드립니다.

• norikae-mcp: tysonwu/norikae-mcp

  • Yahoo! 노선 정보 스크레이핑에 의한 환승 안내 로직의 설계·구현에 감사드립니다.

🛠️ 기반 오픈소스·라이브러리 (Core Libraries & Ecosystem)

• Hono (@yusukebe) — 초고속 Web API 프레임워크 & MCP 통합

• Puppeteer (Google Chrome Team) — 헤드리스 Chromium 제어·스텔스 조작

• Readability (Mozilla) — 리더 모드 기사 본문 추출 엔진

• Cheerio (cheeriojs team) — 고속 DOM 파싱 & 메타데이터 추출

• Turndown (Dom Christie) — HTML to Markdown 컨버터

• LinkeDOM (Andrea Giammarchi) — 초경량 인메모리 DOM 엔진

• unpdf (UnJS Team) — 고속·경량 PDF 텍스트 추출

• Model Context Protocol SDK (Anthropic / MCP Team) — 차세대 AI 도구 접속 규격

6. 면책 조항 (Disclaimer)

• 비공식 서드파티 제작 도구:

  • 본 소프트웨어는 개인 개발·학술 연구·자사 내 이용을 목적으로 개발된 비공식(서드파티 제작) 도구입니다.

• 상표에 대하여:

  • "Yahoo!" "Yahoo! JAPAN" 및 각 서비스명은 LINE 야후 주식회사의 상표 또는 등록 상표입니다. 본 프로젝트는 LINE 야후 주식회사와 일절 관계가 없습니다.

• 이용 약관·법령의 준수:

  • 각 외부 서비스(Yahoo! JAPAN, 기상청 등)에 대한 액세스 시 상대방 서비스의 이용 약관, 가이드라인, robots.txt, 및 적용 법령을 준수하고 과도한 부하를 걸지 않도록 이용자 자신의 책임 하에 이용해 주십시오.

• 책임의 한정:

  • 본 소프트웨어 이용으로 발생한 어떠한 손해(상대방 서비스로부터의 액세스 제한, 데이터의 완전성·정확성·최신성 등을 포함)에 대해 본 프로젝트의 개발자는 일절 책임을 지지 않습니다.

7. 라이선스 (License)

본 소프트웨어는 Business Source License 1.1 (BSL 1.1 / BUSL-1.1) 하에 공개되어 있습니다.

• 자유·무료로 이용하실 수 있는 용도:

  • 개인 개발, 학술 연구, 비상업적 이용

  • 기업·조직 내 자사 시스템용 셀프호스트 이용(자사 제품이나 사내 도구를 지탱하는 내부 백엔드로 동작시키는 것)

  • 소스 코드의 수정·포크·내부 공유

• 금지 사항 (Restriction):

  • 본 소프트웨어(또는 그 파생물)를 제3자용 "유료 클라우드 서비스" "유료 스크레이핑 / 검색 API 서비스" "매니지드 서비스"로 제공·재판매하는 것.

• Change Date (오픈소스 전환일):

  • 2030년 8월 1일(또는 그 이전)에 자동으로 완전한 MIT License로 전환됩니다.

자세한 내용은 LICENSE를 확인해 주십시오.

Copyright (c) 2026 ikeno