Expo Docs MCP Server

A blazing-fast MCP (Model Context Protocol) server for Expo documentation that reads directly from local .mdx files.

🚀 Key Features

• Lightning Fast: Reads directly from local .mdx files - no HTTP server needed
• Smart Caching: Disk-based cache with version + docs fingerprint invalidation
• Full-Text Search: Powerful search with intelligent scoring algorithm
• Zero Network: Works completely offline
• Optimized for Bun: Built specifically for Bun's performance

📊 Performance

Metric	First Run	Cached Run
Index Build	~90-120ms	~12-20ms
Search Query	~1-10ms	~1-10ms
Documents	997 .mdx files	997 .mdx files
Cache Size	~4.4MB	~4.4MB

Measured on the current local docs snapshot.

🛠️ Setup

Choose your preferred installation method:

Option 1: npx (Zero Install)

No installation needed! Just add to your Cursor MCP configuration:

{
  "mcpServers": {
    "expo-docs": {
      "command": "npx",
      "args": ["expo-local-docs-mcp"]
    }
  }
}

✅ Always uses latest version
✅ No manual updates needed
⚠️ Slight delay on first run (cached after)

Option 2: Global Install (Recommended)

Install once, use everywhere:

npm install -g expo-local-docs-mcp
# or with pnpm
pnpm install -g expo-local-docs-mcp

Then add to your Cursor MCP configuration:

{
  "mcpServers": {
    "expo-docs": {
      "command": "expo-local-docs-mcp"
    }
  }
}

✅ Instant startup (no download)
✅ Cleaner config
⚠️ Manual updates: npm update -g expo-local-docs-mcp

Option 3: Local Project Install

Install in your project:

cd ~/my-expo-project
npm install expo-local-docs-mcp

Then add to your Cursor MCP configuration:

{
  "mcpServers": {
    "expo-docs": {
      "command": "node",
      "args": [
        "/absolute/path/to/node_modules/expo-local-docs-mcp/dist/server.js"
      ]
    }
  }
}

✅ Version locked to project
⚠️ Must install per project
⚠️ Need absolute path in config

---

That's it! The package includes 997 Expo SDK docs in the current snapshot and works out of the box with any method.

For Contributors: Local Development

If you want to contribute or customize:

Prerequisites

• Bun installed (recommended) or Node.js
• Expo documentation .mdx files in the expo-sdk/ folder

Installation

cd /path/to/expo-local-docs-mcp
bun install
bun run build

Test It Works

bun run test

You should see:

✅ All tests passed!
✓ Index loaded: 997 entries (~90-120ms first run)
✓ Index loaded: 997 entries (~12-20ms cached run)

Configuration for Local Development

Add to your Cursor MCP configuration (~/.cursor/mcp.json or ~/.config/cursor/mcp.json):

{
  "mcpServers": {
    "expo-docs": {
      "command": "bun",
      "args": ["/<workingdirectory>/expo-local-docs-mcp/dist/server.js"],
      "env": {
        "EXPO_DOCS_PATH": "/<workingdirectory>/expo-local-docs-mcp/expo-sdk",
        "EXPO_CACHE_DIR": "/<workingdirectory>/expo-local-docs-mcp/.expo-cache"
      }
    }
  }
}

Important: Update the paths to match your actual installation location.

📚 Available Tools

1. search_expo_docs

Search the Expo documentation with intelligent ranking.

Parameters:

• query (string, required): Search query
• section (string, optional): Filter by section (e.g., 'guides', 'router', 'versions')
• maxResults (number, optional): Max results (default: 10)

Example:

{
  "query": "camera permissions",
  "section": "guides",
  "maxResults": 5
}

2. get_expo_doc_content

Get the full content of a specific documentation page.

Parameters:

• path (string, required): Document path (e.g., /versions/latest/sdk/camera)

Example:

{
  "path": "/get-started/introduction"
}

3. list_expo_sections

List all documentation sections or get documents in a specific section.

Parameters:

• section (string, optional): Get documents in this section

Example:

{
  "section": "router"
}

4. get_expo_api_reference

Get API reference for a specific Expo SDK module.

Parameters:

• module (string, required): Module name (e.g., 'camera', 'expo-camera')
• version (string, optional): SDK version (e.g., 'latest', 'v55.0.0', or '55.0.0')

Example:

{
  "module": "camera"
}

5. get_expo_quick_start

Get quick start documentation.

Parameters:

• topic (string, optional): Specific topic (e.g., 'create-a-project')

Example:

{
  "topic": "create-a-project"
}

🏗️ Architecture

expo-local-docs-mcp/
├── src/
│   ├── server.ts              # MCP server implementation
│   ├── config.ts              # Configuration management
│   ├── diskCache.ts           # Disk cache management
│   ├── mdxParser.ts           # MDX file parser (frontmatter + content)
│   ├── searchIndex/           # Search index module
│   │   ├── index.ts           # Public API exports
│   │   ├── types.ts           # TypeScript types
│   │   ├── state.ts           # Index state management
│   │   ├── loader.ts          # Index building and loading
│   │   ├── search.ts          # Search algorithm
│   │   ├── query.ts           # Document queries
│   │   └── fileUtils.ts       # File system utilities
│   └── tools/                 # MCP tool handlers
│       ├── definitions.ts     # Tool schemas
│       └── handlers/          # Tool implementations
│           ├── index.ts       # Handler dispatcher
│           ├── types.ts       # Handler types
│           ├── searchExpoDocs.ts
│           ├── getExpoDocContent.ts
│           ├── listExpoSections.ts
│           ├── getExpoApiReference.ts
│           └── getExpoQuickStart.ts
├── expo-sdk/                  # Your Expo documentation .mdx files
│   ├── get-started/
│   ├── guides/
│   ├── router/
│   ├── versions/
│   └── ...
├── .expo-cache/               # Generated cache (auto-created)
│   └── search-index.json
├── dist/                      # Built server
│   └── server.js
├── test-server.ts             # Basic functionality tests
├── test-tools.ts              # Comprehensive tool tests
└── package.json

🔧 Development

# Run in development mode
bun run dev

# Build for production
bun run build

# Start built server
bun run start

# Run tests
bun run test
bun run test:tools
bun run test:all

# Clear cache (force rebuild)
bun run clear-cache

🎯 Environment Variables

Variable	Default	Description
EXPO_DOCS_PATH	./expo-sdk	Path to expo-sdk folder containing .mdx files
EXPO_CACHE_DIR	./.expo-cache	Cache directory location
EXPO_DOCS_MAX_RESULTS	20	Max search results to return
EXPO_DOCS_CACHE_MAX_AGE	86400000	Cache age in ms (24 hours)

📦 Dependencies

• @modelcontextprotocol/sdk - MCP protocol implementation
• @types/node - TypeScript Node.js types
• typescript - TypeScript compiler

That's it! No HTTP clients, no HTML parsers, just fast file I/O.

🐛 Troubleshooting

Index not building

• Ensure expo-sdk/ folder exists and contains .mdx files
• Check file permissions on the directory
• Try bun run clear-cache and restart

Search returning no results

• Wait for index to build (check console output)
• Verify .mdx files have content
• Try broader search terms

Cache rebuilding every time

• Check .expo-cache/ folder permissions
• Verify cache file is being created: ls -lh .expo-cache/
• Check disk space

"Cannot find module" errors

• Run bun install to ensure dependencies are installed
• Run bun run build to rebuild

📝 How It Works

1. Startup: Server initializes and attempts to load from disk cache
2. Cache Check: Cache is valid only when version, age, and docs fingerprint all match (typically ~12-20ms load)
3. Fresh Build: If no valid cache, scans expo-sdk/ recursively for all .mdx files (currently 997 files)
4. Parsing: Extracts YAML frontmatter and strips MDX/JSX to get clean text content
5. Indexing: Builds in-memory search index with path mapping (~90-120ms)
6. Caching: Saves complete index to search-index.json (~4.4MB)
7. Search: Uses optimized scoring algorithm (exact matches > word matches)

MDX Parsing

Each .mdx file's frontmatter is parsed:

---
title: Camera
description: A React component that renders a preview...
packageName: expo-camera
platforms: ["android", "ios", "web"]
---

This metadata is used for better search results and filtering.

Search Scoring Algorithm

The search uses a dual-layer scoring system for maximum relevance:

Exact Phrase Matches:

• Title contains exact query: 1000 points
• Description contains exact query: 500 points
• Path contains exact query: 300 points
• Content contains exact query: 100 points

Individual Word Matches (with boundary detection):

• Word match in title: 50 points per occurrence
• Word match in description: 25 points per occurrence
• Word match in path: 15 points per occurrence
• Word match in content: 1 point per occurrence

Performance Optimizations:

• Pre-compiles escaped regex patterns for each search word
• Uses for...of loop instead of .map() for better performance
• Only creates scored objects for entries with matches (score > 0)
• Single-pass algorithm with early section filtering

🔄 Updating Documentation

To update the Expo docs:

1. Replace/update files in expo-sdk/ folder
2. Clear the cache: bun run clear-cache
3. Restart the MCP server

The index will automatically rebuild on next startup.

❓ FAQ

Q: Should I use npx or install globally?
A: Global install (npm install -g) is recommended for faster startup and cleaner config. Use npx if you want automatic updates.

Q: How do I update to the latest version?
A:

• npx: Automatic (always uses latest)
• Global: npm update -g expo-local-docs-mcp
• Local: npm update expo-local-docs-mcp in your project

Q: How do I test npx execution?
A: Run npx expo-local-docs-mcp directly in your terminal. It should start the MCP server on stdio.

Q: Do I need the localhost:3002 server running?
A: No! That was the old v1.x architecture. v2.0 reads files directly.

Q: Can I delete the cache folder?
A: Yes! It will automatically rebuild (typically ~90-120ms). Cache locations:

• npm/npx: /tmp/expo-local-docs-mcp-cache/ (macOS/Linux)
• Local dev: .expo-cache/ (project root)

Q: What happens if an .mdx file is missing?
A: The server gracefully skips it and continues indexing other files.

Q: Can I use this with Node.js instead of Bun?
A: Yes! The npm package is built to work with Node.js. Local development can use either Bun or Node.

Q: How big is the npm package?
A: It depends on the included docs snapshot. The current repo snapshot indexes 997 .mdx docs and builds a ~4.4MB cache file.

📈 Indexed Content

Total documents: 997 .mdx files
Total sections: 40
Cache size: ~4.4MB

Top sections:
  - versions: 602 docs (SDK API references)
  - guides: 59 docs
  - router: 47 docs (Expo Router)
  - eas: 35 docs (EAS services)
  - eas-update: 27 docs
  - tutorial: 25 docs
  - develop: 21 docs
  - build-reference: 21 docs
  - archive: 18 docs
  - modules: 17 docs

🎉 Benefits vs v1.x

Feature	v1.x (HTTP)	v2.0 (Files)
Speed (first run)	5-10s	90-120ms
Speed (cached)	1-2s	12-20ms
Network required	Yes	No
Dependencies	axios, cheerio	None
HTTP server needed	Yes (localhost:3002)	No
Offline support	No	Yes
Search quality	Good	Better

📄 License

MIT

🤝 Contributing

This is a personal MCP server optimized for local Expo documentation access. Feel free to fork and adapt for your needs!

---

Version: 2.0.5
Built with: Bun + TypeScript
Performance: 🚀 Blazing Fast