# sosumi.ai - Apple Docs for LLMs Ever notice Claude struggling to write Swift code? It might not be their fault! Apple Developer docs are locked behind JavaScript, making them invisible to most LLMs. If they try to fetch it, all they see is: > This page requires JavaScript. > Please turn on JavaScript in your browser and refresh the page to view its content. This service translates Apple Developer documentation, Human Interface Guidelines, WWDC sessions, and external Swift-DocC sites into AI-friendly Markdown. Access it in your browser, over MCP, from the command line, as an AI skill, or with an unofficial [Chrome extension](https://chromewebstore.google.com/detail/donffakeimppgoehccpfhlchmbfdmfpj). ## HTTP Usage Replace `developer.apple.com` with `sosumi.ai`: **Original:** **AI-readable:** ### Examples - Swift: - SwiftUI: - Human Interface Guidelines: - WWDC21 — Protect mutable state with Swift actors: - Swift Argument Parser (GitHub Pages): - The Composable Architecture (Swift Package Index): ## MCP Usage Connect your MCP client to `https://sosumi.ai/mcp`. ### GitHub Copilot for Xcode 1. Open **GitHub Copilot for Xcode** and go to **Settings…** 2. Select the **MCP** tab 3. Click **Edit Config** 4. Enter the following configuration: ```json { "servers": { "sosumi": { "type": "http", "url": "https://sosumi.ai/mcp" } } } ``` ### Cursor Open this deep link to automatically install the sosumi MCP server: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=sosumi&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vc29zdW1pLmFpL21jcCJ9) ### VSCode Create a `.vscode/mcp.json` file in your workspace and enter the following configuration: ```json { "servers": { "sosumi": { "type": "http", "url": "https://sosumi.ai/mcp" } } } ``` ### Claude Desktop 1. Open **Claude Desktop** 2. Go to **Settings → Connectors** 3. Click **"Add custom connector"** 4. Set **"Name"** to `"sosumi"` 5. Set **"Remote MCP server URL"** to `"https://sosumi.ai/mcp"` 6. Click "Add" ### Claude Code Run the following command in your terminal: ```shell claude mcp add --transport http sosumi https://sosumi.ai/mcp ``` ### Other MCP Clients 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: ```json { "mcpServers": { "sosumi": { "command": "npx", "args": ["-y", "mcp-remote", "https://sosumi.ai/mcp"] } } } ``` ### 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, by video path - Parameters: `path` (string) - video path (e.g., '/videos/play/wwdc2021/10133', '/videos/play/meet-with-apple/208') - Returns content as Markdown - `fetchExternalDocumentation` - Fetches external Swift-DocC documentation by absolute HTTPS URL - Parameters: `url` (string) - External URL (e.g., '') - Returns content as Markdown ### Troubleshooting If you're experiencing connection timeouts or network issues with the MCP server, you may need to configure a proxy. This is particularly common in corporate environments or regions with restricted internet access. Configure your MCP client to use a proxy by adding environment variables: ```json { "mcpServers": { "sosumi": { "command": "npx", "args": ["-y", "mcp-remote", "https://sosumi.ai/mcp"], "env": { "HTTP_PROXY": "http://proxy.example.com:8080", "HTTPS_PROXY": "http://proxy.example.com:8080" } } } } ``` Replace `proxy.example.com:8080` with your actual proxy server details. For authenticated proxies, use the format: `http://username:password@proxy.example.com:8080` ## CLI Usage Sosumi also provides a CLI that complements MCP. ### Node.js Run directly with [`npx`](https://docs.npmjs.com/cli/commands/npx) (included with [Node.js](https://nodejs.org/)): ```shell npx @nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array ``` If you use it regularly, install it once: ```shell npm i -g @nshipster/sosumi ``` ### Bun Run directly with [`bunx`](https://bun.sh/docs/cli/bunx) (included with [Bun](https://bun.sh/)): ```shell bunx @nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array ``` If you use it regularly, install it once: ```shell bun i -g @nshipster/sosumi ``` ### Deno Run directly with [`deno run`](https://docs.deno.com/runtime/reference/cli/run/): ```shell deno run -A npm:@nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array ``` If you use it regularly, install it once: ```shell deno install -g -A npm:@nshipster/sosumi ``` ### Fetching Documentation Fetch any content type supported by the MCP tools — API docs, Human Interface Guidelines, WWDC sessions, and external Swift-DocC pages: ```shell sosumi fetch /documentation/swift/array sosumi fetch /design/human-interface-guidelines/color sosumi fetch /videos/play/wwdc2021/10133 sosumi fetch https://apple.github.io/swift-argument-parser/documentation/argumentparser ``` ### Searching Search Apple Developer documentation: ```shell sosumi search "SwiftData" ``` ### JSON Output By default, output is plain text / Markdown. Add `--json` for scripts: ```shell sosumi fetch /documentation/swift/array --json sosumi search "SwiftData" --json ``` ### Local Server Run a local instance of the server from the published package: ```shell sosumi serve sosumi serve --port 8787 ``` ## AI Agent Skill Teach your coding assistant to use Sosumi consistently with: `https://sosumi.ai/SKILL.md` Spec-compliant clients can also discover and install it from this domain: ```bash npx skills add https://sosumi.ai ``` ### Claude Code Install as a reusable skill (personal or project-level): ```bash # Personal skill (all your projects) mkdir -p ~/.claude/skills/sosumi curl -o ~/.claude/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md # Project skill (just this project) mkdir -p .claude/skills/sosumi curl -o .claude/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md ``` ### Codex Install globally: ```bash # Global instructions (all your projects) mkdir -p ~/.agents/skills/sosumi curl -o ~/.agents/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md ``` ### Cursor Install as a Cursor skill (global or project-level): ```bash # Personal skill (all your projects) mkdir -p ~/.cursor/skills/sosumi curl -o ~/.cursor/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md # Project skill (just this project) mkdir -p .cursor/skills/sosumi curl -o .cursor/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md ``` ### Other For AGENTS-compatible tools, install as a reusable skill: ```bash mkdir -p ~/.agents/skills/sosumi curl -o ~/.agents/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md ``` Use this together with Sosumi MCP at `https://sosumi.ai/mcp`. ## 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 project is open source and available on [GitHub](https://github.com/NSHipster/sosumi.ai). 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. 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. Fetches are made with the user agent `sosumi-ai/1.0 (+https://sosumi.ai/#bot)`. For external Swift-DocC hosts, sosumi honors `robots.txt` rules and opt-out response directives such as `X-Robots-Tag: noai`. **Contact:**