# Rockaway Q / QAQ Brain MCP

This connects Claude Code or Codex to the read-only Rockaway Q / QAQ brain.

After setup, you can chat naturally and ask questions like:

```text
Use the Rockaway brain to answer this: what do we know about this project?
Use the Rockaway brain to find recent notes about this customer.
Use the Rockaway brain to find open blockers around this workflow.
Use the Rockaway brain to enrich this CSV.
```

This repository connects the Rockaway Q / QAQ brain and installs a small Rockaway brain skill so Claude Code or Codex knows how to ask it questions.

Use this from the terminal on the same machine where Claude Code or Codex runs. Do not add this URL through Claude's custom connector UI: custom connectors are reached from Anthropic's cloud, while this private endpoint is intentionally reachable only from Tailscale-connected local machines.

## What You Install

This one setup gives you both pieces:

```text
1. The read-only Rockaway Q / QAQ brain connection.
2. The Rockaway QBrain skill.
3. A separate read-only QMD search connection for fast semantic recall.
```

After setup, the skill command is:

```text
$rockaway-qbrain
```

Use that command at the start of your message when you want Claude Code or Codex to use the Rockaway Q / QAQ brain.

## Install As An Agent Plugin

Make sure Tailscale is connected, then use the one line for your app.

Codex:

```bash
codex plugin marketplace add zabrodsk/rockaway-q-brain-mcp && codex plugin add rockaway-qbrain@rockaway-qbrain
```

Claude Code:

```bash
claude plugin marketplace add zabrodsk/rockaway-q-brain-mcp && claude plugin install rockaway-qbrain@rockaway-qbrain
```

The plugin installs the skill and both read-only brain connections together. There is no bearer token and no separate QMD installation. Restart the app after installation.

Legacy setup remains available as a compatibility fallback: `bash -c "$(curl -fsSL https://raw.githubusercontent.com/zabrodsk/rockaway-q-brain-mcp/main/bootstrap.sh)"`.

## What Gets Connected

```text
MCP name: rockaway-q
MCP URL:  https://clawdbot--mac-mini.taild9e247.ts.net:8446/mcp
Access:   read-only

QMD MCP name: rockaway-q-qmd
QMD MCP URL:  https://clawdbot--mac-mini.taild9e247.ts.net:8444/mcp
QMD collection: rockaway-q
```

The brain and QMD connections are read-only. QMD search runs as a separate Mac mini QMD MCP; no local QMD install is needed. Existing GBrain MCP remains canonical for page expansion, links, backlinks, and stats.

The repository follows Agent Plugins 1.0 with portable `plugin.json`, `mcp.json`, and `skills/` components. Codex and Claude Code compatibility manifests are included until every client loads the portable files directly.

## How To Use It

After setup, use this skill command:

```text
$rockaway-qbrain
```

The easiest pattern is:

```text
$rockaway-qbrain Use the Rockaway brain to answer this: ...
```

Examples:

```text
$rockaway-qbrain Use the Rockaway brain to answer this: what do we know about this project?
$rockaway-qbrain Use the Rockaway brain to find the latest customer context.
$rockaway-qbrain Use the Rockaway brain to find notes related to the onboarding workflow.
```

For CSV or spreadsheet lookup, tell Codex or Claude:

```text
$rockaway-qbrain Use the Rockaway brain to enrich this CSV.
```

Useful output columns are `row`, `match`, `confidence`, `summary`, `next step`, and `sources`.

To verify from a terminal:

```powershell
codex mcp list
```

You should see `rockaway-q` and `rockaway-q-qmd`.

## Need Access?

You need to be on the Rockaway Tailscale network, and your Tailscale identity must be allowed to reach the Q / QAQ brain port. Open this URL in a browser while Tailscale is connected:

```text
https://clawdbot--mac-mini.taild9e247.ts.net:8446/mcp
```

Seeing JSON such as `Method not allowed` means the private network path is working.

## Troubleshooting

If `codex mcp list` or Claude Code shows `rockaway-q` failing to start, first confirm Tailscale is connected and the browser check above reaches the URL. If the browser cannot connect, ask the Rockaway brain admin to verify your Tailscale access. If the browser reaches the URL but Claude Code or Codex still fails, fully quit and reopen the app.

Claude custom connectors are not the supported path for this private brain. They connect from Anthropic's cloud, not from your local Tailscale-connected machine.

The `linear` MCP is independent of this toolkit. If it reports "not logged in,"
run `codex mcp login linear`.

## Setup Guide

Open or download the guide:

[Rockaway Q Brain MCP Guide.pdf](docs/Rockaway%20Q%20Brain%20MCP%20Guide.pdf)