mcp-distribution-template

# MCP Distribution Template This project is a template for building MCP servers with the [`@waniwani/sdk`](https://docs.waniwani.ai) & [Skybridge](https://docs.skybridge.tech). It is a starting point for building your own MCP App. ## Quick start ```bash cp .env.example .env # add WANIWANI_API_KEY (https://docs.waniwani.ai/setup/api-key) bun install # or npm install / pnpm install bun run dev # or npm run dev ``` - DevTools: http://localhost:3000 - MCP endpoint: http://localhost:3000/mcp To test in ChatGPT/Claude, expose the port with [ngrok](https://ngrok.com) or [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-guide), then add `<public-url>/mcp` under **Settings → Connectors → Create**. > Inside Claude Code, just run `/waniwani-sdk tunnel` — the skill starts the dev server and opens a public tunnel for you. ## Run with Docker ```bash docker build -t mcp-template . docker run --rm -p 3000:3000 --env-file .env mcp-template ``` - MCP endpoint: http://localhost:3000/mcp - Override the port with `-e PORT=8080 -p 8080:8080`. - `--env-file .env` supplies `WANIWANI_API_KEY` and `WANIWANI_PUBLIC_KEY` (see `.env.example`). ## Layout ``` server/src/ MCP server — tools, flows, resources web/src/widgets/ React widgets rendered in the chat client knowledge-base/ Markdown docs searched by the FAQ tool scripts/ Maintenance scripts (e.g. kb:ingest) api/index.ts Vercel serverless adapter alpic.json Alpic config vercel.json Vercel config ``` The server is platform-agnostic. `web/` widgets mount via `mountWidget(...)` from `skybridge/web`. ## Knowledge base (FAQ tool) The template ships with a `faq` tool that runs semantic search over the markdown files in `knowledge-base/` and answers general product questions. ```bash # 1. Add or edit .md files in knowledge-base/ (split into chunks by ## headings) # 2. Upload them to the WaniWani knowledge base: bun run kb:ingest # or npm run kb:ingest ``` Ingestion is **destructive** — it replaces all existing chunks for the environment with the current contents of `knowledge-base/`. Requires `WANIWANI_API_KEY`. ## Deploy For a managed deploy, choose Alpic or Vercel. To run it on your own infrastructure, self-host the Docker image. [](https://app.alpic.ai/new/clone?repositoryUrl=https%3A%2F%2Fgithub.com%2FWaniWani-AI%2Fmcp-distribution-template) OR [](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FWaniWani-AI%2Fmcp-distribution-template) ### Self-host with Docker The template ships a production `Dockerfile`, so you can deploy it to anything that runs containers (a VPS, Fly.io, Railway, Render, Cloud Run, Kubernetes, …). Build the image and run the container — see [Run with Docker](#run-with-docker) for the commands. For a hosted deployment: - Publish the image to your registry (or build it on the host), then run the container behind your platform's router. - The MCP endpoint is served at `http://<your-host>/mcp` — port `3000` by default. Set `PORT` to match your platform and map it, e.g. `-e PORT=8080 -p 8080:8080`. - Supply `WANIWANI_API_KEY` and `WANIWANI_PUBLIC_KEY` as environment variables / secrets on the host rather than baking a `.env` file into the image. ## Docs - Waniwani SDK: [docs.waniwani.ai](https://docs.waniwani.ai/introduction) - MCP: [modelcontextprotocol.io](https://modelcontextprotocol.io) - Skybridge: [docs.skybridge.tech](https://docs.skybridge.tech) - Vercel: [vercel.com](https://vercel.com)