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

Related MCP server: Filesystem MCP Server

🏗️ 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