sosumi-cc

Apple developer documentation MCP for Claude Code — local stdio, no hosting required.

This is a fork of NSHipster/sosumi.ai packaged as a Claude Code plugin and shipping a working stdio MCP server so it runs entirely on your machine. The upstream search bug (issue #55) is fixed by switching search to Apple's current MSC backend at https://devintserv.msc.sbz.apple.com/api/v1/search (the same endpoint Apple's own developer.apple.com/search/scripts/search.js calls). Builds on the groundwork from upstream PR #54 by @jkaunert.

What you get

Four MCP tools wired into Claude Code (namespaced as mcp__plugin_sosumi_sosumi__* once the plugin is installed):

| Tool | Purpose | |---|---| | searchAppleDocumentation | Full-text search across Apple developer docs | | fetchAppleDocumentation | Fetch a doc page by path (e.g. /documentation/swiftui/view) | | fetchAppleVideoTranscript | Fetch a WWDC session transcript | | fetchExternalDocumentation | Fetch external Swift-DocC hosted docs |

Four slash commands for direct invocation without natural-language wrapping:

| Command | Behavior | |---|---| | /sosumi:fetch <path-or-url> | Fetch a single doc page as Markdown. Accepts /documentation/... paths or full developer.apple.com URLs. | | /sosumi:search <query> | Search Apple docs and print a formatted list of every result. | | /sosumi:wwdc <session> | Fetch a WWDC transcript. Accepts wwdc2024/10150, /videos/play/wwdc2024/10150, or a full URL. | | /sosumi:hig <topic> | Fetch a Human Interface Guidelines page. Accepts a HIG sub-path or a full path. Falls back to a search if the path doesn't resolve. |

One subagent — apple-docs-researcher — for deep multi-page research with isolated context, restricted to the four sosumi MCP tools (read-only). Trigger by asking Claude to "research" or "compare" or "explore" an area of Apple's docs.

One skill (SKILL.md) so the model knows when to reach for the tools.

Install (Claude Code plugin)

/plugin marketplace add PowerBeef/sosumi-cc
/plugin install sosumi@sosumi-cc

Restart Claude Code (or /reload-plugins) and the MCP tools, slash commands, skill, and apple-docs-researcher subagent all become available.

Install (manual MCP, no plugin system)

claude mcp add -s user sosumi -- npx --yes --package sosumi-cc sosumi-mcp-stdio

Or, if you'd rather install once globally:

npm install -g sosumi-cc
claude mcp add -s user sosumi -- sosumi-mcp-stdio

Requirements

• Node.js ≥ 20.18.1. Any node version manager works (mise, nvm, fnm, asdf, volta) — or system-installed node.
• No homebrew dependency. Everything runs through whatever node/npx is on your PATH.

mise users

If you use mise to manage node:

mise install node@22         # or 20.18.1+
mise use -g node@22          # so npx is on PATH globally

If Claude Code is launched from outside a mise-activated shell (e.g. Spotlight, Dock), and npx isn't found by the spawned MCP, fall back to the mise shim path in your .mcp.json:

{
  "command": "/Users/YOU/.local/share/mise/shims/npx",
  "args": ["--yes", "--package", "sosumi-cc", "sosumi-mcp-stdio"]
}

Or use a login-shell wrapper (works for any version manager):

{
  "command": "bash",
  "args": ["-lc", "exec npx --yes --package sosumi-cc sosumi-mcp-stdio"]
}

Configuration

Both env vars are optional (default = no restrictions on external Swift-DocC hosts):

• SOSUMI_ALLOWLIST — newline-delimited hostnames; only these are reachable via fetchExternalDocumentation
• SOSUMI_BLOCKLIST — newline-delimited hostnames; always denied

Verify the install

In a fresh Claude Code session, ask the agent something like "search Apple docs for NavigationStack". It should return real results (proving PR #54 is live), then offer to fetch the page on a follow-up.

You can also smoke-test the stdio entry directly:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx sosumi-cc sosumi-mcp-stdio

Expected: a JSON response listing the four tools.

Running the upstream HTTP service

The upstream Cloudflare Worker setup is preserved. If you want to host your own HTTP version (instead of using the local stdio MCP), see the Self-Hosting section below — npm run dev and npm run deploy still work.

Upstream sosumi.ai docs

sosumi.ai provides Apple Developer documentation in an AI-readable format by converting JavaScript-rendered pages into Markdown. The sections below are inherited from the upstream README.

Usage

HTTP API

Replace developer.apple.com with sosumi.ai in any Apple Developer documentation URL:

Original:

https://developer.apple.com/documentation/swift/array

AI-readable:

https://sosumi.ai/documentation/swift/array

This works for all API reference docs, as well as Apple's Human Interface Guidelines (HIG).

WWDC session transcripts are also supported by replacing the same host for video URLs:

Original:

https://developer.apple.com/videos/play/wwdc2021/10133/

AI-readable:

https://sosumi.ai/videos/play/wwdc2021/10133

Sosumi can also proxy public non-Apple Swift-DocC pages using:

Original:

https://apple.github.io/swift-argument-parser/documentation/argumentparser

AI-readable:

https://sosumi.ai/external/https://apple.github.io/swift-argument-parser/documentation/argumentparser

[!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.

CLI

npx sosumi-cc fetch https://developer.apple.com/documentation/swift/array

If you use it regularly, install once:

npm i -g sosumi-cc

Then use sosumi directly:

sosumi fetch https://developer.apple.com/documentation/swift/array
sosumi search "SwiftData"

You can fetch all content types covered by MCP tools:

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
sosumi search "SwiftData"

Run a local HTTP server from the published package:

sosumi serve
sosumi serve --port 8787

JSON output is available with --json:

sosumi fetch https://developer.apple.com/documentation/swift/array --json
sosumi search "SwiftData" --json

Self-Hosting

This project is designed to run on your own machine or deploy to a hosting provider. Upstream sosumi.ai runs on Cloudflare Workers; this fork preserves that setup.

[!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.18.1
• npm

Quick Start

git clone https://github.com/PowerBeef/sosumi-cc.git
cd sosumi-cc
npm install
npm run dev

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

Restrict which external Swift-DocC hosts are reachable with two env vars (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.

Development

Testing

npm run test          # Run tests
npm run test:ui       # Run tests with UI
npm run test:run      # Run tests once

Building the stdio MCP

npm run build         # bundles src/lib/mcp.ts → dist/lib/mcp.js (esbuild)
npm run stdio         # runs the stdio MCP locally for hand-testing

Code Quality

This project uses Biome for formatting and linting:

• npm run format — format
• npm run lint — lint
• npm run check — format + lint + organize imports
• npm run check:ci — check without changes (CI)

Cloudflare Workers

npm run cf-typegen    # regenerate Worker bindings types

Credits

• Upstream: NSHipster/sosumi.ai by @mattt and contributors. MIT.
• Search fix: PR #54 by @jkaunert. Switches Apple Developer search to the current /search/services/search.php endpoint.
• This fork: packaging for Claude Code (stdio MCP, plugin manifest, marketplace) by PowerBeef.

License

MIT. See LICENSE.md. All upstream copyrights are preserved.

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.