sosumi.ai
Making Apple docs AI-readable
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nshipster/sosumi.ai with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nshipster/sosumi.ai'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/nshipster-sosumi-ai)HTML
<a href="/listings/nshipster-sosumi-ai"><img src="/api/listings/nshipster-sosumi-ai/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. **Clone the repository:**
git clone https://github.com/nshipster/sosumi.ai.git cd sosumi.ai
2. **Install dependencies:**
npm install
3. **Start development server:**
npm run dev
Once the application is up and running, press the <kbd>b</kbd> 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).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 15 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "name": "sosumi-ai",
- "description": "Plugins from sosumi.ai",
- "owner": {
- "name": "NSHipster",
- "url": "https://nshipster.com"
- },
- "plugins": [
- {
- "name": "sosumi",
- "source": "./plugin",
- "description": "Search and read Apple Developer documentation, Human Interface Guidelines, WWDC transcripts, and Swift-DocC pages as Markdown."
- }
- ]
- }
README.md · README · 447 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # sosumi.ai
- Making Apple docs AI-readable.
- [sosumi.ai](https://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](https://developer.apple.com/design/human-interface-guidelines/) (HIG).
- WWDC session transcripts are also supported by replacing the same host for video URLs.
- When a session has code samples,
- the Markdown ends with a Code section that lists each sample with its timestamp and title.
- To get a transcript, replace the host in the video URL:
- **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 the Streamable HTTP transport.
- If your client supports it,
- configure it to connect directly to `https://sosumi.ai/mcp`.
- If your client supports stdio but not Streamable HTTP,
- such as a client whose only remote transport is the older HTTP+SSE transport,
- you can run this command to proxy over stdio:
- ```json
- {
- "mcpServers": {
- "sosumi": {
- "command": "npx",
- "args": ["-y", "mcp-remote", "https://sosumi.ai/mcp"]
- }
- }
- }
- ```
- See [the website](https://sosumi.ai/#clients) for client-specific instructions.
- #### Plugin
- The [`plugin`](plugin) folder packages the MCP server and the [agent skill](#ai-agent-skill)
- for Claude Code, Cursor, and [Agent Plugins](https://agent-plugins.org) clients
- such as ChatGPT and Codex.
- In Claude Code, run:
- ```text
- /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:
- ```bash
- 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 the transcript as Markdown, followed by the session's code samples when it has any
- - `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:
- ```bash
- npx @nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array
- ```
- If you use it regularly, install once:
- ```bash
- npm i -g @nshipster/sosumi
- ```
- Then use `sosumi` directly:
- ```bash
- sosumi fetch https://developer.apple.com/documentation/swift/array
- ```
- You can fetch all content types covered by MCP tools:
- ```bash
- # 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:
- ```bash
- sosumi serve
- sosumi serve --port 8787
- ```
- By default, output is plain text / Markdown.
- Use JSON output for scripts:
- ```bash
- 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`](https://sosumi.ai/SKILL.md)
- Spec-compliant clients can also install it with:
- ```bash
- npx skills add https://sosumi.ai
- ```
- ### Chrome Extension
- You can also use Sosumi from a community-contributed
- [Chrome extension](https://chromewebstore.google.com/detail/donffakeimppgoehccpfhlchmbfdmfpj?utm_source=item-share-cb),
- which adds a "Copy sosumi Link" button
- to Apple Developer documentation pages.
- [Source code](https://github.com/FromAtom/Link-Generator-for-sosumi.ai) is available on GitHub.
- ## Evaluation
- The [Swift API eval](evals/swift-api#results) gives agents 41 Swift tasks,
- most of which use APIs that are new in the macOS 27 and iOS 27 SDKs,
- and type-checks each answer against the SDK.
- Each model tried each task 3 times with Sosumi,
- with its provider's built-in web search, and with no documentation.
- Each cell shows the pass rate and the cost per attempt at list prices.
- | Model | Sosumi | Built-in web search | No documentation |
- | --- | --- | --- | --- |
- | Claude Haiku 5.5 | 76.4% ($0.0022) | 64.2% ($0.0197) | 22.8% ($0.0009) |
- | Claude Sonnet 5.5 | 93.5% ($0.0218) | 63.4% ($0.0446) | 30.9% ($0.0083) |
- | Claude Opus 5.5 | 98.4% ($0.0573) | 83.7% ($0.1116) | 38.2% ($0.0251) |
- | GPT-6.1 Sol | 96.7% ($0.0127) | 99.2% ($0.0396) | 33.3% ($0.0155) |
- With Sosumi, Claude models score 12 to 30 percentage points higher than with web search,
- at about half the cost or less.
- GPT-6.1 Sol scored 2.5 percentage points higher with web search than with Sosumi,
- at about 3 times the cost per attempt.
- Each score has a 95% interval of about ±9 points,
- and the providers' web tools differ,
- so compare conditions for one model.
- The eval's README describes the method, the caveats,
- and the commands that reproduce the runs.
- ## 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](https://workers.cloudflare.com).
- > [!NOTE]
- > The application is built with Hono,
- > making it compatible with various runtimes.
- >
- > See the [Hono docs](https://hono.dev/docs/getting-started/basic)
- > for more information about deploying to different platforms.
- ### Prerequisites
- - Node.js 20+
- - npm
- ### Quick Start
- 1. **Clone the repository:**
- ```bash
- git clone https://github.com/nshipster/sosumi.ai.git
- cd sosumi.ai
- ```
- 2. **Install dependencies:**
- ```bash
- npm install
- ```
- 3. **Start development server:**
- ```bash
- npm run dev
- ```
- Once the application is up and running, press the <kbd>b</kbd>
- 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](https://datatracker.ietf.org/wg/webbotauth/about/),
- so those hosts can cryptographically verify the traffic.
- - The public key set is published at
- [`/.well-known/http-message-signatures-directory`](https://sosumi.ai/.well-known/http-message-signatures-directory).
- - Requests to external hosts are signed
- with an Ed25519 [HTTP Message Signature (RFC 9421)](https://www.rfc-editor.org/rfc/rfc9421)
- 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:
- ```bash
- 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:
- ```bash
- 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](https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/)
- for these signatures.
- ## Development
- ### Testing
- This project uses [vitest](https://vitest.dev)
- for unit and integration testing.
- ```bash
- 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](https://biomejs.dev/)
- 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](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
- - [Vim/Neovim](https://github.com/biomejs/biome/tree/main/editors/vim)
- - [Emacs](https://github.com/biomejs/biome/tree/main/editors/emacs)
- ### Cloudflare Workers
- Whenever you update your `wrangler.toml` or change your Worker bindings,
- be sure to re-run:
- ```bash
- 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](https://registry.modelcontextprotocol.io)
- 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](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/authentication.mdx#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):
- ```bash
- 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=<public key>`
- 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 implements rate limiting to avoid imposing unreasonable load.
- For external Swift-DocC hosts, access can be denied by `robots.txt`
- and opt-out response directives such as `X-Robots-Tag: noai`.
- Content is fetched transiently and may be cached briefly to improve performance.
- No permanent archives are maintained.
- All copyrights and other rights in the underlying content remain with Apple Inc.
- Each page links back to the original source.
- Your use of this service must comply with Apple's Terms of Use and applicable law.
- You are solely responsible for how you access and use Apple's content through this tool.
- Do not use this service to circumvent technical measures or for redistribution.
- **Contact:** <info@sosumi.ai>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.