upstash/skills

Upstash Agent Skills

将你的 AI 编码代理连接到 Upstash。此仓库提供 skills（按 SDK 划分的指令包，你的代理按需加载）以及将它们安装到 Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Zed 以及任何兼容 Agent Skills 的客户端中的 plugin manifests——现在还包含 Upstash MCP server。

Upstash 代理界面

- Skills — 为每个 Upstash SDK（Redis、QStash、Workflow、Vector、Search、Box、Blob、Ratelimit）打包的指令和 CLI 参考。无需凭据。→ 文档
- MCP server — 用于查询、调试和管理你的账户的实时工具。有两种运行方式：
- 远程（托管） — https://mcp.upstash.com/mcp，可流式 HTTP，通过 OAuth（首次使用时浏览器授权）或开发者 API 密钥请求头进行身份验证。无需安装任何东西。
- 本地（stdio） — 使用 npx 运行 @upstash/mcp-server，通过你的账户邮箱 + 开发者 API 密钥进行身份验证。

→ 文档
- 初次使用？请从 AI 工具概览 开始，并查看 按代理安装 了解完整的各客户端设置。

此仓库包含的内容

- skills/upstash-/ — 按 SDK 划分的 skill 源文件（每个都有一个 SKILL.md）。编辑这些文件。
- skills/upstash/ — 合并后的 skill，由 npm run build 从所有源文件生成。切勿手动编辑它（参见 AGENTS.md）。
- Plugin manifests — .claude-plugin/、.codex-plugin/、.cursor-plugin/、gemini-extension.json，以及可移植的 Agent Plugins plugin.json + mcp.json。它们使此仓库可作为插件/扩展安装。这些插件现在捆绑了远程 Upstash MCP server（OAuth），因此安装插件即可一步完成 skills 和* MCP 的设置——无需为 Claude Code、Codex、Cursor 或 Gemini CLI 单独配置 MCP。
- zed-extension/ — 一个 Zed MCP server 扩展（Rust → Wasm）。
- assets/ — 插件卡片上使用的品牌素材，由 Codex（interface.logo / interface.composerIcon）和 Cursor（logo）读取。Claude Code、Gemini CLI 和 Agent Plugins schema 没有图标字段。

可用的 Skills

| Skill | 描述 |
|-------|-------------|
| upstash | 涵盖所有 Upstash SDK 和 CLI 的合并 skill。 |
| upstash-blob-js | 兼容 S3 的对象存储，支持直接从浏览器上传和签名 URL。 |
| upstash-box-cli | 使用 box CLI 从终端驱动沙箱化云容器。 |
| upstash-box-js | 带有 AI 代理、shell、文件系统和 git 的沙箱化云容器。 |
| upstash-box-py | 同样的沙箱化云容器，来自 Python SDK。 |
| upstash-box-remote-work | 通过远程 MCP 在沙盒化的云端 Box 中完成工作，支持预览 URL、截图和 PR。 |
| upstash-cli | 使用 upstash CLI 从终端驱动 Upstash Developer API。 |
| upstash-qstash-js | 通过 HTTP 端点实现无服务器消息传递和调度。 |
| upstash-ratelimit-js | 使用 Redis Rate Limit TypeScript SDK 进行速率限制。 |
| upstash-redis-js | 无服务器 Redis——缓存、会话、排行榜、全文搜索。 |
| upstash-redis-start | 为 agent 配置一个零配置、无需注册的临时 Redis 数据库。 |
| upstash-search-js | 全文搜索快速入门、核心概念和 TypeScript SDK。 |
| upstash-vector-js | 向量数据库功能、SDK 用法和框架集成。 |
| upstash-workflow-js | 持久化工作流——定义、触发和管理多步骤流程。 |

安装

通过 plugin（Claude Code、Codex、Cursor、Gemini CLI）安装会同时设置 skills 和远程 MCP 服务器——首次使用时批准 MCP 的 OAuth 授权同意。仅安装 skills 的安装器（Agent Skills CLI、OpenCode、Zed）只安装 skills；如果你想要实时账户访问，请单独添加 MCP 服务器。

有关完整、最新的各客户端说明，请参阅 按 agent 安装。

Claude Code（skills + MCP）

Add the marketplace
/plugin marketplace add upstash/skills

Install the plugin
/plugin install upstash@upstash

OpenAI Codex（skills + MCP）

Add the marketplace
codex plugin marketplace add upstash/skills

Install the plugin
codex plugin add upstash@upstash

Cursor（skills + MCP）

我们正在等待此 plugin 被官方
Cursor Marketplace 接受。一旦上架，就可以从 Cursor 侧边栏的 Customize 中安装，它会同时带来 skills 和 MCP 服务器。

Gemini CLI（skills + MCP）

Gemini CLI 将此仓库作为 extension 加载——manifest 是仓库根目录下的 gemini-extension.json；skills/ 下的每个 skill 和远程 MCP 服务器都会被自动识别：

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

OpenCode

OpenCode 从项目中的 .agents/skills/ 和全局的 ~/.config/opencode/skills/ 加载 Agent Skills，Agent Skills CLI 正是为 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 工具将已安装的 skills 暴露给 agent，因此
agent 只加载与当前任务相关的子技能。若要对你的账户进行实时访问
（创建数据库、检查 QStash 日志等），还需添加 MCP 服务器。

Zed

Zed 会从项目中的 .agents/skills/ 以及全局的 ~/.agents/skills/ 加载
Agent Skills，而这正是 Agent Skills CLI 写入它们的位置：

在每个项目中都可用
npx skills add upstash/skills --agent zed --global

或者仅在此项目中
npx skills add upstash/skills --agent zed

随后这些技能会显示在 Zed 的 Agent Panel 中，agent 可以自行加载它们，或通过
/upstash 加载。Zed 的扩展市场提供语言、主题、调试器、代码片段和 MCP
服务器，但没有用于技能的渠道，因此 CLI 是安装它们的唯一方式。zed-extension/ 中的 Zed
扩展则用于 MCP 服务器。

Context7 CLI

npx ctx7 skills install upstash/skills

Agent Skills CLI

npx skills add upstash/skills

DeepSeek Harness

一步安装技能以及 Upstash MCP 服务器。需要
pnpm 位于你的 PATH 中。

安装到某个 profile（web 是 dsh web 启动时使用的那个）
dsh plugin --profile web add github:upstash/skills

启动 harness
dsh web

然后在会话中存储你的 Upstash 凭据：

/upstash-login YOUR_EMAIL YOUR_API_KEY

凭据存储在 ~/.dsh/.credentials.yaml 中，一旦两者都设置好，MCP 服务器就会连接。
技能无需凭据即可使用。

MCP 服务器

安装上面的插件已经配置好了远程 MCP 服务器。当你使用仅支持技能的安装器（OpenCode、Zed）
或不带插件的客户端时，可以单独设置它。

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

Claude Code

OAuth（首次使用 /mcp 时进行浏览器授权）
claude mcp add --transport http upstash https://mcp.upstash.com/mcp

或使用开发者 API 密钥，无需浏览器
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 密钥方式，添加带有 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= 来限定 agent 能看到哪些产品工具——以逗号分隔，
可选值为 redis、qstash_workflow、vector、search、box、blob（省略表示全部），例如
https://mcp.upstash.com/mcp?features=redis,qstash_workflow。

本地（stdio）——自行运行 @upstash/mcp-server，
使用你的邮箱 + API key 进行认证。支持只读 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）：

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

进行更改

更新现有 skill

1. 编辑各个 skill 文件夹中的文件（例如 skills/upstash-qstash-js/）。
2. 运行 npm run build 以重新生成 skills/upstash/。
3. 同时提交源更改和重新生成的输出。

添加新 skill

1. 在 skills/ 下创建一个新文件夹（例如 skills/upstash-redis-js/）。
2. 添加一个带有标准 frontmatter（name 和 description）的 SKILL.md 以及任何支持文件。
3. 运行 npm run build——新 skill 会被自动识别。
4. 提交所有内容。

更改组合 skill 的头部

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 扩展
无法携带 skills。

cd zed-extension
rustup target add wasm32-wasip2   # once
cargo build --release --target wasm32-wasip2

使用 zed: install dev extension 测试本地构建，并将 Zed 指向 zed-extension/。
测试时在某个文件夹上打开 Zed——上下文服务器是项目作用域的，因此如果没有打开项目
（或者项目的工作树无法打开），服务器就永远不会启动，面板会一直停留在
“Connecting Server...”直到 Zed 的 60 秒超时。

要发布或更新它，请向
zed-industries/extensions 提交一个 PR，将该仓库
作为子模块添加到 extensions/mcp-server-upstash 下，并在 extensions.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 重新生成 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 将会失败。