# stitchkit

> Contract-first backend framework for Bun and Node

Define your API once with defineContract() and get an HTTP API, MCP tools, AI-agent tools, a CLI and a fully-typed client — from a single source that cannot drift.

- Repository: https://github.com/max-listov/stitchkit
- Package: https://www.npmjs.com/package/stitchkit
- License: MIT
- Language: TypeScript
- Status: pre-1.0 — core stable and tested, public API may shift between minor versions

## Install

```bash
bun add stitchkit zod
```

## What it does

A modern backend exposes the same operations several ways: an HTTP API for the app,
MCP tools for assistants like Claude and Cursor, tool definitions for AI agents, and a
CLI for scripts. Written by hand that is one surface described many times. stitchkit
collapses them into a single contract — change it once and every surface moves with it.

One `defineContract()` produces:

1. **HTTP API** — plain REST routes on `Bun.serve()` or `srvx`, with no HTTP framework underneath.
2. **MCP tools** — for any Model Context Protocol client; your app never imports the MCP SDK.
3. **AI-agent tools** — tool definitions for the Vercel AI SDK.
4. **CLI** — every endpoint callable from scripts and Skills.
5. **Typed client** — inferred from the contract, no codegen and no build step.

## Requirements

- Bun >= 1.2 (first-class) or Node >= 22 via `stitchkit/node`
- TypeScript
- `zod` as a required peer dependency, so your app and stitchkit share one instance
- Optional peers, each used by one entrypoint only: `@modelcontextprotocol/sdk`, `ai`,
  `@tanstack/react-query` with `react-query-kit`, `socket.io`

## How it compares

- **tRPC** — its contract is the router type and exists only in TypeScript, so it cannot
  be walked to build other surfaces. tRPC speaks RPC; stitchkit emits ordinary REST routes.
- **ts-rest** — same philosophy, narrower scope: HTTP only, and it adapts to an existing
  framework rather than serving on its own.
- **Hono / Elysia** — a different layer: general-purpose HTTP frameworks with no contract
  object to reuse for assistant-facing surfaces.

Full comparison: https://maxlistov.com/stitchkit/vs.md

## When not to use it

- You need a full-stack framework — stitchkit owns the contract and the transport, not
  routing, rendering or your database.
- The API will only ever have one consumer; a plain router costs less.
- You are on a runtime older than Node 22.
- You need a stable 1.0 API today.
- You need GraphQL — out of scope.

## Documentation

- [Getting started](https://maxlistov.com/stitchkit/docs/guide/getting-started.md)
- [Contracts](https://maxlistov.com/stitchkit/docs/guide/contracts.md)
- [HTTP server](https://maxlistov.com/stitchkit/docs/guide/server.md)
- [Typed client](https://maxlistov.com/stitchkit/docs/guide/client.md)
- [Realtime](https://maxlistov.com/stitchkit/docs/guide/realtime.md)
- [Auth & errors](https://maxlistov.com/stitchkit/docs/guide/auth-and-errors.md)
- [MCP & AI agents](https://maxlistov.com/stitchkit/docs/guide/mcp-and-agents.md)
- [CLI](https://maxlistov.com/stitchkit/docs/guide/cli.md)
- [Multi-tenant / resource-scoped paths](https://maxlistov.com/stitchkit/docs/guide/multi-tenant.md)
- [Observability](https://maxlistov.com/stitchkit/docs/guide/observability.md)
- [Testing & deployment](https://maxlistov.com/stitchkit/docs/guide/testing-and-deployment.md)
- [Upgrading stitchkit](https://maxlistov.com/stitchkit/docs/guide/upgrading.md)
- [API reference](https://maxlistov.com/stitchkit/docs/api/reference.md)

Design decisions (architecture decision records): https://maxlistov.com/stitchkit/docs/decisions

---

Author: Max Listov · https://maxlistov.com · maxlistov@gmail.com