# CRAN MCP

A Model Context Protocol server that provides up-to-date R package documentation, package status information and R release information directly from CRAN.

The server is stateless: it fetches current CRAN data on demand and returns only the relevant information to the MCP client.

## Tools

- `search_packages(query, limit=20)` searches all current CRAN package names and short descriptions and ranks matching packages.
- `get_package_info(package)` returns the package title, description, current version, CRAN publication date and dependency groups (`Depends`, `Imports`, `Suggests`, `LinkingTo`, `Enhances`).
- `get_package_news(package, version=None, max_chars=50000)` returns the package NEWS/changelog page from CRAN, optionally restricted to one version such as `1.18.4`.
- `get_package_check_status(package)` returns the current CRAN check status, status counts and results for every check flavor.
- `get_package_topics(package, query=None, limit=100)` lists help topics from a CRAN package.
- `get_topic_documentation(package, topic, max_chars=30000)` returns one help topic as plain text with its CRAN source URL.
- `search_package_documentation(package, query, limit=10)` searches the reference manual and returns matching snippets.
- `get_r_versions(major=None, limit=100)` lists R releases available from CRAN, optionally restricted to a major version such as `4`.
- `get_r_version_news(version, max_chars=50000)` returns the official R NEWS section for one R release, for example `4.5.1`.

## Package discovery

`search_packages()` uses the same machine-readable CRAN package database as `tools::CRAN_package_db()` in R:

```text
https://cran.r-project.org/web/packages/packages.rds
```

The RDS database contains the package metadata for current CRAN packages. The search uses `Package` and `Title`, where `Title` is the short package description shown in CRAN's package-by-name list. The RDS file is parsed directly in Python; R is not required at runtime.

Examples:

```text
search_packages("survival model")
search_packages("arrow", limit=10)
```

## R releases

`get_r_versions()` reads the official CRAN R source directories, so the version list is not hard-coded.

Examples:

```text
get_r_versions()
get_r_versions(major=4)
get_r_version_news("4.5.1")
```

## Local setup

```bash
uv sync --dev
uv run cran-mcp
```

The MCP endpoint is available at `http://127.0.0.1:8000/mcp`.

## Docker

```bash
docker build -t cran-mcp .
docker run --rm -p 8000:8000 -e MCP_ALLOWED_HOSTS=localhost,localhost:* cran-mcp
```

## Environment variables

- `PORT`: HTTP port, default `8000`.
- `MCP_ALLOWED_HOSTS`: comma-separated allowed Host values for public deployment.
- `MCP_ALLOWED_ORIGINS`: optional comma-separated allowed browser origins.

## Examples

```text
search_packages("Bayesian survival")
get_package_info("data.table")
get_package_news("data.table")
get_package_news("data.table", version="1.18.4")
get_package_check_status("data.table")
get_topic_documentation("data.table", "fread")
get_r_versions(major=4)
get_r_version_news("4.5.1")
```

```text
MCP client
    |
    | package / R release request
    v
CRAN MCP
    |
    | HTTPS
    v
CRAN package database, package pages, NEWS, checks, R source index and HTML reference manuals
```