learn TypeScript MCP

Learning monorepo for the Model Context Protocol TypeScript SDK, built on Bun workspaces. Each learning topic lives in its own app under apps/ — new topics get a new apps/<topic> workspace.

To install dependencies for all workspaces:

bun install

Weather app (apps/weather/) — NestJS + MCP

Follows the official MCP TypeScript SDK "Build your first server" / "Build your first client" tutorials, using the real NWS weather API — hosted inside a NestJS app.

• apps/weather/src/main.ts — Nest HTTP bootstrap (port 3000, bodyParser: false)

• apps/weather/src/stdio.ts — stdio entry point (Nest application context, logger disabled so stdout stays protocol-only)

• apps/weather/src/weather/weather.service.ts — NWS API calls (getActiveAlertHeadlines, getForecastPeriods)

• apps/weather/src/weather/weather-mcp.service.ts — builds the McpServer, registers get-alerts / get-forecast, owns the shared HTTP transport

• apps/weather/src/weather/mcp.controller.ts — routes every method on /mcp into the MCP transport

• apps/weather/src/weather/express-web-bridge.ts — converts Express req/res ↔ web-standard Request/Response (the SDK's v2 transport is web-standard only)

• apps/weather/client.ts — example client (spawns the stdio server itself)

• apps/weather/test/mcp-http.test.ts — bun test boots the Nest app on an ephemeral port and connects a real streamable-HTTP MCP client

• tutorial/weather-server.ts — compatibility shim for clients still pointing at the old pre-monorepo path (e.g. a saved MCP Inspector connection); safe to delete once nothing references it

Both tools declare default values in their input schemas for development convenience — Inspector pre-fills its form with them (state: CA, latitude/longitude: San Francisco), so you can hit "Run Tool" without typing. Callers that pass their own arguments override them; the defaults only apply when an argument is omitted.

Run the stdio server

Each client that connects (Claude Code, Inspector, client.ts) spawns its own private copy of this process — it's not a shared server.

bun run weather:stdio

Run the HTTP server

One shared process that clients connect to over the network. Kill this terminal and every connected client loses the connection immediately.

bun run weather:http

Run the example client

bun run weather:client

Run the tests / typecheck

bun test          # from apps/weather/ (or the repo root)
bun run typecheck # from the repo root — tsc over both apps

Related MCP server: MCP Test Server

Tax assistant (apps/tax-assistant/)

Minimal stdio MCP server with a single calculate-vat tool (Thai VAT 7%):

bun run tax:stdio

Knowledge base (apps/knowledge-base/)

Persistent notes-with-tags server backed by bun:sqlite (apps/knowledge-base/src/db.ts, apps/knowledge-base/src/notes.ts). Unlike weather/tax-assistant, this app exercises all three MCP primitives:

• Tools (actions a client explicitly calls): add-note, get-note, search-notes, list-notes, delete-note, add-tags, list-tags

• Resources (data a client can pull into context without a tool call): kb://notes (JSON index of every note) and the kb://notes/{id} template (one note as markdown)

• Prompts (reusable message templates a client can surface as a menu item): summarize-notes-by-tag, which embeds matching notes' content into the generated prompt

The SQLite file (apps/knowledge-base/knowledge-base.sqlite, plus its -wal/-shm sidecars) is created on first run and gitignored — each clone starts with an empty knowledge base.

bun run kb:stdio

Inspect/test with MCP Inspector

bunx @modelcontextprotocol/inspector

Opens a browser UI (proxy on port 6277, UI on port 6274). In the sidebar, connect it either way:

• stdio: Transport Type STDIO, Command bun, Args apps/weather/src/stdio.ts

• HTTP: Transport Type Streamable HTTP, URL http://localhost:3000/mcp — requires the HTTP server (bun run weather:http) to already be running

Inspector remembers your last-used connection in the browser and auto-reconnects with it on load/refresh — always check the sidebar's Transport Type/URL before assuming what it's actually connected to.

To switch between this repo's stdio servers without retyping Command/Args each time, use mcp.inspector.json (same mcpServers shape as .mcp.json):

bunx @modelcontextprotocol/inspector --config mcp.inspector.json --server knowledge-base
# or --server weather / --server tax-assistant

There's no in-UI dropdown to swap servers from a config file — picking a different one means relaunching with a different --server value.

Inspecting multiple servers at once

One Inspector instance connects to exactly one server. To inspect two or three at the same time, run separate instances on separate ports (CLIENT_PORT/SERVER_PORT) and open each in its own browser tab:

# terminal 1
CLIENT_PORT=6274 SERVER_PORT=6277 bunx @modelcontextprotocol/inspector --config mcp.inspector.json --server weather

# terminal 2
CLIENT_PORT=6280 SERVER_PORT=6281 bunx @modelcontextprotocol/inspector --config mcp.inspector.json --server tax-assistant

# terminal 3
CLIENT_PORT=6282 SERVER_PORT=6283 bunx @modelcontextprotocol/inspector --config mcp.inspector.json --server knowledge-base

Each opens its UI on its own port (http://localhost:6274, :6280, :6282) — leaving CLIENT_PORT/SERVER_PORT unset on more than one instance will collide on the 6274/6277 defaults.

If you get PORT IS IN USE on 6274/6277, a previous Inspector instance didn't shut down cleanly (it can leave its proxy process orphaned even after reporting failure). Find and kill it before retrying:

lsof -nP -iTCP:6274,6277 -sTCP:LISTEN
kill <PID>

Connect to Claude Code

.mcp.json registers the weather server, pointed at the HTTP transport — start the Nest server (bun run weather:http) yourself before opening a Claude Code session here, or /mcp will show it disconnected.

NestJS-on-Bun notes

• No nest-cli/webpack build step — Bun runs the TypeScript entrypoints directly (bun src/main.ts).

• tsconfig.json enables experimentalDecorators + emitDecoratorMetadata; Bun's transpiler honors both, which is what makes Nest constructor injection work.

• Nest still uses its Express adapter internally; only the runtime and package manager are Bun.