> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waniwani.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install @waniwani/sdk in a new or existing project.

## Choose your approach

<CardGroup cols={2}>
  <Card title="Start from template" icon="rocket" href="#option-a-start-from-template">
    Clone a ready-to-go MCP app (server + widgets + UI) with the SDK pre-configured. Best for **new projects**.
  </Card>

  <Card title="Add to existing project" icon="plus" href="#option-b-add-to-existing-project">
    Install the SDK package into your existing MCP server or app. Best for **existing projects**.
  </Card>
</CardGroup>

The SDK is open source and works without an API key. Set `WANIWANI_API_KEY` to connect the [Waniwani Platform](/sdk/platform/overview) and unlock hosted state, tracking, knowledge base, and the chat widget on top.

***

## Option A: Start from template

The [MCP Distribution Template](https://github.com/WaniWani-AI/mcp-distribution-template) gives you a production-ready **MCP app** (server + widgets + UI) with the SDK, event tracking, flows, and widgets already wired up.

<Note>
  The template is an MCP app. If you only need a bare MCP server (no widgets or embedded UI), skip to [Option B](#option-b-add-to-existing-project) or follow the [Quickstart](/sdk/quickstart). The SDK works for both.
</Note>

<Steps>
  <Step title="Create your repo">
    Click **"Use this template"** on [GitHub](https://github.com/WaniWani-AI/mcp-distribution-template) to create a new repository from the template, or clone it directly:

    ```bash theme={null}
    git clone https://github.com/WaniWani-AI/mcp-distribution-template.git my-mcp-server
    cd my-mcp-server
    ```
  </Step>

  <Step title="Install and run">
    ```bash theme={null}
    bun install
    cp .env.example .env
    bun dev
    ```

    The template runs without an API key. Set `WANIWANI_API_KEY` in `.env` to connect the [Platform](/sdk/platform/overview) and enable hosted state, tracking, and the dashboard.
  </Step>

  <Step title="Customize">
    The template includes a reference flow (Alpine ski lessons) you can replace with your own. If you have the [agent skill](/sdk/guides/skills) installed, run `/waniwani-sdk initialize` to interactively scaffold a flow tailored to your business.
  </Step>
</Steps>

***

## Option B: Add to existing project

### Requirements

* Node.js 18.17 or newer (Node 20+ recommended)
* An MCP server runtime. The SDK is tested against:
  * [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
  * [Skybridge](https://github.com/alpic-ai/skybridge) (Alpic)
  * [`@vercel/mcp-handler`](https://www.npmjs.com/package/@vercel/mcp-handler)
* A Waniwani account at [app.waniwani.ai](https://app.waniwani.ai) — optional, only needed for [Platform](/sdk/platform/overview) features.

`@modelcontextprotocol/sdk` and `zod` are peer dependencies. Install them in your project if you do not already have them.

### Install

<CodeGroup>
  ```bash bun theme={null}
  bun add @waniwani/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @waniwani/sdk
  ```

  ```bash npm theme={null}
  npm install @waniwani/sdk
  ```

  ```bash yarn theme={null}
  yarn add @waniwani/sdk
  ```
</CodeGroup>

<Note>
  The SDK has zero runtime dependencies and targets a sub-5KB core bundle. It runs in long-lived Node processes, serverless functions, and edge runtimes.
</Note>

### Pick what you need

Three things you can add independently to an existing MCP server. Any subset works.

| Add                    | What it gives you                                                                                          | API key                                                                               |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `createFlow`           | Multi-step typed flows registered as a single MCP tool. The primary entry point.                           | Not required. Required only if you want hosted state instead of bringing a `KvStore`. |
| `withWaniwani(server)` | Wraps existing `registerTool` handlers to emit tracking events and bridge session IDs. No handler changes. | Required for events. Bridging works without.                                          |
| `waniwani()` client    | Direct calls to Platform APIs (custom events, `identify()`, KB search).                                    | Required.                                                                             |

### Add a flow to an existing server

Assume you already have an `McpServer` instance with some tools registered on it. Define a flow and `.register()` it alongside them:

```ts theme={null}
import { createFlow, END, MemoryKvStore, START } from "@waniwani/sdk/mcp";
import { z } from "zod";
import { server } from "./mcp-server"; // your existing McpServer

const onboardingFlow = createFlow({
  id: "onboarding",
  title: "User Onboarding",
  description: "Use when a new user wants to get started.",
  state: { name: z.string().describe("Their name") },
})
  .addNode({
    id: "ask_name",
    run: ({ interrupt }) =>
      interrupt({ name: { question: "What is your name?" } }),
  })
  .addEdge(START, "ask_name")
  .addEdge("ask_name", END)
  .compile({ store: new MemoryKvStore() });

await onboardingFlow.register(server);
```

`MemoryKvStore` is fine for development and tests. For production, plug in a real backend (Redis, Upstash, Cloudflare KV, DynamoDB) or set `WANIWANI_API_KEY` to use hosted state. See [KV store adapters](/sdk/flows/kv-store).

### Wrap an existing server for Platform tracking

If your server already has plain `registerTool` handlers and you just want them tracked, wrap it once. No changes to the handlers themselves:

```ts theme={null}
import { withWaniwani } from "@waniwani/sdk/mcp";
import { server } from "./mcp-server"; // your existing McpServer

withWaniwani(server);
```

```bash .env theme={null}
WANIWANI_API_KEY=wwk_...
```

Every wrapped tool call now emits a `tool.called` event to your [Waniwani dashboard](https://app.waniwani.ai). Without an API key, the wrapper still bridges session IDs and forwards widget metadata but emits no events. Safe to wrap unconditionally. See [Wrap your server](/sdk/configuration/wrap-server) for all options.

## Create a Platform client

The `waniwani()` client is needed only when you call Platform APIs directly (custom event tracking via `track()`, `identify()`, KB search). It is **not** required for `createFlow` or `withWaniwani`.

```ts theme={null}
import { waniwani } from "@waniwani/sdk";

const wani = waniwani();
```

With no arguments, the client reads `WANIWANI_API_KEY` from the environment and uses `https://app.waniwani.ai` as the base URL.

See [API keys](/sdk/configuration/api-key) for how to obtain and configure the key, and [Client & KV store reference](/sdk/reference/kv-store-api) for the full client config.

## Also supported

* **Project config file.** Drop a `waniwani.json` at the project root with `$schema` set to `https://docs.waniwani.ai/waniwani.json`. The SDK auto-loads it on the first `waniwani()` call; the CLI uses the same file for `connect`/`dev`/evals. No explicit import required.

Next: [get your API key](/sdk/configuration/api-key) (if you want Platform features), then [wrap your MCP server](/sdk/configuration/wrap-server).