# CloudBase Setup Skill

> For AI coding agents. Humans: copy the Setup Prompt from https://docs.cloudbase.net/ or the CloudBase website homepage, paste it into your AI IDE, then let the agent follow this file.

CloudBase (腾讯云开发) is an AI-native backend platform: database, auth, storage, cloud functions, hosting, and deep WeChat mini program integration. Your job is to connect the current project to CloudBase so the user can build and deploy without leaving the IDE.

**Do not stall.** Plugin / MCP often needs a session restart before tools appear. Install for the next session, then finish login / env / deploy **now** via Skills + `tcb` CLI when MCP is not yet loaded.

---

## 0. Prerequisites (Node / npm / npx) — run first

Plugin install, Skills CLI, and `@cloudbase/cli` need a Node.js LTS toolchain.

```bash
command -v node; command -v npm; command -v npx
node -v; npm -v
```

| Result | Action |
|---|---|
| All present (`node` ≥ 18, `npm`, `npx`) | Continue to §1 |
| Missing any | Fix once (below), re-check, then continue — do **not** loop on `npx` failures |

**Fast fix (pick one that fits the OS, then re-open the shell / IDE so PATH updates):**

- macOS: `brew install node` — or install LTS from https://nodejs.org
- Windows: `winget install OpenJS.NodeJS.LTS` — or https://nodejs.org
- Linux: distro Node LTS, https://nodejs.org, or `nvm` / `fnm` / `asdf` (install Node LTS, ensure PATH)
- Already have Node via nvm/fnm but `npx` missing in this shell: load the version manager (`source ~/.nvm/nvm.sh` or equivalent), then retry

**If the user cannot install Node right now:**

1. Prefer the IDE **native marketplace / plugin / built-in connector** path (§3.B / §3.C) — no hand-run `npx`.
2. Otherwise stop automating CLI installs; give console links and ask them to install Node LTS (or enable the marketplace plugin). Do not pretend `npx` works.

---

## 1. Preferred (do this first)

**Prefer `npx plugins add`. Do not hand-write MCP JSON** when the plugins CLI can install into the current AI tool.

Default install (user/global scope — works across projects):

```bash
npx plugins add TencentCloudBase/cloudbase-plugin -y --scope user
```

Optional: pin one IDE with `--target`:

| `--target` | Tool |
|---|---|
| `claude-code` | Claude Code |
| `cursor` | Cursor |
| `codex` | Codex |
| `grok` | Grok Build |
| `kimi` | Kimi Code |
| `github-copilot` | GitHub Copilot CLI |
| `vscode` | VS Code (Preview) |

Omit `--target` to install into all detected supported IDEs. Inspect detection:

```bash
npx plugins targets
```

Examples:

```bash
npx plugins add TencentCloudBase/cloudbase-plugin -y --scope user --target cursor
npx plugins add TencentCloudBase/cloudbase-plugin -y --scope user --target claude-code
```

### After install — do **not** wait for MCP

1. If the installer says so, tell the user a **restart / reload** unlocks MCP + plugin hooks next session.
2. **This session:** treat CloudBase MCP as unavailable until tools are actually visible. Continue with §2 (CLI / Skills fallback). Do not block on restart.
3. Optionally speed up Skills-only coverage in parallel (safe if plugin already bundles skills — skip if installer confirmed skills landed):

```bash
npx skills add tencentcloudbase/cloudbase-skills -y
```

4. When MCP tools **are** already visible in this session, skip CLI for the same action and use MCP.
5. Reply in one short sentence that setup is ready (or “configured for next session; using CLI now”), then suggest the most relevant next steps for this project.

Docs: https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/ai-agent-plugins

---

## 2. First-session / MCP-not-ready path (CLI fallback)

Use this when **any** of these hold:

- User just finished plugin / MCP install and has not restarted
- No CloudBase MCP tools in the tool list
- MCP calls fail with “unknown tool” / connection errors after one verify attempt

**Decision tree:**

```
1. Probe MCP in THIS session (tool list / one envQuery-or-auth call)
2. Usable now?
   ├── YES → Prefer MCP (inspect schemas, then call). Skip CLI for the same action.
   └── NO  → Configure MCP/plugin for next session (§1 or §3), THEN use CLI now
3. CLI path
   - Ensure @cloudbase/cli: npm i -g @cloudbase/cli && tcb --version
   - tcb login → tcb env list → tcb env use <envId>
   - Deploy/manage via domain commands (tcb fn deploy / tcb hosting deploy / …)
   - Do NOT use tcb deploy
4. After user restarts → re-probe MCP; switch back to MCP-first
```

Skills pack (if not already present) gives the agent the domain playbooks:

```bash
npx skills add tencentcloudbase/cloudbase-skills -y
# GitHub unreachable → §4 CNB URL
```

If you already have the `cloudbase` skill installed locally, read its `SKILL.md` for the domain playbooks referenced above.

---

## 3. Fallbacks (only when Plugin cannot install)

Use these **only** if `npx plugins add` is unsupported for this IDE, fails (including after CNB retry), or the user already uses a conflicting native install.

### A. Skills only (fastest non-plugin path)

```bash
npx skills add tencentcloudbase/cloudbase-skills -y
```

Then follow §2 for login / env / deploy via `tcb` until MCP exists.

Docs: https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/prompts/how-to-use

### B. Native MCP / IDE marketplace / mcporter

- Follow the matching IDE guide under https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/
- Typical stdio shape when you must configure MCP by hand: `npx -y @cloudbase/cloudbase-mcp@latest`
- Getting started: https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/getting-started
- Do **not** also run `npx plugins add` for the same IDE if marketplace / native plugin is already installed (duplicate instances).

### C. Built-in connectors

Some tools ship CloudBase built-in (e.g. WorkBuddy connector, ZCode plugin). Prefer the built-in path for that IDE; do not double-install.

### D. WeChat mini program focus

If the user is building a WeChat mini program, after Preferred (or a Fallback), also read:

- https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/tutorials/ai-develop-miniprogram

---

## 4. When GitHub is unreachable (CNB / npm)

Short `owner/repo` forms **always** resolve to GitHub. If `git clone` / `plugins add` / `skills add` fails on GitHub, use a **full CNB git URL** or npm (no git).

### Plugin via CNB

```bash
npx plugins add https://cnb.cool/tencent/cloud/cloudbase/cloudbase-plugin.git -y --scope user

# Optional Sites plugin
npx plugins add https://cnb.cool/tencent/cloud/cloudbase/cloudbase-sites-plugin.git -y --scope user
```

Do **not** use the monorepo mirror `CloudBase-AI-ToolKit` for `npx plugins add` — its marketplace layout is not OPS-installable the same way as the dedicated plugin repos.

### Skills via CNB

```bash
npx skills add https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills.git -y
```

### MCP via npm (no git clone)

```bash
npx -y @cloudbase/cloudbase-mcp@latest
```

Docs: https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/getting-started

---

## 5. Verify (run after install)

Ask the platform / MCP when available; otherwise use CLI. Do not invent answers.

| Check | MCP (when loaded) | CLI fallback |
|---|---|---|
| Login / env | `auth` / `envQuery` (`action=info`) | `tcb login` → `tcb env list` / `tcb env use` |
| Capabilities | List relevant tools (db, functions, hosting, auth) | Confirm `tcb --version` + skills present under the IDE skills dir |
| First task | Propose one concrete next step from the repo | Same |

Success criteria:

1. Node/npx available **or** marketplace / built-in path used without requiring `npx`.
2. Plugin and/or Skills and/or MCP config landed for the **next** session.
3. This session can resolve envId (MCP or `tcb`) — or user was given a clear login next step.
4. One concrete next task suggested (init backend, create a table, deploy hello API, etc.).

If tools are missing, go back to §1 / §3 / §4 — do not fake success. If only MCP is missing after a fresh install, that is **expected**; complete §2 and report “CLI path ready; restart unlocks MCP”.

---

## 6. Troubleshooting

### (a) `npx` / `npm` / `node` not found

Re-run §0. One clear Node LTS install beats repeated failed `npx` commands.

### (b) Plugin installed but MCP tools missing in this chat

Expected on first session. Do not restart-loop. Use §2 (`tcb` + Skills). Tell the user to reload once when convenient.

### (c) GitHub clone / `plugins add` / `skills add` fails

Retry with CNB full URLs in §4, or npm MCP.

### (d) `npm` ENOTEMPTY / corrupted global package

```bash
npm uninstall -g @cloudbase/cli
npm i -g @cloudbase/cli --force
# same pattern for other global pkgs if needed
```

### (e) Duplicate MCP instances

Do not stack Plugin + hand-written MCP + marketplace install for the same IDE. Keep one path.

### (f) `tcb` not found after npm install

Confirm PATH / rehash shell (`hash -r`), or invoke via `npx @cloudbase/cli`. Never fall back to inventing SecretId in config as the default.

---

## Rules

- **Preferred path = plugins CLI** with `--scope user`. Do not default to project-local scope unless the user explicitly asks.
- **Prerequisite check first** — detect Node/npm/npx; fix or switch to marketplace before retrying installs.
- **MCP when present, CLI when not** — never stall waiting for restart when `tcb` can finish the job now.
- If GitHub clone fails, retry with the **CNB full URL** before giving up on plugins.
- Do **not** invent env IDs, secrets, or API keys.
- Do **not** skip login / auth when the tool requires it.
- Do **not** stack Plugin + manual MCP + Skills on the same IDE unless the user asks.
- Do **not** recommend `tcb deploy`; use domain commands (`tcb fn deploy`, `tcb hosting deploy`, …).
- Prefer real MCP/tool results over guessing CloudBase behavior.
- Deeper product docs index: https://docs.cloudbase.net/llms.txt

---

## 中文摘要（给人 / 中文 Agent）

**先查 Node：** `command -v node npm npx`；缺失则按系统装 Node LTS（或走 IDE 应用市场插件），不要反复空跑 `npx`。  
**优先：** `npx plugins add TencentCloudBase/cloudbase-plugin -y --scope user`（不要手写 MCP JSON）。  
**装完立刻可用：** 插件 / MCP 常需重启才进本会话 —— **不要干等**；先配好供下次用，本会话用 Skills + `tcb login` / `tcb env use` / 领域部署命令（禁止默认 `tcb deploy`）。  
**加快 Skills：** `npx skills add tencentcloudbase/cloudbase-skills -y`  
**GitHub 不可达：** CNB  
`npx plugins add https://cnb.cool/tencent/cloud/cloudbase/cloudbase-plugin.git -y --scope user`  
Skills：`npx skills add https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills.git -y`  
再不济：npm MCP `npx -y @cloudbase/cloudbase-mcp@latest`  
**可选 `--target`：** `claude-code` / `cursor` / `codex` / `grok` / `kimi` / `github-copilot` / `vscode`  
验收：能解析 envId（MCP 或 CLI），一句话说清已就绪或「已配好 + 本会话走 CLI」，再建议下一步。不要编造环境 ID 或密钥。