ts-mcp-starter

A minimal Bun + TypeScript + Biome starter that ships a working MCP (Model Context Protocol) server simulating weather queries. No external API calls — responses are deterministic mock data seeded by city + date.

Stack

• Runtime: Bun 1.x (TypeScript natively, no build step required)
• Language: TypeScript (strict)
• Lint/format: Biome
• MCP: @modelcontextprotocol/sdk over stdio

Setup

bun install

Tools exposed by the server

Tool	Description
get_current_weather	Simulated current conditions for any city. Args: city, units (metric / imperial).
get_forecast	1–7 day simulated forecast. Args: city, days, units.
list_supported_cities	Cities with curated baseline climate (others fall back to a default profile).

All output is JSON text. Values are deterministic per (city, hour) for current weather and per (city, date) for forecasts.

Run locally

The same server supports two MCP transports simultaneously:

Transport	When to use	How to start
stdio	Local MCP clients that launch the process (Cursor, Claude Desktop, etc.)	bun run start
Streamable HTTP	Remote use — any MCP client that speaks the Streamable HTTP transport	bun run start:http
Both at once	Single process exposes stdio and HTTP	bun run start:both

Useful scripts:

bun run start          # stdio only
bun run start:http     # Streamable HTTP on http://127.0.0.1:3000/mcp
bun run start:both     # stdio + HTTP in one process
bun run dev            # stdio, watch mode
bun run dev:http       # HTTP, watch mode
bun run test           # bun test (stdio + HTTP + unit)
bun run typecheck      # tsc --noEmit
bun run check          # biome lint + format

CLI flags (also work in any combination): --stdio, --http, --both, --port=4000, --host=0.0.0.0. Env vars: MCP_HTTP=1, MCP_STDIO=1, PORT / MCP_PORT, MCP_HOST.

Streamable HTTP details

• Endpoint: POST/GET/DELETE /mcp on the configured port (default 3000).
• Health check: GET /health → ok.
• Stateful sessions: the server issues an Mcp-Session-Id header on initialize; clients must echo it on every subsequent request. Each session gets its own McpServer instance.
• Supports both SSE streaming responses and JSON responses (negotiated by the client's Accept header).
• DELETE /mcp with a valid Mcp-Session-Id terminates that session.

Quick smoke test (no client needed)

{
  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'
  printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'
  printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
  printf '%s\n' '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_current_weather","arguments":{"city":"Tokyo"}}}'
} | bun run src/index.ts

Wire it into an MCP client

Local (stdio) — Cursor / Claude Desktop mcp.json:

{
  "mcpServers": {
    "weather-demo": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/ts-mcp-starter/src/index.ts"]
    }
  }
}

Remote (Streamable HTTP) — run bun run start:http on the host, then point a Streamable-HTTP-capable MCP client at:

http://your-host:3000/mcp

Project layout

src/
  index.ts     CLI dispatcher (--stdio / --http / --both)
  server.ts    createServer() factory: McpServer with the three weather tools
  stdio.ts     stdio transport bootstrap
  http.ts     Streamable HTTP transport on Bun.serve (stateful sessions)
  weather.ts   Pure functions that generate simulated weather data
tests/
  weather.test.ts          unit tests for the simulation functions
  mcp-server.test.ts       end-to-end JSON-RPC over stdio (hand-written client)
  mcp-http.test.ts         end-to-end JSON-RPC over Streamable HTTP (hand-written client)
  mcp-client-sdk.test.ts   end-to-end tests via the official MCP Client SDK (stdio + HTTP)
biome.json     Lint + format config
bunfig.toml    Bun config
tsconfig.json  Strict TS for editor / typecheck