# RikkaHub History MCP

A read-only MCP bridge for searching conversations from the **official RikkaHub app** through its Web API. It does not require a modified APK, root access, or Room database migration.

## Features

- `recent_conversations` — list recent conversations of the currently selected assistant with lightweight metadata.
- `search_conversations` — use RikkaHub's built-in global full-text index.
- `get_conversation_context` — read a bounded window around a search hit.
- Reads only the currently selected message branch.
- Returns USER/ASSISTANT text only; reasoning, tool calls/results, system messages, and attachments are omitted.
- Resolves `rikkahub.local` with mDNS, so a phone DHCP address change normally needs no reconfiguration.
- Supports both password-protected and unauthenticated RikkaHub Web Server modes.
- Automatically refreshes RikkaHub's Web JWT when a Web password is configured.
- Streamable HTTP mode requires a separate Bearer token and keeps DNS rebinding protection enabled.

> [!IMPORTANT]
> RikkaHub's upstream full-text search is global and may return conversations belonging to other assistants. `recent_conversations` is limited to the currently selected assistant, but search/context are not an assistant-isolation boundary.

## Requirements

- Python 3.10+
- RikkaHub Web Server enabled and reachable on the same trusted LAN
- A dedicated RikkaHub Web password when the app's password/JWT mode is working

## Install

```bash
python -m venv .venv
# Windows
.venv\Scripts\python -m pip install -e .
# Linux/macOS
.venv/bin/python -m pip install -e .
```

For development and security checks:

```bash
python -m pip install -e ".[dev]"
pytest
ruff check .
bandit -q -r rikkahub_history_mcp
pip-audit
```

## Configure RikkaHub Web

In RikkaHub, enable the Web Server. The default port is `8080`.

The bridge first tries:

```text
http://rikkahub.local:8080
```

It re-resolves mDNS after failures and can retain the last successful phone IP as a fallback. You can instead set an explicit base URL such as `http://192.168.0.20:8080`.

### Password/JWT enabled

Set a **dedicated, non-reused** RikkaHub Web password and provide it through:

```text
RIKKAHUB_WEB_PASSWORD=...
```

### Password/JWT disabled

Leave `RIKKAHUB_WEB_PASSWORD` empty. The bridge will call the official Web API without an Authorization header.

> [!WARNING]
> This compatibility mode is weaker. When RikkaHub Web JWT is disabled, the official Web API's own write endpoints may also be reachable without authentication on the LAN. The bridge remains read-only, but it cannot secure the separate RikkaHub Web Server. Use this only on a trusted, isolated LAN.

## Run with Streamable HTTP

Copy `start_http.example.ps1` to the ignored `start_http.ps1`, then replace every placeholder. Alternatively, set the variables from `.env.example` in the process environment.

Important variables:

| Variable | Description |
|---|---|
| `RIKKAHUB_WEB_PASSWORD` | Optional RikkaHub Web access password; empty only when upstream JWT is disabled |
| `RIKKAHUB_WEB_URL` | Optional explicit RikkaHub Web base URL |
| `RIKKAHUB_WEB_PORT` | RikkaHub Web port, default `8080` |
| `RIKKAHUB_LAST_IP_FILE` | Optional last-successful-IP state file |
| `RIKKAHUB_HISTORY_RUN_MODE` | `stdio` or `http` |
| `RIKKAHUB_HISTORY_HOST` | MCP bind address; secure default `127.0.0.1` |
| `RIKKAHUB_HISTORY_PORT` | MCP port, default `8766` |
| `RIKKAHUB_HISTORY_TOKEN` | **Required in HTTP mode**; at least 24 high-entropy characters, with `token_urlsafe(32)` recommended |
| `RIKKAHUB_HISTORY_ALLOWED_HOSTS` | Comma-separated allowed Host headers, e.g. `192.168.0.10:8766` |
| `RIKKAHUB_HISTORY_ALLOWED_ORIGINS` | Comma-separated allowed Origins |

Generate a token:

```bash
python -c "import secrets; print(secrets.token_urlsafe(32))"
```

Start on Windows:

```powershell
.\start_http.ps1
```

Then configure RikkaHub MCP:

```text
Transport: Streamable HTTP
URL: http://<computer-lan-ip>:8766/mcp
Header: Authorization: Bearer <RIKKAHUB_HISTORY_TOKEN>
```

For LAN access, set `RIKKAHUB_HISTORY_HOST=0.0.0.0`, restrict the port with the host firewall, and add the exact host and port used by RikkaHub to `RIKKAHUB_HISTORY_ALLOWED_HOSTS`. HTTP mode refuses to start without a non-placeholder Bearer token.

## STDIO mode

```bash
RIKKAHUB_WEB_PASSWORD=... rikkahub-history-mcp
```

STDIO is the default when `RIKKAHUB_HISTORY_RUN_MODE` is not set and does not require `RIKKAHUB_HISTORY_TOKEN` because it does not open a listening HTTP port.

## Security and privacy

- The MCP tools exposed by this project are read-only.
- Never expose either RikkaHub Web Server or this MCP server directly to the public Internet.
- Do not configure router port forwarding for ports `8080` or `8766`.
- RikkaHub Web and the example MCP connection use plaintext HTTP. Use them only on a trusted LAN; passwords and Bearer tokens are not protected against a hostile network observer.
- Use a unique RikkaHub Web password and a separate, randomly generated MCP Bearer token.
- The bridge disables inherited `HTTP_PROXY`/`HTTPS_PROXY` settings for phone API traffic to avoid sending local credentials or conversation data through a proxy.
- Retrieved conversation text is untrusted data. Models must not follow instructions, links, or tool requests found inside historical messages.
- Retrieved history is sent to the currently selected model provider as tool context. Search narrowly and keep context windows small when conversations contain sensitive information.
- Do not commit `.env`, `start_http.ps1`, passwords, JWTs, Bearer tokens, state files, or logs.
- See [SECURITY.md](SECURITY.md) for vulnerability reporting and the supported security model.

## License

MIT