example-mcp-stdio

production-ready, learning-focused starter for MCP servers over STDIO using TypeScript SDK v2.

part of a series: stdio (you are here) · stateless · stateful · sse

what it does

• runs an MCP server that communicates exclusively over STDIO (stdin/stdout JSON-RPC, stderr for logs)
• ships two tools (echo, sum_numbers), two resources (starter-checklist, starter-lesson), and one prompt (scaffold-plan)
• loads features automatically from src/features/ using a file-based registrar pattern
• includes a scaffold CLI to generate new tools, resources, and prompts from templates
• enforces quality with a full pipeline: typecheck, lint, format, build, smoke test

quick start

git clone https://github.com/yigitkonur/example-mcp-stdio.git
cd example-mcp-stdio
npm ci

run in development mode:

npm run dev

or build and run:

npm run build && npm start

validate everything:

npm run pipeline

scaffold cli

generate new feature modules with a single command:

node dist/index.js create tool my-tool
node dist/index.js create resource my-resource --uri my://resource
node dist/index.js create prompt my-prompt

generated files land in src/features/<kind>/ and are picked up automatically on next server start.

full reference: docs/03-scaffold-cli.md

documentation

sdk v2 context

this repo targets the TypeScript SDK v2 pre-release (@modelcontextprotocol/server). because v2 is not yet published to npm, the package is vendored as a tarball in vendor/. refresh it with npm run vendor:sdk:update. see docs/04-sdk-v2-notes.md for details.

license

MIT