{
  "markdown": "# sosumi.ai\n\nMaking Apple docs AI-readable.\n\n[sosumi.ai](https://sosumi.ai)\nprovides Apple Developer documentation in an AI-readable format\nby converting JavaScript-rendered pages into Markdown.\n\n## Usage\n\n### HTTP API\n\nReplace `developer.apple.com` with `sosumi.ai`\nin any Apple Developer documentation URL:\n\n**Original:**\n\n```\nhttps://developer.apple.com/documentation/swift/array\n```\n\n**AI-readable:**\n\n```\nhttps://sosumi.ai/documentation/swift/array\n```\n\nThis works for all API reference docs,\nas well as Apple's [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/) (HIG).\n\nWWDC session transcripts are also supported by replacing the same host for video URLs:\n\n**Original:**\n\n```\nhttps://developer.apple.com/videos/play/wwdc2021/10133/\n```\n\n**AI-readable:**\n\n```\nhttps://sosumi.ai/videos/play/wwdc2021/10133\n```\n\nSosumi can also proxy public non-Apple Swift-DocC pages using:\n\n**Original:**\n\n```\nhttps://apple.github.io/swift-argument-parser/documentation/argumentparser\n```\n\n**AI-readable:**\n\n```\nhttps://sosumi.ai/external/https://apple.github.io/swift-argument-parser/documentation/argumentparser\n```\n\n> [!NOTE]\n> Sosumi resolves the URL to the site's underlying DocC JSON endpoint\n> and renders Markdown, preserving any base path from the original URL.\n> External hosts can opt out via `robots.txt`\n> by disallowing user-agent `sosumi-ai`\n> (full UA: `sosumi-ai/1.0 (+https://sosumi.ai/#bot)`).\n> See `/bot` for the crawler policy and contact details.\n\n### MCP Integration\n\nSosumi's MCP server supports Streamable HTTP and Server-Sent Events (SSE) transport.\nIf your client supports either of these,\nconfigure it to connect directly to `https://sosumi.ai/mcp`.\n\nOtherwise,\nyou can run this command to proxy over stdio:\n\n```json\n{\n  \"mcpServers\": {\n    \"sosumi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-remote\", \"https://sosumi.ai/mcp\"]\n    }\n  }\n}\n```\n\nSee [the website](https://sosumi.ai/#clients) for client-specific instructions.\n\n#### Available Tools\n\n- `searchAppleDocumentation` - Searches Apple Developer documentation\n  - Parameters: `query` (string)\n  - Returns structured results with titles, URLs, descriptions, breadcrumbs, and tags\n\n- `fetchAppleDocumentation` - Fetches Apple Developer documentation and Human Interface Guidelines by path\n  - Parameters: `path` (string) - Documentation path (e.g., '/documentation/swift', '/documentation/swiftui/view', '/design/human-interface-guidelines/foundations/color')\n  - Returns content as Markdown\n\n- `fetchAppleVideoTranscript` - Fetches video transcripts, including WWDC sessions\n  - Parameters: `path` (string) - video path (e.g., `/videos/play/wwdc2021/10133`)\n  - Returns transcript content as Markdown\n\n- `fetchExternalDocumentation` - Fetches external Swift-DocC documentation by absolute HTTPS URL\n  - Parameters: `url` (string) - External URL (e.g., `https://apple.github.io/swift-argument-parser/documentation/argumentparser`)\n  - Returns content as Markdown\n\n### CLI\n\nSosumi also provides a CLI that complements MCP:\n\n```bash\nnpx @nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array\n```\n\nIf you use it regularly, install once:\n\n```bash\nnpm i -g @nshipster/sosumi\n```\n\nThen use `sosumi` directly:\n\n```bash\nsosumi fetch https://developer.apple.com/documentation/swift/array\n```\n\nYou can fetch all content types covered by MCP tools:\n\n```bash\n# Apple documentation / HIG / videos\nsosumi fetch /documentation/swift/array\nsosumi fetch /design/human-interface-guidelines/color\nsosumi fetch /videos/play/wwdc2021/10133\n\n# External Swift-DocC pages\nsosumi fetch https://apple.github.io/swift-argument-parser/documentation/argumentparser\n\n# Apple documentation search\nsosumi search \"SwiftData\"\n```\n\nRun a local server from the published package:\n\n```bash\nsosumi serve\nsosumi serve --port 8787\n```\n\nBy default, output is plain text / Markdown.\nUse JSON output for scripts:\n\n```bash\nsosumi fetch https://developer.apple.com/documentation/swift/array --json\nsosumi search \"SwiftData\" --json\n```\n\n### AI Agent Skill\n\nWant your AI coding assistant to use Sosumi consistently?\nUse the hosted skill file:\n[`https://sosumi.ai/SKILL.md`](https://sosumi.ai/SKILL.md)\n\nSpec-compliant clients can also install it with:\n\n```bash\nnpx skills add https://sosumi.ai\n```\n\n### Chrome Extension\n\nYou can also use Sosumi from a community-contributed\n[Chrome extension](https://chromewebstore.google.com/detail/donffakeimppgoehccpfhlchmbfdmfpj?utm_source=item-share-cb),\nwhich adds a \"Copy sosumi Link\" button\nto Apple Developer documentation pages.\n[Source code](https://github.com/FromAtom/Link-Generator-for-sosumi.ai) is available on GitHub.\n\n## Self-Hosting\n\nThis project is designed to be easily run on your own machine\nor deployed to a hosting provider.\n\nSosumi.ai is currently hosted by\n[Cloudflare Workers](https://workers.cloudflare.com).\n\n> [!NOTE]  \n> The application is built with Hono,\n> making it compatible with various runtimes.\n>\n> See the [Hono docs](https://hono.dev/docs/getting-started/basic)\n> for more information about deploying to different platforms.\n\n### Prerequisites\n\n- Node.js 20+\n- npm\n\n### Quick Start\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone https://github.com/nshipster/sosumi.ai.git\n   cd sosumi.ai\n   ```\n\n2. **Install dependencies:**\n\n   ```bash\n   npm install\n   ```\n\n3. **Start development server:**\n\n   ```bash\n   npm run dev\n   ```\n\nOnce the application is up and running, press the <kbd>b</kbd>\nto open the URL in your browser.\n\nTo configure MCP clients to use your development server,\nreplace `sosumi.ai` with the local server address\n(`http://localhost:8787` by default).\n\n### External Host Restrictions\n\nYou can restrict which external Swift-DocC hosts are reachable\nwith two environment variables (both newline-delimited):\n\n- `EXTERNAL_DOC_HOST_ALLOWLIST` — only listed hosts are permitted\n- `EXTERNAL_DOC_HOST_BLOCKLIST` — listed hosts are always denied\n\n> [!IMPORTANT]\n> Hostname-based private-network checks cannot fully prevent DNS rebinding.\n> Set an explicit `EXTERNAL_DOC_HOST_ALLOWLIST` in production.\n\n### Web Bot Auth\n\nSosumi identifies itself\nwhen it fetches from external Swift-DocC hosts on a user's behalf\nusing [Web Bot Auth](https://datatracker.ietf.org/wg/webbotauth/about/),\nso those hosts can cryptographically verify the traffic.\n\n- The public key set is published at\n  [`/.well-known/http-message-signatures-directory`](https://sosumi.ai/.well-known/http-message-signatures-directory).\n- Requests to external hosts are signed\n  with an Ed25519 [HTTP Message Signature (RFC 9421)](https://www.rfc-editor.org/rfc/rfc9421)\n  and carry `Signature-Agent`, `Signature-Input`, and `Signature` headers.\n\nTo enable signing on your own deployment,\nprovide an Ed25519 private key (as a JSON Web Key)\nvia the `WEB_BOT_AUTH_KEY` secret.\n\nGenerate a key (the JSON Web Key is the format `WEB_BOT_AUTH_KEY` expects),\nthen paste the printed value when `wrangler secret put` prompts for it:\n\n```bash\nnode -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}))})'\nnpx wrangler secret put WEB_BOT_AUTH_KEY\n```\n\nOr generate and upload in a single step,\nwhich avoids writing the key to disk or shell history:\n\n```bash\nnode -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}))})' \\\n  | npx wrangler secret put WEB_BOT_AUTH_KEY\n```\n\nThe matching public key and its `kid` (JWK thumbprint) are derived automatically,\nso no key material lives in the repository.\nSet the optional `SIGNATURE_AGENT` var to override the advertised origin\n(defaults to `https://sosumi.ai`).\nWhen no key is configured, requests are simply sent unsigned.\n\nCloudflare provides\n[built-in verification](https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/)\nfor these signatures.\n\n## Development\n\n### Testing\n\nThis project uses [vitest](https://vitest.dev)\nfor unit and integration testing.\n\n```bash\nnpm run test          # Run tests\nnpm run test:ui       # Run tests with UI\nnpm run test:run      # Run tests once\n```\n\n> [!TIP]\n> When running the CLI through npm scripts during local development,\n> use `-s` (`--silent`)\n> to suppress npm's script preamble so output pipes cleanly:\n>\n> ```bash\n> npm run -s cli -- fetch https://developer.apple.com/documentation/swift/array | bat -l md\n> ```\n\n### Code Quality\n\nThis project uses [Biome](https://biomejs.dev/)\nfor code formatting, linting, and import organization.\n\n- `npm run format` - Format all code files\n- `npm run lint` - Lint and fix code issues\n- `npm run check` - Format, lint, and organize imports (recommended)\n- `npm run check:ci` - Check code without making changes (for CI)\n\n### Editor Integration\n\nFor the best development experience, install the Biome extension for your editor:\n\n- [VSCode](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)\n- [Vim/Neovim](https://github.com/biomejs/biome/tree/main/editors/vim)\n- [Emacs](https://github.com/biomejs/biome/tree/main/editors/emacs)\n\n### Cloudflare Workers\n\nWhenever you update your `wrangler.toml` or change your Worker bindings,\nbe sure to re-run:\n\n```bash\nnpm run cf-typegen\n```\n\n### Publishing\n\nPublishing is handled by `.github/workflows/release.yml`.\n\n- Trigger: pushed tags matching `v*` or manual dispatch with `tag`\n- Release step: `gh release create \"$TAG_NAME\" --generate-notes`\n- Publish auth: npm trusted publishing via OIDC (`id-token: write`)\n- Publish command: `npm publish --provenance --access public`\n\n## License\n\nThis project is available under the MIT license.\nSee the LICENSE file for more info.\n\n## Legal\n\nThis is an unofficial,\nindependent project and is not affiliated with or endorsed by Apple Inc.\n\"Apple\", \"Xcode\", and related marks are trademarks of Apple Inc.\n\nThis service is an accessibility-first,\non‑demand renderer.\nIt converts a single Apple Developer page to Markdown only when requested by a user.\nIt does not crawl, spider, or bulk download;\nit does not attempt to bypass authentication or security;\nand it implements rate limiting to avoid imposing unreasonable load.\n\nFor external Swift-DocC hosts, access can be denied by `robots.txt`\nand opt-out response directives such as `X-Robots-Tag: noai`.\n\nContent is fetched transiently and may be cached briefly to improve performance.\nNo permanent archives are maintained.\nAll copyrights and other rights in the underlying content remain with Apple Inc.\nEach page links back to the original source.\n\nYour use of this service must comply with Apple's Terms of Use and applicable law.\nYou are solely responsible for how you access and use Apple's content through this tool.\nDo not use this service to circumvent technical measures or for redistribution.\n\n**Contact:** <info@sosumi.ai>\n",
  "bytes": 10984,
  "sha": "a0d27c21d81d8821fde008529951a1c630602e72b03e22324f78246dd07a8604",
  "repo_slug": "nshipster/sosumi.ai",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_nshipster_sosumi_ai_sosumi_289c0aac/readme"
}