NSHipster/sosumi.ai

sosumi.ai – AI가 읽을 수 있는 Apple 개발자 문서

무엇인가요 : Cloudflare Workers에서 호스팅되는 소규모 웹 서비스로, JavaScript로 렌더링되는 Apple 개발자 문서 페이지(예: Swift 문서, HIG, WWDC 녹화 내용)를 깔끔한 Markdown으로 변환합니다. 출력은 언어 모델이나 기타 자동화 도구가 쉽게 처리할 수 있도록 설계되었습니다.

작동 방식 :

서비스는 Apple 문서 URL의 호스트 부분을 developer.apple.com (또는 Swift-DocC 사이트)에서 sosumi.ai로 리라이트합니다.
기반 DocC JSON 엔드포인트를 해결하고, 콘텐츠를 추출하여 Markdown(또는 스크립트용 JSON 래핑된 Markdown)으로 반환합니다.
외부 Swift-DocC 사이트의 경우에도 동일한 방식으로 프록시 처리가 가능하며, robots.txt를 존중하고 사용자 에이전트 sosumi-ai를 사용합니다.

주요 사용 방법

HTTP API – 어떤 Apple 문서나 WWDC 동영상 URL의 호스트만 바꾸면 됩니다.
```
https://developer.apple.com/documentation/swift/array
→ https://sosumi.ai/documentation/swift/array
```
동일한 패턴은 Human Interface Guidelines 및 WWDC 녹화 내용 URL에도 적용 가능합니다.
MCP(메시지 제어 프로토콜) 통합 – HTTP, Server-Sent Events, 또는 간단한 stdio 프록시(npx mcp-remote …)로 사용 가능한 스트리밍 호환 엔드포인트(/mcp).
CLI – npx @nshipster/sosumi fetch <url> (또는 전역 설치 시 sosumi). 문서, HIG 페이지, 동영상 녹화 내용, 외부 Swift-DocC 사이트 가져오기, Apple 문서 인덱스 검색을 지원합니다. --json 옵션으로 JSON 출력 가능.
Chrome 확장 프로그램 – Apple 문서 페이지에 "Copy sosumi Link" 버튼을 추가합니다(커뮤니티 유지보수).
AI 에이전트 스킬 파일 – https://sosumi.ai/SKILL.md에 있는 Markdown 형식의 스킬 정의로, npx skills add https://sosumi.ai로 사양 준수 에이전트에 추가 가능합니다.

내장된 주요 도구 (MCP를 통해 노출)

searchAppleDocumentation – 전체 텍스트 검색을 통해 제목, URL, 브레드크럼 등을 반환합니다.
fetchAppleDocumentation – 문서 페이지를 Markdown으로 가져옵니다.
fetchAppleVideoTranscript – WWDC 세션 녹화 내용을 가져옵니다.
fetchExternalDocumentation – 공개된 모든 Swift-DocC 페이지를 가져옵니다(호스트 허용/차단 목록에 따라 제한됨).

자체 호스팅

Node 20+ 와 Hono 프레임워크로 작성되어 있어 Cloudflare Workers, Vercel, Netlify, 또는 Hono 호환 플랫폼에서 실행 가능합니다.
복제 후 npm install 후 npm run dev로 로컬 개발 서버 시작 (기본 http://localhost:8787).
본격 배포는 Cloudflare Workers(wrangler)를 사용하며, 검증이 필요한 호스트에 대해 선택적 Ed25519 Web Bot 인증 서명을 지원합니다. 키는 WEB_BOT_AUTH_KEY 시크릿으로 제공됩니다.
외부 호스트 접근은 EXTERNAL_DOC_HOST_ALLOWLIST / EXTERNAL_DOC_HOST_BLOCKLIST 환경 변수로 제한 가능합니다.

개발 및 품질

테스트는 vitest로 수행 (npm run test).
포맷팅/라인팅은 Biome로 수행 (npm run check).
CI/CD는 태그된 릴리스를 npm과 GitHub 릴리스에 자동 게시합니다.

법적 고지

공식적이지 않으며 Apple과 관련이 없습니다. 요청 시에만 페이지를 가져오며, robots 지침을 존중하며 영구 복사본을 저장하지 않습니다.

빠른 시작

# 복제 및 로컬 실행
git clone https://github.com/nshipster/sosumi.ai.git
cd sosumi.ai
npm install
npm run dev   # http://localhost:8787 열림

# CLI 사용
npx @nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array

유용한 링크

실시간 서비스: https://sosumi.ai
에이전트용 스킬 파일: https://sosumi.ai/SKILL.md
Chrome 확장 프로그램: https://chromewebstore.google.com/detail/donffakeimppgoehccpfhlchmbfdmfpj
문서: https://sosumi.ai/#clients

NSHipster/sosumi.ai

sosumi.ai – AI가 읽을 수 있는 Apple 개발자 문서

관련