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 for instant subsequent startups (3ms!)
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	~78ms	~3ms
Search Query	8ms	8ms
Documents	958 .mdx files	958 .mdx files
Cache Size	~2.7MB	~2.7MB

26x faster on subsequent runs!

🛠️ 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 all 958 Expo SDK docs 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 /Users/x./Documents/repos/mcps/expo-local-mcp
bun install
bun run build

Test It Works

bun run test

You should see:

✅ All tests passed!
✓ Search index loaded: 958 entries in 78ms (first run)
✓ Search index loaded: 958 entries in 3ms (cached)

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-mcp/dist/server.js"],
      "env": {
        "EXPO_DOCS_PATH": "/<workingdirectory>/expo-local-mcp/expo-sdk",
        "EXPO_CACHE_DIR": "/<workingdirectory>/expo-local-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 (default: latest)

Example:

{
  "module": "camera",
  "version": "v54.0.0"
}

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

# 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

Startup: Server initializes and attempts to load from disk cache
Cache Check: If valid cache exists (<24h old, correct version), loads in ~3ms
Fresh Build: If no cache, scans expo-sdk/ recursively for all .mdx files (958 files)
Parsing: Extracts YAML frontmatter and strips MDX/JSX to get clean text content
Indexing: Builds in-memory search index with path mapping (~78ms)
Caching: Saves complete index to search-index.json (~2.7MB)
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 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 filtering

🔄 Updating Documentation

To update the Expo docs:

Replace/update files in expo-sdk/ folder
Clear the cache: bun run clear-cache
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 (takes ~78ms). 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: ~4-5MB including all 958 Expo SDK docs. First startup takes ~78ms to build the search index.

📈 Indexed Content

Total documents: 958 .mdx files
Total sections: 38
Cache size: ~2.7MB

Top sections:
  - versions: 588 docs (SDK API references)
  - guides: 53 docs
  - router: 40 docs (Expo Router)
  - eas: 31 docs (EAS services)
  - eas-update: 27 docs
  - tutorial: 25 docs
  - develop: 20 docs
  - build-reference: 20 docs
  - archive: 18 docs
  - modules: 16 docs

🎉 Benefits vs v1.x

Feature	v1.x (HTTP)	v2.0 (Files)
Speed (first run)	5-10s	78ms
Speed (cached)	1-2s	3ms
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.0
Built with: Bun + TypeScript
Performance: 🚀 Blazing Fast

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
expo-sdk		expo-sdk
scripts		scripts
src		src
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
TESTING.md		TESTING.md
bun.lock		bun.lock
mcp-config-example.json		mcp-config-example.json
package.json		package.json
test-server.ts		test-server.ts
test-tools.ts		test-tools.ts
tsconfig.json		tsconfig.json

Uh oh!

License

Uh oh!

Ception/expo-local-docs-mcp

Folders and files

Latest commit

History

Repository files navigation

Expo Docs MCP Server

🚀 Key Features

📊 Performance

🛠️ Setup

Option 1: npx (Zero Install)

Option 2: Global Install (Recommended)

Option 3: Local Project Install

For Contributors: Local Development

Prerequisites

Installation

Test It Works

Configuration for Local Development

📚 Available Tools

1. search_expo_docs

2. get_expo_doc_content

3. list_expo_sections

4. get_expo_api_reference

5. get_expo_quick_start

🏗️ Architecture

🔧 Development

🎯 Environment Variables

📦 Dependencies

🐛 Troubleshooting

Index not building

Search returning no results

Cache rebuilding every time

"Cannot find module" errors

📝 How It Works

MDX Parsing

Search Scoring Algorithm

🔄 Updating Documentation

❓ FAQ

📈 Indexed Content

🎉 Benefits vs v1.x

📄 License

🤝 Contributing

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

1. `search_expo_docs`

2. `get_expo_doc_content`

3. `list_expo_sections`

4. `get_expo_api_reference`

5. `get_expo_quick_start`

Packages