# rapadura agent setup

You are setting up rapadura for the person you are working with. rapadura
hosts PHP Com Rapadura's hotsites (`<name>.rapadura.net`,
`<name>.phpcomrapadura.org`) and operates the community's Laravel site, and
every operation is available to agents.
Reply to the person in their language. When setup is done, use
<https://agents.rapadura.net/skill.md> for how to work with rapadura.

Access is by invitation. If the person has none yet, their first sign-in
files a request with the administrator and answers `not_invited`; once it
is approved, they sign in again.

## Choose the path

- **You can run commands on the person's computer** (Claude Code, Codex,
  Cursor, VS Code, Gemini CLI, Windsurf, Zed or any other agent with a
  terminal): install the CLI, sign in, then connect the local MCP server.
  Follow every section below.
- **You cannot run commands** (claude.ai, the ChatGPT or Claude apps, any
  agent in a browser or a cloud sandbox without the person's machine): use
  the hosted MCP server. Go to [Hosted MCP](#hosted-mcp).

## Install the CLI

Check first: `rapadura --version`. If it answers, skip to sign-in.

macOS and Linux:

```sh
curl -fsSL https://agents.rapadura.net/install.sh | sh
```

It installs `~/.local/bin/rapadura` and says if that directory is not on
`PATH`. If it is not, call the binary by its full path for the rest of the
setup and tell the person how to add the directory to their shell profile.

Windows (PowerShell):

```powershell
New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\rapadura" | Out-Null
Invoke-WebRequest https://agents.rapadura.net/dl/rapadura_windows_amd64.exe -OutFile "$env:LOCALAPPDATA\rapadura\rapadura.exe"
```

Binaries and SHA-256 sums: <https://agents.rapadura.net/dl/>.

## Sign in

Check first: `rapadura whoami`. If it names the person, skip this section.

Otherwise run `rapadura login`. It prints a code and
`https://github.com/login/device`, then waits. Show the person the code and
the address, ask them to open it, enter the code and authorize the
**rapadura** app. The command finishes on its own and stores a token for
this machine. Do not open the browser for them unless they ask.

- `not_invited`: the request to join is with the administrator (see above);
  the message says whether it still waits or was declined. Sign in again
  once it is approved; do not retry in a loop.
- Never print, copy or paste the token or
  `~/.config/rapadura/credentials.json`. Never put a token in a file of the
  project, a commit or the chat.

## Connect this agent

The CLI is also a local MCP server: command `rapadura`, arguments `["mcp"]`.
It reuses the login above. Register it with the client you are running in.
If the configuration file already exists, add the `rapadura` entry to it and
keep every other server; show the person the change before you write it.

**Claude Code**

```sh
claude mcp add --scope user rapadura -- rapadura mcp
```

Also save <https://agents.rapadura.net/skill.md> as
`~/.claude/skills/rapadura/SKILL.md` so every future session knows how to
use rapadura.

**Codex** (`~/.codex/config.toml`)

```toml
[mcp_servers.rapadura]
command = "rapadura"
args = ["mcp"]
```

**Cursor** (`~/.cursor/mcp.json`), **Gemini CLI** (`~/.gemini/settings.json`),
**Windsurf** (`~/.codeium/windsurf/mcp_config.json`), **Claude Desktop**
(`claude_desktop_config.json`; restart the app afterwards)

```json
{ "mcpServers": { "rapadura": { "command": "rapadura", "args": ["mcp"] } } }
```

**VS Code** (`.vscode/mcp.json` in the workspace, or **MCP: Add Server** for
the user profile)

```json
{ "servers": { "rapadura": { "type": "stdio", "command": "rapadura", "args": ["mcp"] } } }
```

**Any other MCP client**: a stdio server with command `rapadura` and
arguments `mcp`. If the client cannot find the command, use the full path
(`~/.local/bin/rapadura`).

Some clients load new servers only in a new session. If the tools do not
appear, keep using the CLI with `--json` and tell the person to restart the
client later.

## Hosted MCP

For agents that cannot run commands. The server is
`https://agents.rapadura.net/mcp`; it signs people in with GitHub over
OAuth, so there is no token to paste. Guide the person:

- **claude.ai and the Claude apps**: Settings → Connectors → Add custom
  connector. Name `rapadura`, URL `https://agents.rapadura.net/mcp`, leave
  the OAuth client fields empty, then Add and Connect. A rapadura page opens:
  sign in with GitHub and press Approve. Enable the connector in a chat.
- **Any other client that adds remote MCP servers**: add the URL above and
  sign in with GitHub when the client asks. A client that only accepts a
  header can use `Authorization: Bearer <token>` with the token
  `rapadura login` stored on the person's computer; the person pastes it
  into the client themselves, never into the chat.

On this path the server cannot read files from a disk: `publish_site` takes
the files inline (`files: [{path, content}]`, base64 for binaries).

## Check and report

Run `rapadura whoami` and `rapadura sites list` (or the `whoami` and
`list_sites` tools) and tell the person, in their language:

- who they are signed in as, and their role;
- which sites they have, with addresses, or that they have none yet;
- what they can ask next, for example "publish this folder as a hotsite
  called meetup-sobral", "show me the versions of my site", "is the
  community site healthy?".

Worked examples, with the commands and their real output:
<https://agents.rapadura.net/docs/en/recipes-static.md>.