MCP Server

Apple Text includes an MCP (Model Context Protocol) server that brings the same Apple Text collection to any MCP-compatible AI coding tool.

Choose The Right Surface

Surface	Best For	Front Door
Claude Code plugin	Native plugin install, /plugin, and command-first flow	/apple-text:ask
Generic MCP client	VS Code, Cursor, Claude Desktop, Gemini CLI, OpenCode	apple_text_route
Xcode via MCP	Claude Agent or Codex inside Xcode	apple_text_route plus optional xcrun mcpbridge

What You Get

The MCP server exposes Apple Text as a focused, read-only documentation surface:

• 39 skills as MCP Resources
• 1 command as MCP Prompts
• 5 read-only MCP Tools for route-first guidance, catalog lookup, search, skill reads, and agent inspection

For normal natural-language questions, start with apple_text_route, then follow the suggested apple_text_read_skill call.

Prerequisites

• Node.js 18+

For the published package, that is enough:

npx -y apple-text-mcp

If you are contributing or want development mode, build from a local checkout:

git clone https://github.com/sitapix/apple-text
cd apple-text
npm run setup:all
npm run mcp:bundle

That produces mcp-server/dist/index.js and the bundled snapshot it reads in production mode.

Installation by Tool

Each tool needs a config snippet that tells it how to launch the Apple Text MCP server.

VS Code + GitHub Copilot

Add to your VS Code settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "apple-text": {
      "command": "npx",
      "args": ["-y", "apple-text-mcp"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "apple-text": {
      "command": "npx",
      "args": ["-y", "apple-text-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your workspace:

{
  "mcpServers": {
    "apple-text": {
      "command": "npx",
      "args": ["-y", "apple-text-mcp"]
    }
  }
}

Gemini CLI

Add to ~/.gemini/config.toml:

[[mcp_servers]]
name = "apple-text"
command = "npx"
args = ["-y", "apple-text-mcp"]

OpenCode

Add to opencode.jsonc in your project root, or ~/.config/opencode/opencode.jsonc for global config:

{
  "mcp": {
    "apple-text": {
      "type": "local",
      "command": ["npx", "-y", "apple-text-mcp"]
    }
  }
}

Working Alongside Xcode Tools

Apple Text is a read-only knowledge server. It does not build, test, or control Xcode projects.

If you also want Xcode actions, run Apple’s separate Xcode MCP bridge alongside Apple Text:

codex mcp add xcode -- xcrun mcpbridge

That gives you two complementary servers:

• apple-text for text-system guidance, search, and references
• xcode for build, test, and project actions exposed by Xcode

If you want the full Xcode-specific setup, use Xcode Integration.

Configuration

Environment Variables

Variable	Values	Default	Description
APPLE_TEXT_MCP_MODE	development, production	production	Runtime mode
APPLE_TEXT_DEV_PATH	File path	—	Repo root for development mode
APPLE_TEXT_APPLE_DOCS	true, false	false	Enable Apple-authored markdown docs from the local Xcode install when you want the Xcode-backed overlay
APPLE_TEXT_XCODE_PATH	File path	/Applications/Xcode.app	Override the Xcode.app path used for Apple docs discovery
APPLE_TEXT_MCP_LOG_LEVEL	debug, info, warn, error	info	Logging verbosity

Development Mode (Live Skills)

For Apple Text contributors who want live skill changes without rebundling:

APPLE_TEXT_MCP_MODE=development \
APPLE_TEXT_DEV_PATH=/absolute/path/to/apple-text \
node /absolute/path/to/apple-text/mcp-server/dist/index.js

Changes to skill files are reflected immediately. When Xcode is installed, this mode can also load Apple-authored markdown docs from the local Xcode bundle without failing if they are absent.

Production Mode (Bundled)

The default after npm run mcp:bundle or when launched through the published npm package. The server reads from the bundled snapshot and does not need live repo reads after initialization.

npx -y apple-text-mcp

Verify It Works

Quick Test

Run the server directly to confirm it launches without errors:

npx -y apple-text-mcp

The server should start and wait for stdin input. Press Ctrl+C to stop.

Repo Smoke Test

From the repo root:

npm run mcp:smoke

That uses the official MCP SDK client to verify initialization, resources, tools, and prompts.

MCP Inspector

For interactive testing:

npx @modelcontextprotocol/inspector npx -y apple-text-mcp

In Your Tool

Once configured, the most reliable MCP workflow is:

1. Call apple_text_route with the user’s question.
2. Follow the suggested apple_text_read_skill call.
3. Use apple_text_search_skills only if routing is ambiguous or you want more options.

If you want a quick manual test, try asking your AI tool:

"What Apple text skills do you have?"

It should list Apple Text skills through the MCP resources surface and offer the prompt/tool surface as needed.

Troubleshooting

Server Won’t Start

Check Node version:

node --version

Skills Not Appearing

Enable debug logging to see what the server loads:

APPLE_TEXT_MCP_LOG_LEVEL=debug npx -y apple-text-mcp 2>&1 | head -20

Client Can’t Connect

MCP uses stdin/stdout for communication. Common issues:

• Wrong config — make sure your config points to npx -y apple-text-mcp or an absolute local dist/index.js path
• Other stdout writers — make sure nothing else writes to stdout; logs should go to stderr

If you want live skills, make sure APPLE_TEXT_MCP_MODE=development and APPLE_TEXT_DEV_PATH points at the repo root. If you expect Apple-authored Xcode docs in development mode, make sure Xcode is installed or set APPLE_TEXT_XCODE_PATH to the right app bundle.

What’s Next

Skills Browse the full Apple Text skill catalog.

Commands See how `/apple-text:ask` fits into the MCP prompt surface.

Agents See the 5 bundled specialist agents.

Xcode Integration Configure Apple Text MCP inside Xcode Claude Agent or Codex.