Sosumi

sosumi.ai

Making Apple docs AI-readable.

sosumi.ai provides Apple Developer documentation in an AI-readable format by converting JavaScript-rendered pages into Markdown.

Usage

HTTP API

Replace developer.apple.com with sosumi.ai in any Apple Developer documentation URL:

Original:

https://developer.apple.com/documentation/swift/array

AI-readable:

https://sosumi.ai/documentation/swift/array

This works for all API reference docs, as well as Apple's Human Interface Guidelines (HIG).

WWDC session transcripts are also supported by replacing the same host for video URLs:

Original:

https://developer.apple.com/videos/play/wwdc2021/10133/

AI-readable:

https://sosumi.ai/videos/play/wwdc2021/10133

Sosumi can also proxy public non-Apple Swift-DocC pages using:

Original:

https://swiftlang.github.io/swift-docc-plugin/documentation/swiftdoccplugin

AI-readable:

https://sosumi.ai/external/https://swiftlang.github.io/swift-docc-plugin/documentation/swiftdoccplugin

[!NOTE]

Sosumi resolves the URL to the site's underlying DocC JSON endpoint

and renders Markdown, preserving any base path from the original URL.

External hosts can opt out via robots.txt

by disallowing user-agent sosumi-ai

(full UA: sosumi-ai/1.0 (+https://sosumi.ai/#bot)).

See /bot for the crawler policy and contact details.

MCP Integration

Sosumi's MCP server supports Streamable HTTP and Server-Sent Events (SSE) transport. If your client supports either of these, configure it to connect directly to https://sosumi.ai/mcp.

Otherwise, you can run this command to proxy over stdio:

{

"mcpServers": { "sosumi": { "command": "npx", "args": ["-y", "mcp-remote", "https://sosumi.ai/mcp"] } } }

See the website for client-specific instructions.

Plugin

The plugin folder packages the MCP server and the agent skill for Claude Code, Cursor, and Agent Plugins clients such as ChatGPT and Codex.

In Claude Code, run:

/plugin marketplace add NSHipster/sosumi.ai

/plugin install sosumi@sosumi-ai

public/SKILL.md is the source of the skill. After you edit it, copy it into the plugin:

cp public/SKILL.md plugin/skills/sosumi/SKILL.md

A test fails when the two files differ.

Available Tools

• searchAppleDocumentation - Searches Apple Developer documentation
• Parameters: query (string)
• Returns structured results with titles, URLs, descriptions, breadcrumbs, and tags

• fetchAppleDocumentation - Fetches Apple Developer documentation and Human Interface Guidelines by path
• Parameters: path (string) - Documentation path (e.g., '/documentation/swift', '/documentation/swiftui/view', '/design/human-interface-guidelines/foundations/color')
• Returns content as Markdown

• fetchAppleVideoTranscript - Fetches video transcripts, including WWDC sessions
• Parameters: path (string) - video path (e.g., /videos/play/wwdc2021/10133)
• Returns transcript content as Markdown

• fetchExternalDocumentation - Fetches external Swift-DocC documentation by absolute HTTPS URL
• Parameters: url (string) - External URL (e.g., https://swiftlang.github.io/swift-docc-plugin/documentation/swiftdoccplugin)
• Returns content as Markdown

CLI

Sosumi also provides a CLI that complements MCP:

npx @nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array

If you use it regularly, install once:

npm i -g @nshipster/sosumi

Then use sosumi directly:

sosumi fetch https://developer.apple.com/documentation/swift/array

You can fetch all content types covered by MCP tools:

# Apple documentation / HIG / videos

sosumi fetch /documentation/swift/array sosumi fetch /design/human-interface-guidelines/color sosumi fetch /videos/play/wwdc2021/10133

External Swift-DocC pages

sosumi fetch https://swiftlang.github.io/swift-docc-plugin/documentation/swiftdoccplugin

Apple documentation search

sosumi search "SwiftData"

Run a local server from the published package:

sosumi serve

sosumi serve --port 8787

By default, output is plain text / Markdown. Use JSON output for scripts:

sosumi fetch https://developer.apple.com/documentation/swift/array --json

sosumi search "SwiftData" --json

AI Agent Skill

Want your AI coding assistant to use Sosumi consistently? Use the hosted skill file: https://sosumi.ai/SKILL.md

Spec-compliant clients can also install it with:

npx skills add https://sosumi.ai

Chrome Extension

You can also use Sosumi from a community-contributed Chrome extension, which adds a "Copy sosumi Link" button to Apple Developer documentation pages. Source code is available on GitHub.

Self-Hosting

This project is designed to be easily run on your own machine or deployed to a hosting provider.

Sosumi.ai is currently hosted by Cloudflare Workers.

[!NOTE]

The application is built with Hono,

making it compatible with various runtimes.

See the Hono docs

for more information about deploying to different platforms.

Prerequisites

• Node.js 20+
• npm

Quick Start

1. Clone the repository:

   git clone https://github.com/nshipster/sosumi.ai.git

cd sosumi.ai

1. Install dependencies:

   npm install

1. Start development server:

   npm run dev

Once the application is up and running, press the b to open the URL in your browser.

To configure MCP clients to use your development server, replace sosumi.ai with the local server address (http://localhost:8787 by default).

External Host Restrictions

You can restrict which external Swift-DocC hosts are reachable with two environment variables (both newline-delimited):

• EXTERNAL_DOC_HOST_ALLOWLIST — only listed hosts are permitted
• EXTERNAL_DOC_HOST_BLOCKLIST — listed hosts are always denied

[!IMPORTANT]

Hostname-based private-network checks cannot fully prevent DNS rebinding.

Set an explicit EXTERNAL_DOC_HOST_ALLOWLIST in production.

Web Bot Auth

Sosumi identifies itself when it fetches from external Swift-DocC hosts on a user's behalf using Web Bot Auth, so those hosts can cryptographically verify the traffic.

• The public key set is published at /.well-known/http-message-signatures-directory.
• Requests to external hosts are signed with an Ed25519 HTTP Message Signature (RFC 9421) and carry Signature-Agent, Signature-Input, and Signature headers.

To enable signing on your own deployment, provide an Ed25519 private key (as a JSON Web Key) via the WEB_BOT_AUTH_KEY secret.

Generate a key (the JSON Web Key is the format WEB_BOT_AUTH_KEY expects), then paste the printed value when wrangler secret put prompts for it:

node -e 'crypto.subtle.generateKey({name:"Ed25519"},true,["sign","verify"]).then(async k=>{const j=await crypto.subtle.exportKey("jwk",k.privateKey);console.log(JSON.stringify({kty:j.kty,crv:j.crv,x:j.x,d:j.d}))})'

npx wrangler secret put WEB_BOT_AUTH_KEY

Or generate and upload in a single step, which avoids writing the key to disk or shell history:

node -e 'crypto.subtle.generateKey({name:"Ed25519"},true,["sign","verify"]).then(async k=>{const j=await crypto.subtle.exportKey("jwk",k.privateKey);console.log(JSON.stringify({kty:j.kty,crv:j.crv,x:j.x,d:j.d}))})' \

| npx wrangler secret put WEB_BOT_AUTH_KEY

The matching public key and its kid (JWK thumbprint) are derived automatically, so no key material lives in the repository. Set the optional SIGNATURE_AGENT var to override the advertised origin (defaults to https://sosumi.ai). When no key is configured, requests are simply sent unsigned.

Cloudflare provides built-in verification for these signatures.

Development

Testing

This project uses vitest for unit and integration testing.

npm run test          # Run tests

npm run test:ui # Run tests with UI npm run test:run # Run tests once

[!TIP]

When running the CLI through npm scripts during local development,

use -s (--silent)

to suppress npm's script preamble so output pipes cleanly:

`bash

npm run -s cli -- fetch https://developer.apple.com/documentation/swift/array | bat -l md

`

Code Quality

This project uses Biome for code formatting, linting, and import organization.

• npm run format - Format all code files
• npm run lint - Lint and fix code issues
• npm run check - Format, lint, and organize imports (recommended)
• npm run check:ci - Check code without making changes (for CI)

Editor Integration

For the best development experience, install the Biome extension for your editor:

• VSCode
• Vim/Neovim
• Emacs

Cloudflare Workers

Whenever you update your wrangler.toml or change your Worker bindings, be sure to re-run:

npm run cf-typegen

Publishing

Publishing is handled by .github/workflows/release.yml.

• Trigger: pushed tags matching v* or manual dispatch with tag
• Release step: gh release create "$TAG_NAME" --generate-notes
• Publish auth: npm trusted publishing via OIDC (id-token: write)
• Publish command: npm publish --provenance --access public
• MCP Registry: after npm publish, the workflow publishes server.json to the MCP Registry as ai.sosumi/sosumi.

Keep version in server.json equal to version in package.json; a test fails when they differ.

The registry step uses HTTP authentication for the sosumi.ai domain. It skips with a notice until the MCP_REGISTRY_PRIVATE_KEY secret is set. To set it up, generate an Ed25519 key pair with OpenSSL 3 (macOS's LibreSSL does not support Ed25519):

openssl genpkey -algorithm Ed25519 -out key.pem

Public key: add to "vars" in wrangler.jsonc as MCP_REGISTRY_PUBLIC_KEY, then deploy

openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64

Private key (hex): save as the MCP_REGISTRY_PRIVATE_KEY repository secret

openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n'

The Worker then serves v=MCPv1; k=ed25519; p= at /.well-known/mcp-registry-auth. Without the variable, that path returns 404. Delete key.pem after you save both values.

License

This project is available under the MIT license. See the LICENSE file for more info.

Legal

This is an unofficial, independent project and is not affiliated with or endorsed by Apple Inc. "Apple", "Xcode", and related marks are trademarks of Apple Inc.

This service is an accessibility-first, on‑demand renderer. It converts a single Apple Developer page to Markdown only when requested by a user. It does not crawl, spider, or bulk download; it does not attempt to bypass authentication or security; and it impl