# NotiBuddy Setup Guide — Cursor

> Connect Cursor IDE to NotiBuddy via .cursor/mcp.json. Answer Agent questions, review code diffs, and approve edits from your iPhone or Apple Watch.
> Human-readable page: https://notibuddy.app/cursor
> Full CLI, MCP & protocol reference: https://notibuddy.app/setup.md

## 1. Prerequisites & package verification

- **iOS/iPadOS app:** NotiBuddy (iOS 17+ / watchOS 10+ companion included).
- **Computer client:** `notibuddy` **0.4.0** (use `notibuddy@^0.4.0` with `npx` on Node.js 20+, or `brew install yourbit-network/tap/notibuddy`).
- **Publisher:** Yourbit, LLC ([npm](https://www.npmjs.com/package/notibuddy) · [GitHub](https://github.com/yourbit-network/notibuddy)). Do not substitute similarly named packages or invent pairing credentials.
- Verify the CLI runs before pairing:

```bash
npx -y notibuddy@^0.4.0 --help
```

## 2. Check existing pairing before creating a new one

Run:

```bash
npx -y notibuddy@^0.4.0 status
```

- If a destination alias (such as `personal`) is already saved, verify it with `npx -y notibuddy@^0.4.0 doctor --to personal`. **Do not delete or regenerate existing sender keys** just because a check fails.
- If no destination is paired yet, ask the user to open **NotiBuddy** on iPhone → **Connect → Add** → **Create setup code → Share Setup** (valid for 10 minutes; keep NotiBuddy open and online), and **have the user run pairing directly in their own Terminal — never ask the user to paste `nbpair1.` secrets into chat**:

```bash
pbpaste | npx -y notibuddy@^0.4.0 pair --to personal
```

- If more than one destination is paired, bind this host explicitly by immutable `connectionId` (e.g. `npx -y notibuddy@^0.4.0 bind --client cursor --to personal`).
- Keep `~/.notibuddy/` and the `nbpair1.` bundle strictly private; never paste secrets or keys into chat, logs, repo files, or MCP configuration.

## 3. Configure Cursor

**Target:** `.cursor/mcp.json (project), ~/.cursor/mcp.json (global), or plugins/cursor/notibuddy`

Drop this into your Cursor MCP config (starts cleanly before pairing; if you have multiple destinations, pin with nb bind --client cursor --to personal):

```json
{
  "mcpServers": {
    "notibuddy": {
      "command": "npx",
      "args": ["-y", "notibuddy@^0.4.0", "mcp", "--client", "cursor"]
    }
  }
}
```

> **Homebrew alternative (faster startup):** If the user installed NotiBuddy via `brew install yourbit-network/tap/notibuddy`, you may configure `"command": "notibuddy-mcp"` with `"args": ["--client", "cursor"]` (or `["--to", "personal"]` to pin a single alias directly).

Preserve all existing servers, workflows, or settings when editing configuration files. Always configure NotiBuddy as a **local stdio MCP server or local CLI** — never point an MCP client at `https://notibuddy.app` as a remote MCP server.

## 4. Recommended rule — Example .cursor/rules/notibuddy.mdc

> If a multi-file task needs my input, hits an ambiguous trade-off, or completes after a long run, call notibuddy_notify so I can reply from my iPhone. Use requires_auth: true for destructive or production changes.

## 5. Verify both directions

1. Run `npx -y notibuddy@^0.4.0 doctor --to personal` (replacing `personal` with the actual saved alias) and confirm approval and protocol health.
2. Reload/restart the MCP server in the host app if required.
3. Call `notibuddy_notify` with:

```json
{
  "title": "NotiBuddy connected",
  "message": "Tap OK to confirm two-way replies.",
  "options": ["OK"]
}
```

Or test from Terminal:

```bash
npx -y notibuddy@^0.4.0 gate "NotiBuddy connected" --to personal --message "Tap OK to confirm two-way replies." --approve "OK" --reject "Cancel" --timeout 120
```

Confirm setup only after receiving a verified signed reply from the phone.

## 6. Tool contract & hard rules

- `notibuddy_notify` (`nb notify`): One-way encrypted notification by default; pass `options`, `input_placeholder`, `fields`, `diff`, `screen`, or `requires_auth: true` for interactive signed replies, or `resume_id` to poll an existing request. Ordinary requests allow up to **10,800 seconds (3 hours)**; `wait_seconds` / `--wait` is a separate poll budget (max 55s).
- **Custom Screens (0.4.0+):** Pass `screen: { templateId, labels, data }` (8 built-in layouts) or `screen: { template }` (12 native blocks: `vstack`, `card`, `divider`, `heading`, `text`, `badge`, `alert`, `kpiStrip`, `keyValueList`, `checklist`, `diffViewer`, `formField`, plus `actions` with optional Face ID) to `notibuddy_notify` or `nb notify --screen <json-file>` (or pre-register with `nb screen register <file> [--strict]`). The server validates and caches only the content-free layout template for up to 30 days while all text, metrics, diffs, and replies remain end-to-end encrypted.
- `nb gate`: Fail-closed CLI gate for scripts and CI/CD (exits `0` approved, `2` rejected/unauthenticated, `3` expired, `1` operational error).
- `nb hook claude PermissionRequest`: Native Claude Code permission hook with 10s local grace period, hidden Lock Screen previews by default, opt-in `--requires-auth`, rolling hourly cap, and silent pass-through on non-decision outcomes. Requires a local `nb` install (never `npx`).
- `notibuddy_activity`: Start, update, end, or poll Lock Screen / Dynamic Island / Apple Watch progress and timers (1-hour lifetime; the agent must poll and act on pause/resume/cancel controls).
- `notibuddy_files`: `action: "list"` and `action: "receive"` (`id` required) to download encrypted phone uploads up to 10 MB under `~/.notibuddy/inbox/`. Never auto-execute received files.
- **Fail closed:** Never treat a timeout, expiry, error, or silence as approval.
- **Keep sessions awake:** The sending host or workflow must stay running to receive replies; NotiBuddy cannot wake a sleeping machine or restart an ended session.
- **Full specification:** https://notibuddy.app/setup.md
