From 67f462fe8e3363662c06566dca7d88d5cd2dc180 Mon Sep 17 00:00:00 2001 From: Arunim Chaudhary Date: Fri, 16 Oct 2026 10:28:47 +0530 Subject: [PATCH] chore: publish as @stackguardian/mcp-wizard Rename the npm package from add-sg-mcp to @stackguardian/mcp-wizard and point repository links at StackGuardian/stackguardian-mcp. The add-sg-mcp command, config folder, OAuth client ID and download paths stay, so saved sign-ins and installed skills carry over. CLI hints now print the command the user actually ran: npx @stackguardian/mcp-wizard under Node, add-sg-mcp in the standalone binary. Co-Authored-By: Claude Opus 5.5 --- .npmrc | 1 - AGENTS.md | 4 +-- CHANGELOG.md | 5 +++ NOTICE | 2 +- README.md | 82 +++++++++++++++++++++++----------------------- docs/RELEASING.md | 48 +++++++++++++-------------- package.json | 13 +++++--- skills/README.md | 12 +++---- src/sg/commands.ts | 17 +++++----- src/sg/preset.ts | 3 ++ 10 files changed, 99 insertions(+), 88 deletions(-) diff --git a/.npmrc b/.npmrc index 6691e12..97b895e 100644 --- a/.npmrc +++ b/.npmrc @@ -1,2 +1 @@ -provenance=true ignore-scripts=true diff --git a/AGENTS.md b/AGENTS.md index 928a774..a4ca6b8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 5d2360f..db97fbe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/NOTICE b/NOTICE index 27b36ed..52da791 100644 --- a/NOTICE +++ b/NOTICE @@ -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), diff --git a/README.md b/README.md index d16e745..62c1046 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Work with [StackGuardian](https://www.stackguardian.io) from your coding agent. One command adds the **StackGuardian MCP server** to Claude Code, Codex, Cursor, VS Code, Gemini CLI and [more](#supported-agents), and installs the **StackGuardian skills**. You can then ask your agent, in plain language, to find out why a run failed, deploy a template, change a workflow or check your cloud posture. ```bash -npx add-sg-mcp +npx @stackguardian/mcp-wizard ``` No Node.js? Use the [one-line installer](#install) for macOS, Linux or Windows instead. @@ -19,7 +19,7 @@ No Node.js? Use the [one-line installer](#install) for macOS, Linux or Windows i With Node.js 18 or later: ```bash -npx add-sg-mcp +npx @stackguardian/mcp-wizard ``` Without Node.js, the installer downloads a standalone executable, checks it against the release's `SHA256SUMS`, installs it and runs it: @@ -40,12 +40,12 @@ Then: 2. Back in the terminal, choose the agents to connect. The ones found on this machine (or those you picked last time) are preselected. 3. Restart those agents. -With the standalone executable, run `add-sg-mcp` wherever this README says `npx add-sg-mcp`. See [Install script options](#install-script-options) to pin a version, change the install folder or use a mirror. +With the standalone executable, run `add-sg-mcp` wherever this README says `npx @stackguardian/mcp-wizard`. See [Install script options](#install-script-options) to pin a version, change the install folder or use a mirror. ## Check that it works - **Claude Code:** run `/mcp`. `StackGuardian-` should be listed, and the skills show up as `/sg-create-workflow`, `/sg-update-workflow`, `/sg-upgrade-workflow`, `/sg-create-stack`, `/sg-create-policy` and `/sg-manage-secrets`. -- **Any agent:** `npx add-sg-mcp status` shows your saved sign-in and which agents have the server and the skills. +- **Any agent:** `npx @stackguardian/mcp-wizard status` shows your saved sign-in and which agents have the server and the skills. - Ask your agent something small, such as _"Show my five most recent StackGuardian workflow runs and their status."_ Nothing there? See [Troubleshooting](#troubleshooting). @@ -82,56 +82,56 @@ In Claude Code, start one with `/sg-create-workflow` and so on. Other agents pic ## Choose how your agent signs in -| | Grant token (default) | API key | OAuth (preview) | -| ------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------- | -| Command | `npx add-sg-mcp` | `npx add-sg-mcp --token --org --region ` | `npx add-sg-mcp --auth oauth --org --region ` | -| How you sign in | In the browser | No browser: you pass a key from _Profile → API keys_ | In the agent, on first use | -| What the agent gets | A token for one organization and the roles you approve | Your user API key for the organization | No stored credential; the agent signs you in on first use | -| Access | Only the roles you approved | Everything your roles allow | Your access, through the agent's own sign-in | -| Expiry and revoking | You choose the expiry; revoke from _Profile → Connected apps_ | No expiry; rotate it from _Profile → API keys_ | Handled through the agent's own sign-in | +| | Grant token (default) | API key | OAuth (preview) | +| ------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | +| Command | `npx @stackguardian/mcp-wizard` | `npx @stackguardian/mcp-wizard --token --org --region ` | `npx @stackguardian/mcp-wizard --auth oauth --org --region ` | +| How you sign in | In the browser | No browser: you pass a key from _Profile → API keys_ | In the agent, on first use | +| What the agent gets | A token for one organization and the roles you approve | Your user API key for the organization | No stored credential; the agent signs you in on first use | +| Access | Only the roles you approved | Everything your roles allow | Your access, through the agent's own sign-in | +| Expiry and revoking | You choose the expiry; revoke from _Profile → Connected apps_ | No expiry; rotate it from _Profile → API keys_ | Handled through the agent's own sign-in | Only the grant sign-in opens the dashboard. An API key is never fetched for you: pass it with `--token` (or `SG_API_KEY`). Without `--auth`, a key you pass, or one saved by an earlier `--token` run, selects the API key; otherwise you sign in for a grant. ### Grant tokens -`npx add-sg-mcp` (optionally `--region eu --org my-org`) asks the StackGuardian OAuth broker for a **grant token** instead of using your API key. The browser opens a consent page where you pick the organization, the roles the agent may use and how long the grant should last; the CLI receives an `sgat_` token on a loopback callback and writes it to each agent as an `Authorization: Bearer` header. +`npx @stackguardian/mcp-wizard` (optionally `--region eu --org my-org`) asks the StackGuardian OAuth broker for a **grant token** instead of using your API key. The browser opens a consent page where you pick the organization, the roles the agent may use and how long the grant should last; the CLI receives an `sgat_` token on a loopback callback and writes it to each agent as an `Authorization: Bearer` header. - The token is bound to **one organization and the roles you approved** — it is not your full user key, so an agent can be given less than you have. -- `npx add-sg-mcp status` shows `expires `, `no expiry` or `expired`. An expired grant is never reused; the next run asks for a new one. +- `npx @stackguardian/mcp-wizard status` shows `expires `, `no expiry` or `expired`. An expired grant is never reused; the next run asks for a new one. - `logout` revokes the saved grant and deletes the local copy. Revoke a grant any time from _Profile → Connected apps_ in the dashboard. -- `npx add-sg-mcp login` requests a fresh grant, then asks which agents to install it to. -- If an API key is saved from an earlier `--token` run, `npx add-sg-mcp` keeps using it. Pass `--auth grant` to switch to a grant. +- `npx @stackguardian/mcp-wizard login` requests a fresh grant, then asks which agents to install it to. +- If an API key is saved from an earlier `--token` run, `npx @stackguardian/mcp-wizard` keeps using it. Pass `--auth grant` to switch to a grant. ### OAuth (preview) -`npx add-sg-mcp --auth oauth --org my-org --region eu` writes the server URL without a credential for agents that implement MCP OAuth themselves (Claude Code, VS Code, Cursor, Codex, Gemini CLI, Windsurf). The agent then signs you in on first use. This needs the StackGuardian OAuth broker to be enabled for your environment. +`npx @stackguardian/mcp-wizard --auth oauth --org my-org --region eu` writes the server URL without a credential for agents that implement MCP OAuth themselves (Claude Code, VS Code, Cursor, Codex, Gemini CLI, Windsurf). The agent then signs you in on first use. This needs the StackGuardian OAuth broker to be enabled for your environment. ## Everyday tasks -| To | Run | -| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Connect another agent | `npx add-sg-mcp -a cursor` (`npx add-sg-mcp list-agents` shows the names) | -| Connect another organization | `npx add-sg-mcp login --org other-org --region eu`, then pick your agents. It gets its own `StackGuardian-other-org` entry next to the first. | -| Disconnect one organization | `npx add-sg-mcp remove --name StackGuardian-`. The skills stay for the organizations you keep. | -| Update the tool and the skills | `npx add-sg-mcp@latest`, or run the install script again. Each run refreshes the skills. | -| See what's installed | `npx add-sg-mcp status` | -| Remove everything | `npx add-sg-mcp logout --purge` removes the server and skills from your agents and forgets the credential. For the standalone executable, also delete `~/.local/bin/add-sg-mcp` (Windows: `%LOCALAPPDATA%\add-sg-mcp`). | +| To | Run | +| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Connect another agent | `npx @stackguardian/mcp-wizard -a cursor` (`npx @stackguardian/mcp-wizard list-agents` shows the names) | +| Connect another organization | `npx @stackguardian/mcp-wizard login --org other-org --region eu`, then pick your agents. It gets its own `StackGuardian-other-org` entry next to the first. | +| Disconnect one organization | `npx @stackguardian/mcp-wizard remove --name StackGuardian-`. The skills stay for the organizations you keep. | +| Update the tool and the skills | `npx @stackguardian/mcp-wizard@latest`, or run the install script again. Each run refreshes the skills. | +| See what's installed | `npx @stackguardian/mcp-wizard status` | +| Remove everything | `npx @stackguardian/mcp-wizard logout --purge` removes the server and skills from your agents and forgets the credential. For the standalone executable, also delete `~/.local/bin/add-sg-mcp` (Windows: `%LOCALAPPDATA%\add-sg-mcp`). | ### Headless / CI Skip the browser with an API key from **Profile → API keys** in the dashboard: ```bash -npx add-sg-mcp --token sgu_… --org my-org --region eu -y --all +npx @stackguardian/mcp-wizard --token sgu_… --org my-org --region eu -y --all # or -SG_API_KEY=sgu_… SG_ORG=my-org SG_REGION=eu npx add-sg-mcp -y -a claude-code +SG_API_KEY=sgu_… SG_ORG=my-org SG_REGION=eu npx @stackguardian/mcp-wizard -y -a claude-code ``` `--api-base https://…/api/v1` replaces `--region` for non-standard environments. In a Docker image, `curl -fsSL https://dl.stackguardian.io/add-sg-mcp/install.sh | ADD_SG_MCP_NO_RUN=1 sh` installs the executable without running it. ## Troubleshooting -**The server doesn't show up in my agent.** Restart the agent; most read their MCP config only at startup. Then run `npx add-sg-mcp status`. If the agent isn't listed, it wasn't selected: run `npx add-sg-mcp -a `. With `--project`, the server is only in that project's config. +**The server doesn't show up in my agent.** Restart the agent; most read their MCP config only at startup. Then run `npx @stackguardian/mcp-wizard status`. If the agent isn't listed, it wasn't selected: run `npx @stackguardian/mcp-wizard -a `. With `--project`, the server is only in that project's config. **"No coding agents detected on this machine."** With `-y`, or when there's no terminal to prompt in, only detected agents are used. Name them instead (`-a claude-code -a cursor`) or pass `--all`. @@ -139,9 +139,9 @@ SG_API_KEY=sgu_… SG_ORG=my-org SG_REGION=eu npx add-sg-mcp -y -a claude-code **My agent gets "unauthorized" errors.** The credential in the agent's config no longer works: -- API key rotated or deleted: run `npx add-sg-mcp --token --org --region ` to write the new key to your agents. -- Grant expired: `npx add-sg-mcp` asks for a new one. -- Grant revoked: run `npx add-sg-mcp login` and pick your agents. +- API key rotated or deleted: run `npx @stackguardian/mcp-wizard --token --org --region ` to write the new key to your agents. +- Grant expired: `npx @stackguardian/mcp-wizard` asks for a new one. +- Grant revoked: run `npx @stackguardian/mcp-wizard login` and pick your agents. **The skills don't appear.** Restart the agent. Mastra Code and MCPorter have no skills support, so they get the server only. `--skip-skills` skips them on purpose. @@ -149,14 +149,14 @@ SG_API_KEY=sgu_… SG_ORG=my-org SG_REGION=eu npx add-sg-mcp -y -a claude-code **Claude Desktop.** Not supported here: Claude Desktop only takes local servers from this tool. Add StackGuardian through _Settings → Connectors_ instead. -**"this Linux has no glibc".** The standalone executables need glibc, which Alpine and other musl-based systems lack. Use `npx add-sg-mcp` with Node.js there. +**"this Linux has no glibc".** The standalone executables need glibc, which Alpine and other musl-based systems lack. Use `npx @stackguardian/mcp-wizard` with Node.js there. ## Reference ### Options ``` -npx add-sg-mcp [options] +npx @stackguardian/mcp-wizard [options] --region StackGuardian region (prompted when omitted) --org Organization to connect (pre-selected in the browser) @@ -175,13 +175,13 @@ npx add-sg-mcp [options] --auth Credential mode (default: apikey when a key is given, otherwise grant) ``` -| Command | What it does | -| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | -| `npx add-sg-mcp login` | Sign in again (switch organization or region), then pick the agents to install to. Without a terminal it only saves the credential | -| `npx add-sg-mcp status` | Show the saved credential (masked) and which agents have the server and skills | -| `npx add-sg-mcp remove [-a ] [--project]` | Remove the server entry and the skills from your agents | -| `npx add-sg-mcp logout [--purge]` | Forget the credential; `--purge` also runs `remove` | -| `npx add-sg-mcp list-agents` | List supported agents and their config files | +| Command | What it does | +| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `npx @stackguardian/mcp-wizard login` | Sign in again (switch organization or region), then pick the agents to install to. Without a terminal it only saves the credential | +| `npx @stackguardian/mcp-wizard status` | Show the saved credential (masked) and which agents have the server and skills | +| `npx @stackguardian/mcp-wizard remove [-a ] [--project]` | Remove the server entry and the skills from your agents | +| `npx @stackguardian/mcp-wizard logout [--purge]` | Forget the credential; `--purge` also runs `remove` | +| `npx @stackguardian/mcp-wizard list-agents` | List supported agents and their config files | `remove` and `logout --purge` take every `StackGuardian-` entry and the skills out. `remove --name ` takes out just that entry and keeps the skills. @@ -214,7 +214,7 @@ The executables are not yet notarized by Apple or code-signed for Windows. The i ### Supported agents -Claude Code, Codex, Cursor, VS Code (Copilot), Gemini CLI, OpenCode, GitHub Copilot CLI, Windsurf, Kiro CLI, Zed, Cline, Goose, Grok Build, Kilo Code, Kimi Code, Antigravity, Pi, Mastra Code, MCPorter. Run `npx add-sg-mcp list-agents` for the current list and each agent's config file. +Claude Code, Codex, Cursor, VS Code (Copilot), Gemini CLI, OpenCode, GitHub Copilot CLI, Windsurf, Kiro CLI, Zed, Cline, Goose, Grok Build, Kilo Code, Kimi Code, Antigravity, Pi, Mastra Code, MCPorter. Run `npx @stackguardian/mcp-wizard list-agents` for the current list and each agent's config file. - **Codex** and **Grok Build** store MCP servers in a TOML file that is rewritten as a whole; comments in `~/.codex/config.toml` are not preserved. - **Claude Desktop** and **fx** are skipped: Claude Desktop only supports local (stdio) servers here and fx only sends bearer tokens. Add StackGuardian to Claude Desktop through _Settings → Connectors_ instead. @@ -223,7 +223,7 @@ Claude Code, Codex, Cursor, VS Code (Copilot), Gemini CLI, OpenCode, GitHub Copi ### How it works -1. `npx add-sg-mcp` starts a one-time callback listener on `127.0.0.1` and opens the StackGuardian sign-in for your region in your browser. +1. `npx @stackguardian/mcp-wizard` starts a one-time callback listener on `127.0.0.1` and opens the StackGuardian sign-in for your region in your browser. 2. You sign in if needed and choose the organization, the roles the agent may use and how long the grant lasts. 3. The browser returns a one-time code to the loopback callback, and the CLI exchanges it for a grant token. The token is stored in `~/.config/add-sg-mcp/credentials.json` (mode `0600`). With `--token`, steps 1 to 3 are skipped and the key you passed is stored instead. 4. The CLI writes the server entry into each selected agent's own config file: diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 147ce1e..8420832 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -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. @@ -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. @@ -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//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//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//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. @@ -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. @@ -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 @@ -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`. @@ -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: @@ -122,7 +122,7 @@ 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. @@ -130,9 +130,9 @@ Follow this every time you ship a new version. The whole sequence is typically 5 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.** @@ -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. @@ -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. diff --git a/package.json b/package.json index 0f74758..99c58e3 100644 --- a/package.json +++ b/package.json @@ -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 ", "license": "Apache-2.0", @@ -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", @@ -76,5 +76,8 @@ }, "engines": { "node": ">=18" + }, + "publishConfig": { + "access": "public" } } diff --git a/skills/README.md b/skills/README.md index 4aa8778..7211bd8 100644 --- a/skills/README.md +++ b/skills/README.md @@ -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) @@ -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 @@ -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. diff --git a/src/sg/commands.ts b/src/sg/commands.ts index 788be9f..9d0e4c0 100644 --- a/src/sg/commands.ts +++ b/src/sg/commands.ts @@ -15,6 +15,7 @@ import { getLastSelectedAgents, saveSelectedAgents } from "../config.js"; import { listInstalledServers } from "../reader.js"; import { removeServer } from "../lib.js"; import { + CLI_COMMAND, OAUTH_CAPABLE_AGENTS, PRESET_EXCLUDED_AGENTS, SG_ENVIRONMENTS, @@ -255,7 +256,7 @@ async function credentialsFromGrant( (!options.org || options.org === saved.org) ) { p.log.info( - `Using the saved grant for ${chalk.cyan(saved.org)} (${saved.dashboardUrl || saved.apiBase}). Run ${chalk.cyan("add-sg-mcp logout")} first to request a new one.`, + `Using the saved grant for ${chalk.cyan(saved.org)} (${saved.dashboardUrl || saved.apiBase}). Run ${chalk.cyan(`${CLI_COMMAND} logout`)} first to request a new one.`, ); return saved; } @@ -293,7 +294,7 @@ async function credentialsFromGrant( } fail( error instanceof Error ? error.message : String(error), - "Run again, or use an API key instead: add-sg-mcp --token --org --region eu|us", + `Run again, or use an API key instead: ${CLI_COMMAND} --token --org --region eu|us`, ); } spinner.stop( @@ -347,14 +348,14 @@ export async function resolveCredentials( (!requestedOrigin || requestedOrigin === saved.dashboardUrl); if (orgMatches && envMatches) { p.log.info( - `Using saved credentials for ${chalk.cyan(saved.org)} (${saved.dashboardUrl || saved.apiBase}). Run ${chalk.cyan("add-sg-mcp login")} to switch.`, + `Using saved credentials for ${chalk.cyan(saved.org)} (${saved.dashboardUrl || saved.apiBase}). Run ${chalk.cyan(`${CLI_COMMAND} login`)} to switch.`, ); return saved; } } return fail( "API-key mode needs the key: pass --token (or SG_API_KEY) with --org and --region.", - "To sign in through the browser instead, run add-sg-mcp --auth grant.", + `To sign in through the browser instead, run ${CLI_COMMAND} --auth grant.`, ); } @@ -624,7 +625,7 @@ async function installServerAndSkills( [ `Restart your agents to pick up ${chalk.cyan(outcome.serverName)}.`, `Claude Code: ${chalk.cyan("/mcp")} lists the server; the skills appear as ${SG_SKILL_NAMES.map((s) => chalk.cyan(`/${s}`)).join(", ")}.`, - `Check anytime with ${chalk.cyan("add-sg-mcp status")}; remove with ${chalk.cyan("add-sg-mcp remove")}.`, + `Check anytime with ${chalk.cyan(`${CLI_COMMAND} status`)}; remove with ${chalk.cyan(`${CLI_COMMAND} remove`)}.`, "", "Try asking your agent:", ...SUGGESTED_PROMPTS.map((prompt) => ` ${chalk.cyan(`"${prompt}"`)}`), @@ -658,8 +659,8 @@ export async function runLogin( if (!isInteractive()) { p.outro( grant - ? `Grant saved for ${chalk.cyan(credentials.org)}. Run ${chalk.cyan("add-sg-mcp --auth grant")} to install the server and skills.` - : `Signed in to ${chalk.cyan(credentials.org)}. Run ${chalk.cyan("add-sg-mcp")} to install the server and skills.`, + ? `Grant saved for ${chalk.cyan(credentials.org)}. Run ${chalk.cyan(`${CLI_COMMAND} --auth grant`)} to install the server and skills.` + : `Signed in to ${chalk.cyan(credentials.org)}. Run ${chalk.cyan(CLI_COMMAND)} to install the server and skills.`, ); return; } @@ -718,7 +719,7 @@ export async function runStatus(deps: SgCommandDeps): Promise { "Credentials", ); } else { - p.log.info("Not signed in. Run add-sg-mcp login."); + p.log.info(`Not signed in. Run ${CLI_COMMAND} login.`); } const allAgents = getAgentTypes().filter( diff --git a/src/sg/preset.ts b/src/sg/preset.ts index b9ebdde..5393b9f 100644 --- a/src/sg/preset.ts +++ b/src/sg/preset.ts @@ -3,6 +3,9 @@ import type { SgCredentials } from "./credentials.js"; /** Prefix of the MCP server entry; the organization is appended so several orgs can coexist. */ export const SG_SERVER_NAME_PREFIX = "StackGuardian"; +/** How the user re-runs this tool: the standalone executable is on PATH, the npm package runs through npx. */ +export const CLI_COMMAND = + "Bun" in globalThis ? "add-sg-mcp" : "npx @stackguardian/mcp-wizard"; /** Entry name written before per-org naming; still recognised by status and remove. */ export const LEGACY_SG_SERVER_NAME = "stackguardian";