Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .npmrc
Original file line number Diff line number Diff line change
@@ -1,2 +1 @@
provenance=true
ignore-scripts=true
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# add-sg-mcp
# @stackguardian/mcp-wizard

A CLI that connects coding agents (Claude Code, Codex, Cursor, VS Code, Gemini CLI, OpenCode and more) to the StackGuardian MCP server and installs the StackGuardian skills. Fork of `neon-solutions/add-mcp` 2.4.0.
A CLI (published as `@stackguardian/mcp-wizard`, command `add-sg-mcp`) that connects coding agents (Claude Code, Codex, Cursor, VS Code, Gemini CLI, OpenCode and more) to the StackGuardian MCP server and installs the StackGuardian skills. Fork of `neon-solutions/add-mcp` 2.4.0.

## Layout

Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# Changelog

## 1.2.0

- The npm package is now `@stackguardian/mcp-wizard`: run `npx @stackguardian/mcp-wizard`. `add-sg-mcp` stops at 1.1.0. Your saved sign-in and installed skills carry over, so there is nothing to redo. The standalone executable and the install scripts keep the `add-sg-mcp` name.
- The hints the tool prints, such as "Run … login to switch", show the command you used: `npx @stackguardian/mcp-wizard …` from npm, `add-sg-mcp …` from the standalone executable. Before, they always said `add-sg-mcp`, which is not on your `PATH` when you run it through npx.

## 1.1.0

- Three more skills are installed with the server: `sg-create-stack` creates a stack (several workflows deployed together from a stack template) and walks you through each workflow's inputs; `sg-create-policy` adds a guardrail that blocks, warns on, or requires approval for infrastructure changes; `sg-manage-secrets` stores, rotates and deletes vault secrets and wires them into workflows. Run `npx add-sg-mcp@latest` (or the install script) again to get them. Before, only the three workflow skills were installed.
Expand Down
2 changes: 1 addition & 1 deletion NOTICE
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
add-sg-mcp
@stackguardian/mcp-wizard
Copyright 2026 StackGuardian

This product is a fork of add-mcp (https://github.com/neon-solutions/add-mcp),
Expand Down
82 changes: 41 additions & 41 deletions README.md

Large diffs are not rendered by default.

48 changes: 24 additions & 24 deletions docs/RELEASING.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
> **Fork note:** this pipeline was inherited from upstream `add-mcp`. Before the first release, an npm owner of `add-sg-mcp` must register the Trusted Publisher for the `StackGuardian/add-sg-mcp` repository and the `release.yml` workflow (see the one-time setup below); nothing publishes until that is done.
> **Fork note:** this pipeline was inherited from upstream `add-mcp`. The package was published as `add-sg-mcp` up to 1.1.0 and is now `@stackguardian/mcp-wizard`. Before the first release under the new name, an npm owner of `@stackguardian/mcp-wizard` must register the Trusted Publisher for the `StackGuardian/stackguardian-mcp` repository and the `release.yml` workflow (see the one-time setup below); nothing publishes until that is done.

# Releasing `add-sg-mcp`
# Releasing `@stackguardian/mcp-wizard`

This document is the authoritative guide for publishing `add-sg-mcp` to npm. It covers the threat model, the one-time setup of the secure publishing pipeline, the per-release runbook, and the break-glass procedure if something goes wrong.
This document is the authoritative guide for publishing `@stackguardian/mcp-wizard` to npm. It covers the threat model, the one-time setup of the secure publishing pipeline, the per-release runbook, and the break-glass procedure if something goes wrong.

`add-sg-mcp` does **not** support publishing from a maintainer's laptop. Every published version must pass through the GitHub Actions release workflow with OIDC trusted publishing, provenance, and a manual stage-approval step on npm.
`@stackguardian/mcp-wizard` does **not** support publishing from a maintainer's laptop. Every published version must pass through the GitHub Actions release workflow with OIDC trusted publishing, provenance, and a manual stage-approval step on npm.

## Why

Recent npm supply-chain incidents (Shai-Hulud, repeated maintainer-account takeovers, leaked CI tokens) almost all stem from one root cause: **long-lived npm publish tokens stored somewhere**. The pipeline below removes that root cause and adds two independent gates between "commit on `main`" and "live on the registry":

1. **Click "Publish release" on GitHub** — confirms the commit and version are intentional.
2. **`npm stage approve add-sg-mcp` with WebAuthn** — confirms the actual tarball CI produced is what should go live.
2. **`npm stage approve @stackguardian/mcp-wizard` with WebAuthn** — confirms the actual tarball CI produced is what should go live.

Either gate alone is enough to stop a bad publish.

Expand All @@ -25,14 +25,14 @@ flowchart LR
ciRun --> oidc["GitHub mints OIDC token (id-token: write)"]
oidc --> npmStage["npm stage publish --provenance"]
npmStage --> staging["Package sits in npm staging area"]
staging --> review["Maintainer: npm stage view add-sg-mcp"]
review --> approve["npm stage approve add-sg-mcp (WebAuthn)"]
staging --> review["Maintainer: npm stage view @stackguardian/mcp-wizard"]
review --> approve["npm stage approve @stackguardian/mcp-wizard (WebAuthn)"]
approve --> live["Live on registry.npmjs.org with provenance"]
```

### Defensive primitives in play

- **npm Trusted Publishing (OIDC)** — npm only accepts a publish from `release.yml` in `StackGuardian/add-sg-mcp`, authenticated by a short-lived OIDC token GitHub mints per run. No long-lived tokens exist anywhere.
- **npm Trusted Publishing (OIDC)** — npm only accepts a publish from `release.yml` in `StackGuardian/stackguardian-mcp`, authenticated by a short-lived OIDC token GitHub mints per run. No long-lived tokens exist anywhere.
- **npm provenance attestation** — every published version is cryptographically signed via Sigstore and bound to the exact GitHub commit and workflow that built it. Anyone can run `npm audit signatures` to verify.
- **"Require 2FA and disallow tokens"** on the package — registry-side switch that refuses any publish that is not OIDC + 2FA, even if an attacker steals a legacy token.
- **npm staged publishing** — `release.yml` runs `npm stage publish`, not `npm publish`. The tarball lands in a staging area; the maintainer inspects it and approves with WebAuthn before it goes live.
Expand All @@ -49,15 +49,15 @@ Work through these top to bottom. None of them can be automated; they are all in
> Done under your personal npm user, not the package.

- [ ] **A1.** Enable WebAuthn/passkey 2FA at `https://www.npmjs.com/settings/<your-username>/2fa`. If TOTP is your only second factor, enroll a passkey and then remove TOTP. New TOTP setups are disabled by npm and existing TOTP is being phased out.
- [ ] **A2.** Revoke every existing publish token at `https://www.npmjs.com/settings/<your-username>/tokens` that grants write access to `add-sg-mcp`. After trusted publishing is configured, nothing should need one.
- [ ] **A2.** Revoke every existing publish token at `https://www.npmjs.com/settings/<your-username>/tokens` that grants write access to `@stackguardian/mcp-wizard`. After trusted publishing is configured, nothing should need one.

### B. npm package configuration

> Done on the `add-sg-mcp` package page on npmjs.com.
> Done on the `@stackguardian/mcp-wizard` package page on npmjs.com.

- [ ] **B1.** Go to `https://www.npmjs.com/package/add-sg-mcp/access`. Under **Trusted Publisher**, click **GitHub Actions** and enter:
- [ ] **B1.** Go to `https://www.npmjs.com/package/@stackguardian/mcp-wizard/access`. Under **Trusted Publisher**, click **GitHub Actions** and enter:
- Organization: `StackGuardian`
- Repository: `add-sg-mcp`
- Repository: `stackguardian-mcp`
- Workflow filename: `release.yml`
- Allowed actions: select **`npm stage publish` only**. **Do not** check `npm publish`.
- Save.
Expand All @@ -66,7 +66,7 @@ Work through these top to bottom. None of them can be automated; they are all in

- [ ] **B2.** On the same page, find **Publishing access** and choose **"Require two-factor authentication and disallow tokens"**. Save. From this point any publish that is not OIDC + 2FA-approved staged release is rejected by the registry.

### C. GitHub repository configuration (`StackGuardian/add-sg-mcp`)
### C. GitHub repository configuration (`StackGuardian/stackguardian-mcp`)

- [ ] **C1.** Settings -> Rules -> Rulesets -> **New tag ruleset**. Name it "release tags". Target tags matching `v*`. Enable "Restrict creations", "Restrict updates", and "Restrict deletions". Add yourself (and any future co-maintainers) to the bypass list. Save.
- [ ] **C2.** Settings -> Actions -> General -> **Workflow permissions** = "Read repository contents and packages permissions" (the more restrictive of the two radio buttons). Job-level `id-token: write` in `release.yml` still works because workflow files can request additional permissions explicitly, but they cannot exceed what the repo allows globally.
Expand All @@ -75,7 +75,7 @@ Work through these top to bottom. None of them can be automated; they are all in

### D. First-release smoke test

- [ ] **D1.** Cut a patch release through the runbook below (e.g. `v1.9.1` with an empty CHANGELOG entry like "internal: validate release pipeline"). Walk through the stage-review step slowly: open the staged tarball on npmjs.com, confirm the file list matches `package.json#files` (`dist/`, `README.md`), confirm the provenance attestation badge appears, then approve. Once the version is live, run `npm audit signatures add-sg-mcp@1.9.1` to verify Sigstore signatures end to end.
- [ ] **D1.** Cut a patch release through the runbook below (e.g. `v1.9.1` with an empty CHANGELOG entry like "internal: validate release pipeline"). Walk through the stage-review step slowly: open the staged tarball on npmjs.com, confirm the file list matches `package.json#files` (`dist/`, `README.md`), confirm the provenance attestation badge appears, then approve. Once the version is live, run `npm audit signatures @stackguardian/mcp-wizard@1.9.1` to verify Sigstore signatures end to end.

## Per-release runbook

Expand All @@ -95,7 +95,7 @@ Follow this every time you ship a new version. The whole sequence is typically 5
- Commit as `chore: release vX.Y.Z` and push to `main`.

4. **Draft and publish the GitHub Release.**
- On `https://github.com/StackGuardian/add-sg-mcp/releases`, click **Draft a new release**.
- On `https://github.com/StackGuardian/stackguardian-mcp/releases`, click **Draft a new release**.
- "Choose a tag" -> type `vX.Y.Z` (must match `package.json#version`; the workflow will fail fast if they disagree).
- Target: `main`.
- Title: `vX.Y.Z`.
Expand All @@ -110,7 +110,7 @@ Follow this every time you ship a new version. The whole sequence is typically 5

```bash
npm stage list # shows pending staged versions for packages you maintain
npm stage view add-sg-mcp # inspect the staged release for add-sg-mcp
npm stage view @stackguardian/mcp-wizard # inspect the staged release for @stackguardian/mcp-wizard
```

Verify:
Expand All @@ -122,17 +122,17 @@ Follow this every time you ship a new version. The whole sequence is typically 5
7. **Approve.**

```bash
npm stage approve add-sg-mcp # prompts for WebAuthn
npm stage approve @stackguardian/mcp-wizard # prompts for WebAuthn
```

The package goes live.

8. **Verify it landed correctly.**

```bash
npm view add-sg-mcp version
npm view add-sg-mcp dist-tags
npm audit signatures add-sg-mcp@X.Y.Z
npm view @stackguardian/mcp-wizard version
npm view @stackguardian/mcp-wizard dist-tags
npm audit signatures @stackguardian/mcp-wizard@X.Y.Z
```

9. **If anything looked wrong at step 6, reject instead of approving.**
Expand All @@ -145,7 +145,7 @@ Follow this every time you ship a new version. The whole sequence is typically 5

### Versioning

`add-sg-mcp` follows semver. As a rough guide:
`@stackguardian/mcp-wizard` follows semver. As a rough guide:

- **patch** — bug fixes, registry adds, internal-only changes that do not alter behaviour.
- **minor** — new features, new agent support, new flags. Backward-compatible.
Expand All @@ -162,18 +162,18 @@ Follow this every time you ship a new version. The whole sequence is typically 5

### Suspected repository compromise (malicious PR, force-push, etc.)

1. Disable the trusted-publisher binding on `https://www.npmjs.com/package/add-sg-mcp/access` to halt all CI publishes immediately.
1. Disable the trusted-publisher binding on `https://www.npmjs.com/package/@stackguardian/mcp-wizard/access` to halt all CI publishes immediately.
2. Audit `main`, the `release.yml` workflow, and the `v*` tag history.
3. Once clean, re-enable the trusted publisher and ship a clean release.

Note: even without step 1, an attacker cannot directly publish from a PR branch or a fork because OIDC only accepts publishes from `release.yml` on `StackGuardian/add-sg-mcp`'s default branch flow. Tag protection prevents them from triggering the real `release.yml`. Step 1 is belt and braces.
Note: even without step 1, an attacker cannot directly publish from a PR branch or a fork because OIDC only accepts publishes from `release.yml` on `StackGuardian/stackguardian-mcp`'s default branch flow. Tag protection prevents them from triggering the real `release.yml`. Step 1 is belt and braces.

### Emergency publish when CI is broken

By design you cannot publish from a laptop. The escape hatch:

1. On npmjs.com, **Publishing access** -> flip **"Require two-factor authentication and disallow tokens"** off temporarily.
2. Create a granular access token with a 7-day expiry scoped to `add-sg-mcp` only.
2. Create a granular access token with a 7-day expiry scoped to `@stackguardian/mcp-wizard` only.
3. Publish locally with that token.
4. Revoke the token immediately.
5. Flip "Require 2FA and disallow tokens" back on.
Expand Down
13 changes: 8 additions & 5 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "add-sg-mcp",
"version": "1.1.0",
"name": "@stackguardian/mcp-wizard",
"version": "1.2.0",
"description": "Connect your coding agents to StackGuardian: installs the StackGuardian MCP server and skills into Claude Code, Codex, Cursor, VS Code, Gemini CLI, OpenCode and more with a single command.",
"author": "StackGuardian <support@stackguardian.io>",
"license": "Apache-2.0",
Expand Down Expand Up @@ -51,11 +51,11 @@
],
"repository": {
"type": "git",
"url": "git+https://github.com/StackGuardian/add-sg-mcp.git"
"url": "git+https://github.com/StackGuardian/stackguardian-mcp.git"
},
"homepage": "https://github.com/StackGuardian/add-sg-mcp#readme",
"homepage": "https://github.com/StackGuardian/stackguardian-mcp#readme",
"bugs": {
"url": "https://github.com/StackGuardian/add-sg-mcp/issues"
"url": "https://github.com/StackGuardian/stackguardian-mcp/issues"
},
"dependencies": {
"@clack/prompts": "^0.11.0",
Expand All @@ -76,5 +76,8 @@
},
"engines": {
"node": ">=18"
},
"publishConfig": {
"access": "public"
}
}
12 changes: 6 additions & 6 deletions skills/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# StackGuardian skills

`add-sg-mcp` installs six skills next to the StackGuardian MCP server. A skill teaches your coding agent how to carry out a StackGuardian task step by step. With a skill, the agent looks up your workflow groups, templates and connectors instead of guessing. It shows you the values it is about to use, and it confirms a summary with you before it creates or changes anything.
`@stackguardian/mcp-wizard` installs six skills next to the StackGuardian MCP server. A skill teaches your coding agent how to carry out a StackGuardian task step by step. With a skill, the agent looks up your workflow groups, templates and connectors instead of guessing. It shows you the values it is about to use, and it confirms a summary with you before it creates or changes anything.

- [How the pieces fit](#how-the-pieces-fit)
- [StackGuardian terms you'll see](#stackguardian-terms-youll-see)
Expand All @@ -22,7 +22,7 @@
- **A skill** is a playbook for one task. It tells the agent which tools to use, in what order, and what to ask you along the way.
- **You** make the decisions. The agent brings you the options and you pick.

Not set up yet? Run `npx add-sg-mcp` and follow the [README](../README.md#install). It installs the server and all six skills. Then restart your agent.
Not set up yet? Run `npx @stackguardian/mcp-wizard` and follow the [README](../README.md#install). It installs the server and all six skills. Then restart your agent.

## StackGuardian terms you'll see

Expand Down Expand Up @@ -247,10 +247,10 @@ These skills use the StackGuardian MCP server and act on your StackGuardian orga

## Updating and removing the skills

- **Update:** run `npx add-sg-mcp@latest`, or the install script again. Each run refreshes the skills.
- **Check:** `npx add-sg-mcp status` shows which agents have the skills.
- **Skip:** `npx add-sg-mcp --skip-skills` installs the server without them.
- **Remove:** `npx add-sg-mcp remove` takes the server and the skills out of your agents.
- **Update:** run `npx @stackguardian/mcp-wizard@latest`, or the install script again. Each run refreshes the skills.
- **Check:** `npx @stackguardian/mcp-wizard status` shows which agents have the skills.
- **Skip:** `npx @stackguardian/mcp-wizard --skip-skills` installs the server without them.
- **Remove:** `npx @stackguardian/mcp-wizard remove` takes the server and the skills out of your agents.

The skills are copied to `~/.agents/skills/` and linked into each agent's own skills folder (`~/.claude/skills`, `~/.codex/skills`, `~/.cursor/skills`, …). Mastra Code and MCPorter have no skills support, so they get the server only.

Expand Down
Loading
Loading