🚀 Streamable HTTP MCP Server

A modern Model Context Protocol (MCP) server implementation using the latest Streamable HTTP transport 4. This server provides a collection of useful tools for AI agents and supports both local (stdio) and remote (HTTP) communication modes.

✨ Features

🔄 Streamable HTTP Transport

• Single Endpoint: All communication through /mcp endpoint 3
• Session Management: Automatic session handling with UUID-based identification
• Flexible Response Modes: Support for both JSON and SSE streaming responses
• Backward Compatibility: Works with existing MCP clients
• Stateless Support: Optional stateless operation for scalability

🛠️ Built-in Tools

🧮 Calculator

• Perform mathematical calculations with support for:
  • Basic arithmetic (+, -, *, /)
  • Trigonometric functions (sin, cos, tan)
  • Mathematical constants (pi, e)
  • Advanced functions (sqrt, log, exp, pow)
• Security: Safe expression evaluation with input sanitization

🌤️ Weather

• Get weather information for any location worldwide
• Support for multiple temperature units (Celsius, Fahrenheit, Kelvin)
• Comprehensive weather data including:
  • Current conditions and temperature
  • Humidity, wind speed, and visibility
  • Sunrise/sunset times
  • 3-day forecast

📝 Text Processor

• Advanced text processing capabilities:
  • Case Conversion: uppercase, lowercase, title case
  • Analysis: word count, character count, sentence count
  • Extraction: emails, URLs from text
  • Transformation: reverse text, remove spaces
  • Sentiment Analysis: basic sentiment detection

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/guangxiangdebizi/streamable-http-mcp-server.git
cd streamable-http-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Usage

🌐 HTTP Mode (Streamable HTTP)

Start the server in HTTP mode for remote access:

npm start -- --http

The server will start on http://localhost:3000 with the following endpoints:

• POST /mcp: Send MCP requests
• GET /mcp: Establish SSE stream for real-time communication
• GET /health: Server health check

💻 Stdio Mode (Local)

For local MCP clients like Claude Desktop:

npm start

🔧 Configuration

Environment Variables

PORT=3000  # Server port (default: 3000)

Claude Desktop Configuration

For Stdio Mode:

{
  "mcpServers": {
    "streamable-http-mcp": {
      "command": "node",
      "args": ["path/to/build/index.js"]
    }
  }
}

For HTTP Mode:

{
  "mcpServers": {
    "streamable-http-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

📡 API Reference

Streamable HTTP Protocol 4

The server implements the MCP Streamable HTTP transport specification:

Session Initialization

POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  },
  "id": 1
}

Tool Execution

POST /mcp
Content-Type: application/json
Mcp-Session-Id: <session-id>
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "calculator",
    "arguments": {
      "expression": "2 + 3 * 4"
    }
  },
  "id": 2
}

SSE Stream

GET /mcp
Accept: text/event-stream
Mcp-Session-Id: <session-id>

Available Tools

Calculator

{
  "name": "calculator",
  "arguments": {
    "expression": "sqrt(16) + sin(30) * 2"
  }
}

Weather

{
  "name": "weather",
  "arguments": {
    "location": "New York, NY",
    "units": "metric"
  }
}

Text Processor

{
  "name": "text_processor",
  "arguments": {
    "text": "Hello World! This is a sample text.",
    "operation": "word_count"
  }
}

🏗️ Architecture

Key Components

• src/index.ts: Main server entry point with Streamable HTTP implementation
• src/tools/: Business logic modules for each tool
  • calculator.ts: Mathematical computation tool
  • weather.ts: Weather information tool
  • textProcessor.ts: Text analysis and processing tool

Transport Layer

The server supports both transport mechanisms:

1. Streamable HTTP 0: Modern HTTP-based transport with optional SSE streaming
2. Stdio: Traditional standard input/output for local communication

Session Management

• Session Storage: In-memory session management with automatic cleanup
• Session Timeout: 30-minute inactivity timeout
• UUID Generation: Cryptographically secure session identifiers

🔒 Security Features

• Input Sanitization: All user inputs are validated and sanitized
• Safe Expression Evaluation: Mathematical expressions use secure evaluation methods
• CORS Configuration: Proper cross-origin resource sharing setup
• Session Isolation: Each session maintains isolated state

🚀 Deployment

Local Development

npm run dev  # Watch mode for development

Production

npm run build
npm start -- --http

Docker (Optional)

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY build ./build
EXPOSE 3000
CMD ["npm", "start", "--", "--http"]

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

👨‍💻 Author

Xingyu Chen

• 🌐 LinkedIn: Xingyu Chen
• 📧 Email: [email protected]
• 🐙 GitHub: @guangxiangdebizi
• 📦 NPM: @xingyuchen

🙏 Acknowledgments

• Model Context Protocol for the excellent protocol specification
• Anthropic for Claude and MCP development
• The open-source community for inspiration and support

⭐ If you find this project helpful, please consider giving it a star on GitHub!