[!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:
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.
[!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
Clone the repository:
git clone https://github.com/nshipster/sosumi.ai.git
cd sosumi.ai
Install dependencies:
npm install
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.
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:
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.
Publish auth: npm trusted publishing via OIDC (id-token: write)
Publish command: npm publish --provenance --access public
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.