README.mdโข29.7 kB
# ๐ MCP Demo Project ๐
```
โโโโ โโโโ โโโโโโโโโโโโโโ โโโโโโโ โโโโโโโโโโโโ โโโโ โโโโโโโ
โโโโโ โโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโ
โโโโโโโโโโโโโโ โโโโโโโโ โโโ โโโโโโโโโ โโโโโโโโโโโโโโ โโโ
โโโโโโโโโโโโโโ โโโโโโโ โโโ โโโโโโโโโ โโโโโโโโโโโโโโ โโโ
โโโ โโโ โโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โโโ โโโโโโโโโโโโ
โโโ โโโ โโโโโโโโโโ โโโโโโโ โโโโโโโโโโโ โโโ โโโโโโโ
๐ Word Reversal Server with Server-Sent Events Support ๐
```
A comprehensive demonstration of **Model Context Protocol (MCP)** server with **Server-Sent Events (SSE)** support and a **word reversal tool**.
## ๐จ Visual Architecture
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ MCP DEMO ECOSYSTEM ๐ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ
โ ๐ก STDIO Mode ๐ SSE Mode โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โ
โ โ Client โโโโโโโSTDIOโโโโโโบโ Client โ โ
โ โ ๐ฑ โ โ ๐ฑ โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โ
โ โ โ โ
โ โผ โผ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โ
โ โ MCP Server โ โ MCP Server โ โ
โ โ ๐ฅ๏ธ โ โ ๐ฅ๏ธ โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โ
โ โ โ โ
โ โผ โผ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ ๐ Word Reversal Tool ๐ โ โ
โ โ "hello" โ "olleh" โ โ
โ โ "world" โ "dlrow" โ โ
โ โ "demo" โ "omed" โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
## ๐ Features Showcase
```
๐ฏ FEATURES MATRIX
โโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโ
โ Feature โ STDIO Mode โ SSE Mode โ
โโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโผโโโโโโโโโโโโโโค
โ MCP Protocol โ โ
โ โ
โ
โ Word Reversal โ โ
โ โ
โ
โ Type Safety โ โ
โ โ
โ
โ Error Handling โ โ
โ โ
โ
โ Health Check โ โ โ โ
โ
โ HTTP Endpoint โ โ โ โ
โ
โ Real-time โ โก โ ๐ โ
โโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโดโโโโโโโโโโโโโโ
```
## ๐ฆ Quick Start
```
๐ง INSTALLATION STEPS
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 1๏ธโฃ npm install โ
โ 2๏ธโฃ npm run build โ
โ 3๏ธโฃ npm run demo:stdio OR โ
โ npm run demo:sse โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
### ๐ฏ Usage Options
#### ๐ Option 1: STDIO Mode (Traditional MCP)
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ STDIO WORKFLOW โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ
โ Terminal 1: ๐ฅ๏ธ Server Terminal 2: ๐ฑ Client โ
โ โโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ npm run start โ โ npm run client โ โ
โ โ โ โโโโโบ โ โ โ
โ โ Server running... โ โ Testing tools... โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ OR use combined command: โ
โ ๐ npm run demo:stdio โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
#### ๐ Option 2: SSE Mode (Server-Sent Events)
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ SSE WORKFLOW โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ
โ Terminal 1: ๐ SSE Server Terminal 2: ๐ก SSE Client โ
โ โโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ npm run start:sse โ โ npm run client:sse โ โ
โ โ โ HTTP โ โ โ
โ โ Port 3000 active... โ โโโโโบ โ Connecting via SSE โ โ
โ โ Health: โ
โ โ Testing tools... โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ OR use combined command: โ
โ ๐ npm run demo:sse โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
## ๐ ๏ธ Development Arsenal
```
โก DEVELOPMENT COMMANDS
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ฅ Hot Reload: โ
โ โโ npm run dev # STDIO server with auto-restart โ
โ โโ npm run dev:sse # SSE server with auto-restart โ
โ โ
โ ๐ Quality Checks: โ
โ โโ npm run typecheck # TypeScript validation โ
โ โโ npm run lint # Code style checking โ
โ โโ npm run test # Test suite execution โ
โ โ
โ ๐ Production: โ
โ โโ npm run build # Compile to JavaScript โ
โ โโ npm run start # Production server โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
## ๐ Project Architecture
```
๐ PROJECT STRUCTURE
โโโ ๐ src/
โ โโโ ๐ฅ๏ธ server.ts # MCP STDIO Server
โ โโโ ๐ sse-server.ts # MCP SSE Server
โ โโโ ๐ฑ client.ts # STDIO Test Client
โ โโโ ๐ก sse-client.ts # SSE Test Client
โโโ ๐ dist/ # Compiled JavaScript
โโโ ๐ package.json # Dependencies & Scripts
โโโ ๐ tsconfig.json # TypeScript Config
โโโ ๐ eslint.config.js # Code Quality Rules
โโโ ๐ README.md # This beautiful file!
๐จ COMPONENT RELATIONSHIPS
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ฑ client.ts โโโโโโSTDIOโโโโโโบ ๐ฅ๏ธ server.ts โ
โ โ
โ ๐ก sse-client.ts โโโโHTTP/SSEโโโโบ ๐ sse-server.ts โ
โ โ
โ Both connect to: ๐ Word Reversal Logic โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
## ๐ง API Documentation
### ๐ ๏ธ Available Tools
#### ๐ `reverse_word` Tool
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐ WORD REVERSAL API โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ
โ ๐ฅ INPUT: โ
โ { โ
โ "name": "reverse_word", โ
โ "arguments": { โ
โ "word": "hello" โ
โ } โ
โ } โ
โ โ
โ ๐ค OUTPUT: โ
โ { โ
โ "content": [ โ
โ { โ
โ "type": "text", โ
โ "text": "Reversed word: \"olleh\"" โ
โ } โ
โ ] โ
โ } โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
### ๐ SSE Server Endpoints
```
๐ ENDPOINT MAP
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ฅ GET /health โ
โ โโ Returns server health status โ
โ โ
โ ๐ก GET /sse โ
โ โโ Server-Sent Events MCP endpoint โ
โ โ
โ Example: http://localhost:3000/health โ
โ Response: {"status": "healthy", "server": "..."} โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
## ๐งช Testing Showcase
```
๐ฌ COMPREHENSIVE TEST SUITE
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ โ
Connection Tests โ
Tool Discovery โ
โ โโ STDIO transport โโ List available tools โ
โ โโ SSE transport โโ Validate tool schemas โ
โ โ
โ โ
Tool Execution โ
Error Handling โ
โ โโ Word reversal โโ Invalid inputs โ
โ โโ Multiple test cases โโ Connection failures โ
โ โ
โ ๐ฏ TEST CASES: โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ "hello" โ "olleh" "server" โ "revres" โ โ
โ โ "world" โ "dlrow" "demo" โ "omed" โ โ
โ โ "mcp" โ "pcm" "sse" โ "ess" โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
## ๐๏ธ System Architecture
### ๐ STDIO Mode Flow
```
๐ STDIO COMMUNICATION FLOW
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ฑ Client Process โ
โ โโโโโโโโโโโโโโโโโโโ โ
โ โ 1. List Tools โ โ
โ โ 2. Call Tool โ โ
โ โ 3. Get Response โ โ
โ โโโโโโโโโโโโโโโโโโโ โ
โ โ โ
โ โผ STDIO Pipes โ
โ โโโโโโโโโโโโโโโโโโโ โ
โ โ ๐ฅ๏ธ MCP Server โ โโโโโโโ โ
โ โ โโ Parse JSON โ โ โ
โ โ โโ Route Tool โ โ โ
โ โ โโ Send Result โ โ โ
โ โโโโโโโโโโโโโโโโโโโ โ โ
โ โ โ โ
โ โผ โ โ
โ โโโโโโโโโโโโโโโโโโโ โ โ
โ โ ๐ Word Tool โ โโโโโโโ โ
โ โ reverse("hi") โ โ
โ โ returns "ih" โ โ
โ โโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
### ๐ SSE Mode Flow
```
๐ SERVER-SENT EVENTS FLOW
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ก SSE Client โ
โ โโโโโโโโโโโโโโโโโโโ โ
โ โ 1. HTTP Connect โ โ
โ โ 2. SSE Stream โ โ
โ โ 3. JSON-RPC โ โ
โ โโโโโโโโโโโโโโโโโโโ โ
โ โ โ
โ โผ HTTP/SSE โ
โ โโโโโโโโโโโโโโโโโโโ โ
โ โ ๐ HTTP Server โ โ
โ โ โโ Port 3000 โ โ
โ โ โโ /health โ โโโโโโโ โ
โ โ โโ /sse โ โ โ
โ โโโโโโโโโโโโโโโโโโโ โ โ
โ โ โ โ
โ โผ โ โ
โ โโโโโโโโโโโโโโโโโโโ โ โ
โ โ ๐ Word Tool โ โโโโโโโ โ
โ โ reverse("mcp") โ โ
โ โ returns "pcm" โ โ
โ โโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
## ๐ Security & Quality
```
๐ก๏ธ SECURITY FEATURES
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ โ
Input Validation โ
Type Safety โ
โ โโ Zod schema validation โโ Full TypeScript coverage โ
โ โโ Parameter sanitization โโ Compile-time checks โ
โ โ
โ โ
Error Handling โ
No Secrets โ
โ โโ Graceful failures โโ Environment variables โ
โ โโ Detailed error logs โโ Configuration files โ
โ โ
โ ๐ QUALITY METRICS: โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ ๐ All files < 500 lines โ โ
โ โ ๐ง Modular architecture โ โ
โ โ ๐ Comprehensive documentation โ โ
โ โ ๐งช Test coverage for all features โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
## ๐ Command Reference
```
๐ COMPLETE SCRIPT REFERENCE
โโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Command โ Description โ
โโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ npm run build โ ๐จ Compile TypeScript โ JavaScript โ
โ npm run start โ ๐ฅ๏ธ Start STDIO MCP server โ
โ npm run start:sse โ ๐ Start SSE MCP server (port 3000) โ
โ npm run dev โ ๐ฅ STDIO server with hot reload โ
โ npm run dev:sse โ ๐ SSE server with hot reload โ
โ npm run client โ ๐ฑ Run STDIO test client โ
โ npm run client:sse โ ๐ก Run SSE test client โ
โ npm run demo:stdio โ ๐ Demo STDIO (server + client) โ
โ npm run demo:sse โ ๐ Demo SSE (server + client) โ
โ npm run test โ ๐งช Run test suite โ
โ npm run lint โ ๐ Code quality check โ
โ npm run typecheck โ โ
TypeScript validation โ
โ npm run test-demo โ ๐ฏ Complete demo test โ
โโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
## ๐จ Demo in Action
```
๐ฌ LIVE DEMO EXAMPLE
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ $ npm run demo:sse โ
โ โ
โ ๐ Starting MCP SSE Client Tests โ
โ โ
โ ๐ฅ Server health: { status: "healthy" } โ
โ โ
Connected to MCP SSE server โ
โ โ
โ ๐ Available tools: โ
โ - reverse_word: Reverses characters using SSE โ
โ โ
โ ๐ Testing SSE word reversal with: "sse" โ
โ โจ Result: [SSE] Reversed word: "ess" (original: "sse") โ
โ โ
โ ๐ Testing SSE word reversal with: "server" โ
โ โจ Result: [SSE] Reversed word: "revres" (orig: "server") โ
โ โ
โ โ
All SSE tests completed! โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
## ๐ Technology Stack
```
๐ง TECH STACK RAINBOW
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ฆ TypeScript โโ Type safety & modern JS โ
โ ๐ฉ Node.js โโ Runtime environment โ
โ ๐จ MCP SDK โโ Model Context Protocol โ
โ ๐ช Zod โโ Schema validation โ
โ ๐ง ESLint โโ Code quality โ
โ ๐ฅ npm โโ Package management โ
โ โ
โ ๐ก Transports: โ
โ โโ ๐ STDIO # Standard input/output pipes โ
โ โโ ๐ SSE # Server-Sent Events over HTTP โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
## ๐ License & Contributing
```
๐ MIT LICENSE
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ Feel free to use this demo as a foundation for your โ
โ own MCP projects! โ
โ โ
โ ๐ค CONTRIBUTING: โ
โ โโ This is a demo showcasing MCP capabilities โ
โ โโ Extend it with additional tools and features โ
โ โโ Share your improvements with the community โ
โ โโ Report issues and suggest enhancements โ
โ โ
โ ๐ ENJOY BUILDING WITH MCP! ๐ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
## ๐ฏ What's Next?
```
๐ FUTURE ENHANCEMENTS
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ก Possible Extensions: โ
โ โโ ๐ค Text processing tools (uppercase, lowercase) โ
โ โโ ๐งฎ Math calculation tools โ
โ โโ ๐
Date/time utilities โ
โ โโ ๐ Encoding/decoding tools โ
โ โโ ๐ Data validation tools โ
โ โโ ๐ Multi-language support โ
โ โ
โ ๐ฎ Try adding your own tools and see the magic happen! โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
---
<div align="center">
**๐ Built with SPARC Methodology ๐**
*Specification โ Pseudocode โ Architecture โ Refinement โ Completion*
**Happy coding! ๐**
</div>