# @stepskit/mcp

[![npm version](https://img.shields.io/npm/v/@stepskit/mcp.svg)](https://www.npmjs.com/package/@stepskit/mcp)
[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)

The [StepsKit](https://stepskit.com) MCP server — install StepsKit and author in-app
guidance (product tours, contextual tooltips, NPS surveys, and announcement banners)
from your codebase through your AI coding agent. Works with Claude Code, Claude
Desktop, Cursor, Windsurf — any MCP client.

Because the MCP runs inside your agent — which has your codebase on disk — it can
do the whole setup for you. Ask your agent to **"set up StepsKit in this project
and build an onboarding tour"** and it will:

1. Check whether the embed is installed (`get_integration_status`).
2. Detect your framework and add the embed snippet to the right file.
3. Verify the embed is live once you load a page (`verify_integration`).
4. Whitelist your production domain (`add_allowed_domain`).
5. Author the tour (`create_tour`) — created **unpublished**, so you review and
   publish it from the StepsKit dashboard.

Already have tours? Ask your agent to **"edit my onboarding tour"** and it will
`list_tours` → `get_tour` → change copy, buttons, settings, steps, theme, or
visibility in place.

Beyond tours, it authors three more surfaces (all created unpublished, like tours):

- **Tooltips** — single contextual indicators (a `?`/info glyph, a dot/pulse, or a
  "NEW"/"BETA" badge) anchored to one element that open a small popover on hover or
  click, with an optional CTA. _"Add a NEW badge tooltip next to the Settings button."_
- **NPS surveys** — bottom-corner slide-in cards with a recommend question on an
  NPS 0–10, 1–5, or emoji scale, an optional open-text follow-up, a thank-you
  message, and a re-survey window. _"Add an NPS survey for users on the pro plan."_
- **Announcements** — slim top/bottom banner strips (title, body, optional CTA and
  icon) with an optional schedule window. _"Announce the new reporting feature
  Monday through Friday."_

## Prerequisites

A StepsKit project (the free plan works) and an MCP access token for it
(`sk_live_...`), minted in the [StepsKit dashboard](https://stepskit.com/app) on
your project's **AI** page. The agent handles installing the embed for you — you
don't need to paste any snippet into your site by hand.

## Setup

Add the server to your MCP client config:

```json
{
  "mcpServers": {
    "stepskit": {
      "command": "npx",
      "args": ["-y", "@stepskit/mcp"],
      "env": {
        "STEPSKIT_TOKEN": "sk_live_..."
      }
    }
  }
}
```

Or with Claude Code:

```bash
claude mcp add stepskit --env STEPSKIT_TOKEN=sk_live_... -- npx -y @stepskit/mcp
```

`STEPSKIT_API_URL` is optional (defaults to `https://stepskit.com`).

## Tools

31 tools across seven groups. Each tool carries a full JSON schema, and
`get_capabilities` returns the authoritative can/can't list — so your agent always
knows the current surface without relying on this README.

| Group | Tools |
| ----- | ----- |
| Setup & integration | `get_integration_status` (call first — onboarding state + install snippet), `verify_integration`, `add_allowed_domain`, `suggest_url_pattern` (turn a concrete URL into a wildcard `url_pattern` for dynamic routes), `get_capabilities` |
| Tours | `list_tours`, `get_tour`, `create_tour`, `update_tour_config` (name + behavior settings), `update_tour_visibility` (targeting / url pattern / frequency / trigger), `update_tour_theme` |
| Steps | `add_step`, `update_step` (keeps the step id and its analytics — prefer over delete+add), `delete_step`, `reorder_steps` |
| Tooltips | `list_tooltips`, `get_tooltip`, `create_tooltip`, `update_tooltip`, `delete_tooltip` |
| Surveys | `list_surveys`, `get_survey`, `create_survey`, `update_survey` |
| Announcements | `list_announcements`, `get_announcement`, `create_announcement`, `update_announcement`, `delete_announcement` |
| Project theme | `get_project_theme`, `update_project_theme` (global theme every tour and tooltip inherits) |

## What it deliberately does NOT do

The agent composes the plan; this server validates it and persists it. Guardrails:

- **It never publishes.** Everything it creates arrives unpublished — publishing is
  a deliberate human action in the dashboard.
- **Destructive operations require `confirm: true`** (`delete_step`,
  `delete_tooltip`, `delete_announcement`).
- **No media uploads and no analytics reads** — those stay in the dashboard.

## Security

The token is a long-lived, per-project credential. Keep it out of committed files
(use the MCP client's env config, not a checked-in JSON). Tokens are prefixed
`sk_live_` so secret-scanners recognize a leak. Revoke a token any time from the
dashboard's AI page.

## About this repository

This is the source of the published `@stepskit/mcp` package. StepsKit is developed
in a private monorepo; this mirror is synced from it on every release, and npm
releases are built from the same source via tag-driven CI. Issues and bug reports
are welcome here.

## License

MIT — this package. The StepsKit platform itself is a commercial SaaS.

## Learn more

- **StepsKit** — [stepskit.com](https://stepskit.com)
- **Build tours with your AI coding agent** — [stepskit.com/features/ai-agents](https://stepskit.com/features/ai-agents)
- **Docs: connecting an agent** — [stepskit.com/docs/ai-agents](https://stepskit.com/docs/ai-agents)
- **Dashboard** — [stepskit.com/app](https://stepskit.com/app)