Calculator Learning Demo - STDIO Transport

Calculator Learning Demo - STDIO Transport

🎯 Overview

This repository demonstrates a learning-edition MCP calculator server using STDIO transport. It showcases the Model Context Protocol (MCP) SDK implementation with standard tools/list and tools/call methods, communicating via stdin and stdout using JSON-RPC messages.

This transport is the most performant and secure option for local inter-process communication (IPC).

Key Characteristics

• Transport Layer: Direct stdin/stdout pipes between parent (client) and child (server) processes.
• State Model: Ephemeral, in-process memory. All state (e.g., calculation history) is lost when the process exits.
• Latency: The lowest possible latency (microseconds), as it avoids all network stack overhead.
• Security: Extremely high due to OS-level process isolation. There is no network attack surface.
• Use Case: Ideal for high-performance, secure local tooling, such as command-line interfaces (CLIs), IDE plugins, and build-system integrations.

📊 Transport Comparison

This table compares the four primary MCP transport mechanisms demonstrated in the learning series. The implementation in this repository is highlighted.

📐 Architecture and Flow

The STDIO transport architecture is based on a parent-child process model. A client application spawns the MCP server as a child process and communicates with it by writing to the child's stdin and reading from its stdout.

sequenceDiagram
    participant Client (Parent Process)
    participant Server (Child Process)

    Client->>Server: Writes JSON-RPC request to stdin stream
    Server-->>Client: Writes JSON-RPC response to stdout stream
    
    Note over Client,Server: Communication is full-duplex, concurrent, and newline-delimited.

MCP SDK Implementation

This repository contains a single, production-ready MCP server implementation:

• dist/server.js - Built with the official @modelcontextprotocol/sdk
• Uses standard MCP methods: tools/list, tools/call, resources/list, prompts/list
• High-level abstractions with server.registerTool() and server.registerResource()
• Compatible with all MCP clients and registries (including Smithery)

✨ Feature Compliance

This server implements the complete MCP Latest Standard feature set for the learning edition.

🚀 Getting Started

Prerequisites

• Node.js (v18.x or higher)
• npm or yarn

Installation

# Clone the repository
git clone https://github.com/modelcontextprotocol/mcp-server-examples.git
cd mcp-server-examples/stdio

# Install dependencies
npm install

# Build the project
npm run build

Running the Server

The server is designed to be spawned by a client. You can run it directly to send it commands interactively.

# Run the MCP server
npm start

# Run directly with Node.js
node dist/server.js --stdio

# Run in development mode
npm run dev

Testing with MCP Inspector

Interact with the SDK-based server using the official MCP Inspector CLI. This command spawns the server and pipes its I/O to the inspector.

npx @modelcontextprotocol/inspector --cli "node dist/server.js --stdio"

📋 API Usage Examples

All requests use standard MCP protocol with JSON-RPC messages.

Standard MCP Protocol

The server implements the standard MCP SDK protocol:

# List available tools
→ {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

# Call a tool
→ {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"calculate","arguments":{"a":7,"b":6,"op":"multiply"}}}

# Response
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"7 × 6 = 42"}]}}

Progress Demonstration

Progress notifications are sent as standard JSON-RPC notifications (no id field) over stdout.

# Request
→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"demo_progress","arguments":{}}}

# Response Stream
{"jsonrpc":"2.0","method":"progress","params":{"progressToken":"progress_3","progress":20,"total":100}}
{"jsonrpc":"2.0","method":"progress","params":{"progressToken":"progress_3","progress":40,"total":100}}
{"jsonrpc":"2.0","method":"progress","params":{"progressToken":"progress_3","progress":60,"total":100}}
{"jsonrpc":"2.0","method":"progress","params":{"progressToken":"progress_3","progress":80,"total":100}}
{"jsonrpc":"2.0","method":"progress","params":{"progressToken":"progress_3","progress":100,"total":100}}
{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Progress demonstration completed"}]}}

🧠 State Management Model

Principle: State is ephemeral and strictly scoped to the lifetime of the server process.

• Mechanism: All state is held in standard JavaScript variables and Map objects within the Node.js process.
• Stored Data:
  • Calculation History: A Map stores the last 50 calculation results as a ring buffer.
  • Server Statistics: Variables track the process start time and total request count.
  • In-flight Requests: The MCP SDK maintains a Map to track concurrent requests and route responses correctly.
• Lifecycle: When the process exits for any reason, all in-memory state is irrevocably lost. Each new process starts with a clean slate. This is a fundamental and intentional design choice for this transport.

🛡️ Security Model

The STDIO transport provides the most secure environment of all MCP transports by leveraging operating system primitives.

• Process Isolation: The server runs in a separate memory space from the client, preventing any direct memory access or interference. The OS enforces this boundary.
• No Network Exposure: Communication is entirely via local IPC pipes. There are no open ports, making network-based attacks (e.g., CSRF, MitM, remote exploits) impossible.
• Input Validation: All incoming request parameters are rigorously validated by Zod schemas (defined in src/types.ts) to ensure type safety and prevent injection-style attacks.
• Resource Limiting: The server enforces hard limits on batch sizes (maxBatchSize: 100) and history storage (maxHistorySize: 50) to prevent resource exhaustion attacks.
• Exit Code Signaling: The server uses standard Unix exit codes to signal its termination status to the parent process (e.g., 0 for success, 65 for data errors, 70 for software errors), allowing the client to react appropriately.

🧪 Testing

This project includes a test suite that spawns the server as a child process to validate its I/O behavior.

# Run all tests defined in jest.config.js
npm test

# Run tests and generate a code coverage report
npm run test:coverage

# Run tests in watch mode for interactive development
npm run test:watch

📚 Official Resources

• MCP Specification
• Model Context Protocol Documentation
• STDIO Transport Documentation