# effect-stateless-mcp

A **stateless MCP server** (Model Context Protocol, spec **2026-07-28**) that exposes a `greet` tool. Built and tested with [Effect.ts](https://effect.website) v4 and run on [Bun](https://bun.com).

The server is fully stateless: a fresh `McpServer` instance is created per HTTP request, so no session state is retained between calls (no `initialize` handshake, no `Mcp-Session-Id`).

## Requirements

- [Bun](https://bun.com) (v1.3.14+)
- Node types are provided by Bun; no separate Node install needed

## Install

```bash
bun install
```

## Run

```bash
bun run src/index.ts
```

By default the server listens on `http://localhost:3000/mcp`. Override the port with the `PORT` environment variable (read via Effect's `Config`):

```bash
PORT=8787 bun run src/index.ts
```

### Calling the `greet` tool

Send a JSON-RPC `tools/call` request to the `/mcp` endpoint:

```bash
curl -s -X POST http://localhost:3000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "greet", "arguments": { "name": "Ada", "style": "formal" } }
  }'
```

The `greet` tool accepts:

| Field  | Type                      | Required | Description                          |
| ------ | ------------------------- | -------- | ------------------------------------ |
| `name` | `string`                  | yes      | Name to greet (trimmed, 1–100 chars) |
| `style`| `"formal" \| "casual"`    | no       | Greeting style (defaults to `casual`)|

## Test

Tests use [vitest](https://vitest.dev) with `@effect/vitest`:

```bash
bun run test
```

## Type-check

```bash
bunx tsc --noEmit
```

## Project structure

| File               | Responsibility                                                        |
| ------------------ | --------------------------------------------------------------------- |
| `src/greeting.ts`  | Domain logic — `makeGreeting` and the typed `GreetingError`.          |
| `src/server.ts`    | Stateless MCP handler — registers the `greet` tool via `createMcpHandler`. |
| `src/index.ts`     | Entry point — starts `Bun.serve` on the configured port via `BunRuntime.runMain`. |

## License

See repository for details.