Content
# mcp-demo-test
#### Introduction
This is a sample project for a calculator service based on the MCP (Model Context Protocol) protocol, providing four basic mathematical operations: addition, subtraction, multiplication, and division. The project supports two running modes: SSE (Server-Sent Events) mode and stdio mode, and can be integrated as an MCP server with AI assistants.
#### Software Architecture
- **Tech Stack**: Node.js + Express + Zod + MCP SDK
- **Architecture Pattern**: MCP server architecture
- **Transport Protocol**:
- SSE Mode: HTTP-based Server-Sent Events
- stdio Mode: Standard input/output stream
- **Functional Modules**:
- Core calculator service (add/sub/mul/div tools)
- SSE transport layer handling
- stdio transport layer handling
#### Installation Guide
1. **Clone the Project**
```bash
git clone [project address]
cd mcp-demo-test
```
2. **Install Dependencies**
```bash
npm install
```
3. **Verify Installation**
```bash
npm list
```
#### Usage Instructions
##### 1. Running in SSE Mode
SSE mode provides services via the HTTP protocol, suitable for scenarios requiring network access.
**Start the Service:**
```bash
node index-sse.js
```
**Or specify a port:**
```bash
HTTP_API_PORT=3001 node index-sse.js
```
**Or specify both port and access token:**
```bash
HTTP_API_PORT=3001 HTTP_API_TOKEN=your-secret-token node index-sse.js
```
**After the service starts:**
- Service address: http://localhost:3000
- SSE endpoint: http://localhost:3000/sse
- Message endpoint: http://localhost:3000/messages
**Test the connection:**
```bash
curl http://localhost:3000/sse
```
##### 2. Running in Streamable HTTP Mode (New Version)
Streamable HTTP mode is based on the official MCP Streamable HTTP protocol, using a real StreamableHTTPServerTransport implementation, supporting complete session management and state persistence.
**Start the Service:**
```bash
npm run start:streamable
```
**Or run directly:**
```bash
node index-streamable-http.js
```
**Or specify a port:**
```bash
HTTP_API_PORT=3001 node index-streamable-http.js
```
**Or specify both port and access token:**
```bash
HTTP_API_PORT=3001 HTTP_API_TOKEN=your-secret-token node index-streamable-http.js
```
**After the service starts:**
- Service address: http://localhost:3000
- MCP endpoint: http://localhost:3000/mcp
**Features:**
- Session management (sessionId)
- State persistence
- Server-to-client notifications
- Session termination
- Health checks
**Test the connection:**
```bash
node test-streamable-mcp.js
```
Then visit: http://localhost:3001/test
##### 3. Running in stdio Mode
The stdio mode communicates via standard input and output, suitable for local integration scenarios.
**Start the Service:**
```bash
node index-stdio.js
```
**Or install as a global command:**
```bash
npm install -g .
mcp-calc
```
##### 4. MCP Configuration Integration
Example configuration for integrating the calculator service into the MCP client:
**SSE Mode Configuration:**
```json
{
"mcpServers": {
"calculator-sse": {
"isActive": true,
"name": "calculator-service",
"type": "sse",
"description": "A simple calculator service supporting addition, subtraction, multiplication, and division",
"baseUrl": "http://localhost:3000/sse",
"url": "http://localhost:3000/sse"
}
}
}
```
**Streamable HTTP Mode Configuration (New Version):**
```json
{
"mcpServers": {
"calculator-streamable-http": {
"isActive": true,
"name": "calculator-service",
"type": "streamable",
"description": "A simple calculator service supporting addition, subtraction, multiplication, and division",
"url": "http://localhost:3000/mcp"
}
}
}
```
**stdio Mode Configuration:**
```json
{
"mcpServers": {
"calculator-stdio": {
"isActive": true,
"name": "calculator-service",
"description": "A simple calculator service supporting addition, subtraction, multiplication, and division",
"command": "node",
"args": ["path/to/index-stdio.js"],
"env": {}
}
}
}
```
##### 5. Function Usage
**Available Tools:**
- `add` - Addition operation
- `sub` - Subtraction operation
- `mul` - Multiplication operation
- `div` - Division operation
**Usage Example:**
**Addition:**
```json
{
"tool": "add",
"arguments": {
"a": 10,
"b": 5
}
}
```
Result: 15
**Division (note division by zero error):**
```json
{
"tool": "div",
"arguments": {
"a": 10,
"b": 0
}
}
```
Result: Error message "Division by zero"
#### Development Instructions
**Project Structure:**
```
mcp-demo-test/
├── index-sse.js # SSE mode server (old version)
├── index-stdio.js # stdio mode server
├── index-streamable-http.js # Streamable HTTP mode server (new version)
├── test-streamable-mcp.js # Streamable HTTP test script
├── package.json # Project configuration
├── LICENSE # License
└── README.md # Project documentation
```
**Dependency Information:**
- `@modelcontextprotocol/sdk`: MCP protocol SDK
- `express`: Web server framework
- `zod`: Data validation library
#### Notes
1. **Port Conflicts**: If port 3000 is occupied, please set the `PORT` environment variable.
2. **Cross-Origin Issues**: SSE mode has handled cross-origin requests.
3. **Error Handling**: All operations have appropriate error handling mechanisms.
4. **Performance Optimization**: The service runs as a single instance, suitable for individual or small team use.
#### Environment Variable Configuration
The project supports the following environment variables for configuration:
- **HTTP_API_PORT**: Service port configuration (default: 3000)
- SSE Mode: `HTTP_API_PORT=3001 node index-sse.js`
- Streamable HTTP Mode: `HTTP_API_PORT=3001 node index-streamable-http.js`
- **HTTP_API_TOKEN**: HTTP Bearer Token access authentication (optional)
- Once set, all HTTP requests need to include in the Authorization header:
```
Authorization: Bearer your-secret-token
```
- Example:
```bash
HTTP_API_TOKEN=my-secret-key node index-sse.js
```
- If not set, the service allows anonymous access.
