<p align="center">
  <img src="assets/logo.png" alt="mobile-docs-mcp" width="160" />
</p>

<h1 align="center">mobile-docs-mcp</h1>

<p align="center">
  <strong>MCP server that gives LLMs access to up-to-date mobile SDK documentation, package registry info, and GitHub issues.</strong>
</p>

<p align="center">
  <a href="#supported-sdks">28 SDKs</a> •
  <a href="#tools">6 Tools</a> •
  <a href="#package-registries">5 Registries</a> •
  <a href="#getting-started">Getting Started</a>
</p>

---

## Why?

LLMs often have outdated knowledge about mobile SDKs. **mobile-docs-mcp** solves this by:

- Fetching **live documentation** from official sources and converting it to clean markdown
- Querying **package registries** for the latest versions in real-time
- Pulling **open GitHub issues** so the LLM knows about current bugs and limitations
- **Caching everything** locally (24h TTL) for fast, offline-friendly responses

---

## Supported SDKs

<table>
  <tr>
    <td align="center"><img src="https://cdn.simpleicons.org/firebase/FFCA28" width="28" /><br /><sub>Firebase</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/supabase/3FCF8E" width="28" /><br /><sub>Supabase</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/revenuecat/F25A5F" width="28" /><br /><sub>RevenueCat</sub></td>
    <td align="center"><img src="https://cdn.worldvectorlogo.com/logos/onesignal.svg" width="28" /><br /><sub>OneSignal</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/sentry/362D59" width="28" /><br /><sub>Sentry</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/auth0/EB5424" width="28" /><br /><sub>Auth0</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/algolia/003DFF" width="28" /><br /><sub>Algolia</sub></td>
  </tr>
  <tr>
    <td align="center"><img src="https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRQVRSNCZKUcvSYkmDLtSNNaRwRDh8rz5HxHA&s" width="28" /><br /><sub>OpenAI</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/googlegemini/8E75B2" width="28" /><br /><sub>Gemini</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/googlemaps/4285F4" width="28" /><br /><sub>Google Maps</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/googleadmob/EA4335" width="28" /><br /><sub>AdMob</sub></td>
    <td align="center"><img src="https://framerusercontent.com/images/GR57N0iyy5LPXJ0oHSs9m2s0mVI.webp?width=256&height=256" width="28" /><br /><sub>Amplitude</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/mixpanel/7856FF" width="28" /><br /><sub>Mixpanel</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/posthog/1D4AFF" width="28" /><br /><sub>PostHog</sub></td>
  </tr>
  <tr>
    <td align="center"><img src="https://cdn.prod.website-files.com/5ecbeb8d7557e7f636691721/65837c5f480644e2de769eb5_AppsFlyer_logo.png" width="28" /><br /><sub>AppsFlyer</sub></td>
    <td align="center"><img src="https://images.seeklogo.com/logo-png/48/2/adjust-logo-png_seeklogo-481577.png" width="28" /><br /><sub>Adjust</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/mapbox/000000" width="28" /><br /><sub>Mapbox</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/cloudinary/3448C5" width="28" /><br /><sub>Cloudinary</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/clerk/6C47FF" width="28" /><br /><sub>Clerk</sub></td>
    <td align="center"><img src="https://images.seeklogo.com/logo-png/42/2/aws-amplify-logo-png_seeklogo-426696.png" width="28" /><br /><sub>AWS Amplify</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/fastlane/00F200" width="28" /><br /><sub>Fastlane</sub></td>
  </tr>
  <tr>
    <td align="center"><img src="https://cdn.simpleicons.org/unity/000000" width="28" /><br /><sub>Unity Ads</sub></td>
    <td align="center"><img src="https://cdn.simpleicons.org/meta/0081FB" width="28" /><br /><sub>Meta Audience</sub></td>
    <td align="center"><img src="https://marketyourcraft.com/wp-content/uploads/2025/12/Sendbird_Logo.png" width="28" /><br /><sub>Sendbird</sub></td>
    <td align="center"><img src="https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR2POIwieEwHt6kp-IdA4JkXIbaA569S3nUJg&s" width="28" /><br /><sub>Maestro</sub></td>
    <td align="center"><sub><img src="https://images.crunchbase.com/image/upload/c_pad,h_256,w_256,f_auto,q_auto:eco,dpr_1/cnqy3l17gemegwrmw7oa?ik-sanitizeSvg=true" width="28" /></sub><br /><sub>Adapty</sub></td>
    <td align="center"><sub><img src="https://api.nuget.org/v3-flatcontainer/stream-chat-net/2.20.0/icon" width="28" /></sub><br /><sub>Stream</sub></td>
    <td align="center"><sub><img src="https://avatars.githubusercontent.com/u/88794805?s=280&v=4" width="28" /></sub><br /><sub>Superwall</sub></td>
  </tr>
</table>

> Adding a new SDK is as simple as dropping a JSON file into the `sdks/` directory.

---

## Tools

### iDocumentation

| Tool           | Description                                                              |
| -------------- | ------------------------------------------------------------------------ |
| `list_sdks`    | List all available SDKs with their categories and documentation pages    |
| `search_docs`  | Full-text search across all SDK documentation, returns relevant sections |
| `refresh_docs` | Invalidate cache and re-fetch documentation (all or specific SDK)        |

### Package Registries

| Tool               | Description                                                                |
| ------------------ | -------------------------------------------------------------------------- |
| `search_packages`  | Search for packages across npm, pub.dev, CocoaPods, Maven Central, or PyPI |
| `get_package_info` | Get latest version, license, homepage, and repository for any package      |

### GitHub

| Tool                | Description                                                          |
| ------------------- | -------------------------------------------------------------------- |
| `get_github_issues` | Fetch open issues from any GitHub repo with optional label filtering |

---

## Package Registries

<table>
  <tr>
    <td align="center"><img src="https://cdn.simpleicons.org/npm/CB3837" width="32" /><br /><strong>npm</strong></td>
    <td align="center"><img src="https://cdn.simpleicons.org/dart/0175C2" width="32" /><br /><strong>pub.dev</strong></td>
    <td align="center"><img src="https://cdn.simpleicons.org/cocoapods/EE3322" width="32" /><br /><strong>CocoaPods</strong></td>
    <td align="center"><img src="https://cdn.simpleicons.org/apachemaven/C71A36" width="32" /><br /><strong>Maven</strong></td>
    <td align="center"><img src="https://cdn.simpleicons.org/pypi/3775A9" width="32" /><br /><strong>PyPI</strong></td>
  </tr>
  <tr>
    <td align="center"><sub>React Native, JS</sub></td>
    <td align="center"><sub>Flutter, Dart</sub></td>
    <td align="center"><sub>iOS, macOS</sub></td>
    <td align="center"><sub>Android, KMP</sub></td>
    <td align="center"><sub>Python</sub></td>
  </tr>
</table>

---

## Getting Started

### Quick Start (npx — no install needed)

Run directly without installing:

```bash
npx @freeapptools/mobile-docs-mcp
```

### Configure Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "mobile-docs-mcp": {
      "command": "npx",
      "args": ["-y", "@freeapptools/mobile-docs-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

> `GITHUB_TOKEN` is optional but recommended to avoid GitHub API rate limits (60 → 5,000 requests/hour).

### Configure Claude Code

Add to your Claude Code settings:

```json
{
  "mcpServers": {
    "mobile-docs-mcp": {
      "command": "npx",
      "args": ["-y", "@freeapptools/mobile-docs-mcp"]
    }
  }
}
```

### Global Install (optional)

If you prefer a permanent installation:

```bash
npm install -g @freeapptools/mobile-docs-mcp
```

Then use `mobile-docs-mcp` directly as the command instead of `npx`.

---

## Adding a New SDK

Create a JSON file in the `sdks/` directory:

```json
{
  "name": "YourSDK",
  "version": "latest",
  "baseUrl": "https://docs.yoursdk.com",
  "docs": [
    {
      "category": "Getting Started",
      "pages": [
        {
          "title": "Installation",
          "url": "https://docs.yoursdk.com/install"
        },
        {
          "title": "Quick Start",
          "url": "https://docs.yoursdk.com/quickstart"
        }
      ]
    }
  ]
}
```

That's it. The server picks it up automatically on next startup.

---

## Configuration

`docs-config.json` in the project root:

```json
{
  "cacheTtlMs": 86400000,
  "cacheDir": ".cache",
  "sdksDir": "./sdks"
}
```

| Field        | Default          | Description                         |
| ------------ | ---------------- | ----------------------------------- |
| `cacheTtlMs` | `86400000` (24h) | Cache time-to-live in milliseconds  |
| `cacheDir`   | `.cache`         | Local cache directory path          |
| `sdksDir`    | `./sdks`         | Directory containing SDK JSON files |

Override the config path with the `DOCS_CONFIG_PATH` environment variable.

---

## Development

```bash
# Watch mode
npm run dev

# Run tests (82 tests)
npm test

# Build
npm run build
```

### Project Structure

```
mobile-docs-mcp/
├── src/
│   ├── index.ts          # Entry point — stdio transport
│   ├── config.ts         # Config loading + Zod validation
│   ├── tools.ts          # 6 MCP tool registrations
│   ├── resources.ts      # MCP resource registrations
│   ├── registry.ts       # Package registry API handlers
│   ├── github.ts         # GitHub issues API
│   ├── fetcher.ts        # HTML → Markdown conversion
│   ├── cache.ts          # File-based cache with TTL
│   ├── parser.ts         # Markdown section parser
│   ├── search.ts         # Full-text search engine
│   ├── types.ts          # TypeScript interfaces
│   └── __tests__/        # 82 unit tests
├── sdks/                 # SDK documentation configs (28 files)
├── docs-config.json      # Global configuration
├── package.json
└── tsconfig.json
```

---

## License

MIT