Skip to content

Commit 4296b79

Browse files
yigitkonurclaude
andcommitted
Streamline MCP server to single SDK implementation
- Remove custom STDIO server implementation (server-stdio.js) - Update all configurations to use standard MCP SDK server (dist/server.js --stdio) - Simplify README and CLAUDE.md to focus on single, production-ready implementation - Update package.json scripts and entry points - Remove custom protocol tests and references - Ensure compatibility with Smithery registry and all MCP clients 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 4574ffe commit 4296b79

File tree

8 files changed

+38
-1859
lines changed

8 files changed

+38
-1859
lines changed

CLAUDE.md

Lines changed: 15 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
44

55
## Project Overview
66

7-
This repository implements a **learning-edition MCP calculator server using STDIO transport**. It demonstrates the Model Context Protocol (MCP) with newline-delimited JSON-RPC communication over stdin/stdout, showcasing both modern MCP SDK usage and custom JSON-RPC implementation patterns.
7+
This repository implements a **learning-edition MCP calculator server using STDIO transport**. It demonstrates the Model Context Protocol (MCP) with standard JSON-RPC communication over stdin/stdout using the official MCP SDK.
88

99
## Development Commands
1010

1111
### Core Development
1212
- `npm install` - Install dependencies
13-
- `npm start` - Run the production STDIO server (`dist/server-stdio.js`)
13+
- `npm start` - Run the MCP server (`dist/server.js --stdio`)
1414
- `npm run dev` - Development mode with auto-reload
1515
- `npm run build` - Build TypeScript to JavaScript (may fail due to legacy API usage)
1616
- `npm run clean` - Remove dist directory
@@ -24,24 +24,22 @@ This repository implements a **learning-edition MCP calculator server using STDI
2424
- `npm run typecheck` - TypeScript type checking
2525

2626
### MCP Inspection
27-
- `npx @modelcontextprotocol/inspector --cli node dist/mcp-server.js --method tools/list` - List all 7 tools with schemas
28-
- `npx @modelcontextprotocol/inspector --cli node dist/mcp-server.js --method prompts/list` - List all 3 prompts
29-
- `npx @modelcontextprotocol/inspector --cli node dist/mcp-server.js --method resources/list` - List all 4 resources
30-
- `npx @modelcontextprotocol/inspector --cli node dist/mcp-server.js --method resources/read --uri "calculator://constants"` - Read specific resource
27+
- `npx @modelcontextprotocol/inspector --cli "node dist/server.js --stdio" --method tools/list` - List all 7 tools with schemas
28+
- `npx @modelcontextprotocol/inspector --cli "node dist/server.js --stdio" --method prompts/list` - List all 3 prompts
29+
- `npx @modelcontextprotocol/inspector --cli "node dist/server.js --stdio" --method resources/list` - List all 4 resources
30+
- `npx @modelcontextprotocol/inspector --cli "node dist/server.js --stdio" --method resources/read --uri "calculator://constants"` - Read specific resource
3131

3232
### Manual Testing
33-
- `echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculate","arguments":{"a":7,"b":6,"op":"multiply"}}}' | node dist/mcp-server.js` - Test MCP SDK server
34-
- `echo '{"jsonrpc":"2.0","id":1,"method":"calculate","params":{"a":7,"b":6,"op":"multiply"}}' | node dist/server-stdio.js` - Test custom JSON-RPC server
33+
- `echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculate","arguments":{"a":7,"b":6,"op":"multiply"}}}' | node dist/server.js --stdio` - Test MCP SDK server
3534

3635
## Architecture
3736

38-
### Dual Server Implementation
39-
The project provides **two functional server implementations**:
37+
### MCP SDK Implementation
38+
The project provides a **single, production-ready MCP server implementation**:
4039

41-
1. **`dist/mcp-server.js`** - Modern MCP SDK server using `registerTool()`, `registerResource()`, `registerPrompt()` APIs
42-
2. **`dist/server-stdio.js`** - Custom newline-delimited JSON-RPC server with manual message handling
43-
44-
Both servers implement the same 7 tools, 3 prompts, and 4 resources but use different communication protocols.
40+
- **`dist/server.js`** - MCP SDK server using standard `registerTool()`, `registerResource()`, `registerPrompt()` APIs
41+
- Implements standard MCP protocol with `tools/list`, `tools/call`, `resources/list`, `prompts/list` methods
42+
- Compatible with all MCP clients and registries including Smithery
4543

4644
### MCP Golden Standard Features
4745
- **7 Tools**: `calculate`, `batch_calculate`, `advanced_calculate`, `demo_progress`, `solve_math_problem`, `explain_formula`, `calculator_assistant`
@@ -77,23 +75,16 @@ The test suite focuses on STDIO transport validation:
7775

7876
## Message Protocol Specifics
7977

80-
### STDIO JSON-RPC Format
81-
```
82-
→ {"jsonrpc":"2.0","id":1,"method":"calculate","params":{"a":5,"b":3,"op":"add"}}
83-
{"jsonrpc":"2.0","id":1,"result":{"value":8,"meta":{"calculationId":"abc123","timestamp":"2024-..."}}}
84-
```
85-
86-
### MCP SDK Format
78+
### Standard MCP Protocol Format
8779
```
8880
→ {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculate","arguments":{"a":5,"b":3,"op":"add"}}}
8981
{"result":{"content":[{"type":"text","text":"5 + 3 = 8"}]},"jsonrpc":"2.0","id":1}
9082
```
9183

9284
## Key Implementation Files
9385

94-
- **`dist/mcp-server.js`** - Modern MCP SDK server (669 lines, production-ready)
95-
- **`dist/server-stdio.js`** - Custom JSON-RPC server (504 lines, reference implementation)
86+
- **`dist/server.js`** - MCP SDK server (production-ready)
9687
- **`src/tests/stdio-transport.test.ts`** - Integration tests for STDIO protocol
9788
- **`mcp-demo-manifest.json`** - Feature matrix documentation
9889

99-
When working with this codebase, prioritize the working `dist/` JavaScript files over the TypeScript source files.
90+
The server is built with the MCP SDK and uses standard protocol methods for maximum compatibility.

README.md

Lines changed: 18 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
## 🎯 Overview
1313

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.
14+
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.
1515

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

@@ -52,19 +52,14 @@ sequenceDiagram
5252
Note over Client,Server: Communication is full-duplex, concurrent, and newline-delimited.
5353
```
5454

55-
### Dual Server Implementations for Learning
55+
### MCP SDK Implementation
5656

57-
This repository contains two distinct server implementations to illustrate different levels of abstraction:
57+
This repository contains a single, production-ready MCP server implementation:
5858

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.
63-
64-
2. **Low-Level (Manual): `dist/server-stdio.js`**
65-
- A from-scratch implementation of the newline-delimited JSON-RPC protocol.
66-
- Manually parses `stdin`, handles message framing, and constructs JSON-RPC responses.
67-
- Excellent for learning the fundamental mechanics of the MCP transport protocol itself.
59+
- **`dist/server.js`** - Built with the official `@modelcontextprotocol/sdk`
60+
- Uses standard MCP methods: `tools/list`, `tools/call`, `resources/list`, `prompts/list`
61+
- High-level abstractions with `server.registerTool()` and `server.registerResource()`
62+
- Compatible with all MCP clients and registries (including Smithery)
6863

6964
## ✨ Feature Compliance
7065

@@ -113,13 +108,13 @@ npm run build
113108
The server is designed to be spawned by a client. You can run it directly to send it commands interactively.
114109

115110
```bash
116-
# Run the low-level (manual) server implementation
111+
# Run the MCP server
117112
npm start
118113

119-
# Run the high-level (SDK) server implementation
114+
# Run directly with Node.js
120115
node dist/server.js --stdio
121116

122-
# Run in development mode (rebuilds on changes)
117+
# Run in development mode
123118
npm run dev
124119
```
125120

@@ -133,30 +128,21 @@ npx @modelcontextprotocol/inspector --cli "node dist/server.js --stdio"
133128

134129
## 📋 API Usage Examples
135130

136-
All requests must be a single JSON object terminated by a newline character (`\n`).
131+
All requests use standard MCP protocol with JSON-RPC messages.
137132

138-
### High-Level (SDK) Server (`dist/server.js`)
133+
### Standard MCP Protocol
139134

140-
The SDK uses a structured `tools/call` method.
135+
The server implements the standard MCP SDK protocol:
141136

142137
```bash
143-
# Request (as a single line)
144-
→ {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculate","arguments":{"a":7,"b":6,"op":"multiply"}}}
145-
146-
# Response
147-
{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"7 × 6 = 42"}]}}
148-
```
138+
# List available tools
139+
→ {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
149140

150-
### Low-Level (Manual) Server (`dist/server-stdio.js`)
151-
152-
This implementation uses direct method names, bypassing the `tools/call` wrapper.
153-
154-
```bash
155-
# Request (as a single line)
156-
→ {"jsonrpc":"2.0","id":1,"method":"calculate","params":{"a":7,"b":6,"op":"multiply"}}
141+
# Call a tool
142+
→ {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"calculate","arguments":{"a":7,"b":6,"op":"multiply"}}}
157143

158144
# Response
159-
{"jsonrpc":"2.0","id":1,"result":{"value":42,"meta":{"calculationId":"...","timestamp":"..."}}}
145+
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"7 × 6 = 42"}]}}
160146
```
161147

162148
### Progress Demonstration

0 commit comments

Comments
 (0)