# example-mcp-stateful

learning-first boilerplate for stateful MCP servers over Streamable HTTP with TypeScript SDK v2.

> part of a series: [stdio](https://github.com/yigitkonur/example-mcp-stdio) · [stateless](https://github.com/yigitkonur/example-mcp-stateless) · **stateful** (you are here) · [sse](https://github.com/yigitkonur/example-mcp-sse)

## what it does

- runs a stateful MCP server where sessions persist across requests with in-memory storage
- implements the full Streamable HTTP lifecycle: `POST /mcp` (JSON-RPC), `GET /mcp` (SSE stream), `DELETE /mcp` (session close)
- demonstrates SSE resumability via an in-memory event store with `Last-Event-Id` replay
- registers example tools (`add_note`, `list_notes`, `simulate_work`), resources (`session://overview`, `session://notes/{index}`), and a prompt (`study-notes`)
- includes a scaffold CLI to generate new projects from templates
- vendors MCP TypeScript SDK v2 pre-release tarballs for reproducible installs

## quick start

```bash
npm install
npm run dev
```

server starts at `http://127.0.0.1:1453`. endpoints:

- `POST /mcp` -- JSON-RPC requests
- `GET /mcp` -- SSE stream
- `DELETE /mcp` -- close session
- `GET /health` -- health check
- `GET /sessions` -- list active sessions

Docker alternative:

```bash
docker compose up --build -d
```

## scaffold cli

generate a new project from the included templates:

```bash
npm run create -- init my-mcp-app
```

options: `--force`, `--dir <path>`, `--sdk vendored|registry`. see [scaffold CLI docs](docs/03-scaffold-cli.md) for details.

## documentation

| doc | description |
|-----|-------------|
| [getting started](docs/01-getting-started.md) | install, run, verify endpoints |
| [architecture](docs/02-architecture.md) | module layout, session lifecycle, resumability |
| [scaffold cli](docs/03-scaffold-cli.md) | generate new projects from templates |
| [sdk v2 notes](docs/04-sdk-v2-notes.md) | v2 packages, vendoring, migration |
| [validation](docs/05-validation.md) | smoke tests, primitive checks, release checklist |

## sdk v2 context

this project targets MCP TypeScript SDK v2 pre-release (`2.0.0-alpha.0`). the v2 SDK splits the monolithic `@modelcontextprotocol/sdk` package into `server`, `node`, `client`, and `core`. this repo uses `@modelcontextprotocol/server` for `McpServer` and `@modelcontextprotocol/node` for `NodeStreamableHTTPServerTransport`. vendored tarballs under `vendor/mcp-sdk-v2/` ensure reproducible installs until v2 reaches stable release.

## license

MIT