Add upstash setup to connect AI agents to Upstash

[CahidArda]

Upstash's answer to npx ctx7 setup: one command that wires the Upstash MCP server and skills into the user's agents.

npx @upstash/cli setup

What it installs

Agent	Method
Claude Code	claude plugin marketplace add upstash/skills + claude plugin install upstash@upstash (user or project scope)
Codex	codex plugin marketplace add upstash/skills + codex plugin add upstash@upstash
Gemini CLI	gemini extensions install https://github.com/upstash/skills --consent
Cursor	Local plugin in ~/.cursor/plugins/local/upstash (no plugin CLI, and not in the Cursor marketplace yet)
VS Code, Copilot CLI, OpenCode	Remote MCP (https://mcp.upstash.com/mcp) merged into the agent's config + the combined upstash skill

Plugin agents fall back to MCP + skill when the plugin can't be installed (CLI not on PATH, install error), --project is used for a user-only plugin, or --auth api-key is set (the plugins are OAuth-only). Reruns refresh the marketplace and update the plugin.

Flags

--claude --codex --cursor --gemini --vscode --copilot --opencode, --mode auto|plugin|mcp, --auth oauth|api-key (api-key uses the existing resolveAuth: flags, env, or upstash login; header is Authorization: Bearer email:key), -p/--project, -y/--yes, --ref, --dry-run, --json. With no agent flags it prompts (TTY) or uses detected agents (non-TTY / -y).

Differences from ctx7 setup

• ctx7 never installs plugins; this does, since upstash/skills already ships Claude/Codex/Cursor/Gemini manifests that bundle the MCP.
• No rules files — the combined skill already tells the agent when to prefer MCP tools.
• No new dependencies (the CLI only has commander + dotenv). Skills come from one codeload.github.com tarball download, parsed with a ~60-line tar reader; no GitHub API rate limits.
• Warns when a manual upstash MCP entry and the plugin would both load the server.

Tested

• 15 unit tests (tests/unit/setup.test.ts): synthetic tarball, fake agent-CLI runner, temp HOME.
• End-to-end in a sandbox with the real claude 2.1.263 and codex 0.153.4 CLIs: plugin installs are idempotent and show up in claude plugin list / ~/.codex/config.toml; TOML and JSON merges keep other servers; project scope writes .claude/settings.json with the plugin enabled.
• Not tested: Gemini CLI install (not in the sandbox) and Cursor actually loading the local plugin — worth a manual check on a Mac before merging.

Follow-ups

• Switch Cursor to the marketplace install once the listing is accepted.
• Document upstash setup in the upstash-cli skill and the docs "Install by agent" page.
• upstash setup --remove, and an API-key option for plugins (e.g. a headersHelper like context7's Claude plugin).

[linear-code]

DX-3074

DX-3075

[Copilot]

Copilot review overview

🟡 Changes recommended

Project-scoped credentials, unsafe config handling, and ignored ref selection introduce security and correctness risks.

Review effort: Balanced
Findings: 4 · 3 · 1

Open (8)

• Prevent API keys from being written to project config files · New
• Propagate unreadable config errors instead of treating them as missing · New
• Create new credential files with restrictive permissions · New
• Validate archive entries before deleting the destination · New
• Honor --ref for Claude and Codex installers · New
• Parse trailing commas in JSONC configuration files · New
• Handle quoted TOML keys when matching MCP tables · New
• Update dependency claims for added runtime packages · New

What changed in this PR

Adds upstash setup to connect supported AI agents through plugins or MCP plus skills.

Changes:

• Adds agent detection, interactive setup, authentication, and fallbacks.
• Adds configuration merging, plugin installation, and skill downloads.
• Adds documentation and unit coverage.

File	Description
src/​commands/​setup.ts	Implements setup orchestration and CLI flags.
src/​setup/​agents.ts	Defines agent-specific configuration.
src/​setup/​mcp-config.ts	Merges MCP configuration files.
src/​setup/​plugins.ts	Installs supported agent plugins.
src/​setup/​repo.ts	Downloads and extracts skills.
src/​setup/​ui.ts	Provides interactive terminal prompts.
src/​cli.ts	Registers the setup command.
tests/​unit/​setup.test.ts	Tests setup behavior and helpers.
README.md	Documents agent setup.
package.json	Adds prompt and color dependencies.
package-lock.json	Locks new dependencies.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Ref validation, TOML merging, replacement safety, and PR description discrepancies remain unresolved.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Validate --ref before installer dispatch to prevent command injection · New
• Preserve existing installation until staging rename succeeds · New
• Align authentication implementation with the advertised CLI interface · New

Resolved since last review (8)

• Validate archive entries before deleting the destination
• Create new credential files with restrictive permissions
• Propagate unreadable config errors instead of treating them as missing
• Prevent API keys from being written to project config files
• Handle quoted TOML keys when matching MCP tables
• Parse trailing commas in JSONC configuration files
• Honor --ref for Claude and Codex installers
• Update dependency claims for added runtime packages

Previously missed (1)

In code that hasn't changed since last review

Handle inline and dotted MCP tables before appending TOML sections

src/​setup/​mcp-config.ts:167

This only detects explicit table headers. A valid Codex config can instead contain mcp_servers.upstash = { url = "old" }; appending [mcp_servers.upstash] then declares the same table twice and makes the entire TOML config invalid. Handle dotted assignments/inline tables before appending, or use a TOML parser for the merge.