NSHipster/sosumi.ai

sosumi.ai – AI‑readable Apple Developer docs

What it is : A small web service (hosted on Cloudflare Workers) that turns Apple Developer documentation pages—normally rendered with JavaScript—into clean Markdown. The output is easy for language models or other automation tools to consume.

How it works :

The service rewrites the host part of an Apple docs URL from developer.apple.com (or a Swift‑DocC site) to sosumi.ai.
It resolves the underlying DocC JSON endpoint, extracts the content, and returns it as Markdown (or JSON‑wrapped Markdown for scripts).
For external Swift‑DocC sites it can proxy the same way, respecting robots.txt and a custom sosumi‑ai user‑agent.

Main ways to use it

HTTP API – just replace the host in any Apple docs or WWDC video URL.
```
https://developer.apple.com/documentation/swift/array
→ https://sosumi.ai/documentation/swift/array
```
The same pattern works for Human Interface Guidelines and WWDC transcript URLs.
MCP (Message Control Protocol) integration – a streaming‑compatible endpoint (/mcp) that can be consumed via HTTP, Server‑Sent Events, or a simple stdio proxy (npx mcp-remote …).
CLI – npx @nshipster/sosumi fetch <url> (or install globally as sosumi). Supports fetching docs, HIG pages, video transcripts, external Swift‑DocC sites, and searching the Apple docs index. JSON output is available with --json.
Chrome extension – adds a “Copy sosumi Link” button on Apple docs pages (community‑maintained).
AI‑agent skill file – a markdown skill definition (https://sosumi.ai/SKILL.md) that can be added to spec‑compliant agents via npx skills add https://sosumi.ai.

Key built‑in tools (exposed via MCP)

searchAppleDocumentation – full‑text search returning titles, URLs, breadcrumbs, etc.
fetchAppleDocumentation – fetch a doc page as Markdown.
fetchAppleVideoTranscript – fetch WWDC session transcripts.
fetchExternalDocumentation – fetch any public Swift‑DocC page (subject to host allow/block lists).

Self‑hosting

Written in Node 20+ using the Hono framework, so it can run on Cloudflare Workers, Vercel, Netlify, or any platform that supports Hono.
Clone, npm install, then npm run dev to start a local dev server (default http://localhost:8787).
Production deployment uses Cloudflare Workers (wrangler), with optional Ed25519 Web Bot Auth signatures for hosts that require verification. Keys are supplied via the WEB_BOT_AUTH_KEY secret.
External host access can be limited with EXTERNAL_DOC_HOST_ALLOWLIST / EXTERNAL_DOC_HOST_BLOCKLIST environment variables.

Development & quality

Tests with vitest (npm run test).
Formatting / linting with Biome (npm run check).
CI/CD publishes tagged releases to npm and GitHub releases.

Legal note

Unofficial, not affiliated with Apple. It only fetches pages on‑demand, respects robots directives, and does not store permanent copies.

Quick start

# Clone & run locally
git clone https://github.com/nshipster/sosumi.ai.git
cd sosumi.ai
npm install
npm run dev   # opens http://localhost:8787

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

Useful links

Live service: https://sosumi.ai
Skill file for agents: https://sosumi.ai/SKILL.md
Chrome extension: https://chromewebstore.google.com/detail/donffakeimppgoehccpfhlchmbfdmfpj
Documentation: https://sosumi.ai/#clients

NSHipster/sosumi.ai

sosumi.ai – AI‑readable Apple Developer docs

Related