# PaperMC Docs MCP Server

A Model Context Protocol (MCP) server that provides access to [PaperMC documentation](https://docs.papermc.io) and [Javadocs](https://jd.papermc.io).

## How It Works

This server has two modes:

**1. Cached Documentation** — Downloads all pages from `docs.papermc.io/llms.txt` and caches them as markdown files in `~/papermc-docs-mcp/`. Each page stores its HTTP ETag for efficient update detection. Tools and resources in this mode operate entirely on the local cache — no network calls at query time.

**2. Live Javadocs** — Fetches JavaDoc pages on-the-fly from `jd.papermc.io`. No caching — always up-to-date. Supports version resolution (auto-redirect to latest, partial version matching).

## Resources

### Cached Documentation

| URI Pattern | Description |
|---|---|
| `papermc-docs://{path}` | Direct access to any cached doc page (e.g. `papermc-docs://paper/dev/getting-started/index.md`) |
| `papermc-docs://what-is-papermc` | Beginner-friendly introduction to PaperMC |

### Live Javadocs (no resource — use tools below)

## Tools

### Cached Documentation Tools

| Tool | Description |
|---|---|
| `list_categories` | List all documentation projects (paper, adventure, velocity, folia, etc.) |
| `list_docs` | List pages, optionally filtered by category |
| `search_docs` | Full-text search across all cached pages with ranking and snippets |
| `refresh_cache` | Download all pages to local cache (needed once on first setup) |
| `check_updates` | ETag-based per-page update detection across all projects |

### Live Javadoc Tools

| Tool | Description |
|---|---|
| `list_javadoc_projects` | List all javadoc projects with their latest resolved versions |
| `resolve_javadoc` | Fetch a class, interface, or package javadoc page (e.g. `org.bukkit.plugin.JavaPlugin`) |
| `search_javadoc` | Search for classes by name across a project's javadocs |

## Installation

```bash
# Clone and install
git clone https://github.com/SatuSattr/papermc-docs-mcp.git
cd papermc-docs-mcp
npm install

# Optional: download all docs on first run
npm run start:cache

# Start MCP server
npm start
```

### MCP Configuration (opencode.json / claude_desktop_config.json)

```json
{
  "mcpServers": {
    "papermc-docs": {
      "command": "npx",
      "args": ["tsx", "path/to/papermc-docs-mcp/src/index.ts"]
    }
  }
}
```

## Cache Directory

All cached documentation is stored in `~/papermc-docs-mcp/`. The `--cache` flag or `refresh_cache` tool fills this directory. Once populated, all cached tools and resources work offline.