# MCP Production Demo (TypeScript)

A minimal but genuinely production-shaped MCP server: real API calls (live
GitHub API), typed config validation, structured logging, consistent error
handling, auth on the network transport, health checks, graceful shutdown,
Docker packaging, and tests. This is what the toy stdio scripts were missing.

## What's different from the toy version

| Concern | Toy version | This version |
|---|---|---|
| Data | hardcoded fake dict | live GitHub REST API |
| Config | none | `zod`-validated env, fails fast on boot if misconfigured |
| Errors | uncaught = crash/hang | every handler wrapped, typed errors, client never sees a stack trace |
| Logging | none | structured JSON (pino), stderr-only so it can't corrupt stdio protocol |
| Timeouts | none | every outbound call has an `AbortController` timeout |
| Auth | none | bearer token required on the HTTP transport |
| Transport | stdio only | both `stdio` (local/desktop) and `Streamable HTTP` (deployed) |
| Deployment | none | multi-stage Dockerfile, non-root user, health check |
| Tests | none | error-handling contract covered with `node:test` |

## Project layout

```
src/
  config.ts          env validation (zod) — the only place process.env is read
  lib/
    logger.ts         pino logger, stderr-only
    errors.ts         typed error classes (Validation / Upstream / Timeout)
    http.ts           fetch wrapper: timeout + typed errors
    safeTool.ts        wraps every tool: catch, log, clean client-facing result
  tools/
    github.ts          real tools: get_repo, search_issues (live GitHub API)
  mcpServer.ts          registers all tools onto an McpServer instance
  stdioEntry.ts         entrypoint for local/desktop clients
  httpEntry.ts           entrypoint for a deployed, authenticated server
  safeTool.test.ts        tests for the error-handling contract
```

## Setup

```bash
npm install
cp .env.example .env
# edit .env: add a GITHUB_TOKEN (unauthenticated GitHub calls are capped
# at 60/hour and will 403 fast — I hit this in testing), and if you'll
# run the HTTP transport, an MCP_AUTH_TOKEN (openssl rand -hex 32)
```

## Run it — stdio (local/desktop)

```bash
npm run dev:stdio
```

This is what you'd point Claude Desktop / Claude Code at directly (see
their MCP config docs) instead of writing your own client script.

## Run it — HTTP (deployed)

```bash
MCP_TRANSPORT=http npm run dev:http
# in another terminal:
curl http://localhost:3000/health
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
```

A request with no/wrong `Authorization` header gets a `401` before it ever
reaches the MCP layer.

## Tests

```bash
npm test
```

Covers the actual thing that matters in production: no matter what a tool
handler throws, the client always gets back a well-formed
`{ content, isError }` — never a raw stack trace, never a hang.

## Docker

```bash
docker build -t mcp-production-demo .
docker run -p 3000:3000 \
  -e MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
  -e GITHUB_TOKEN=ghp_xxx \
  mcp-production-demo
```

Multi-stage build (compiled output only ships, no `devDependencies`),
runs as a non-root user, has a `HEALTHCHECK`.

## Production decisions worth understanding (not just copying)

- **Logs go to stderr, always.** stdout is reserved for the JSON-RPC
  protocol stream on the stdio transport. A single stray `console.log`
  would silently corrupt every message after it — this bit me in early
  testing of similar setups, which is why `logger.ts` calls it out
  explicitly.
- **Fail fast on bad config.** `config.ts` validates env vars at import
  time and calls `process.exit(1)` on failure, with the specific field
  that's wrong. A server that boots "successfully" into a broken state is
  worse than one that refuses to start.
- **Never forward raw errors to the client.** `safeTool.ts` logs full
  detail server-side (including stack traces for unexpected errors) but
  only ever returns a small set of clean, typed messages to the MCP
  client. I confirmed this live: an unauthenticated call to the GitHub API
  from this sandbox hit their real rate limit and returned a `403` with a
  detailed message — the client only saw "The upstream service returned
  an error (403). Please try again later," while the full GitHub response
  was in the server log.
- **Stateless HTTP by default.** Each `/mcp` request gets a fresh
  `McpServer` + `StreamableHTTPServerTransport`. No shared session state
  means it scales horizontally with zero coordination. If you need
  long-lived stateful sessions (e.g. server-initiated notifications
  between calls), you'd switch to the SDK's stateful mode with a
  `sessionId -> transport` map — more capable, more to get right.
- **Every outbound call has a timeout.** `lib/http.ts` uses
  `AbortController` so a hung upstream can't hang your tool call
  indefinitely and, transitively, whatever's waiting on it.
- **Graceful shutdown matters for zero-downtime deploys.** `httpEntry.ts`
  handles `SIGTERM`/`SIGINT` by stopping new connections and waiting for
  in-flight ones to finish, with a forced-exit timeout as a backstop.
  Without this, a rolling deploy on k8s/ECS kills in-flight requests
  mid-response.

## Where this still isn't "enterprise production"

Being straight about the gaps rather than overselling it:
- **Auth is a single shared bearer token.** Fine for an internal tool;
  for anything multi-tenant you'd want the SDK's OAuth support instead.
- **No rate limiting on the HTTP endpoint itself** (only on the upstream
  GitHub calls) — add something like `express-rate-limit` before internet
  exposure.
- **No metrics/tracing** (Prometheus, OpenTelemetry) — logs alone aren't
  enough to debug latency issues at scale.
- **No CI pipeline** — `npm test` and `docker build` should run in GitHub
  Actions (or similar) on every PR, not just locally.