TurboSteed MCP

TurboSteed CLI

从终端或 CI/CD 工作流部署和管理 TurboSteed 站点。

功能

• 使用单条命令部署站点
• 管理资源（上传、列出、删除）
• 获取联系表单提交内容
• 管理 CMS 架构和条目
• 进度指示器和格式化输出
• 支持 GitHub Actions、GitLab CI 和 Bitbucket Pipelines
• MCP 服务，用于集成 Claude Code / Claude Desktop

要求

• Node.js 18.0.0 或更高版本
• TurboSteed 账户（注册）

安装

全局安装（推荐）

npm install -g @turbosteed/cli

验证安装：

turbosteed --version

本地安装（每个项目单独安装）

npm install --save-dev @turbosteed/cli

通过 npx 运行：

npx turbosteed deploy

或者添加到 package.json 脚本中：

{
  "scripts": {
    "deploy": "turbosteed deploy --source ./dist"
  }
}

配置

第 1 步：获取凭据

1. 登录 TurboSteed Dashboard
2. 前往 Settings > API Keys
3. 复制你的 Account SID 和 API Key
4. 前往你的站点并复制 Site ID

第 2 步：设置环境变量

export TURBOSTEED_ACCOUNT_SID="your-account-sid"
export TURBOSTEED_API_KEY="your-api-key"
export TURBOSTEED_SITE_ID="your-site-id"

如需永久设置，请将这些变量添加到 shell 配置文件（~/.bashrc、~/.zshrc 等）中。

第 3 步（可选）：创建配置文件

在项目根目录中创建 turbosteed.json：

{
  "version": "1",
  "site": {
    "id": "your-site-id",
    "accountSid": "your-account-sid"
  },
  "deploy": {
    "source": "./dist",
    "exclude": ["**/*.map", ".DS_Store"]
  }
}

**注意：**不要将 API 密钥放入配置文件。请始终使用环境变量存储机密。

环境变量参考

变量	必需	说明
TURBOSTEED_ACCOUNT_SID	是	你的账户标识符
TURBOSTEED_API_KEY	是	你的 API 密钥（请保密）
TURBOSTEED_SITE_ID	是*	站点 ID（*可放在配置文件中）
TURBOSTEED_API_BASE	否	API 基础 URL（默认为生产环境）

用法

部署站点

# Deploy from ./dist (default)
turbosteed deploy

# Deploy from a specific directory
turbosteed deploy --source ./build

# Preview what would be deployed
turbosteed deploy --dry-run

# Output result as JSON
turbosteed deploy --json

要求：

• 源目录必须包含 index.html 文件
• zip 文件最大体积：25 MB

管理资源

# Upload a file
turbosteed assets upload ./images/logo.png

# List first page of assets
turbosteed assets list

# List ALL assets (automatic pagination)
turbosteed assets list --all

# Manual pagination (next page)
turbosteed assets list --page <token>

# Delete an asset
turbosteed assets delete logo.png

联系表单

# List first page of submissions
turbosteed forms list

# List ALL submissions (automatic pagination)
turbosteed forms list --all

# Manual pagination (next page)
turbosteed forms list --page <formId>

# Get a specific submission
turbosteed forms get <formId>

CMS 内容

# List first page of schemas
turbosteed cms schema list

# List ALL schemas (automatic pagination)
turbosteed cms schema list --all

# Create a schema from JSON file
turbosteed cms schema create ./blog-schema.json

# List first page of entries in a schema
turbosteed cms entry list <schemaId>

# List ALL entries (automatic pagination)
turbosteed cms entry list <schemaId> --all

# Create an entry
turbosteed cms entry create <schemaId> ./post.json

# Publish an entry
turbosteed cms entry publish <schemaId> <entryId>

架构文件示例（blog-schema.json）：

{
  "display_name": "Blog Posts",
  "schema_mode": "custom",
  "fields": [
    { "name": "title", "type": "text", "required": true, "max_length": 200 },
    { "name": "slug", "type": "slug", "source_field": "title", "required": true },
    { "name": "body", "type": "richtext", "required": true },
    { "name": "published_date", "type": "date", "required": false }
  ]
}

条目文件示例（post.json）：

{
  "title": "My First Post",
  "slug": "my-first-post",
  "body": "# Hello World\n\nThis is my first blog post.",
  "published_date": "2026-07-01"
}

CI/CD 集成

GitHub Actions

创建 .github/workflows/deploy.yml：

name: Deploy to TurboSteed

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install and Build
        run: npm ci && npm run build

      - name: Deploy to TurboSteed
        env:
          TURBOSTEED_ACCOUNT_SID: ${{ secrets.TURBOSTEED_ACCOUNT_SID }}
          TURBOSTEED_API_KEY: ${{ secrets.TURBOSTEED_API_KEY }}
          TURBOSTEED_SITE_ID: ${{ secrets.TURBOSTEED_SITE_ID }}
        run: npx @turbosteed/cli deploy --source ./dist

GitLab CI

创建 .gitlab-ci.yml：

stages:
  - build
  - deploy

build:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

deploy:
  stage: deploy
  image: node:20
  dependencies:
    - build
  script:
    - npx @turbosteed/cli deploy --source ./dist
  only:
    - main

Bitbucket Pipelines

创建 bitbucket-pipelines.yml：

image: node:20

pipelines:
  branches:
    main:
      - step:
          name: Build
          caches:
            - node
          script:
            - npm ci
            - npm run build
          artifacts:
            - dist/**

      - step:
          name: Deploy to TurboSteed
          deployment: production
          script:
            - npx @turbosteed/cli deploy --source ./dist

MCP 集成（Claude Code / Claude Desktop）

此 CLI 包含一个 MCP（Model Context Protocol）服务，允许 Claude 等 AI 助手以编程方式管理你的 TurboSteed 站点。

设置

添加到 Claude Desktop 配置文件（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "turbosteed": {
      "command": "npx",
      "args": ["@turbosteed/cli", "--mcp"],
      "env": {
        "TURBOSTEED_ACCOUNT_SID": "your-account-sid",
        "TURBOSTEED_API_KEY": "your-api-key",
        "TURBOSTEED_SITE_ID": "your-site-id",
        "TURBOSTEED_API_BASE": "https://api-us.turbosteed.com"
      }
    }
  }
}

对于 Claude Code，添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "turbosteed": {
      "command": "npx",
      "args": ["@turbosteed/cli", "--mcp"],
      "env": {
        "TURBOSTEED_ACCOUNT_SID": "your-account-sid",
        "TURBOSTEED_API_KEY": "your-api-key",
        "TURBOSTEED_SITE_ID": "your-site-id",
        "TURBOSTEED_API_BASE": "https://api-us.turbosteed.com"
      }
    }
  }
}

直接启动 MCP 服务

你也可以直接从命令行启动 MCP 服务：

turbosteed --mcp

或者通过 npx 运行：

npx @turbosteed/cli --mcp

MCP 环境变量

变量	必需	说明
TURBOSTEED_ACCOUNT_SID	是	账户标识符（例如，AC...）
TURBOSTEED_API_KEY	是	API 密钥（例如，sk_...）
TURBOSTEED_SITE_ID	是	站点标识符（例如，site_...）
TURBOSTEED_API_BASE	否	API 基础 URL（https://api-us.turbosteed.com）

工作原理

CLI 会运行一个本地 stdio MCP 服务，将所有请求代理到 TurboSteed 后端 MCP HTTP 端点 ${TURBOSTEED_API_BASE}/users/${accountSid}/sites/${siteId}/mcp。该服务通过 stdio 接收来自 Claude 的 MCP 协议消息，通过 HTTP 将消息转发到后端，并通过 stdio 返回响应。

可用工具

配置完成后，Claude 可以使用以下工具：

工具	描述
site.get	获取站点配置
site.update	更新站点设置
cms.schema.list	列出 CMS 架构
cms.schema.get	获取架构定义
cms.schema.create	创建新架构
cms.entry.list	列出架构中的条目
cms.entry.get	获取指定条目
cms.entry.create	创建新条目
cms.entry.update	更新条目
cms.entry.publish	发布条目
webhooks.list	列出 Webhook
webhooks.create	创建 Webhook
contacts.list	列出联系表单提交记录
contacts.get	获取指定提交记录
assets.list	列出所有资源
assets.delete	删除资源
deploy.getUploadUrl	获取预签名上传 URL
deploy.trigger	触发部署
apikeys.getSiteCredentials	获取用于 RAG/小组件的公开站点凭据

使用示例

向 Claude 提问：

• “列出我的所有 CMS 架构”
• “创建一篇标题为 ‘Hello World’ 的新博客文章”
• “显示我的站点配置”
• “我有哪些联系表单提交记录？”

退出代码

代码	含义
0	成功
1	一般错误
2	身份验证失败
3	未找到资源
4	上传/网络失败
5	输入无效
6	配置错误

替代方案：Shell 脚本（无需 Node.js）

对于未安装 Node.js 的环境，请使用 Shell 脚本：

curl -sSL https://raw.githubusercontent.com/turbosteed/shell-tools/main/scripts/deploy.sh | bash -s ./dist

参见 github.com/turbosteed/shell-tools

支持

• 文档
• 控制面板
• 电子邮件：[email protected]

许可证

本软件仅授权用于 TurboSteed 账户。完整条款请参见 LICENSE。