You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This repository demonstrates a **learning-edition MCP calculator server using STDIO transport**. It showcases the classic local-pipe transport where the server runs as a child process and communicates via `stdin` and `stdout` using newline-delimited JSON-RPC messages.
14
+
This repository demonstrates a **learning-edition MCP calculator server using STDIO transport**. It is a reference implementation for the classic local pipe transport, where the server runs as a child process and communicates with a parent process via `stdin` and `stdout` using newline-delimited JSON-RPC messages.
15
+
16
+
This transport is the most performant and secure option for local inter-process communication (IPC).
14
17
15
18
### Key Characteristics
16
19
17
-
-**Zero-network latency**: Direct inter-process communication (microseconds)
18
-
-**Per-process state**: All state resets when the process exits
19
-
-**No sockets, no SSE, no HTTP**: Pure stdin/stdout communication
|**Ideal use case**|**Local CLI tools, IDE plugins**| Web apps, real-time updates | Enterprise APIs, complex workflows | Serverless, edge computing |
28
+
This table compares the four primary MCP transport mechanisms demonstrated in the learning series. The implementation in **this repository is highlighted**.
|**Ideal Use Case**| ✅ **CLI Tools, IDE Plugins**| Legacy Web Apps | Enterprise APIs, Workflows | Serverless, Edge Functions |
36
39
40
+
## 📐 Architecture and Flow
41
+
42
+
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`.
43
+
44
+
```mermaid
45
+
sequenceDiagram
46
+
participant Client (Parent Process)
47
+
participant Server (Child Process)
48
+
49
+
Client->>Server: Writes JSON-RPC request to stdin stream
50
+
Server-->>Client: Writes JSON-RPC response to stdout stream
51
+
52
+
Note over Client,Server: Communication is full-duplex, concurrent, and newline-delimited.
37
53
```
38
-
┌─────────────┐ stdin ┌─────────────┐
39
-
│ Client │ ─────────────────────► │ Server │
40
-
│ (Parent) │ │ (Child) │
41
-
│ Process │ ◄───────────────────── │ Process │
42
-
└─────────────┘ stdout └─────────────┘
43
-
44
-
JSON-RPC messages
45
-
(newline-delimited)
46
-
```
47
54
48
-
Each JSON-RPC message is sent as a single line terminated with `\n`. The server processes requests concurrently and emits progress notifications for long-running operations.
55
+
### Dual Server Implementations for Learning
56
+
57
+
This repository contains two distinct server implementations to illustrate different levels of abstraction:
58
+
59
+
1.**High-Level (SDK-based): `dist/server.js`**
60
+
- Built using the official `@modelcontextprotocol/sdk`.
61
+
- Uses high-level abstractions like `server.registerTool()` and `server.registerResource()`.
62
+
- Represents the standard, recommended approach for building MCP servers.
49
63
50
-
## 📊 Golden Standard Feature Matrix
64
+
2.**Low-Level (Manual): `dist/server-stdio.js`**
65
+
- A from-scratch implementation of the newline-delimited JSON-RPC protocol.
{"jsonrpc":"2.0","id":7,"result":{"description":"Explain the calculation: 25 × 4 at intermediate level with step-by-step breakdown","messages":[{"role":"user","content":{"type":"text","text":"Please explain how to calculate 25 × 4 step by step..."}}]}}
157
-
```
158
-
159
-
## 🛠️ Transport Internals
160
-
161
-
### Message Framing
179
+
## 🧠 State Management Model
162
180
163
-
- Each JSON-RPC envelope MUST end with `\n`
164
-
- No non-JSON output on `stdout` (diagnostic logs go to `stderr`)
165
-
- Supports concurrent request processing
181
+
**Principle:** State is ephemeral and strictly scoped to the lifetime of the server process.
166
182
167
-
### Concurrency Model
183
+
-**Mechanism:** All state is held in standard JavaScript variables and `Map` objects within the Node.js process.
184
+
-**Stored Data:**
185
+
-**Calculation History:** A `Map` stores the last 50 calculation results as a ring buffer.
186
+
-**Server Statistics:** Variables track the process start time and total request count.
187
+
-**In-flight Requests:** The MCP SDK maintains a `Map` to track concurrent requests and route responses correctly.
188
+
-**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.
168
189
169
-
- Maintains `Map<id, PromiseResolver>` for in-flight requests
170
-
- Notifications (no `id` field) are fire-and-forget
171
-
- Progress notifications reference original request ID
190
+
## 🛡️ Security Model
172
191
173
-
### Exit Codes
192
+
The STDIO transport provides the most secure environment of all MCP transports by leveraging operating system primitives.
174
193
175
-
-**0**: Normal shutdown
176
-
-**65**: Fatal parse error (EX_DATAERR)
177
-
-**70**: Unhandled exception (EX_SOFTWARE)
194
+
-**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.
195
+
-**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.
196
+
-**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.
197
+
-**Resource Limiting:** The server enforces hard limits on batch sizes (`maxBatchSize: 100`) and history storage (`maxHistorySize: 50`) to prevent resource exhaustion attacks.
198
+
-**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.
178
199
179
200
## 🧪 Testing
180
201
202
+
This project includes a test suite that spawns the server as a child process to validate its I/O behavior.
203
+
181
204
```bash
182
-
# Run all tests
205
+
# Run all tests defined in jest.config.js
183
206
npm test
184
207
185
-
# Run with coverage
208
+
# Run tests and generate a code coverage report
186
209
npm run test:coverage
187
210
188
-
# Run integration tests
189
-
npm run test:integration
190
-
191
-
# Watch mode for development
211
+
# Run tests in watch mode for interactive development
192
212
npm run test:watch
193
-
194
-
# Memory leak testing
195
-
npm run test:memory
196
213
```
197
214
198
-
### Test Coverage
199
-
200
-
The implementation includes comprehensive testing:
201
-
- Unit tests for all 7 tools
202
-
- Resource access validation
203
-
- Prompt generation testing
204
-
- Progress notification flow
205
-
- Error handling and exit codes
206
-
- Memory usage validation
207
-
208
-
## 📝 State Management
209
-
210
-
**Important**: All state is stored in process memory and resets when the process exits:
0 commit comments