MCP (Model Context Protocol) Server
A production-ready implementation of a Model Context Protocol (MCP) server with a modern React frontend. The server provides a secure JSON-RPC interface for AI model interactions, while the frontend offers a user-friendly dashboard for monitoring and management.
✨ Features
Backend (Node.js/TypeScript)
- JSON-RPC 2.0 over HTTP with WebSocket support
- TypeScript with full type safety
- Modular Architecture for easy extension
- SQLite database with migrations
- JWT-based authentication with OAuth 2.0 support
- Rate limiting and security headers
- Winston logging with file rotation
- Health checks with detailed system metrics
- API Documentation with Swagger/OpenAPI
- Containerization with Docker
Frontend (React/TypeScript)
- 🚀 Vite for fast development and builds
- 🎨 Material-UI (MUI) for beautiful, responsive UI
- 🔄 React Query for server state management
- 🛡️ Secure API client with token refresh
- 📱 Mobile-responsive design with PWA support
- 🎭 Theming support
- 📊 Real-time monitoring and metrics
- 🔍 Error tracking with Sentry
🚀 Getting Started
Prerequisites
- Node.js 18+
- npm or yarn
- SQLite3 (included in most systems)
- Docker (optional, for containerized deployment)
Quick Start
- Clone and install dependencies:
git clone https://github.com/edogola4/mcp.git
cd mcp
# Install backend dependencies
npm install
# Install frontend dependencies
cd client
npm install
cd ..
- Set up environment variables:
# Run the setup script
npm run setup
# Or manually copy the example config
cp config.example.ts .env
.env file and update the configuration values as needed. - Start the development servers:
# In the root directory (for the backend)
npm run dev
# In a new terminal, from the client directory (for the frontend)
cd client
npm run dev
🛠️ Configuration
Environment Variables
All configuration is managed through environment variables. The following environment variables are available:
Server Configuration
NODE_ENV: Application environment (development, production, test)PORT: Port to run the server on (default: 3000)HOST: Host to bind the server to (default: 0.0.0.0)
Security
JWT_SECRET: Secret key for JWT token signing (required)JWT_EXPIRES_IN: JWT token expiration time (default: 1d)CORS_ORIGIN: Allowed CORS origins (default: *)RATE_LIMIT_WINDOW_MS: Rate limiting window in milliseconds (default: 900000 - 15 minutes)RATE_LIMIT_MAX: Maximum requests per window (default: 100)
Database
DB_PATH: Path to SQLite database file (default: ./data/mcp-db.sqlite)DB_LOGGING: Enable database query logging (default: false)
Logging
LOG_LEVEL: Logging level (error, warn, info, http, verbose, debug, silly)LOG_TO_FILE: Enable logging to file (default: false)LOG_FILE_PATH: Path to log file (default: logs/app.log)
API Documentation
API_DOCS_ENABLED: Enable API documentation (default: true)API_DOCS_PATH: Path to API documentation (default: /api-docs)
OAuth (Optional)
OAUTH_ENABLED: Enable OAuth authentication (default: false)OAUTH_ISSUER_URL: OAuth provider URLOAUTH_CLIENT_ID: OAuth client IDOAUTH_CLIENT_SECRET: OAuth client secretOAUTH_REDIRECT_URI: OAuth redirect URIOAUTH_SCOPE: OAuth scopes (default: openid profile email)
🚀 Development
Running the Application
Development Mode
# Start the backend server
npm run dev
# In a separate terminal, start the frontend
cd client
npm run dev
Production Build
# Build the application
npm run build
# Start the production server
npm start
Testing
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Run tests in watch mode
npm run test:watch
🐳 Docker Support
The application includes Docker support for easy deployment:
# Build the Docker image
docker build -t mcp-server .
# Run the container
docker run -p 3000:3000 --env-file .env mcp-server
📦 Production Deployment
For production deployment, consider the following:
- Set
NODE_ENV=production - Configure a reverse proxy (Nginx, Apache, etc.)
- Set up HTTPS with a valid SSL certificate
- Configure proper logging and monitoring
- Set up a process manager (PM2, systemd, etc.)
🤝 Contributing
Contributions are welcome! Please read our Contributing Guidelines for details.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
📞 Support
For support, please open an issue in the GitHub repository.
npm run dev
4. Access the application:
- Frontend: http://localhost:3001
- Backend API: http://localhost:3000
## Project Structure
mcp-server/
├── client/ # Frontend React application
│ ├── public/ # Static files
│ └── src/ # React source code
│ ├── api/ # API client and RPC calls
│ ├── components/ # Reusable UI components
│ └── pages/ # Page components
├── src/ # Backend source code
│ ├── config/ # Configuration files
│ ├── controllers/ # Request handlers
│ ├── core/ # Core application logic
│ └── services/ # Business logic services
├── .env.example # Example environment variables
└── package.json # Backend dependencies and scripts
## Development
### Backend
```bash
# Install dependencies
npm install
# Start development server with hot-reload
npm run dev:server
# Run tests
npm test
Frontend
cd client
# Install dependencies
npm install
# Start development server
npm run dev
Production Build
# Build frontend
cd client
npm run build
# Start production server (from root)
npm start
⚙️ Configuration
Backend Environment Variables
Create a .env file in the root directory with the following variables:
# Server Configuration
PORT=3000
NODE_ENV=development
BASE_URL=http://localhost:3000
# Database
DB_PATH=./data/mcp-db.sqlite
DB_LOGGING=false
# JWT Configuration
JWT_SECRET=your_secure_jwt_secret
JWT_EXPIRES_IN=1h
REFRESH_TOKEN_EXPIRES_IN=7d
# CORS
CORS_ORIGIN=http://localhost:3001
CORS_METHODS=GET,POST,PUT,DELETE,OPTIONS
CORS_ALLOWED_HEADERS=Content-Type,Authorization
CORS_CREDENTIALS=true
Frontend Configuration
The frontend is pre-configured to connect to the backend at http://localhost:3000. If you need to change this, modify the proxy settings in client/vite.config.final.ts.
📡 API Reference
The API uses JSON-RPC 2.0 over HTTP. All endpoints are prefixed with /api.
Authentication
- LoginAuthenticate with username and password.
- Refresh TokenGet a new access token using a refresh token.
RPC Endpoint
Example request:
{
"jsonrpc": "2.0",
"method": "health.check",
"params": {},
"id": 1
}
📦 Deployment
PM2 (Recommended for Production)
# Install PM2 globally
npm install -g pm2
# Start the application
pm2 start npm --name "mcp-server" -- start
# Enable startup on system boot
pm2 startup
pm2 save
Docker
# Build and start containers
docker-compose up --build -d
Base URL
All API endpoints are prefixed with /api/v1.
Authentication
- LoginInitiates the OAuth 2.0 flow.
- CallbackOAuth callback URL (handled automatically).
- Refresh TokenRefresh an access token.
JSON-RPC 2.0 Endpoint
All RPC methods require a valid JWT token in the Authorization header:
Authorization: Bearer <your_jwt_token>
Example Request
curl -X POST http://localhost:3000/rpc \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your_jwt_token>" \
-d '{
"jsonrpc": "2.0",
"method": "weather.getCurrent",
"params": {
"city": "London"
},
"id": 1
}'
Example response:
{
"jsonrpc": "2.0",
"result": {
"location": {
"name": "London",
"country": "GB",
"coord": {
"lat": 51.5074,
"lon": -0.1278
},
"timezone": 0,
"sunrise": "2023-05-01T04:45:12.000Z",
"sunset": "2023-05-01T19:53:12.000Z"
},
"weather": {
"main": "Clear",
"description": "clear sky",
"icon": "01d",
"temperature": {
"current": 15.5,
"feelsLike": 14.8,
"min": 13.2,
"max": 17.1
},
"pressure": 1012,
"humidity": 72,
"visibility": 10,
"wind": {
"speed": 3.6,
"deg": 200
},
"clouds": 0
},
"lastUpdated": "2023-05-01T12:00:00.000Z"
},
"id": 1
}
🔐 Authentication
The server uses OAuth 2.0 with OpenID Connect for authentication. The flow is as follows:
- Client redirects to
/auth/login - User authenticates with the OAuth provider
- Provider redirects to
/auth/callback with an authorization code - Server exchanges the code for tokens
- Client receives an access token and refresh token
Token Management
- Access Token: Short-lived (default: 1h), used for API authentication
- Refresh Token: Long-lived (default: 7d), used to obtain new access tokens
Protected Endpoints
All endpoints except the following require authentication:
GET /health - Health checkGET /auth/login - OAuth loginGET /auth/callback - OAuth callbackPOST /auth/refresh - Token refresh
🛠️ Available Methods
Authentication
auth.getUserInfo(accessToken: string)
Get user information from the OAuth provider.
Weather
weather.getCurrent(params: { city?: string, lat?: number, lon?: number, units?: string, lang?: string })
Get current weather for a location by city name or coordinates.
File System
file.read(params: { path: string, encoding?: string })
Read a file from the sandbox directory.file.write(params: { path: string, content: string, encoding?: string, createDir?: boolean, append?: boolean })
Write content to a file in the sandbox directory.
Database
database.query(params: { sql: string, params?: any[], readOnly?: boolean })
Execute a SQL query against the database.{
"method": "database.query",
"params": {
"sql": "SELECT * FROM users WHERE id = ?",
"params": ["user123"],
"readOnly": true
},
"id": 1
}
database.transaction(queries: Array<{ sql: string, params?: any[] }>)
Execute multiple SQL queries in a transaction.{
"method": "database.transaction",
"params": {
"queries": [
{"sql": "INSERT INTO users (id, email) VALUES (?, ?)", "params": ["user123", "test@example.com"]},
{"sql": "INSERT INTO user_profiles (user_id, name) VALUES (?, ?)", "params": ["user123", "Test User"]}
]
},
"id": 2
}
User Management
user.getProfile()
Get the current user's profile.user.updateProfile(params: { email?: string, name?: string })
Update the current user's profile.user.changePassword(params: { currentPassword: string, newPassword: string })
Change the user's password.
System
system.getStatus()
Get system status and health information.system.getMetrics()
Get system metrics (CPU, memory, etc.).
🧪 Testing
Running Tests
# Run all tests
npm test
# Run tests with coverage
npm run test:coverage
# Run integration tests
npm run test:integration
# Run tests in watch mode
npm run test:watch
Test Coverage
We aim to maintain high test coverage. Current coverage:
- Unit Tests: ~90%
- Integration Tests: ~80%
- E2E Tests: ~70%
Linting
# Run linter
npm run lint
# Fix linting issues
npm run lint:fix
🚀 Deployment
Docker (Recommended)
# Build and run with Docker Compose
docker-compose up --build -d
# View logs
docker-compose logs -f
# Run migrations
docker-compose run --rm app npm run db:migrate
PM2 (Production)
# Install PM2 globally
npm install -g pm2
# Start in production
NODE_ENV=production pm2 start dist/index.js --name "mcp-server"
# Save process list
pm2 save
# Set up startup script
pm2 startup
# Monitor logs
pm2 logs mcp-server
# Monitor application
pm2 monit
Kubernetes
Example deployment:
apiVersion: apps/v1
kind: Deployment
metadata:
name: mcp-server
spec:
replicas: 3
selector:
matchLabels:
app: mcp-server
template:
metadata:
labels:
app: mcp-server
spec:
containers:
- name: mcp-server
image: your-registry/mcp-server:latest
ports:
- containerPort: 3000
envFrom:
- secretRef:
name: mcp-secrets
resources:
limits:
cpu: "1"
memory: "512Mi"
requests:
cpu: "0.5"
memory: "256Mi"
livenessProbe:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 5
periodSeconds: 5
📚 Documentation
🤝 Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request