# Connect Social Collector to this AI (runbook for AI agents)

You are an AI assistant. Your user wants to connect their Social Collector (社群收藏管理器, https://socialcollector.app) saves to you through a local MCP server, so you can search their saved posts and propose cleanups. Follow this runbook. Reply in the user's language (default: Traditional Chinese).

## Rules (read first)

1. **One step per message.** Do one thing, say what you did in one sentence, then ask the user to act or confirm. Never send a list of steps. The user may have ADHD: short, calm, no walls of text.
2. **Never ask the user to paste their key into the chat.** The setup script reads it from the clipboard. If they pasted it anyway, continue, and at the end suggest pressing 「重新產生金鑰」 in the App.
3. **Only run commands written here**, and say in plain words what each does first.
4. When something fails, run the check in step 5 and use the table at the bottom. Do not guess.
5. Trust only https://socialcollector.app and https://api.socialcollector.app.

## Step 0: which route are you?

- **Route A**: you can run shell commands on the user's computer (Claude Code, Cursor, Codex CLI, Gemini CLI, Cowork, similar). Use steps 1 to 6.
- **Route B**: plain chat window, no shell (Claude Desktop chat, ChatGPT, etc.). Jump to "Route B".

## Route A

### 1. Check the basics
- They must be on a **computer** (Windows or Mac), not a phone, and be an **Elite** member (this feature is Elite only).
- Run `node -v`; need v20 or newer. **On Windows use PowerShell**: a Bash tool often has a different PATH and says "command not found" although Node is installed (try `where.exe node` or `C:\Program Files\nodejs\node.exe -v`). If Node is really missing, offer to install it (Windows: `winget install OpenJS.NodeJS.LTS`; Mac: https://nodejs.org) and **wait for their yes**.

### 2. Get the setup script
```
node -e "fetch('https://socialcollector.app/setup.mjs').then(r=>r.text()).then(t=>require('fs').writeFileSync('setup.mjs',t))"
```
You may read `setup.mjs` first. It downloads the official extension from socialcollector.app into `~/.social-collector-mcp/`, stores the key there, and registers the server. It contacts only socialcollector.app, api.socialcollector.app and Google Drive.

### 3. Ask the user to copy the key (their only manual job)
Say, in one message: 「請打開社群收藏管理器 App：設定 → 連線 AI 助理 → 按「產生連線金鑰」→ 按「複製金鑰」。複製好就跟我說「好了」。不用貼給我，也請不要再複製別的東西。」 Wait for "done".

### 4. Install and register
Pick the client: `claude-code`, `claude-desktop`, `cursor`, `codex`, `gemini`, or `other`. Always write options as `--name=value`.
```
node setup.mjs --client=<client> --key-from-clipboard
```
- Clipboard has no key (must start with `scmcp_`): ask them to copy again from the App.
- **Claude Desktop only**: ask them to fully quit it from the system tray / menu bar before this step, and reopen it after.
- `other`: the script prints a JSON block (no secret in it). Put it into that tool's MCP config following that tool's own documentation.
- **If you cannot run it yourself or cannot read the clipboard** (sandbox, restricted shell): do NOT ask the user to copy anything yet. Tell them to open a normal terminal in the folder containing `setup.mjs` (PowerShell on Windows, Terminal on Mac), run that one short line, and only THEN press 「複製金鑰」 in the App. Run by a person, the script waits up to 3 minutes for the key, so the order never matters. Never make them copy a command after the key: that overwrites the key. Keep what you give them to one short line.

### 5. Check
```
node setup.mjs --check
```
Expect `OK：已連線，讀到 N 篇收藏`. Otherwise use the table below.

### 6. Restart and test
Ask the user to restart the AI tool or open a new chat so it loads the new server, then call `list_categories`. If it returns categories, tell them. They can also see 「最後使用」 under 設定 → 連線 AI 助理 (leave the page and return to refresh).

Finish with three example questions: 「幫我找跟 OO 有關的收藏」, 「我最近存了什麼」, 「從未分類挑 3 篇，提案加上標籤」. You only **propose**; the user approves in the App; you cannot delete anything.

## Route B (chat only): coach the user through the extension

One bullet per message; wait for the user. Ask for a screenshot when the screen differs from what you expect.

1. Ask: 「你的 Claude Desktop 已經登入了嗎？是 Windows 還是 Mac？」
2. 「請在 App 按「設定 → 連線 AI 助理 → 產生連線金鑰 → 複製金鑰」，好了跟我說。」
3. Give https://socialcollector.app/social-collector.mcpb and ask them to download it and double-click it in Downloads. If Windows asks which app to use, choose Claude, then 「僅一次」. On Mac, if nothing happens, drag the file into the Claude window.
4. In the install window press 「安裝」. The red "not verified by Anthropic" warning is normal for non-store extensions.
5. It shows 「已停用」. Press 「設定」, paste the key (Ctrl+V, Mac Cmd+V; shows as dots), then switch the toggle on until it says 「已啟用」. Forgetting the toggle is the most common failure.
6. Open a **new chat** and ask 「用社群收藏管理器列出我的分類」. When asked for permission, choose 「允許一次」.

(Here the user pastes the key into the extension's own settings box, never into the chat.)

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| 找不到「社群收藏管理器」工具 | Toggle off, or old chat | Turn the toggle on (Claude settings, Extensions), open a new chat |
| 連線金鑰無效或已被撤銷 | Key regenerated or revoked | App: 重新產生金鑰, copy, rerun step 4 (or paste into the extension settings) |
| Elite 已到期 | Plan expired | Renew Elite; the same key works again |
| `node` missing or older than 20 | Node | Step 1 |
| Clipboard has no key | Copied something else | Copy the key again in the App |
| Download blocked | Company or school computer | Route B, or ask IT |
| 最後使用 shows 還沒使用過 | App page not refreshed | Leave and reopen the page; if `list_categories` works, it is connected |
| Key leaked, or new computer | | App: 重新產生金鑰 (old one dies at once) or 中斷連線 |

Tell the user if asked: you can only search and read, and only **propose** changes that they approve in the App; you cannot delete collections. Collection content does not pass through the developer's servers; the key only exchanges for read access to the user's own Google Drive backup. Support: support@socialcollector.app