apple-docs
# apple-docs-mcp
An [MCP](https://modelcontextprotocol.io) server that gives AI coding agents current Apple Developer Documentation: search API symbols and read full pages (declaration, availability, discussion, code samples) as Markdown.
It reads only the public DocC JSON that developer.apple.com itself loads, and searches locally over Apple's per-framework symbol indexes. It doesn't scrape Apple's search page, so it isn't affected when that page changes.
> Not affiliated with or endorsed by Apple Inc. Apple, Swift, SwiftUI and other Apple marks are trademarks of Apple Inc. Documentation content is fetched from developer.apple.com at runtime and remains Apple's. This repository contains no Apple documentation.
## Tools
| Tool | What it does |
|---|---|
| `search_apple_docs(query, frameworks?, limit?)` | Finds types, methods, properties and articles by name, ranked. |
| `get_apple_doc(path)` | Returns one page as Markdown: declaration, min OS versions, deprecation, discussion, parameters, code samples, topic links. Accepts a path, a full URL, or `framework/symbol`. |
| `list_apple_frameworks(filter?)` | Lists framework slugs to use with `frameworks`. |
Without `frameworks`, search covers SwiftUI, FamilyControls, ManagedSettings, ManagedSettingsUI, DeviceActivity, SwiftData, Observation, Foundation, UIKit, WidgetKit, ActivityKit, AppIntents, UserNotifications, StoreKit and Swift, plus any framework named in the query. Pass `frameworks` to search any other framework.
Example:
```
search_apple_docs("AuthorizationCenter")
→ AuthorizationCenter — /documentation/familycontrols/authorizationcenter (class)
→ func requestAuthorization(for: FamilyControlsMember) async throws — …/requestauthorization(for:) (method)
get_apple_doc("/documentation/familycontrols/authorizationcenter/requestauthorization(for:)")
→ # requestAuthorization(for:)
**Availability:** iOS 16.0+, iPadOS 16.0+
func requestAuthorization(for member: FamilyControlsMember) async throws
…
```
## Install
Requires Node.js 20 or later.
### Claude Code
```sh
git clone https://github.com/hyu758/apple-docs-mcp.git
cd apple-docs-mcp && npm install
claude mcp add apple-docs -- node "$(pwd)/server.mjs"
```
Add `--scope project` to share it with a project through `.mcp.json`.
### Other MCP clients (Cursor, Codex, Claude Desktop, …)
```json
{
"mcpServers": {
"apple-docs": {
"command": "node",
"args": ["/absolute/path/to/apple-docs-mcp/server.mjs"]
}
}
}
```
### Tip: make your agent use it
Models often remember Apple APIs wrong, especially recent ones. Add a rule like this to your `CLAUDE.md` or `AGENTS.md`:
```md
Before using an Apple API you haven't verified in this session, call `search_apple_docs`,
then `get_apple_doc`, and check availability against the deployment target. Don't write
Apple API code from memory.
```
## Configuration
| Env var | Default | Meaning |
|---|---|---|
| `APPLE_DOCS_DEFAULT_FRAMEWORKS` | see above | Comma-separated slugs searched when `frameworks` isn't given. |
| `APPLE_DOCS_CACHE_TTL_HOURS` | `72` | How long fetched indexes and pages are cached. |
| `APPLE_DOCS_CACHE_DIR` | `~/.cache/apple-docs-mcp` | Cache location. |
## How it works
| Endpoint (under `https://developer.apple.com/tutorials/data`) | Used for |
|---|---|
| `/documentation/technologies.json` | Framework list |
| `/index/<framework>` | Full symbol tree of a framework, flattened and searched locally |
| `/documentation/<path>.json` | One page, rendered from DocC JSON to Markdown |
Responses are cached in memory and on disk. A search across the default frameworks takes about 0.3–1.5 s the first time and is near-instant afterwards.
## Development
```sh
npm install
npm test # live smoke test against developer.apple.com
VERBOSE=1 npm test # also print tool output
```
CI runs the smoke test weekly. If it fails, Apple has probably changed the DocC JSON shape: adjust `frameworkIndex` (index shape) or `getDoc` / `blocks` (page shape) in `server.mjs`.
## License
MIT
TDQS
Scored across 3 tools
The three tools map cleanly to a discover/fetch/enumerate pipeline: search_apple_docs finds symbol paths, get_apple_doc fetches a known path, list_apple_frameworks enumerates framework slugs used as a search filter. The only mild overlap (frameworks appearing in both search and list) is explicitly resolved by the descriptions telling the agent to use list for slugs and search for symbols.
All three follow a predictable verb_apple_noun pattern (search_apple_docs, get_apple_doc, list_apple_frameworks) with a shared product prefix. The singular/plural difference between 'doc' and 'docs' mirrors the single-vs-many semantics and reads naturally.
Three tools is the minimal complete surface for a documentation-lookup server: search, fetch, and enumerate frameworks. No tool is redundant and nothing feels padded or vague.
Core lifecycle is covered: find a symbol, then fetch its full page including declaration, availability, discussion, and topic links for navigation. Minor gaps remain, such as no bulk retrieval of multiple pages or explicit version/availability-scoped search, but agents can work around these with repeated calls.