Upstash 技能集 upstash/skills

Upstash Agent Skills

把 AI 编程智能体接到 Upstash。这个仓库提供 技能（按 SDK 拆分的指令包，智能体按需加载）和 插件清单，把技能装进 Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Zed 以及任何兼容 Agent Skills 的客户端——现在还带上了 Upstash MCP 服务器。

Upstash 智能体能力面

- 技能 — 每个 Upstash SDK（Redis、QStash、Workflow、Vector、Search、Box、Blob、Ratelimit）都配了打包好的指令和命令行参考。不需要凭证。→ 文档
- MCP 服务器 — 提供实时工具，用来查询、调试和管理你的账号。两种运行方式：
- 远程（托管） — https://mcp.upstash.com/mcp，streamable HTTP，用 OAuth 认证（首次使用时在浏览器里授权），也可以用开发者 API key 请求头认证。无需安装任何东西。
- 本地（stdio） — 用 npx 运行 @upstash/mcp-server，用账号邮箱 + 开发者 API key 认证。

→ 文档
- 第一次来？先看 AI 工具概览，各客户端的完整安装步骤见 按智能体安装。

仓库内容

- skills/upstash-*/ — 按 SDK 拆分的技能源文件（每个都有 SKILL.md）。改这里。
- skills/upstash/ — 合并后的技能，由 npm run build 从所有源文件生成。不要手动改（见 AGENTS.md）。
- 插件清单 — .claude-plugin/、.codex-plugin/、.cursor-plugin/、gemini-extension.json，以及可移植的 Agent Plugins plugin.json + mcp.json。有了它们，仓库就能作为插件/扩展安装。这些插件现在打包了远程 Upstash MCP 服务器（OAuth），所以装插件一步就同时配好技能和 MCP —— Claude Code、Codex、Cursor、Gemini CLI 都不用再单独配 MCP。
- zed-extension/ — Zed 的 MCP 服务器扩展（Rust → Wasm）。
- assets/ — 插件卡片用的品牌素材，Codex（interface.logo / interface.composerIcon）和 Cursor（logo）会读取。Claude Code、Gemini CLI 和 Agent Plugins schema 没有图标字段。

可用技能

| 技能 | 说明 |
| upstash | 合并技能，覆盖所有 Upstash SDK 和命令行。 |
| upstash-blob-js | S3 兼容的对象存储，支持浏览器直传和签名 URL。 |
| upstash-box-cli | 用 box 命令行从终端操作沙箱云容器。 |
| upstash-box-js | 沙箱云容器，带 AI 智能体、shell、文件系统和 git。 |
| upstash-box-py | 同样的沙箱云容器，走 Python SDK。 |
| upstash-box-remote-work | 通过远程 MCP 在沙箱化的云端 Box 里干活，支持预览 URL、截图和 PR。 |
| upstash-cli | 在终端里用 upstash 命令行调用 Upstash Developer API。 |
| upstash-qstash-js | 通过 HTTP 端点实现无服务器消息传递与定时调度。 |
| upstash-ratelimit-js | 用 Redis Rate Limit TypeScript SDK 做限流。 |
| upstash-redis-js | 无服务器 Redis——缓存、会话、排行榜、全文搜索。 |
| upstash-redis-start | 为智能体开一个零配置、免注册的临时 Redis 数据库。 |
| upstash-search-js | 全文搜索快速上手、核心概念与 TypeScript SDK。 |
| upstash-vector-js | 向量数据库功能、SDK 用法与框架集成。 |
| upstash-workflow-js | 持久化工作流——定义、触发并管理多步流程。 |

安装

通过插件安装（Claude Code、Codex、Cursor、Gemini CLI）会同时装好技能和远程 MCP 服务器——首次使用时批准 MCP 的 OAuth 授权即可。仅装技能的安装方式（Agent Skills CLI、OpenCode、Zed）只装技能；想要实时访问账户，就另外加上 MCP 服务器，或者用 npx upstash，它会两样都装好。

各客户端最新、最全的安装说明见 Install by agent。

一条命令搞定（Claude Code、Codex、Cursor、Gemini CLI、VS Code、Copilot CLI、OpenCode）

npx upstash

在终端里运行，Upstash CLI 会检测你装了哪些智能体，并在支持插件的智能体上装插件（Claude Code、Codex、Cursor、Gemini CLI），其余情况则装远程 MCP 服务器加 upstash 技能（VS Code、Copilot CLI、OpenCode）。不管哪种方式，智能体都能拿到技能和 MCP 服务器，首次使用时通过 OAuth 登录。下面按智能体分列的步骤，就是手动做同样的事。

在智能体或脚本里运行时，指定智能体并跳过交互提示：

npx -y upstash setup --yes --claude # or --codex, --cursor, --gemini, --vscode, --copilot, --opencode
npx -y upstash setup --yes --mode mcp # MCP server + skill everywhere, no plugins

Claude Code（技能 + MCP）

Add the marketplace
/plugin marketplace add upstash/skills

Install the plugin
/plugin install upstash@upstash

OpenAI Codex（技能 + MCP）

Add the marketplace
codex plugin marketplace add upstash/skills

Install the plugin
codex plugin add upstash@upstash

Cursor（技能 + MCP）

我们正在等这个插件通过官方审核 Cursor Marketplace。上架之后，你可以在 Cursor 侧边栏的 Customize 里安装，技能和 MCP 服务器会一起装好。在那之前，用 npx upstash setup --cursor 可以把同一个插件装到本地（装完重载 Cursor 窗口）。

Gemini CLI（技能 + MCP）

Gemini CLI 把这个仓库当作扩展加载 —— 清单文件是仓库根目录的 gemini-extension.json；skills/ 下的每个技能和远程 MCP 服务器都会自动识别：

gemini extensions install https://github.com/upstash/skills

OpenCode

OpenCode 从项目里的 .agents/skills/ 和全局的 ~/.config/opencode/skills/ 加载 Agent Skills，Agent Skills 命令行正是把技能写到这两个位置给 OpenCode 用：

Available in every project
npx skills add upstash/skills --agent opencode --global

Or just this project
npx skills add upstash/skills --agent opencode

OpenCode 通过原生 skill 工具把已安装的技能暴露给智能体，所以智能体只加载当前任务相关的子技能。想实时访问你的账号（创建数据库、查看 QStash 日志等），再添加 MCP 服务器，或者运行 npx upstash setup --opencode，一步装好技能并添加 MCP 服务器。

Zed

Zed 从项目里的 .agents/skills/ 和全局的 ~/.agents/skills/ 加载 Agent Skills，Agent Skills 命令行正是把技能写到这两个位置：

Available in every project
npx skills add upstash/skills --agent zed --global

Or just this project
npx skills add upstash/skills --agent zed

装好后技能会出现在 Zed 的 Agent Panel 里，智能体可以自行加载，也可以用 /upstash 加载。Zed 的扩展市场只收语言、主题、调试器、代码片段和 MCP 服务器，没有技能的上架渠道，所以命令行是安装技能的唯一方式。zed-extension/ 里的 Zed 扩展负责的是 MCP 服务器。

Agent Skills 命令行

npx skills add upstash/skills

DeepSeek Harness

一步装好技能和 Upstash MCP 服务器。需要 PATH 里有 pnpm。

Install into a profile (web is the one dsh web boots)
dsh plugin --profile web add github:upstash/skills

Start the harness
dsh web

然后在会话里保存 Upstash 凭据：

/upstash-login YOUR_EMAIL YOUR_API_KEY

凭据保存在 ~/.dsh/.credentials.yaml，两项都设置好后 MCP 服务器就会连接。不设凭据技能也能用。

MCP 服务器

安装上面的插件时已经顺带接好了远程 MCP 服务器。如果你用的是只装技能的安装器（OpenCode、Zed），或者客户端不支持插件，就单独配置它。

远程（推荐） —— 无需安装；首次使用时走 OAuth，或者传开发者 API key 请求头（email:API_KEY）用于无头/CI 场景。在 Console → Account → API Keys 创建密钥。

Claude Code

OAuth (browser consent on first /mcp use)
claude mcp add --transport http upstash https://mcp.upstash.com/mcp

Or a developer API key, no browser
claude mcp add --transport http upstash https://mcp.upstash.com/mcp \
--header "Authorization: Bearer you@example.com:YOUR_API_KEY"

Cursor

添加到 ~/.cursor/mcp.json（走 API key 方式时，加上带 Authorization 行的 headers）：

{
"mcpServers": {
"upstash": { "url": "https://mcp.upstash.com/mcp" }
}
}

OpenCode

添加到 opencode.json，或添加到 ~/.config/opencode/opencode.json 让它在所有地方可用。
参见 OpenCode MCP 文档。

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"upstash": {
"type": "remote",
"url": "https://mcp.upstash.com/mcp",
"enabled": true
}
}
}

在 URL 后追加 ?features=，即可限定智能体能看到哪些产品工具——用逗号分隔，可选值为 redis、qstash_workflow、vector、search、box、blob（省略表示全部），例如 https://mcp.upstash.com/mcp?features=redis,qstash_workflow。

本地（stdio） —— 自己运行 @upstash/mcp-server，用你的邮箱 + API key 认证。支持只读密钥（此时服务器会禁用所有会改变状态的工具）。

Claude Code

claude mcp add upstash -- npx -y @upstash/mcp-server@latest --email YOUR_EMAIL --api-key YOUR_API_KEY

Cursor

添加到 .cursor/mcp.json：

{
"mcpServers": {
"upstash": {
"command": "npx",
"args": ["-y", "@upstash/mcp-server@latest", "--email", "YOUR_EMAIL", "--api-key", "YOUR_API_KEY"]
}
}
}

OpenCode

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"upstash": {
"type": "local",
"command": ["npx", "-y", "@upstash/mcp-server@latest", "--email", "YOUR_EMAIL", "--api-key", "YOUR_API_KEY"],
"enabled": true
}
}
}

Zed

本仓库在 zed-extension/ 里附带了一个 Zed MCP 扩展。等它被 Zed 扩展注册表收录后，从 Settings → AI → MCP Servers → Add Server → Install from Extensions 安装 Upstash Redis MCP Server，Zed 会提示你填写 upstash_email 和 upstash_api_key。
在那之前，可以按开发扩展安装（zed: install dev extension，然后选择 zed-extension/ 目录）。

想完全跳过扩展，也可以手动把服务器加到 Zed 设置里（zed: open settings file）：

{json
"context_servers": {
"upstash": {
"command": "npx",
"args": ["-y", "@upstash/mcp-server@latest", "--email", "YOUR_EMAIL", "--api-key", "YOUR_API_KEY"]
}
}
}

修改内容

更新已有技能

1. 编辑对应技能文件夹里的文件（例如 skills/upstash-qstash-js/）。
2. 运行 npm run build，重新生成 skills/upstash/。
3. 把源文件改动和重新生成的产物一起提交。

新增技能

1. 在 skills/ 下新建文件夹（例如 skills/upstash-redis-js/）。
2. 添加 SKILL.md，写上标准 frontmatter（name 和 description），再放入需要的辅助文件。
3. 运行 npm run build —— 新技能会自动被识别。
4. 提交全部内容。

修改合并技能的头部

skills/upstash/SKILL.md 的 frontmatter 和开头说明文字来自 scripts/header.md。编辑该文件，然后运行 npm run build。

更新插件版本

发版时，把每个带 version 字段的清单文件都改一遍：plugin.json（可移植的 Agent Plugins 清单）、.claude-plugin/plugin.json、.cursor-plugin/plugin.json、.codex-plugin/plugin.json 和 gemini-extension.json。

Zed 扩展

zed-extension/ 是 Zed 的 MCP 服务器扩展，用来运行 @upstash/mcp-server。它是一个编译成 WebAssembly 的 Rust crate，只负责 MCP 服务器 —— Zed 扩展无法携带技能。
bash
cd zed-extension
rustup target add wasm32-wasip2 # once
cargo build --release --target wasm32-wasip2

用 zed: install dev extension 测试本地构建，把 Zed 指向 zed-extension/。测试时要在 Zed 里打开一个文件夹 —— context server 的作用域是项目，所以没打开项目（或者项目的工作区打不开）时，服务器根本不会启动，面板会一直停在「Connecting Server...」，直到 Zed 的 60 秒超时。

要发布或更新它，请向 zed-industries/extensions 提 PR：把本仓库作为子模块加到 extensions/mcp-server-upstash 下，并在 extensions.toml 里加一条记录： toml [mcp-server-upstash]
submodule = "extensions/mcp-server-upstash"
path = "zed-extension"
version = "0.1.0"

这里的 version 必须和 zed-extension/extension.toml 里的 version 一致，所以两处要一起改。zed-extension/LICENSE 是指向仓库 MIT 协议的符号链接 —— Zed 要求扩展路径下有协议文件，光在仓库根目录放不够，缺了 CI 会直接拒掉 PR。

Zed 计划弃用 MCP 服务器扩展，改用官方 MCP 注册表。如果这事落地，把 @upstash/mcp-server 发布到 registry.modelcontextprotocol.io 就能取代这个扩展。

脚本

| 脚本 | 命令 | 说明 |
| build | npm run build | 从各个独立技能重新生成 skills/upstash/。 |
| check | npm run check | 先执行构建，如果出现 git diff 就报错失败——CI 用它确保生成结果已提交。 |

CI

GitHub Actions 工作流（.github/workflows/check.yml）在每次 push 和 PR 时运行 npm run check。如果推送前忘了运行 npm run build，CI 就会失败。