sosumi.ai

# 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:**
<https://developer.apple.com/documentation/swift/array>

**AI-readable:**
<https://sosumi.ai/documentation/swift/array>

### Examples

- Swift: <https://sosumi.ai/documentation/swift>
- SwiftUI: <https://sosumi.ai/documentation/swiftui>
- Human Interface Guidelines: <https://sosumi.ai/design/human-interface-guidelines>
- WWDC21 — Protect mutable state with Swift actors: <https://sosumi.ai/videos/play/wwdc2021/10133>
- Swift Argument Parser (GitHub Pages): <https://sosumi.ai/external/https://apple.github.io/swift-argument-parser/documentation/argumentparser/>
- The Composable Architecture (Swift Package Index): <https://sosumi.ai/external/https://swiftpackageindex.com/pointfreeco/swift-composable-architecture/1.23.1/documentation/composablearchitecture>

## 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., '<https://apple.github.io/swift-argument-parser/documentation/argumentparser>')
  - 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:** <info@sosumi.ai>