cloudbase-all-in-one

# CloudBase All-In-One ## Step 0 — Confirm the site (domestic vs international) CloudBase runs 国内站 (domestic, `cloud.tencent.com`) and 国际站 (international, `tencentcloud.com`) as **two independent account systems** — environments, consoles, API keys, and login state do not cross over. A wrong-site login looks like *"logged in, but no environments"* rather than a clear error, so settle the site before logging in or configuring MCP. - **International (国际站)** — connect the international remote MCP endpoint directly: `https://tcb-api.tencentcloud.com/mcp/v1`. For local stdio set `TCB_SITE=intl` + `TCB_REGION=ap-singapore`; for the `tcb` CLI set `TCB_IS_INTL=true`. - **Domestic (国内站)** — `https://tcb-api.cloud.tencent.com/mcp/v1`. Both switches are the defaults, so nothing extra to declare. - Two gaps to plan around: remote endpoints take **no `site` / `region` query parameter** (the hostname decides), and the international site has **no NoSQL / document-database tools**. ## Workflow Every CloudBase task follows this three-stage process: ``` 1. Exploration → Read the matching skill completely before writing any code. Search for it if needed, then Read the full SKILL.md content. Only start implementing after understanding the API patterns, pitfalls, and correct usage from the skill document. 2. Implementation ├── 2a. Resource preparation → Prefer MCP to prepare backend resources │ (enable auth providers, create database tables, configure storage domains, │ set up security rules — before writing frontend code). │ If MCP tools are missing in THIS session, run the readiness check in │ `./cloudbase-mcp/SKILL.md` first — missing tools are often wiring │ (connector unbound or in need of a reconnect), not configuration. │ Then configure for next time and use `tcb` CLI now (`./cloudbase-cli/SKILL.md`). └── 2b. Frontend implementation → Write code, install deps, start server, test 3. Close-out → Run cloudbase-code-review, fix all errors, declare done ``` **Key constraints:** - **Stage 2a (resource preparation) must come before frontend code.** Prefer MCP tools; when they are not loaded yet (first session / pre-restart), fall back to `tcb` CLI after configuring MCP. Don't write frontend code that depends on uncreated resources (tables, auth providers, storage buckets) — the app cannot run end-to-end without them. - **Do not skip Stage 3.** The close-out catches known pitfalls that agents commonly miss during implementation. ## Scope Only handle tasks that are part of building, integrating, or maintaining a CloudBase application — including UI design, spec planning, and other development activities when they are in service of a CloudBase app. If the request has no CloudBase application context at all, stop and tell the user this skill only covers CloudBase-based development. ## Activation Contract ### Use this first when - The task is a CloudBase app build, integration, or repair and the workspace already contains an application implementation. - The request mixes auth, database, storage, and frontend work in one CloudBase application task. ### Do this before broad exploration - **Read the relevant skill before writing any code.** Search for the matching skill with `searchKnowledgeBase(mode="skill", skillName=...)`, then `Read` the returned file path to get the full SKILL.md content. Do not start implementing based only on the search result summary — the full document contains API signatures, parameter schemas, and pitfall warnings. - Inspect the existing implementation surfaces first: - `src/lib/backend.*` - `src/lib/auth.*` - `src/lib/*service.*` - route guards - the page handlers bound to the active form submit buttons - If these files contain TODOs, implement those TODOs in place before creating new helpers, examples, or replacement pages. - Do not start with UI redesign or design-spec output unless the user explicitly asks for visual changes. - Do not start with project-management loops such as repeated `TaskCreate` / `TaskUpdate` when the task is a single targeted repair. Read the active files and edit them directly. ### Route quickly to the minimum needed skills - Minimal Web + database demo / Lovable-like BaaS fast path -> `./minimal-web-baas-demo/SKILL.md` (default for 最小前后端 demo; BaaS-first, no cloud functions) - Web app execution -> `./web-development/SKILL.md` - Declarative whole-project deploy from cloudbaserc (deployApply/deployPlan) -> `./cloudbase-declarative-deploy/SKILL.md` - Web auth provider readiness -> `./auth-tool-cloudbase/SKILL.md` - Web auth implementation -> `./auth-web-cloudbase/SKILL.md` - CloudBase PostgreSQL / PG app data -> `./postgresql-development-cloudbase/SKILL.md` - WeChat Pay / Official Account OAuth through CloudBase Integration Center -> `./cloudbase-wechat-integration/SKILL.md` - Browser-side document database CRUD -> `./cloudbase-document-database-web-sdk/SKILL.md` - Browser-side file upload -> `./cloud-storage-web/SKILL.md` - Manage/operate underlying Tencent Cloud resources via cloud APIs (monitoring & alarms, CLB, CAM roles, cross-product infra) when no dedicated MCP tool exists -> `./cloud-api-operations/SKILL.md` - Platform overview only when capability selection is still unclear -> `./cloudbase-platform/SKILL.md` - MCP connection, local versus remote, or a fix to this open-source repo -> `./cloudbase-mcp/SKILL.md` - If using `searchKnowledgeBase(mode="skill")`, pass the reference directory id such as `postgresql-development-cloudbase` or `minimal-web-baas-demo`, not a guessed alias. ### High-yield guardrails - **Prepare backend resources before writing frontend code.** Prefer MCP for auth providers, database tables, storage domains, and security rules. If MCP tools are missing in this session, configure MCP for the next session and use `tcb` CLI now — do not stall waiting for restart. Frontend code written against non-existent resources will fail at runtime and require rework. - **Change Safety Protocol**: Before any non-trivial code or configuration change, you must strictly follow `cloudbase-platform/references/protocols/change-safety-protocol.md` (declare impact → obtain user confirmation → verify after change → escalate to root cause analysis after 3 occurrences of the same symptom). - **Deployment Gate**: Before any deployment, publish, custom domain, CloudRun, or public exposure work, you must complete the checks in `cloudbase-platform/references/protocols/deployment-gate.md` and present the mandatory declaration template. - If the same path fails 2-3 times, stop retrying and reroute. Check platform skill, auth domain, runtime, and permission model before editing more code. - Always specify `EnvId` explicitly in code, configuration, and command examples when initializing CloudBase clients or manager operations. Do not rely on the current CLI-selected environment or implicit defaults. - If the conversation only provides an environment alias, nickname, or other shorthand, resolve it with `queryEnv(action=list, alias=..., aliasExact=true)` and use the returned canonical full `EnvId` before calling `auth.set_env`, generating console links, or writing config/code. If the alias is ambiguous or missing, stop and ask the user to confirm. ### Do NOT use this as - A reason to read every CloudBase skill before touching code. - A reason to start from platform overview when the existing code already reveals the stack and the missing pieces. ## Working rules 1. **BaaS-first, functions as last resort**: - For 最小前后端 / Lovable-like demos, route first to `./minimal-web-baas-demo/SKILL.md`. Order: connector ready → template warmup during credential wait → `queryEnv` → lock one DB → MCP schema → `@cloudbase/js-sdk` CRUD → preview. Default cloud function count = 0. - Before writing any cloud function or CloudRun service, ask: can the correct JS SDK surface handle this directly? Use `db.collection(...).get()` only for confirmed NoSQL collections; use `app.rdb().from(...)` for CloudBase PG tables; use `auth` / `storage` from the matching skill. - Use the matching JS SDK surface directly for: data reads/writes, file uploads, real-time updates, simple queries including leaderboards, lists, aggregations. - Only drop down to cloud functions when: the logic requires server-side permission enforcement that cannot be expressed in database rules/RLS, calling third-party services (payment, SMS, external APIs), or background jobs not triggered by the user. - Only drop down to CloudRun when: persistent connections (WebSocket), long-running compute, or custom runtimes are genuinely required. 2. Existing application with TODOs: - Treat it as a targeted repair task, not a greenfield build. - Prefer the shortest path from current code to working flow. 3. Auth tasks: - Read `./auth-web-cloudbase/SKILL.md` before writing auth code — the full username/password recipe and provider readiness flow live there. - Blocking prerequisite for username-style accounts (`admin`, `editor`, any string without `@`): call `queryAppAuth(action="getLoginConfig")`; if `loginMethods.usernamePassword !== true`, enable it with `manageAppAuth(action="patchLoginStrategy", patch={ usernamePassword: true })` first. - Use `auth.signInWithPassword({ username, password })`; never `signUpWithEmailAndPassword` / `signInWithEmailAndPassword` for username-style flows. - Once readiness is confirmed, return to the active frontend handler and finish the real login/register flow. 4. Database and storage tasks: - Reuse the current shared `app`, `auth`, `db`, and storage helpers instead of creating parallel SDK wrappers. - If the task mentions CloudBase PG, PostgreSQL, Postgres, PG mode, JS SDK v3 PostgreSQL, `app.rdb()`, `queryPgDatabase`, `managePgDatabase`, `mysqldb` OpenAPI, or RLS, read `./postgresql-development-cloudbase/SKILL.md` before touching database code. - When the PG task defines an access pattern or investigates a slow query, also read `./postgresql-best-practices-cloudbase/SKILL.md`. - For CloudBase PG, use `queryPgDatabase` / `managePgDatabase` for schema and management. Do not route new relational work to MySQL `queryMysqlDatabase` / `manageMysqlDatabase` or to NoSQL collection APIs. MySQL tools are only for an environment that already has MySQL. - For OpenAPI lookup, call `searchKnowledgeBase({ mode: "openapi", apiName: "mysqldb" })` directly. Do not pass guessed `action` values such as `getApiDocs` or `listEndpoints`; those belong to no supported tool mode. - For CloudBase PG Web CRUD, prefer JS SDK v3 `app.rdb()` and documented storage `app.storage.from()` APIs before raw HTTP. - For browser-side CloudBase storage upload from local Vite/preview, check the actual browser `host:port` in security domains first (`queryEnv(action="domains")`, then `envDomainManagement(action="create")` if missing). A failed cover upload must not silently skip the subsequent PG article insert. - For CloudBase Web SDK `db.collection(...).add(...)`, persist the created document ID from `result._id`. - For writes, validate the actual SDK result instead of assuming success. - **Legacy API STOP card:** If the task says `PostgreSQL`, `CloudBase PG`, `PG mode`, `app.rdb()`, `queryPgDatabase`, `managePgDatabase`, `PostgREST`, or `RLS`, do not write NoSQL examples from memory. Use `app.rdb().from(...)` for Web CRUD, `queryPgDatabase` / `managePgDatabase` for management, and `auth.getSession()` for Web auth guards. Do not use `app.database()`, `db.collection(...)`, `.where()`, `.orderBy()`, `app.uploadFile()`, `getLoginState()`, or `auth.getUser()` as the PG/auth default. 5. Targeted repair tasks: - Functional closure beats exploration. - Avoid broad repo sweeps, UI redesign, and detached demo code. - Keep file discovery narrow. Prefer direct reads of the known active files over `Glob` / broad search across the whole project. ## Open source The MCP server, skills, and CLI live in one public repo: - https://github.com/TencentCloudBase/CloudBase-AI-ToolKit - https://cnb.cool/tencent/cloud/cloudbase/CloudBase-AI-ToolKit A bug in those surfaces should be a pull request. Connection steps and `CONTRIBUTING.md` are in `./cloudbase-mcp/SKILL.md`. A cloud platform, permission, or account problem should be an issue, and the text must not include an environment ID or a secret. Pull requests are how fixes land in the project.