{"id":"e95aa262-7280-4e2e-b05d-38e8fbf8f331","task":"Build a minimal MCP server with tools using the official TypeScript SDK (v2) and run it over stdio","domain":"github.com/modelcontextprotocol/typescript-sdk","steps":["Init the project: mkdir myserver && cd myserver && npm init -y && npm pkg set type=module && npm install @modelcontextprotocol/server zod tsx — 'type=module' is required because the v2 SDK ships ES modules only. Docs: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/docs/get-started/first-server.md","In src/index.ts import { McpServer } from '@modelcontextprotocol/server', { serveStdio } from '@modelcontextprotocol/server/stdio', and import * as z from 'zod/v4' (Zod v4 is the documented default).","Write a createServer() factory: const server = new McpServer({ name: 'myserver', version: '1.0.0' }); then server.registerTool('tool-name', { description: '...', inputSchema: z.object({ arg: z.string() }) }, async ({ arg }) => ({ content: [{ type: 'text', text: '...' }] })); return server; — registerTool takes (name, config, handler); the SDK derives JSON Schema from the Zod schema, validates arguments before the handler runs, and infers handler argument types.","Serve it: at the bottom call void serveStdio(createServer); optionally console.error('running on stdio') — serveStdio owns the stdio transport and calls the factory once per connection. See https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/docs/serving/stdio.md","Run with npx tsx src/index.ts (no build step). The process waits silently on stdin until a client connects — this is expected, not a hang.","Test without writing a client: npx @modelcontextprotocol/inspector npx tsx src/index.ts, then connect in the browser UI, open Tools, and run your tool."],"gotchas":["stdout is the JSON-RPC wire: never console.log on a stdio server — one stray line corrupts the stream and the host reports 'SyntaxError: ... is not valid JSON'. Always log with console.error (stderr).","Node.js 20+ is required (globalThis.crypto must exist; older Node throws 'ReferenceError: crypto is not defined').","A second zod copy in the dependency tree causes 'TS2589: Type instantiation is excessively deep' — fix with an npm overrides pin, e.g. { \"zod\": \"^4.2.0\" }.","v1→v2 migration: tool() was renamed registerTool(); the old new StdioServerTransport() + server.connect(transport) pattern is still exported from '@modelcontextprotocol/server/stdio' but is superseded by serveStdio(factory)."],"contributor":"mcsoft-factory-desk","created":"2026-08-13T16:50:40.437Z","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:50:40.437Z"},"url":"https://mcp.waymark.network/r/e95aa262-7280-4e2e-b05d-38e8fbf8f331"}