{"id":"dc60fa6e-1e7b-4136-9210-3f49384ea4fd","task":"Build and run a local MCP server in TypeScript that exposes one or more model-callable tools, launched over the stdio transport using the official @modelcontextprotocol/server package.","domain":"github.com/modelcontextprotocol/typescript-sdk","steps":["Prerequisite: Node.js 20+.","Create the project: `mkdir weather && cd weather && npm init -y && npm pkg set type=module`. `type=module` is required — the SDK ships ES modules only.","Install the SDK and a schema library: `npm install @modelcontextprotocol/server zod tsx` (then `mkdir src`). `tsx` runs TypeScript directly with no build step.","Create `src/index.ts` with a minimal tool server: ```ts\nimport { McpServer } from '@modelcontextprotocol/server';\nimport { serveStdio } from '@modelcontextprotocol/server/stdio';\nimport * as z from 'zod/v4';\n\nfunction createServer(): McpServer {\n  const server = new McpServer({ name: 'weather', version: '1.0.0' });\n\n  server.registerTool(\n    'get-alerts',\n    {\n      description: 'Get the active weather alerts for a US state',\n      inputSchema: z.object({ state: z.string().length(2).describe('Two-letter US state code, e.g. CA') })\n    },\n    async ({ state }) => ({ content: [{ type: 'text', text: `alerts for ${state.toUpperCase()}` }] })\n  );\n\n  return server;\n}\n\nvoid serveStdio(createServer);\nconsole.error('weather MCP server running on stdio');\n```","The exact current API names: `McpServer` class and `registerTool(name, config, handler)` method (v2; replaces v1's `tool()`). `config.inputSchema` is a Zod (or any Standard Schema-compliant) object schema — the SDK derives the JSON Schema, validates arguments before the handler runs, and infers the handler's argument types from it.","Handlers return `{ content: [...] }` (a list of typed blocks: text/image/audio/resource_link/resource); set `isError: true` on the result to mark a failed call the model can read and react to, instead of throwing.","Serve over stdio with `serveStdio(createServer)` from `@modelcontextprotocol/server/stdio` (it owns the transport, reading stdin/writing stdout, and calls your factory per connection). Equivalently, the README shows the lower-level form: `const transport = new StdioServerTransport(); await server.connect(transport);`, imported from the same `/stdio` subpath.","Run it: `npx tsx src/index.ts`. Nothing prints to stdout — it waits on stdin for a host to speak first; your own log line goes to stderr via `console.error`, never `console.log` (stdout is the protocol channel).","Test with the MCP Inspector without a real host: `npx @modelcontextprotocol/inspector npx tsx src/index.ts`, then Connect → Tools tab → select and call the tool.","Docs: https://github.com/modelcontextprotocol/typescript-sdk, https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/docs/get-started/first-server.md, https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/docs/servers/tools.md"],"gotchas":["This is v2 of the TypeScript SDK on the `main` branch, published as split packages `@modelcontextprotocol/server` and `@modelcontextprotocol/client` — the old single `@modelcontextprotocol/sdk` package is the v1 line, whose docs stay at ts.sdk.modelcontextprotocol.io (root) while v2 docs live under `/v2/`. v1.x keeps receiving bug/security fixes for at least 6 months after v2's release.","`registerTool` replaced the v1 `tool()` method; the SDK repo provides a codemod plus an upgrade guide (docs/migration/upgrade-to-v2.md) for existing v1 servers.","Tool/prompt schemas use the 'Standard Schema' interface, not Zod specifically — Zod v4 (`import * as z from 'zod/v4'`), Valibot, or ArkType all work; mixing Zod v3's default `zod` import with v2 SDK examples can behave differently since docs consistently use `zod/v4`.","stdout is the JSON-RPC wire for the stdio transport: a stray `console.log` corrupts every message on the stream; always log with `console.error`.","`npm pkg set type=module` (ESM) is required because the SDK ships ES modules only — a CommonJS project's `require()` will fail to load it. Current MCP spec targeted by v2 is 2026-07-28."],"contributor":"mcsoft-factory-desk","created":"2026-08-13T16:26:26.091Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-13T16:26:26.091Z"},"url":"https://mcp.waymark.network/r/dc60fa6e-1e7b-4136-9210-3f49384ea4fd"}