Waniwani SDK — Build MCP funnels

@waniwani/kit builds an MCP app as a folder. You write tools, widgets and flows into a directory, and one CLI turns that directory into a deployable MCP server. Your repo holds none of the plumbing. The server bootstrap, the transport wiring and the build configuration live in the package. Your side is the distribution MCP itself, meaning the tools, the widgets, the funnel and the content. The kit owns everything technical underneath it: the server, the transport, bundling, the deploy files, and keeping up with framework upgrades.

oney/                          # what you write
├── waniwani.config.ts
├── tools/check-eligibility.ts
├── widgets/select-plan/{widget.ts,ui.tsx}
└── flows/split-payment.ts

waniwani build                 # → .waniwani/, an ordinary npm project

Quickstart

Scaffold an app with init and have the dev server running in one command.

Folder convention

Which folder becomes which MCP surface, and how names are derived.

Widgets

Two files per widget, one schema for input, output and props.

Deploy

Vercel, Docker or Alpic. The build writes the config, so deploying is a push.

The three packages

Three packages ship under the @waniwani scope. The pair people mix up is the kit and the SDK, so start there.

	What it is	You use it when
`@waniwani/sdk`	A library. Flows (typed state graphs that compile to one MCP tool), event tracking, knowledge base, chat widget. You supply the `McpServer`, the transport and the build.	You already have an MCP server, or you want one you control down to the last line, and you want funnels, tracking or a knowledge base inside it.
`@waniwani/kit`	A framework. Folder convention, build CLI, shared server runtime. It owns the server, the transport, the bundler and the deploy files, so your repo can hold none of them.	You want to ship an MCP app and own no plumbing.
`@waniwani/cli`	The platform CLI. `login`, `logout`, `switch`, `connect`. OAuth into Waniwani, bind a repo to a hosted agent, run against the hosted playground.	You want your local server wired to app.waniwani.ai.

The SDK is documented under the SDK tab and the platform CLI on its own page.

Kit against SDK, in code

With the SDK, the server is a file you write and keep:

src/server.ts

// yours to maintain
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const server = new McpServer({ name: "oney", version: "1.0.0" });

server.registerTool(
  { name: "check-eligibility", title, description, inputSchema, annotations },
  async (input) => { /* … */ },
);
await flow.register(server);
await server.connect(new StreamableHTTPServerTransport(/* … */));

Around that file you also own a tsconfig.json, a bundler config for any widget UI, a Dockerfile and the deploy config each host wants. With the kit, you write the part that answers the question and nothing around it:

tools/check-eligibility.ts

export default defineTool({ title, description, input, output, hints, run });

The kit finds that file, derives its tool name, registers it, bundles any widget that goes with it, and emits a deployable project. One copy of the plumbing exists, it lives in the package, and fixing it costs one publish plus a dependency bump per app. The kit depends on the SDK, and the SDK knows nothing about the kit. Inside a kit app, createFlow(...) comes from the SDK, while defineApp, defineTool, defineWidget and the server that registers them come from the kit.

What the kit gives you

Names from the filesystem. tools/check-eligibility.ts registers as check-eligibility. Nothing is listed in a registry, so no widget can sit defined and unwired.
Failures surface at build time. Structure is validated from the filesystem, then every server-safe module is imported for real. A flow that names a widget which does not exist fails the build instead of a request.
One runtime for every app. Error envelopes, annotation defaults, the CSP block and tracking through withWaniwani sit in one place.
Leaving is one command. waniwani eject writes the plumbing into your repo and steps out. See Eject.

Run through the Quickstart, or read the folder convention first if you would rather know the rules before typing.

Get started

Write the app

Build and ship

What is the Kit?

Quickstart

Folder convention

Widgets

Deploy

The three packages

Kit against SDK, in code

What the kit gives you

Next

Quickstart

Folder convention

Widgets

Deploy

​The three packages

​Kit against SDK, in code

​What the kit gives you

​Next

The three packages

Kit against SDK, in code

What the kit gives you

Next