rankrat

# rankrat

<!-- mcp-name: io.github.psyb0t/rankrat -->

[![CI](https://github.com/psyb0t/rankrat/actions/workflows/pipeline.yml/badge.svg?branch=main)](https://github.com/psyb0t/rankrat/actions/workflows/pipeline.yml)
[![coverage](https://raw.githubusercontent.com/psyb0t/rankrat/badges/coverage.svg)](https://github.com/psyb0t/rankrat/actions/workflows/pipeline.yml)
[![version](https://raw.githubusercontent.com/psyb0t/rankrat/badges/version.svg)](https://github.com/psyb0t/rankrat/tags)
[![license](https://raw.githubusercontent.com/psyb0t/rankrat/badges/license.svg)](LICENSE)
[![Docker Pulls](https://img.shields.io/docker/pulls/psyb0t/rankrat?style=flat-square)](https://hub.docker.com/r/psyb0t/rankrat)

Search Console, Bing Webmaster Tools, GA4 and PageSpeed each ship a dashboard.
Dashboards answer the question you already knew to ask. The interesting ones —
*which queries actually caused last week's drop*, *is this page down because it
lost rankings or because it fell out of the index*, *do Google and Bing agree
something broke* — need you to pull four exports and do the join yourself, in a
spreadsheet, at 1am.

rankrat puts those APIs behind one MCP server so an agent does the joining. You
ask; it goes and rats out whichever provider knows.

It's a rat, not a burglar. It answers only for the accounts and properties you
list in a boundary file, and no tool widens that from inside a session.
Read-only unless you deliberately turn writes on, at which point the write tools
appear and stay inside the same boundaries. Nothing here crawls a site, tracks a
competitor, or touches a domain you haven't verified — it reads what the
providers already hold about you.

Speaks MCP over stdio and Streamable HTTP, plus a REST API for callers that
don't speak MCP.

**Status:** alpha. Everything documented here works against real accounts; the
tool surface is still free to move.

## Contents

- [Quick start](#quick-start)
- [Running it](#running-it)
- [Agent integrations](#agent-integrations)
- [Write capability](#write-capability)
- [Onboarding a new site](#onboarding-a-new-site)
- [Credentials](#credentials)
- [Configuration](#configuration)
- [Verification](#verification)
- [Security](#security)
- [Release information](#release-information)

## Quick start

Rankrat ships as a Docker image; Docker is the only requirement. Create the
working layout in a directory of your choosing — Rankrat reads all three paths
as mounts and never writes outside them:

```sh
mkdir -p config oauth secrets/google secrets/bing secrets/indexnow secrets/rankrat
chmod 700 config oauth secrets secrets/rankrat

curl -fsSL https://raw.githubusercontent.com/psyb0t/rankrat/main/config/boundaries.json.example \
  -o config/boundaries.json
chmod 600 config/boundaries.json

install -m 600 /dev/null secrets/rankrat/http-bearer-token
openssl rand -base64 32 | tr -d '\n' > secrets/rankrat/http-bearer-token
```

The bearer secret authenticates `/v1/` and `/mcp` for non-loopback HTTP; stdio
never uses it, but the HTTP mode requires the file to exist.

Then edit `config/boundaries.json` to list only what Rankrat may read, put the
credentials for the providers you actually use at the paths in
[Credentials](#credentials), and authorize Google if you configured it:

```sh
rankrat.sh auth-google --account-id google --print-authorization-url
rankrat.sh setup
```

`setup` is a live, read-only verification gate. It checks configured provider
access; it does not create a provider resource or submit an IndexNow URL. It
reports the missing local file, OAuth grant, provider permission, or configured
resource that needs attention. It is the one mode that reads `.env`, where the
`RANKRAT_LIVE_*` selectors choose which providers it checks — leave the
selectors for unused providers empty and their checks skip.

## Running it

```sh
rankrat.sh          # MCP over stdio
rankrat.sh http     # REST + Streamable HTTP MCP on 127.0.0.1:8080
```

[`rankrat.sh`](rankrat.sh) is a wrapper around `docker run`: it resolves the
mounts, publishes the port, and applies the container hardening flags. Install
it once —

```sh
curl -fsSL https://raw.githubusercontent.com/psyb0t/rankrat/main/rankrat.sh \
  -o rankrat.sh
less rankrat.sh                       # it is ~250 lines; read before installing
chmod +x rankrat.sh
sudo mv rankrat.sh /usr/local/bin/rankrat.sh
```

— or skip it entirely and run the image yourself. `docker run` is the supported
contract and the wrapper is only convenience:

```sh
docker run -i --rm --init --read-only \
  --user "$(id -u):$(id -g)" \
  --cap-drop=ALL --security-opt no-new-privileges:true \
  --pids-limit 128 --memory 512m --cpus 1 \
  --tmpfs /tmp:rw,noexec,nosuid,size=32m \
  -e RANKRAT_READ_ONLY=true \
  -e RANKRAT_BOUNDARY_FILE=/run/config/boundaries.json \
  -e RANKRAT_OAUTH_TOKEN_ROOT=/run/oauth \
  --mount type=bind,src="$PWD/config",dst=/run/config,readonly \
  --mount type=bind,src="$PWD/secrets",dst=/run/secrets,readonly \
  --mount type=bind,src="$PWD/oauth",dst=/run/oauth \
  psyb0t/rankrat:latest stdio
```

Mount `config/` as a directory, not `config/boundaries.json` as a single file.
The image bakes `/run/config` owned by its own `rankrat` user, so a single-file
mount leaves that directory in place and the boundary file then reads only when
the container uid happens to match the host file's owner. Mounting the directory
replaces it, and `readonly` still covers the file inside.

Swap `stdio` for `http` and add `-p 127.0.0.1:8080:8080`,
`-e RANKRAT_HTTP_HOST=0.0.0.0` and
`-e RANKRAT_HTTP_BEARER_SECRET_FILE=/run/secrets/rankrat/http-bearer-token`.
`RANKRAT_HTTP_HOST=0.0.0.0` binds inside the container; `-p` is what keeps it on
loopback. MCP is then at `http://127.0.0.1:8080/mcp`.

The wrapper reads `RANKRAT_IMAGE`, `RANKRAT_BOUNDARIES`, `RANKRAT_SECRETS`,
`RANKRAT_OAUTH`, `RANKRAT_ENV_FILE`, `RANKRAT_HTTP_PORT` and
`RANKRAT_OAUTH_CALLBACK_PORT` from the environment to point at non-default
paths. Those are host-side only — keep them out of `.env`, which goes straight
to the container, where an unrecognized `RANKRAT_*` variable fails startup.
`rankrat.sh --help` lists every mode.

On a checkout, the Make targets call the same wrapper against the locally built
image, so `make run` and `make run-http` exercise the path above rather than a
second copy of it. See [Verification](#verification) and `make help`.

## Agent integrations

The [skill](.agents/skills/rankrat) works in any agent that reads
`.agents/skills/`, and installs natively in the clients below. An agent runs the
published image directly and does not need the wrapper.

### Claude Code

```sh
claude plugin marketplace add psyb0t/agents
claude plugin install rankrat@psyb0t
```

### Codex

```sh
codex plugin marketplace add psyb0t/agents
codex plugin add rankrat@psyb0t
```

Installed this way the skill invokes as `$rankrat:rankrat`. Codex also picks it
up on its own in any repo containing `.agents/skills/`, where it is `$rankrat`.

### OpenClaw

The skill and the MCP bridge are published to ClawHub on every release:

```sh
openclaw skills install @psyb0t/rankrat
openclaw plugins install clawhub:@psyb0t/rankrat
```

The [bridge](.agents/plugins/rankrat) covers both transports. It defaults to
stdio, running the published image itself — set `RANKRAT_CONFIG_DIR` (plus
`RANKRAT_SECRETS_DIR` and `RANKRAT_OAUTH_DIR` when those are needed) and nothing
has to be running first. For a shared server, set `RANKRAT_TRANSPORT=http` and
`RANKRAT_URL`, plus `RANKRAT_AUTH_TOKEN` if a bearer secret is configured.

## Write capability

There is no approval ID, admin API, or second bearer token.

```dotenv
# Default: no write services, REST write routes, or MCP write tools exist.
RANKRAT_READ_ONLY=true

# Direct, boundary-limited writes become visible to the trusted caller.
RANKRAT_READ_ONLY=false
```

In read-only mode, write routes are not mounted and write MCP tools are absent
from `tools/list`, so an LLM cannot discover or call them. In writable mode,
all writes remain restricted to the explicit boundaries and the provider's own
permissions. The regular HTTP bearer token protects `/v1/` for non-loopback
HTTP; stdio access is controlled by who can start the process.

Writes cover IndexNow submission, Bing URL/sitemap/property changes, Google
Indexing notifications, Search Console site/sitemap changes, and new-site
onboarding. They are marked destructive/non-idempotent in MCP.

## Onboarding a new site

`onboard-site` creates a GA4 property, a Search Console property and a Bing site
for one URL, then records their IDs in the boundary file. Two things are worth
knowing before using it.

**It cannot verify the site, and does not pretend to.** Verification proves to a
provider that you own the domain; the token is issued by that provider's own
console and Rankrat holds no credential that can read it. So onboarding returns
success — meaning the three create calls were accepted — while the properties are
still unverified and returning no data. What you do next depends on the property
form:

| Property | Methods it accepts |
| --- | --- |
| `sc-domain:example.com` | DNS TXT record, and nothing else |
| `https://example.com/` | GA4 tag, HTML file, meta tag, DNS TXT |
| Bing | Import from a verified Search Console property, XML file, meta tag, CNAME |

Deploy the returned GA4 Measurement ID first. It is the one artifact Rankrat
hands you directly, and on a URL-prefix property it also satisfies Search Console
verification on its own — after which Bing can simply import that property. Least
work, no extra APIs.

The procedure is served rather than left implied, so an agent can walk you through
it instead of guessing: the `rankrat://onboarding` MCP resource, a
`rankrat://onboarding/{site_url}` template for one percent-encoded site, and an
`onboarding_guide` tool returning the same document for clients without resource
support. All three are read-only and present even on a read-only server — knowing
the procedure is not a privile