the-real-therealorry/mcp-server

MCP Server - Production Monorepo

A production-grade Model Context Protocol (MCP) server with a beautiful React dashboard, built with security, scalability, and maintainability in mind.

🚀 Features

Backend (Node.js + Express + TypeScript)

• Full MCP Protocol Compliance - Complete implementation of the Model Context Protocol
• Secure ZIP Processing - Advanced security validation, zip bomb protection, path traversal prevention
• Context Management - Approval workflow for uploaded content
• System Snapshots - Comprehensive state snapshots with configurable options
• Production Security - Rate limiting, CORS, helmet, input validation
• Structured Logging - Winston-based logging with rotation and levels
• Health Monitoring - Comprehensive health checks and system statistics

Frontend (React + TypeScript + Tailwind)

• Modern Dashboard - Beautiful, responsive interface with dark/light mode
• Real-time Monitoring - Live system stats, logs, and activity feeds
• Secure File Upload - Drag-and-drop ZIP upload with progress tracking
• Context Browser - Search, filter, and manage uploaded contexts
• Log Viewer - Real-time log streaming with filtering and export
• Tool Management - MCP tool monitoring and configuration

MCP Tools

• load_zip - Securely extract and process ZIP archives
• mark_approved - Context approval workflow management
• snapshot - Create comprehensive system state snapshots

🏗️ Architecture

mcp-server/
├── backend/           # Node.js + Express API server
│   ├── src/
│   │   ├── mcp/      # MCP protocol implementation
│   │   ├── api/      # REST API routes and middleware
│   │   ├── utils/    # Utilities and security
│   │   └── types.ts  # TypeScript definitions
├── dashboard/         # React frontend
│   ├── src/
│   │   ├── components/ # Reusable UI components
│   │   ├── pages/     # Application pages
│   │   └── api.ts     # API client
├── data/             # Runtime data storage
│   ├── zips/         # Uploaded ZIP files
│   ├── extracted/    # Extracted file contents
│   ├── vds/          # Vector database storage
│   └── snapshots/    # System snapshots
└── logs/             # Application logs

🚦 Quick Start

Prerequisites

• Node.js 18+
• npm 8+

Local Development

1. Clone and install dependencies:

git clone <repository>
cd mcp-server
npm install

2. Start development servers:

npm run dev

This starts both the backend (port 3001) and frontend (port 5173) in development mode.

3. Access the application:

• Dashboard: http://localhost:5173
• API: http://localhost:3001
• Health Check: http://localhost:3001/api/health

Production Build

npm run build
npm start

🔧 Configuration

Environment Variables

Create a .env file in the backend directory:

NODE_ENV=production
PORT=3001
CORS_ORIGIN=*
MAX_FILE_SIZE=52428800
LOG_LEVEL=info
RATE_LIMIT_ENABLED=true

Security Configuration

The server includes comprehensive security measures:

• File Upload Limits: 50MB max file size, ZIP files only
• Rate Limiting: 5 uploads per 15 minutes, 100 API calls per 15 minutes
• ZIP Security: Zip bomb protection, path traversal prevention, file type validation
• Input Validation: Joi-based validation for all endpoints
• CORS: Configurable cross-origin resource sharing
• Helmet: Security headers and CSP

📡 API Endpoints

MCP Tools

• POST /api/mcp/tools/load-zip - Upload and extract ZIP files
• POST /api/mcp/tools/mark-approved - Approve/reject contexts
• POST /api/mcp/tools/snapshot - Create system snapshots

Data Management

• GET /api/context - List contexts with filtering and pagination
• GET /api/logs - Retrieve system logs
• GET /api/stats - System statistics and metrics
• GET /api/mcp/tools - List available MCP tools

System

• GET /api/health - Health check endpoint

🔒 Security Features

ZIP File Processing

• File Type Validation: Only ZIP files accepted
• Size Limits: 50MB upload limit, 100MB extraction limit
• Zip Bomb Protection: Compression ratio analysis
• Path Traversal Prevention: Sanitized file paths
• Content Filtering: Allowed file extensions only

API Security

• Rate Limiting: Configurable request limits
• Input Validation: Comprehensive request validation
• Error Handling: Secure error responses
• CORS Configuration: Controlled cross-origin access
• Security Headers: Helmet.js integration

🚀 Deployment

Render (Recommended)

The project includes a render.yaml configuration for easy deployment:

1. Connect your repository to Render
2. The build and deployment will happen automatically
3. Environment variables are configured in the YAML file

Manual Deployment

1. Build the project:

npm run build

2. Set environment variables:

export NODE_ENV=production
export PORT=3001

3. Start the server:

npm start

📊 Monitoring

Dashboard Features

• System Overview: Uptime, file counts, memory/disk usage
• Real-time Logs: Live log streaming with filtering
• Context Management: Upload approval workflow
• Tool Monitoring: MCP tool usage statistics

Logging

• Structured Logging: JSON format with metadata
• Log Rotation: Automatic log file rotation
• Multiple Levels: Error, warn, info, debug
• Export Capability: Download logs for analysis

🧪 Testing

# Run backend tests
npm run test --workspace=backend

# Run frontend tests  
npm run test --workspace=dashboard

# Run all tests
npm test

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

📄 License

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

🆘 Support

For support and questions:

• Check the Issues page
• Review the API documentation
• Check the logs for error details

🔄 Version History

• v1.0.0 - Initial release with full MCP protocol support
• Production-ready security features
• Complete React dashboard
• Render deployment configuration