Enables testing of the MCP server by spawning it as a child process to validate its I/O behavior, supporting various test modes including coverage reporting.
Provides tools for generating Markdown-formatted explanations of calculations, practice problems, and tutoring content through various calculator functions.
Used to visualize and document the sequence diagram of parent-child process communication in the MCP server documentation.
Serves as the runtime environment for the MCP server, managing the process-based architecture and handling stdin/stdout communication streams.
Provides type safety and structure for the MCP server implementation, with the server being built using TypeScript 5.x.
Implements rigorous validation of incoming request parameters through Zod schemas to ensure type safety and prevent injection-style attacks.
STDIO | Stateful HTTP | Stateless HTTP | SSE
🎓 MCP STDIO Server - Educational Reference
A Production-Ready Model Context Protocol Server Teaching STDIO Transport and Process Isolation Best Practices
Learn by building a world-class MCP server with a focus on security, simplicity, and architectural resilience.
🎯 Project Goal & Core Concepts
This repository is a deeply educational reference implementation that demonstrates how to build a production-quality MCP server using the STDIO (Standard I/O) transport. It is the definitive guide for creating secure, efficient, and resilient locally-running tools.
Through a fully-functional calculator server, this project will teach you:
- 🏗️ Clean Architecture & Design: Master a layered architecture that separates business logic, protocol wiring, and state management, making the code maintainable and testable.
- ⚙️ Protocol & Transport Mastery: Correctly implement the
StdioServerTransport
by learning the critical distinction between thestdout
stream (for JSON-RPC messages) and thestderr
stream (for all logging). - 🛡️ Resilient Error Handling: Implement a "fail-fast" error philosophy using
McpError
to ensure predictable, protocol-compliant failure states and prevent leaking internal details. - 🔒 Inherent Security: Leverage the natural security boundary of process isolation, which prevents network-based attacks and contains the server in a secure sandbox provided by the operating system.
🤔 When to Use This Architecture
The STDIO transport is the simplest and most secure MCP transport. Its process-based architecture makes it the ideal choice for:
- IDE & Editor Extensions: Integrating AI-powered tools directly into development environments like VS Code.
- Command-Line Tools (CLIs): Building powerful, local command-line applications that leverage LLMs.
- Desktop Applications: Embedding MCP capabilities into native desktop applications as managed subprocesses.
- Secure Local Agents: Any scenario where tools must run locally without exposing network ports, ensuring maximum security and data privacy.
🚀 Quick Start
Prerequisites
- Node.js ≥ 20.0.0
- npm or yarn
- A basic understanding of how parent/child processes communicate.
Installation & Running
Essential Commands
📐 Architecture Overview
High-Level Principles
- Process Isolation: The server is a separate OS process, providing a hardware-enforced security boundary.
- Stream-Based Communication: All protocol messages are newline-delimited JSON-RPC 2.0 objects exchanged over
stdin
andstdout
. - Dedicated Logging Channel: All non-protocol output (logs, debug messages) must be written to
stderr
. - Zero Network Footprint: The server does not open any network ports, eliminating entire classes of vulnerabilities.
Architectural Diagram
Code Structure
The source code is intentionally structured for clarity and maintainability.
src/types.ts
: Contains only pure data structures, static constants, and the global logger. It acts as the project's stable "header file."src/server.ts
: The single source of truth for all logic, organized into clear, layered sections:- Global State: Defines the server's in-memory state (e.g.,
calculationHistory
). - Core Business Logic: Contains pure, testable functions (e.g.,
factorial
,performBasicCalculation
) that are completely unaware of the MCP protocol. - MCP Wiring: A set of
register...
functions that connect the business logic to the MCP SDK, defining tools, resources, and prompts. This is where the application's capabilities are composed. - Execution: The
main
function that bootstraps the server, handles the process lifecycle, and implements graceful shutdown.
- Global State: Defines the server's in-memory state (e.g.,
🔧 World-Class Best Practices
This server is built on a foundation of non-negotiable best practices for creating professional, resilient software.
1. Architecture: Composition over Configuration
Instead of a single, monolithic function, the server's capabilities are built using a clean, compositional pattern. The main createCalculatorServer
factory assembles the final server by calling a series of dedicated, single-responsibility functions.
The Principle: This pattern makes the server's features immediately discoverable by reading the factory's body. It's organized, scalable, and easy to reason about.
2. Logic: Co-location of Schemas and Handlers
Each tool, resource, or prompt is defined as a self-contained unit. Its Zod schema, metadata, and handler logic are co-located, making the code easy to understand, modify, and test.
The Principle: A developer should be able to understand everything about a tool by looking at a single, focused block of code, without hunting through other files.
3. Resilience: Advanced Error Handling Strategy
This server implements a sophisticated, multi-layered error handling approach that distinguishes between protocol-level and application-level failures.
The Principle: Never throw new Error()
. Always throw an instance of McpError
from the SDK. This ensures the client always receives a well-formed JSON-RPC error response and prevents internal details like stack traces from ever leaking.
Advanced Pattern - Application vs Protocol Errors: Some tools (like batch_calculate
) demonstrate application-level error handling where individual item failures don't fail the entire operation, providing granular error feedback while maintaining overall tool success.
4. Transport: Protocol-Safe Logging to stderr
This is the most critical rule for STDIO transport. stdout
is a sacred data channel reserved exclusively for JSON-RPC messages.
The Principle: All logging, debugging, and other non-protocol text must be written to the stderr
stream to avoid corrupting the communication channel.
📊 Features Implemented
This server implements a comprehensive set of capabilities to demonstrate the full power of the Model Context Protocol.
(The features table remains the same as it accurately reflects the server's capabilities.)
... (Tools, Resources, Prompts tables here) ...
🧪 Testing & Validation
(This section remains the same.)
... (Manual Request, Inspector, Test Suite sections here) ...
🏭 Deployment & Configuration
A STDIO server is not deployed like a web server. It is designed to be executed as a child process by a parent application.
Configuration
The server's behavior can be modified with command-line flags.
Flag | Description |
---|---|
--debug | Enables verbose debug logging to stderr . |
--help | Shows the help message and exits. |
Environment Variables
Variable | Description | Default |
---|---|---|
SAMPLE_TOOL_NAME | (Educational) Demonstrates dynamic tool registration via environment variables. When set, adds a simple echo tool with the specified name that takes a value parameter and returns test string print: {value} . This pattern shows how MCP servers can be configured at runtime. | None |
Production Readiness Checklist
- Process Isolation: The OS provides a natural security sandbox.
- Input Validation: Zod schemas are used for all incoming tool arguments.
- No Network Exposure: The server does not listen on any network ports.
- Sanitized Errors: Using
McpError
ensures no internal details are ever leaked. - Robust Lifecycle Management: The
main
function implements modular signal handlers (SIGINT
,SIGTERM
) and global exception handlers to ensure the server always exits cleanly with a specific exit code, making it a reliable citizen in any process-managed environment. - Compositional Architecture: Clean separation of setup functions (
setupGracefulShutdown
,setupGlobalErrorHandlers
) for maximum maintainability and testability.
Monitoring:
- Health & Logs: The parent process is responsible for monitoring the child process's health and capturing its
stderr
stream for logging. - Resources: Standard OS tools (
top
,htop
) can be used to monitor CPU and memory usage.
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
example-mcp-server-stdio
Related MCP Servers
- AsecurityAlicenseAqualityMCP server allowing any and all command execution over CMDLast updated -261820JavaScriptMIT License
- Python
- -securityFlicense-qualityexample-mcp-server-streamable-httpLast updated -TypeScript