Writing your first MCP server means getting the SDK calls, the zod schemas, stdout hygiene and the client config right at once. This kit is a working TypeScript project: five tools, typed outputs, 33 passing tests, a stdio smoke test and a Docker image that answered a tool call. Built on the 1.x SDK on 8 October 2026.
What You Get
- Five working tools. calculate_gst (exact to the paisa, CGST and SGST or IGST), slugify_text, summarize_csv, hash_text and date_difference, each a pure function plus a registered tool.
- Zod input and output schemas. Every argument has limits and a description the model can read, and every result is validated against an outputSchema and returned as structuredContent.
- Stdio entry point. Connects with StdioServerTransport, logs to stderr only, shuts down on SIGINT and SIGTERM, and keeps stdout clean for the protocol.
- 33 vitest tests. 25 unit tests on the pure functions and 8 integration tests that run a real client against the server over an in-memory transport, including error cases.
- Smoke test and Inspector script. npm run smoke spawns the built server over stdio, lists the tools and calls one. npm run inspect opens the MCP Inspector.
- Multi-stage Dockerfile. Node 22 Alpine, production dependencies only, runs as a non-root user, and was built and tested over stdio before shipping.
- Client configs. A claude mcp add command, a project .mcp.json example and a Claude Desktop config with node and Docker entries.
- Reference and guides. TOOLS.md with every argument and error, EXTENDING.md for adding a sixth tool with ten design rules, and TROUBLESHOOTING.md for stdout pollution, paths and Docker flags.
How to Use
- Run npm install, then npm test and confirm 33 tests pass.
- Run npm run build and npm run smoke to see the server answer over stdio.
- Register it with claude mcp add wowhow-starter -- node /absolute/path/dist/index.js, or copy the Desktop config.
- Open EXTENDING.md and add your own tool in src/tools following the same pattern.
- Add a test for it and update the expected tool list in tests/server.test.ts.
- Build the Docker image when you want to share or deploy it.
Who This Is For
- Developers writing their first MCP server in TypeScript.
- Teams that want a tested baseline instead of copying snippets from a README.
- Consultants building client tools who need schemas, errors and Docker done properly.
- Anyone who wants to see how tool annotations, structured output and error results should look.
Pinned ranges keep you on the stable 1.x SDK, and the tests tell you fast if an upgrade breaks something. Browse more in the MCP server templates collection, or try browse all products.
