Skip to content

feat: StackGuardian MCP + skills installer (npx add-sg-mcp) - #1

Open
arunim2405 wants to merge 11 commits into
mainfrom
feat/sg-installer
Open

feat: StackGuardian MCP + skills installer (npx add-sg-mcp)#1
arunim2405 wants to merge 11 commits into
mainfrom
feat/sg-installer

Conversation

@arunim2405

@arunim2405 arunim2405 commented Sep 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

What

Turns the add-mcp fork into add-sg-mcp: one command that signs the user in through the StackGuardian dashboard, lets them pick an organization, receives the org API key on a loopback callback (a form POST from the dashboard, so the key never sits in a URL; GET is kept for manual use), writes the StackGuardian-<org> MCP server into every selected coding agent (20 agents: Claude Code, Codex, Cursor, VS Code, Gemini CLI, OpenCode, Copilot CLI, Windsurf, Kiro, Zed, Cline, Goose, Grok Build, Kilo, Kimi, Antigravity, Pi, Mastra, MCPorter) and installs the StackGuardian skills.

npx add-sg-mcp                     # browser login → org picker → install server + skills
npx add-sg-mcp --token sgu_… --org my-org --region eu -y --all   # headless
npx add-sg-mcp login | status | remove | logout --purge

Design: docs/superpowers/specs/2026-09-08-sg-mcp-installer-design.md. Dashboard counterpart: StackGuardian/dashboard#6934 (/orchestrator/cli-connect).

Key decisions

  • Credential = per-org user API key (Authorization: apikey sgu_…), which the gateway authorizer accepts on /orgs/<org>/mcp/. Long-lived, so static agent configs keep working. The MCP OAuth broker (api#1739 & co.) is not deployed and only yields 60-minute tokens; --auth oauth is a preview hook for when it is.
  • User scope by default; --project opts into project files and adds them to .gitignore.
  • Upstream untouched: agents.ts, installer.ts, formats/* etc. are byte-identical; everything StackGuardian is in src/sg/. Registry site, find, list, sync removed.
  • Skills (sg-create-workflow, sg-update-workflow, sg-upgrade-workflow) are bundled, copied to ~/.agents/skills and symlinked into each agent's skills dir (copy fallback; manifest so remove never touches foreign skills).
  • Claude Desktop (stdio-only) and fx (Bearer-only) are excluded from the preset with a message.
  • Loopback listener accepts one delivery per state and closes; a wrong state is refused without closing; bodies are capped at 64 KiB; the landing pages (connected / cancelled / refused) never contain the key and link back to the dashboard.

Tests

bun run typecheck && bun run test — upstream suites (minus the removed commands) plus tests/sg-{preset,credentials,auth,skills}.test.ts and tests/e2e/sg-cli.test.ts (sandboxed HOME: every agent config, credential file mode, skills links, status/remove/logout, --project, failure paths, --help, --auth oauth). The login test spins up the real loopback server.

Before release

  • Register the npm Trusted Publisher for StackGuardian/add-sg-mcp + release.yml (docs/RELEASING.md).
  • Merge/deploy dashboard#6934 so the browser flow works; until then --token is the path.
  • Point the dashboard's MCP install snippet and the sg-clickhouse-mcp README at npx add-sg-mcp.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NyMjkoCS1ic9P14Yo3dLLh

arunim2405 and others added 7 commits September 8, 2026 20:19
@arunim2405 @claude
docs: design spec for the StackGuardian MCP + skills installer
1ea7b5c 
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyMjkoCS1ic9P14Yo3dLLh
@arunim2405 @claude
docs: implementation plan for add-sg-mcp
cd2616d 
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyMjkoCS1ic9P14Yo3dLLh
@arunim2405 @claude
chore: rename fork to add-sg-mcp; add sg preset, credentials, loopbac…
ee6d635 
…k auth and skills modules

- package name, bin and config dir become add-sg-mcp; version 0.1.0
- remove registry.json, registry/, web/, scripts/, find.ts and the
  find/search/list/sync commands (no tests depend on them any more)
- main() returns an InstallOutcome and honours options.local so the
  StackGuardian connect flow can route to project scope without a prompt
- src/sg/{preset,credentials,auth,skills}.ts with tests; bundled skills
  under skills/ (sg-create/update/upgrade-workflow)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyMjkoCS1ic9P14Yo3dLLh
@arunim2405 @claude
feat(sg): connect, login, logout, status and remove commands; docs
5a2d75b 
- default command: browser login via the dashboard's /orchestrator/cli-connect
  page (loopback callback), agent selection without the excluded agents,
  upstream install with the apikey header, skills install, next steps
- headless --token/SG_API_KEY path, --project scope with .gitignore,
  --auth oauth preview, status/remove/logout --purge
- e2e suite tests/e2e/sg-cli.test.ts; README, CHANGELOG, RELEASING,
  AGENTS.md and NOTICE for the fork

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyMjkoCS1ic9P14Yo3dLLh
@arunim2405 @claude
chore: drop zod devDependency (only the removed registry scripts used…
7dae892 
… it)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyMjkoCS1ic9P14Yo3dLLh
@arunim2405 @claude
test: run every suite under a throwaway HOME (tests/run.mjs)
2484da6 
Upstream's installer tests exercise global routing in-process and wrote an
`example` server into the developer's real ~/.cursor/mcp.json and VS Code
mcp.json. The runner sandboxes HOME/XDG_CONFIG_HOME/CODEX_HOME/APPDATA for
every test file; the explicit file lists move from package.json into it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyMjkoCS1ic9P14Yo3dLLh
@arunim2405 @claude
fix(sg): review follow-ups
d487a86 
- guard --dashboard-url parsing when saved credentials exist (was an
  uncaught TypeError)
- validate --api-base in --auth oauth mode like the apikey path
- write credentials.json via temp file + rename
- a skills directory counts as ours only when the manifest recorded it (or
  it is a symlink); ownership during removal is judged against the manifest
  as read at the start of the call
- drop the upstream remove-<query> e2e tests (command replaced in Task 7)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyMjkoCS1ic9P14Yo3dLLh
@arunim2405
arunim2405 marked this pull request as ready for review September 8, 2026 15:27
arunim2405 and others added 4 commits September 8, 2026 22:20
@arunim2405 @claude
feat(sg): style the callback page with the StackGuardian design-syste…
9abb58b 
…m tokens

Inter, #1b71ec primary, 10px radius, neutral card on muted background, the
SG mark inline, and a status pill — matching the dashboard instead of a
generic teal card. Still self-contained, key-free, and strips the query.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyMjkoCS1ic9P14Yo3dLLh
@arunim2405 @claude
feat(sg): name the server entry StackGuardian-<org>
3420b30 
One entry per organization, named after it, so several orgs coexist without
--name. A spaced form was ruled out: Claude Code rejects server names with
anything but letters, digits, hyphens and underscores (they feed the
mcp__<server>__<tool> ids) and Codex has the same rule; org names are slugs,
so StackGuardian-<org> is always valid. status and remove recognise both name
generations and any entry pointing at a StackGuardian MCP URL, and remove
without --name clears every such entry.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyMjkoCS1ic9P14Yo3dLLh
@arunim2405 @claude
docs(spec): SSO accounts create an API access key in place on the con…
506d84e 
…nect page

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyMjkoCS1ic9P14Yo3dLLh
@arunim2405 @claude
feat(auth): accept the credential as a form POST and link the landing…
8c9a00e 
… page back

The dashboard now hands the credential to the loopback with a form POST
instead of a GET redirect, so the key never sits in the browser history,
a Referer header or the request line; GET stays for manual use. The
landing pages (success, cancelled, refused) link back to the dashboard so
Cancel never strands the user on a loopback page. Bodies are capped at
64 KiB; a wrong state is refused without closing the listener.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyMjkoCS1ic9P14Yo3dLLh
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@arunim2405