Lesson 12 — The TypeScript MCP SDK

Port L04's hello-world to TypeScript with the official SDK, Zod schemas, and a pino log line per call.

MCP Servers Module 5

What we're building

The SDK's two-handler model

The TS SDK does not ship a decorator like FastMCP. You register two request handlers — ListToolsRequestSchema and CallToolRequestSchema — and dispatch inside CallTool by tool name.

server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [/* ... */] }));

server.setRequestHandler(CallToolRequestSchema, async (req) => {
  const { name, arguments: args } = req.params;
  if (name === "echo") return { content: [{ type: "text", text: await echoTool(args) }] };
  return { isError: true, content: [{ type: "text", text: `unknown tool: ${name}` }] };
});

Trade-off vs FastMCP: more boilerplate, more control over every seam.

StdioServerTransport

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const transport = new StdioServerTransport();
await server.connect(transport);

Same wire protocol as Python's stdio; same Inspector compatibility; same Claude-Desktop compatibility. Transport is swappable — L13 swaps in HTTP+SSE without touching tools.ts.

Zod vs Pydantic — the same job

class EchoInput(BaseModel):
    text: str

const EchoInput = z.object({
  text: z.string(),
});

Same role: validate at the runtime boundary, infer types statically. Zod just lives at the value level, not at the class level.

Why runtime validation matters in TS

• TS types erase at compile time.
• A tool argument from the wire is unknown until something validates it.
• Without Zod (or equivalent), your handler accepts {} and crashes at the first property access.
• Zod gives you three things at once:
  • A parsed, typed value.
  • A typed error if the shape is wrong.
  • A schema that doubles as the JSON Schema you advertise in ListTools.

z.infer<typeof Schema>

export const EchoInput = z.object({
  text: z.string().min(1).max(10_000),
});
export type EchoInput = z.infer<typeof EchoInput>;

One definition produces both a runtime validator and a compile-time type. No drift.

pino and the child-logger pattern

export const logger = pino({ base: { service: "pkb" } });

export function toolLogger(tool: string) {
  return logger.child({ tool });
}

Every tool grabs a child logger that pre-stamps {tool: "..."}. The rest of the log shape (phase, dur_ms, type) matches the Python log_tool_call decorator from L10.

The tool function shape

export async function echoTool(rawArgs: unknown): Promise<string> {
  const log = toolLogger("echo");
  const t0 = performance.now();
  log.info({ phase: "start" });
  try {
    const args = EchoInput.parse(rawArgs);
    const result = args.text;
    log.info({ phase: "ok", dur_ms: +(performance.now()-t0).toFixed(1), text_len: args.text.length });
    return result;
  } catch (err) {
    log.warn({ phase: "err", dur_ms: +(performance.now()-t0).toFixed(1), type: (err as Error).name });
    throw err;
  }
}

Each tool repeats the start/ok/err pattern. We don't extract a decorator yet — async-decorator support in TS is uneven across runtimes. We extract a helper in L15.

The dispatcher in server.ts

The CallToolRequestSchema handler switches on req.params.name and returns { content: [{ type: "text", text }] }:

server.setRequestHandler(CallToolRequestSchema, async (req) => {
  const { name, arguments: args } = req.params;
  if (name === "echo") {
    const text = await echoTool(args);
    return { content: [{ type: "text", text }] };
  }
  return { isError: true, content: [{ type: "text", text: `unknown tool: ${name}` }] };
});

tsx for dev, tsc for prod

npm run dev    # tsx src/server.ts  (runs TS source directly)
npm run build  # tsc                (emits dist/server.js)
npm start      # node dist/server.js

Dev loop is tsx — no separate compile step. Production runs tsc-compiled JS so the Docker image (L13) doesn't need TypeScript at runtime.

Connect to Inspector

npx @modelcontextprotocol/inspector node dist/server.js

Inspector boots, lists echo, you call it with {"text":"smoke"}, watch the log line in your terminal. Same workflow as mcp dev in Python — different harness, same loop.

What's in the lab

• Read src/server.ts, tools.ts, schemas.ts, logger.ts.
• npm run build — zero errors.
• Connect via the MCP Inspector.
• Call echo with {"text":"smoke"}.
• Confirm the log-line shape matches the Python L10 format.

Recap & what's next

• Two-handler model + Zod + pino = the TS PKB foundation.
• The start/ok/err log pattern survives the port intact.
• Project structure scales to L13–L15 without rework.