mcp-hello-typescript-server CLAUDE.md

mcp-hello-typescript-server — notes for Claude

A minimal MCP server built with TypeScript and the official @modelcontextprotocol/sdk — a good starting point for a new server or a demo. It exposes two tools: server_info (a health/status check) and greet (a friendly greeting in one of a handful of languages, defaulting to English). Built with npm, tsc, and make; a multi-stage Docker build compiles the TypeScript and runs it on a distroless Chainguard/Wolfi node base (cgr.dev/chainguard/node). It is the TypeScript port of the sibling Python mcp-hello-server, following the official MCP Build a server (TypeScript) reference (alongside the Go mcp-hello-go-server and Rust mcp-hello-rust-server ports).

Layout

• src/greetings.ts — greeting data (GREETINGS), language resolution (names, aliases, ISO codes), and the greet() builder. Unit-tested in tests/greetings.test.ts.
• src/server.ts — createServer() builds the McpServer, defines the tool input/output schemas (zod) and handlers, and registers them with server.registerTool. Tools return structuredContent for the structured result.
• src/version.ts — reads the version from package.json at runtime (the single source of truth) so the MCP handshake and server_info stay in sync.
• src/index.ts — the entry point; picks the transport from MCP_TRANSPORT and wires up stdio (StdioServerTransport) or streamable HTTP (StreamableHTTPServerTransport on a node:http server, stateless, mounted at /mcp).
• tests/server.test.ts — integration tests connecting a client and server over InMemoryTransport.createLinkedPair() (the analog of the Python suite's in-memory FastMCP client). No network, no subprocess.

Conventions

• Build / deps: npm. package.json / package-lock.json are committed and the Dockerfile installs npm ci from the lockfile. make build = tsc → build/. Run npm install after changing dependencies to refresh the lock.
• Version: the source of truth is "version" in package.json; make release bumps it with npm version. src/version.ts reads it at runtime.
• Running: make run (stdio, the default MCP transport, from source via tsx), make run-http (streamable HTTP on PORT, default 8000). The transport is chosen by MCP_TRANSPORT (stdio | http); the HTTP endpoint is /mcp.
• Tests / gate: make test (node --test), make check (prettier check + tsc --noEmit + tests) — the CI gate.
• Adding a language: add a row to GREETINGS in greetings.ts (and, optionally, an alias / ISO code to ALIASES). server_info reports the set automatically.
• Docker: the image defaults to HTTP transport (MCP_TRANSPORT=http, HOST=0.0.0.0, PORT=8000). TypeScript is compiled in a builder stage on cgr.dev/chainguard/node:latest-dev; the pruned production node_modules, the compiled build/, and package.json are copied onto cgr.dev/chainguard/node:latest, which has no shell / package manager and runs as the non-root node user (uid 65532). Its entrypoint is node, so the Dockerfile uses CMD ["build/index.js"]. make scan should report 0 CRITICAL/HIGH.
• Releasing: make release (BUMP=patch|minor|major, default patch) bumps the version in package.json (+ package-lock.json), commits, tags vX.Y.Z, pushes, and creates the matching GitHub Release from the CHANGELOG.md section. The tag triggers the GHCR + Docker Hub publish workflows. It refuses to run unless the tree is clean, you're on main, and CHANGELOG.md already has the new version's section.