README.md•6.28 kB
# Fibonacci MCP Server
A secure Model Context Protocol (MCP) server that provides tools for calculating Fibonacci numbers. This server is designed to meet OpenAI's MCP specifications and includes comprehensive security measures for production deployment.
## Features
- **Fibonacci Calculator**: Calculate the nth Fibonacci number with input validation
- **BMI Calculator**: Calculate BMI from weight and height with realistic bounds
- **Code Review Prompt**: Generate prompts for code review with size limits
- **Web Interface**: Beautiful home page explaining the server capabilities
- **Session Management**: Stateful MCP server with automatic session cleanup
- **Security Features**: Rate limiting, CORS, input validation, and error handling
- **Production Ready**: Health checks, logging, and environment-specific configurations
## Security & Compliance Features
### 🔒 Security Measures
- **Rate Limiting**: 1000 requests per 15-minute window per IP
- **Input Validation**: Comprehensive validation using Zod schemas
- **Request Size Limits**: 10MB limit on request payloads
- **CORS Configuration**: Proper CORS headers for MCP client compatibility
- **Session Timeout**: Automatic cleanup of sessions older than 1 hour
- **Error Handling**: Proper error responses following MCP protocol standards
### 🛡️ Production Readiness
- **Health Check Endpoint**: `/health` for monitoring and load balancers
- **Structured Logging**: Comprehensive error logging and monitoring
- **Environment Detection**: Automatic configuration for production vs development
- **Memory Management**: Automatic cleanup of rate limit and session data
- **Graceful Error Handling**: Proper HTTP status codes and JSON-RPC error responses
### 📋 MCP Protocol Compliance
- **Proper Error Codes**: JSON-RPC 2.0 compliant error responses
- **Server Metadata**: Complete server information and capabilities
- **Session Management**: Proper MCP session lifecycle management
- **Resource Validation**: Input validation for dynamic resources
## Local Development
### Prerequisites
- Node.js 18.0.0 or higher
- npm
### Installation
1. Clone the repository:
```bash
git clone <your-repo-url>
cd fibonacci-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Start the server:
```bash
npm start
```
The server will be available at:
- Home page: http://localhost:7171/
- MCP endpoint: http://localhost:7171/mcp
- Health check: http://localhost:7171/health
## Deployment on Render
### Option 1: Using render.yaml (Recommended)
1. Push your code to a Git repository (GitHub, GitLab, etc.)
2. Connect your repository to Render
3. Render will automatically detect the `render.yaml` file and deploy your service
### Option 2: Manual Deployment
1. Create a new Web Service on Render
2. Connect your Git repository
3. Configure the service:
- **Environment**: Node
- **Build Command**: `npm install`
- **Start Command**: `npm start`
- **Environment Variables**:
- `NODE_ENV`: `production`
### Environment Variables
- `PORT`: Port number (automatically set by Render)
- `NODE_ENV`: Set to `production` for production deployments
## MCP Tools
### fibonacci
Calculate the nth Fibonacci number with input validation.
**Parameters:**
- `n` (number): The position in the Fibonacci sequence (0-indexed, max 1000)
**Example:**
```json
{
"method": "tools/call",
"params": {
"name": "fibonacci",
"arguments": {
"n": 10
}
}
}
```
**Response:**
```json
{
"content": [
{
"type": "text",
"text": "The 10th Fibonacci number is: 55"
}
]
}
```
### calculate-bmi
Calculate BMI from weight and height with realistic bounds.
**Parameters:**
- `weightKg` (number): Weight in kilograms (0-1000)
- `heightM` (number): Height in meters (0.1-3.0)
### review-code
Generate a prompt for code review with size limits.
**Parameters:**
- `code` (string): The code to review (max 10,000 characters)
## MCP Resources
- `config://app`: Static application configuration
- `users://{userId}/profile`: Dynamic user profile data (with input validation)
## API Endpoints
- `GET /`: Home page with server information
- `GET /health`: Health check endpoint for monitoring
- `POST /mcp`: MCP protocol endpoint
- `GET /mcp`: Server-sent events (SSE) for notifications
- `DELETE /mcp`: Session termination
## Security Headers
The server automatically includes the following security headers:
- `Access-Control-Allow-Origin: *`
- `Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS`
- `Access-Control-Allow-Headers: Content-Type, mcp-session-id, Authorization`
## Rate Limiting
- **Limit**: 1000 requests per 15-minute window per IP address
- **Response**: HTTP 429 with JSON-RPC error when limit exceeded
- **Storage**: In-memory with automatic cleanup
## Error Handling
The server returns proper JSON-RPC 2.0 error responses:
```json
{
"jsonrpc": "2.0",
"error": {
"code": -32000,
"message": "Bad Request: No valid session ID provided"
},
"id": null
}
```
Common error codes:
- `-32000`: Bad Request
- `-32029`: Rate limit exceeded
- `-32601`: Method not found
- `-32603`: Internal server error
## Monitoring & Health Checks
### Health Check Response
```json
{
"status": "healthy",
"timestamp": "2024-01-15T10:30:00.000Z",
"uptime": 3600,
"sessions": 5
}
```
### Logging
The server logs:
- Session creation and cleanup
- Rate limit violations
- Error conditions
- Server startup information
## Technical Details
- **Server Name**: fibonacci-mcp-server
- **Version**: 1.0.0
- **Protocol**: Model Context Protocol (MCP)
- **Transport**: HTTP/Express with session management
- **Node.js Version**: >=18.0.0
- **Security**: Rate limiting, CORS, input validation
- **Compliance**: JSON-RPC 2.0, MCP protocol standards
## OpenAI MCP Compliance
This server is designed to meet OpenAI's MCP specifications:
✅ **Authentication & Security**: Rate limiting, input validation, CORS
✅ **Error Handling**: Proper JSON-RPC error responses
✅ **Session Management**: Secure session lifecycle
✅ **Production Readiness**: Health checks, logging, monitoring
✅ **Protocol Compliance**: MCP and JSON-RPC 2.0 standards
✅ **Resource Management**: Memory cleanup and timeout handling
## License
ISC