Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nshipster-sosumi-ai/badge.svg)](/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

i

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.

  1. {
  2. "name": "sosumi-ai",
  3. "description": "Plugins from sosumi.ai",
  4. "owner": {
  5. "name": "NSHipster",
  6. "url": "https://nshipster.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "sosumi",
  11. "source": "./plugin",
  12. "description": "Search and read Apple Developer documentation, Human Interface Guidelines, WWDC transcripts, and Swift-DocC pages as Markdown."
  13. }
  14. ]
  15. }
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.

  1. # sosumi.ai
  2. Making Apple docs AI-readable.
  3. [sosumi.ai](https://sosumi.ai)
  4. provides Apple Developer documentation in an AI-readable format
  5. by converting JavaScript-rendered pages into Markdown.
  6. ## Usage
  7. ### HTTP API
  8. Replace `developer.apple.com` with `sosumi.ai`
  9. in any Apple Developer documentation URL:
  10. **Original:**
  11. ```
  12. https://developer.apple.com/documentation/swift/array
  13. ```
  14. **AI-readable:**
  15. ```
  16. https://sosumi.ai/documentation/swift/array
  17. ```
  18. This works for all API reference docs,
  19. as well as Apple's [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/) (HIG).
  20. WWDC session transcripts are also supported by replacing the same host for video URLs.
  21. When a session has code samples,
  22. the Markdown ends with a Code section that lists each sample with its timestamp and title.
  23. To get a transcript, replace the host in the video URL:
  24. **Original:**
  25. ```
  26. https://developer.apple.com/videos/play/wwdc2021/10133/
  27. ```
  28. **AI-readable:**
  29. ```
  30. https://sosumi.ai/videos/play/wwdc2021/10133
  31. ```
  32. Sosumi can also proxy public non-Apple Swift-DocC pages using:
  33. **Original:**
  34. ```
  35. https://swiftlang.github.io/swift-docc-plugin/documentation/swiftdoccplugin
  36. ```
  37. **AI-readable:**
  38. ```
  39. https://sosumi.ai/external/https://swiftlang.github.io/swift-docc-plugin/documentation/swiftdoccplugin
  40. ```
  41. > [!NOTE]
  42. > Sosumi resolves the URL to the site's underlying DocC JSON endpoint
  43. > and renders Markdown, preserving any base path from the original URL.
  44. > External hosts can opt out via `robots.txt`
  45. > by disallowing user-agent `sosumi-ai`
  46. > (full UA: `sosumi-ai/1.0 (+https://sosumi.ai/#bot)`).
  47. > See `/bot` for the crawler policy and contact details.
  48. ### MCP Integration
  49. Sosumi's MCP server supports the Streamable HTTP transport.
  50. If your client supports it,
  51. configure it to connect directly to `https://sosumi.ai/mcp`.
  52. If your client supports stdio but not Streamable HTTP,
  53. such as a client whose only remote transport is the older HTTP+SSE transport,
  54. you can run this command to proxy over stdio:
  55. ```json
  56. {
  57. "mcpServers": {
  58. "sosumi": {
  59. "command": "npx",
  60. "args": ["-y", "mcp-remote", "https://sosumi.ai/mcp"]
  61. }
  62. }
  63. }
  64. ```
  65. See [the website](https://sosumi.ai/#clients) for client-specific instructions.
  66. #### Plugin
  67. The [`plugin`](plugin) folder packages the MCP server and the [agent skill](#ai-agent-skill)
  68. for Claude Code, Cursor, and [Agent Plugins](https://agent-plugins.org) clients
  69. such as ChatGPT and Codex.
  70. In Claude Code, run:
  71. ```text
  72. /plugin marketplace add NSHipster/sosumi.ai
  73. /plugin install sosumi@sosumi-ai
  74. ```
  75. `public/SKILL.md` is the source of the skill.
  76. After you edit it, copy it into the plugin:
  77. ```bash
  78. cp public/SKILL.md plugin/skills/sosumi/SKILL.md
  79. ```
  80. A test fails when the two files differ.
  81. #### Available Tools
  82. - `searchAppleDocumentation` - Searches Apple Developer documentation
  83. - Parameters: `query` (string)
  84. - Returns structured results with titles, URLs, descriptions, breadcrumbs, and tags
  85. - `fetchAppleDocumentation` - Fetches Apple Developer documentation and Human Interface Guidelines by path
  86. - Parameters: `path` (string) - Documentation path (e.g., '/documentation/swift', '/documentation/swiftui/view', '/design/human-interface-guidelines/foundations/color')
  87. - Returns content as Markdown
  88. - `fetchAppleVideoTranscript` - Fetches video transcripts, including WWDC sessions
  89. - Parameters: `path` (string) - video path (e.g., `/videos/play/wwdc2021/10133`)
  90. - Returns the transcript as Markdown, followed by the session's code samples when it has any
  91. - `fetchExternalDocumentation` - Fetches external Swift-DocC documentation by absolute HTTPS URL
  92. - Parameters: `url` (string) - External URL (e.g., `https://swiftlang.github.io/swift-docc-plugin/documentation/swiftdoccplugin`)
  93. - Returns content as Markdown
  94. ### CLI
  95. Sosumi also provides a CLI that complements MCP:
  96. ```bash
  97. npx @nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array
  98. ```
  99. If you use it regularly, install once:
  100. ```bash
  101. npm i -g @nshipster/sosumi
  102. ```
  103. Then use `sosumi` directly:
  104. ```bash
  105. sosumi fetch https://developer.apple.com/documentation/swift/array
  106. ```
  107. You can fetch all content types covered by MCP tools:
  108. ```bash
  109. # Apple documentation / HIG / videos
  110. sosumi fetch /documentation/swift/array
  111. sosumi fetch /design/human-interface-guidelines/color
  112. sosumi fetch /videos/play/wwdc2021/10133
  113. # External Swift-DocC pages
  114. sosumi fetch https://swiftlang.github.io/swift-docc-plugin/documentation/swiftdoccplugin
  115. # Apple documentation search
  116. sosumi search "SwiftData"
  117. ```
  118. Run a local server from the published package:
  119. ```bash
  120. sosumi serve
  121. sosumi serve --port 8787
  122. ```
  123. By default, output is plain text / Markdown.
  124. Use JSON output for scripts:
  125. ```bash
  126. sosumi fetch https://developer.apple.com/documentation/swift/array --json
  127. sosumi search "SwiftData" --json
  128. ```
  129. ### AI Agent Skill
  130. Want your AI coding assistant to use Sosumi consistently?
  131. Use the hosted skill file:
  132. [`https://sosumi.ai/SKILL.md`](https://sosumi.ai/SKILL.md)
  133. Spec-compliant clients can also install it with:
  134. ```bash
  135. npx skills add https://sosumi.ai
  136. ```
  137. ### Chrome Extension
  138. You can also use Sosumi from a community-contributed
  139. [Chrome extension](https://chromewebstore.google.com/detail/donffakeimppgoehccpfhlchmbfdmfpj?utm_source=item-share-cb),
  140. which adds a "Copy sosumi Link" button
  141. to Apple Developer documentation pages.
  142. [Source code](https://github.com/FromAtom/Link-Generator-for-sosumi.ai) is available on GitHub.
  143. ## Evaluation
  144. The [Swift API eval](evals/swift-api#results) gives agents 41 Swift tasks,
  145. most of which use APIs that are new in the macOS 27 and iOS 27 SDKs,
  146. and type-checks each answer against the SDK.
  147. Each model tried each task 3 times with Sosumi,
  148. with its provider's built-in web search, and with no documentation.
  149. Each cell shows the pass rate and the cost per attempt at list prices.
  150. | Model | Sosumi | Built-in web search | No documentation |
  151. | --- | --- | --- | --- |
  152. | Claude Haiku 5.5 | 76.4% ($0.0022) | 64.2% ($0.0197) | 22.8% ($0.0009) |
  153. | Claude Sonnet 5.5 | 93.5% ($0.0218) | 63.4% ($0.0446) | 30.9% ($0.0083) |
  154. | Claude Opus 5.5 | 98.4% ($0.0573) | 83.7% ($0.1116) | 38.2% ($0.0251) |
  155. | GPT-6.1 Sol | 96.7% ($0.0127) | 99.2% ($0.0396) | 33.3% ($0.0155) |
  156. With Sosumi, Claude models score 12 to 30 percentage points higher than with web search,
  157. at about half the cost or less.
  158. GPT-6.1 Sol scored 2.5 percentage points higher with web search than with Sosumi,
  159. at about 3 times the cost per attempt.
  160. Each score has a 95% interval of about ±9 points,
  161. and the providers' web tools differ,
  162. so compare conditions for one model.
  163. The eval's README describes the method, the caveats,
  164. and the commands that reproduce the runs.
  165. ## Self-Hosting
  166. This project is designed to be easily run on your own machine
  167. or deployed to a hosting provider.
  168. Sosumi.ai is currently hosted by
  169. [Cloudflare Workers](https://workers.cloudflare.com).
  170. > [!NOTE]
  171. > The application is built with Hono,
  172. > making it compatible with various runtimes.
  173. >
  174. > See the [Hono docs](https://hono.dev/docs/getting-started/basic)
  175. > for more information about deploying to different platforms.
  176. ### Prerequisites
  177. - Node.js 20+
  178. - npm
  179. ### Quick Start
  180. 1. **Clone the repository:**
  181. ```bash
  182. git clone https://github.com/nshipster/sosumi.ai.git
  183. cd sosumi.ai
  184. ```
  185. 2. **Install dependencies:**
  186. ```bash
  187. npm install
  188. ```
  189. 3. **Start development server:**
  190. ```bash
  191. npm run dev
  192. ```
  193. Once the application is up and running, press the <kbd>b</kbd>
  194. to open the URL in your browser.
  195. To configure MCP clients to use your development server,
  196. replace `sosumi.ai` with the local server address
  197. (`http://localhost:8787` by default).
  198. ### External Host Restrictions
  199. You can restrict which external Swift-DocC hosts are reachable
  200. with two environment variables (both newline-delimited):
  201. - `EXTERNAL_DOC_HOST_ALLOWLIST` — only listed hosts are permitted
  202. - `EXTERNAL_DOC_HOST_BLOCKLIST` — listed hosts are always denied
  203. > [!IMPORTANT]
  204. > Hostname-based private-network checks cannot fully prevent DNS rebinding.
  205. > Set an explicit `EXTERNAL_DOC_HOST_ALLOWLIST` in production.
  206. ### Web Bot Auth
  207. Sosumi identifies itself
  208. when it fetches from external Swift-DocC hosts on a user's behalf
  209. using [Web Bot Auth](https://datatracker.ietf.org/wg/webbotauth/about/),
  210. so those hosts can cryptographically verify the traffic.
  211. - The public key set is published at
  212. [`/.well-known/http-message-signatures-directory`](https://sosumi.ai/.well-known/http-message-signatures-directory).
  213. - Requests to external hosts are signed
  214. with an Ed25519 [HTTP Message Signature (RFC 9421)](https://www.rfc-editor.org/rfc/rfc9421)
  215. and carry `Signature-Agent`, `Signature-Input`, and `Signature` headers.
  216. To enable signing on your own deployment,
  217. provide an Ed25519 private key (as a JSON Web Key)
  218. via the `WEB_BOT_AUTH_KEY` secret.
  219. Generate a key (the JSON Web Key is the format `WEB_BOT_AUTH_KEY` expects),
  220. then paste the printed value when `wrangler secret put` prompts for it:
  221. ```bash
  222. 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}))})'
  223. npx wrangler secret put WEB_BOT_AUTH_KEY
  224. ```
  225. Or generate and upload in a single step,
  226. which avoids writing the key to disk or shell history:
  227. ```bash
  228. 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}))})' \
  229. | npx wrangler secret put WEB_BOT_AUTH_KEY
  230. ```
  231. The matching public key and its `kid` (JWK thumbprint) are derived automatically,
  232. so no key material lives in the repository.
  233. Set the optional `SIGNATURE_AGENT` var to override the advertised origin
  234. (defaults to `https://sosumi.ai`).
  235. When no key is configured, requests are simply sent unsigned.
  236. Cloudflare provides
  237. [built-in verification](https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/)
  238. for these signatures.
  239. ## Development
  240. ### Testing
  241. This project uses [vitest](https://vitest.dev)
  242. for unit and integration testing.
  243. ```bash
  244. npm run test # Run tests
  245. npm run test:ui # Run tests with UI
  246. npm run test:run # Run tests once
  247. ```
  248. > [!TIP]
  249. > When running the CLI through npm scripts during local development,
  250. > use `-s` (`--silent`)
  251. > to suppress npm's script preamble so output pipes cleanly:
  252. >
  253. > ```bash
  254. > npm run -s cli -- fetch https://developer.apple.com/documentation/swift/array | bat -l md
  255. > ```
  256. ### Code Quality
  257. This project uses [Biome](https://biomejs.dev/)
  258. for code formatting, linting, and import organization.
  259. - `npm run format` - Format all code files
  260. - `npm run lint` - Lint and fix code issues
  261. - `npm run check` - Format, lint, and organize imports (recommended)
  262. - `npm run check:ci` - Check code without making changes (for CI)
  263. ### Editor Integration
  264. For the best development experience, install the Biome extension for your editor:
  265. - [VSCode](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
  266. - [Vim/Neovim](https://github.com/biomejs/biome/tree/main/editors/vim)
  267. - [Emacs](https://github.com/biomejs/biome/tree/main/editors/emacs)
  268. ### Cloudflare Workers
  269. Whenever you update your `wrangler.toml` or change your Worker bindings,
  270. be sure to re-run:
  271. ```bash
  272. npm run cf-typegen
  273. ```
  274. ### Publishing
  275. Publishing is handled by `.github/workflows/release.yml`.
  276. - Trigger: pushed tags matching `v*` or manual dispatch with `tag`
  277. - Release step: `gh release create "$TAG_NAME" --generate-notes`
  278. - Publish auth: npm trusted publishing via OIDC (`id-token: write`)
  279. - Publish command: `npm publish --provenance --access public`
  280. - MCP Registry: after `npm publish`, the workflow publishes `server.json`
  281. to the [MCP Registry](https://registry.modelcontextprotocol.io)
  282. as `ai.sosumi/sosumi`.
  283. Keep `version` in `server.json` equal to `version` in `package.json`;
  284. a test fails when they differ.
  285. The registry step uses
  286. [HTTP authentication](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/authentication.mdx#http-authentication)
  287. for the `sosumi.ai` domain.
  288. It skips with a notice until the `MCP_REGISTRY_PRIVATE_KEY` secret is set.
  289. To set it up, generate an Ed25519 key pair with OpenSSL 3
  290. (macOS's LibreSSL does not support Ed25519):
  291. ```bash
  292. openssl genpkey -algorithm Ed25519 -out key.pem
  293. # Public key: add to "vars" in wrangler.jsonc as MCP_REGISTRY_PUBLIC_KEY, then deploy
  294. openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64
  295. # Private key (hex): save as the MCP_REGISTRY_PRIVATE_KEY repository secret
  296. openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n'
  297. ```
  298. The Worker then serves `v=MCPv1; k=ed25519; p=<public key>`
  299. at `/.well-known/mcp-registry-auth`.
  300. Without the variable, that path returns 404.
  301. Delete `key.pem` after you save both values.
  302. ## License
  303. This project is available under the MIT license.
  304. See the LICENSE file for more info.
  305. ## Legal
  306. This is an unofficial,
  307. independent project and is not affiliated with or endorsed by Apple Inc.
  308. "Apple", "Xcode", and related marks are trademarks of Apple Inc.
  309. This service is an accessibility-first,
  310. on‑demand renderer.
  311. It converts a single Apple Developer page to Markdown only when requested by a user.
  312. It does not crawl, spider, or bulk download;
  313. it does not attempt to bypass authentication or security;
  314. and it implements rate limiting to avoid imposing unreasonable load.
  315. For external Swift-DocC hosts, access can be denied by `robots.txt`
  316. and opt-out response directives such as `X-Robots-Tag: noai`.
  317. Content is fetched transiently and may be cached briefly to improve performance.
  318. No permanent archives are maintained.
  319. All copyrights and other rights in the underlying content remain with Apple Inc.
  320. Each page links back to the original source.
  321. Your use of this service must comply with Apple's Terms of Use and applicable law.
  322. You are solely responsible for how you access and use Apple's content through this tool.
  323. Do not use this service to circumvent technical measures or for redistribution.
  324. **Contact:** <info@sosumi.ai>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.