@scemoon/cdh 1.0.8 → 1.0.9-beta.2

package/ai-dlc-skill/providers/tcb/integration/mcp-server.md

@@ -0,0 +1,371 @@
+# TCB MCP Server Integration
+
+## What is MCP
+
+MCP (Model Context Protocol) provides structured, type-safe tool access for AI agents. Instead of parsing CLI output, agents use typed tools with documented parameters.
+
+## MCP Server: @cloudbase/cloudbase-mcp
+
+The official TCB MCP server provides tools for:
+- Deploying functions
+- Invoking functions
+- Querying databases
+- Managing storage
+- Deploying hosting
+- Getting environment info
+
+## When to Use MCP vs CLI
+
+| Scenario | Use |
+|----------|-----|
+| AI agent executing cloud operations | MCP (structured, composable) |
+| One-off admin task | CLI |
+| CI/CD pipeline | CLI (or MCP with token) |
+| Scripted automation | CLI |
+| Debugging | CLI (more detailed output) |
+
+## Connection Methods
+
+### Auto-Configuration via CDH (Recommended)
+
+```bash
+cdh cloudbase init --secret-id xxx --secret-key xxx --env-id xxx
+```
+
+This writes the opencode-style entry to `~/.onecode/mcp.json` (with `{env:VAR}` templates that resolve at connect time) and stores the credentials in `~/.cloud-harness-tokens.json`.
+
+The resulting `mcp.json` entry:
+
+```json
+{
+  "mcp": {
+    "cloudbase": {
+      "type": "local",
+      "command": ["npx", "-y", "@cloudbase/cloudbase-mcp@latest"],
+      "environment": {
+        "TENCENTCLOUD_SECRETID": "{env:TENCENTCLOUD_SECRETID}",
+        "TENCENTCLOUD_SECRETKEY": "{env:TENCENTCLOUD_SECRETKEY}",
+        "CLOUDBASE_ENV_ID": "{env:CLOUDBASE_ENV_ID}"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+### stdio (Manual)
+
+```bash
+cdh mcp add cloudbase --type stdio \
+  --command npx,-y,@cloudbase/cloudbase-mcp@latest \
+  --env TENCENTCLOUD_SECRETID={env:TENCENTCLOUD_SECRETID},TENCENTCLOUD_SECRETKEY={env:TENCENTCLOUD_SECRETKEY}
+```
+
+### HTTP (For remote servers)
+
+```bash
+cdh mcp add cloudbase --type http \
+  --url "https://tcb-api.cloud.tencent.com/mcp/v1?env_id=xxx" \
+  --headers "X-TencentCloud-SecretId={env:TENCENTCLOUD_SECRETID}"
+```
+
+### Diagnostic / OAuth
+
+```bash
+cdh cloudbase status          # live probe + tool count
+cdh mcp debug cloudbase       # full config dump + live probe
+cdh mcp migrate               # one-shot: mcps.yaml -> mcp.json (legacy)
+cdh mcp auth <name>           # OAuth flow (for future remote servers)
+cdh mcp logout <name>         # clear stored OAuth token
+```
+
+## MCP Tools Reference
+
+### Functions
+
+#### deploy_function
+
+Deploy a cloud function.
+
+```javascript
+MCPTool(server="cloudbase", tool="deploy_function", arguments={
+  name: "hello",
+  dir: "./functions/hello",
+  envId: "env-xxxxx",
+  options: {
+    timeout: 60,
+    memory: 256,
+    httpFn: true
+  }
+})
+```
+
+#### invoke_function
+
+Invoke a function and get result.
+
+```javascript
+MCPTool(server="cloudbase", tool="invoke_function", arguments={
+  name: "hello",
+  params: { userId: "123" },
+  envId: "env-xxxxx"
+})
+```
+
+#### list_functions
+
+List all functions in environment.
+
+```javascript
+MCPTool(server="cloudbase", tool="list_functions", arguments={
+  envId: "env-xxxxx"
+})
+```
+
+#### get_function_logs
+
+Get function execution logs.
+
+```javascript
+MCPTool(server="cloudbase", tool="get_function_logs", arguments={
+  name: "hello",
+  envId: "env-xxxxx",
+  limit: 50
+})
+```
+
+### Database
+
+#### query_database
+
+Query DocDB with Mongoose-like syntax.
+
+```javascript
+MCPTool(server="cloudbase", tool="query_database", arguments={
+  query: "SELECT * FROM users WHERE status = 'active'",
+  envId: "env-xxxxx"
+})
+```
+
+#### insert_document
+
+Insert a document into collection.
+
+```javascript
+MCPTool(server="cloudbase", tool="insert_document", arguments={
+  collection: "users",
+  data: { name: "Alice", email: "alice@example.com" },
+  envId: "env-xxxxx"
+})
+```
+
+#### update_document
+
+Update a document.
+
+```javascript
+MCPTool(server="cloudbase", tool="update_document", arguments={
+  collection: "users",
+  query: { _id: "doc-id" },
+  update: { $set: { status: "inactive" } },
+  envId: "env-xxxxx"
+})
+```
+
+#### delete_document
+
+Delete a document.
+
+```javascript
+MCPTool(server="cloudbase", tool="delete_document", arguments={
+  collection: "users",
+  query: { _id: "doc-id" },
+  envId: "env-xxxxx"
+})
+```
+
+### Storage
+
+#### upload_file
+
+Upload a file to COS.
+
+```javascript
+MCPTool(server="cloudbase", tool="upload_file", arguments={
+  localPath: "./avatar.jpg",
+  cloudPath: "/uploads/avatar.jpg",
+  envId: "env-xxxxx"
+})
+```
+
+#### download_file
+
+Download a file from COS.
+
+```javascript
+MCPTool(server="cloudbase", tool="download_file", arguments={
+  cloudPath: "/uploads/avatar.jpg",
+  localPath: "./downloads/avatar.jpg",
+  envId: "env-xxxxx"
+})
+```
+
+#### list_storage
+
+List files in storage path.
+
+```javascript
+MCPTool(server="cloudbase", tool="list_storage", arguments={
+  path: "/uploads",
+  envId: "env-xxxxx"
+})
+```
+
+#### get_file_url
+
+Get temporary URL for file access.
+
+```javascript
+MCPTool(server="cloudbase", tool="get_file_url", arguments={
+  cloudPath: "/uploads/private.pdf",
+  envId: "env-xxxxx",
+  maxAge: 3600
+})
+```
+
+### Hosting
+
+#### deploy_hosting
+
+Deploy static site.
+
+```javascript
+MCPTool(server="cloudbase", tool="deploy_hosting", arguments={
+  dir: "./dist",
+  envId: "env-xxxxx",
+  buildEnv: { BACKEND_URL: "https://api.example.com" }
+})
+```
+
+### Environment
+
+#### get_environment_info
+
+Get environment details.
+
+```javascript
+MCPTool(server="cloudbase", tool="get_environment_info", arguments={
+  envId: "env-xxxxx"
+})
+```
+
+#### list_environments
+
+List all environments.
+
+```javascript
+MCPTool(server="cloudbase", tool="list_environments", arguments={})
+```
+
+## MCP Resources
+
+### list_resources
+
+List available TCB resources.
+
+```javascript
+MCPResources(server="cloudbase", action="list")
+```
+
+Returns: Functions, collections, storage paths, environment info.
+
+### resource template
+
+```
+cloudbase://{envId}/function/{functionName}
+cloudbase://{envId}/collection/{collectionName}
+cloudbase://{envId}/storage/{path}
+```
+
+## Agent Workflows
+
+### Workflow: Deploy and Test Function
+
+```javascript
+// 1. Deploy function
+const deployResult = await MCPTool(server="cloudbase", tool="deploy_function", arguments={
+  name: "hello",
+  dir: "./functions/hello",
+  envId: "env-xxxxx"
+});
+
+// 2. Invoke function
+const invokeResult = await MCPTool(server="cloudbase", tool="invoke_function", arguments={
+  name: "hello",
+  params: { test: true },
+  envId: "env-xxxxx"
+});
+
+// 3. Check logs if error
+if (invokeResult.error) {
+  const logs = await MCPTool(server="cloudbase", tool="get_function_logs", arguments={
+    name: "hello",
+    envId: "env-xxxxx"
+  });
+}
+```
+
+### Workflow: Query and Update Data
+
+```javascript
+// 1. Query users
+const users = await MCPTool(server="cloudbase", tool="query_database", arguments={
+  query: "SELECT * FROM users WHERE status = 'active' LIMIT 10",
+  envId: "env-xxxxx"
+});
+
+// 2. Update first user
+if (users.data.length > 0) {
+  await MCPTool(server="cloudbase", tool="update_document", arguments={
+    collection: "users",
+    query: { _id: users.data[0]._id },
+    update: { $set: { lastAccessed: new Date() } },
+    envId: "env-xxxxx"
+  });
+}
+```
+
+## Configuration
+
+### Manual Configuration
+
+Create `~/.cloudbase/mcp.json`:
+
+```json
+{
+  "envId": "env-xxxxx",
+  "credentials": {
+    "secretId": "your-secret-id",
+    "secretKey": "your-secret-key"
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `TENCENTCLOUD_SECRETID` | Tencent Cloud credential ID |
+| `TENCENTCLOUD_SECRETKEY` | Tencent Cloud credential key |
+| `TCB_ENV_ID` | Default environment ID |
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| MCP server not responding | Server not started | Restart MCP server |
+| `Invalid credentials` | Wrong secret ID/key | Verify credentials |
+| `Environment not found` | Wrong env ID | Check with `cdh cloudbase status` |
+| `Tool not found` | Wrong tool name | Check tool list in MCP server docs |
+
+For troubleshooting → `../best-practices/troubleshooting.md`

package/ai-dlc-skill/providers/tcb/preview.yaml

@@ -0,0 +1,83 @@
+# TCB Stack Preview
+
+Preview deployment for the unified stack (backend + all clients: web, native, desktop, wxa, mya, tta). URL resolution is dynamic per platform; `BACKEND_URL` is injected into client builds at build time.
+
+## Overview
+
+`deploy_stack --preview --provider tcb` deploys the full stack to an isolated preview environment and exports the stack URL. Used for per-component e2e AND cross-stack e2e verification before staging or production.
+
+## Preview Flow
+
+```
+git push feature branch
+  → deploy_stack --preview --provider tcb
+  → STACK_URL = BACKEND_URL = https://{env-id}.tcb-preview.com
+  → WEB_URL  = https://{env-id}-{project}.tcb-preview.com
+  → NATIVE_DIST_URL = internal distribution URL
+  → DESKTOP_DIST_URL = internal distribution URL
+  → WXA_URL / MYA_URL / TTA_URL = mini-program preview QR
+  → Per-component e2e: pytest apps/{comp}/tests/e2e/ --base-url $URL
+  → Cross-stack e2e:  pytest aidlc/tests/cross-stack/ --stack-url $STACK_URL
+  → TTL: 24h → auto cleanup
+```
+
+## Configuration
+
+```yaml
+preview:
+  orchestrator: deploy_stack
+  strategy: unified
+  ttl: 24h
+  auto_cleanup: true
+  db_sandbox: true          # isolated database per preview
+  url_pattern: "https://{env-id}.tcb-preview.com"
+  build_env:
+    web:
+      - BACKEND_URL
+      - STACK_URL
+    native:
+      - BACKEND_URL
+    desktop:
+      - BACKEND_URL
+    wxa:
+      - BACKEND_URL
+    mya:
+      - BACKEND_URL
+    tta:
+      - BACKEND_URL
+  env:
+    - STACK_URL             # = BACKEND_URL (gateway)
+    - BACKEND_URL
+    - WEB_URL
+    - NATIVE_DIST_URL
+    - DESKTOP_DIST_URL
+    - WXA_URL
+    - MYA_URL
+    - TTA_URL
+    - DATABASE_URL (sandbox)
+```
+
+## BDD E2E Integration
+
+```bash
+# Deploy unified stack preview
+export STACK_URL=$(deploy_stack --preview --provider tcb --output url)
+export BACKEND_URL=$STACK_URL
+export WEB_URL=$(deploy_stack --preview --provider tcb --output web_url)
+export NATIVE_DIST_URL=$(deploy_stack --preview --provider tcb --output native_url)
+export DESKTOP_DIST_URL=$(deploy_stack --preview --provider tcb --output desktop_url)
+
+# Per-component e2e
+pytest apps/backend/tests/e2e/ --base-url $BACKEND_URL
+pytest apps/web/tests/e2e/ --base-url $WEB_URL --api-url $BACKEND_URL
+pytest apps/native/tests/e2e/ --backend-url $BACKEND_URL
+pytest apps/desktop/tests/e2e/ --backend-url $BACKEND_URL
+pytest apps/wxa/tests/e2e/ --backend-url $BACKEND_URL
+pytest apps/mya/tests/e2e/ --backend-url $BACKEND_URL
+pytest apps/tta/tests/e2e/ --backend-url $BACKEND_URL
+
+# Cross-stack e2e
+pytest aidlc/tests/cross-stack/ --stack-url $STACK_URL
+
+# Cleanup (automatic after TTL)
+```

package/ai-dlc-skill/providers/tcb/provider.yaml

@@ -0,0 +1,172 @@
+# TCB Provider (Stack-aware)
+
+Default cloud development platform. Supports the unified stack deploy (backend + all clients: web, native, desktop, wxa, mya, tta) and per-component deploys (for isolated dev sandboxes only).
+
+## Metadata
+
+```yaml
+provider:
+  name: tcb
+  display_name: Tencent CloudBase
+  default: true
+  version: 3.0.0
+  website: https://cloud.tencent.com/product/tcb
+
+stack:
+  components:
+    - id: backend
+      deploy_order: 1
+      exposes: BACKEND_URL
+    - id: web
+      deploy_order: 2
+      consumes: BACKEND_URL
+    - id: native
+      deploy_order: 2
+      consumes: BACKEND_URL
+    - id: desktop
+      deploy_order: 2
+      consumes: BACKEND_URL
+    - id: wxa
+      deploy_order: 2
+      consumes: BACKEND_URL
+    - id: mya
+      deploy_order: 2
+      consumes: BACKEND_URL
+    - id: tta
+      deploy_order: 2
+      consumes: BACKEND_URL
+
+regions:
+  - id: ap-shanghai
+    name: Shanghai
+  - id: ap-beijing
+    name: Beijing
+  - id: ap-guangzhou
+    name: Guangzhou
+  - id: ap-singapore
+    name: Singapore
+
+services:
+  - functions: cloudbase
+  - database: cloudbase
+  - storage: cloudbase
+  - hosting: cloudbase
+
+limits:
+  function_timeout: 60s
+  function_memory: 1536MB
+  max_instances: 100
+
+compute_modes:
+  - id: cloudbase-functions
+    type: faas
+    default: true
+    description: "CloudBase Functions (SCF) — event-driven functions"
+    limits:
+      timeout: 60s
+      memory: 1536MB
+      max_instances: 100
+  - id: cloudbase-run
+    type: caas
+    description: "CloudBase Run — container hosting"
+    limits:
+      timeout: 3600s
+      memory: 4096MB
+
+capabilities:
+  - serverless_functions
+  - static_hosting
+  - serverless_database
+  - serverless_storage
+  - preview_deploy
+  - ssl_cert
+  - custom_domain
+  - cdn_acceleration
+  - stack_deploy
+  - build_env_injection
+  - container_hosting
+
+storage:
+  object_storage: cloudbase-storage
+  document_db: docdb
+  relational_db: mysql
+  cdn: tencent-cloud-cdn
+```
+
+## Stack Deploy (recommended for shared environments)
+
+```bash
+# Unified stack preview (returns STACK_URL = BACKEND_URL + per-component URLs)
+deploy_stack --preview --provider tcb
+# → backend:  tcb fn deploy --env preview
+# → backend:  tcb db migrate --env preview
+# → web:      tcb hosting deploy --env preview --build-env BACKEND_URL=${STACK_URL}
+# → native:   build with BACKEND_URL injected; upload to internal distribution
+# → desktop:  build with BACKEND_URL injected; upload to internal distribution
+# → wxa:      build with BACKEND_URL injected; upload to mini-program platform
+# → mya:      build with BACKEND_URL injected; upload to mini-program platform
+# → tta:      build with BACKEND_URL injected; upload to mini-program platform
+# → STACK_URL = https://{env-id}.tcb-preview.com
+
+# Stack staging
+deploy_stack --env staging --provider tcb
+
+# Stack production (after human approval)
+deploy_stack --env production --provider tcb
+
+# Stack rollback
+deploy_stack --rollback ${LAST_STABLE_STACK_VERSION} --provider tcb
+```
+
+## Per-Component Deploy (dev sandboxes only)
+
+For isolated dev work on a single component, per-component deploy is allowed into a personal sandbox env.
+
+```bash
+# Functions
+tcb fn deploy --name hello --dir ./functions
+tcb fn invoke --name hello --params '{}'
+tcb fn logs --name hello
+
+# Database
+tcb db query "SELECT * FROM users"
+tcb db migrate
+
+# Hosting (web only)
+tcb hosting deploy --env dev-<user>
+
+# Environment
+tcb env list
+tcb env use <env-id>
+```
+
+> Per-component deploys to shared environments (preview, staging, production) are forbidden (STK-004). Use `deploy_stack`.
+
+## URL Resolution
+
+| Component | Pattern |
+|-----------|---------|
+| `STACK_URL` / `BACKEND_URL` | `https://{env-id}.tcb-preview.com` |
+| `WEB_URL` | `https://{env-id}-{project}.tcb-preview.com` |
+| `NATIVE_DIST_URL` | internal distribution URL |
+| `DESKTOP_DIST_URL` | internal distribution URL |
+| `WXA_URL` | mini-program preview QR |
+| `MYA_URL` | mini-program preview QR |
+| `TTA_URL` | mini-program preview QR |
+
+## Build Config Injection
+
+```bash
+tcb hosting deploy --env preview --build-env BACKEND_URL=$STACK_URL
+# web reads process.env.BACKEND_URL at build time
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| TCB_SECRET_ID | Tencent Cloud secret ID |
+| TCB_SECRET_KEY | Tencent Cloud secret key |
+| TCB_ENV_ID | CloudBase environment ID |
+| BACKEND_URL | Stack URL injected at build time |
+| STACK_URL | Alias of BACKEND_URL (gateway) |