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

Related MCP server: MCP Weather Server

🚀 Getting Started

Prerequisites

• Node.js 18+

• npm or yarn

• SQLite3 (included in most systems)

• Docker (optional, for containerized deployment)

Quick Start

1. 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 ..

2. Set up environment variables:

   # Run the setup script npm run setup # Or manually copy the example config cp config.example.ts .env

   Edit the .env file and update the configuration values as needed.

3. 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 URL

• OAUTH_CLIENT_ID: OAuth client ID

• OAUTH_CLIENT_SECRET: OAuth client secret

• OAUTH_REDIRECT_URI: OAuth redirect URI

• OAUTH_SCOPE: OAuth scopes (default: openid profile email)

🚀 Development

Running the Application

Development Mode

Production Build

Testing

🐳 Docker Support

The application includes Docker support for easy deployment:

📦 Production Deployment

For production deployment, consider the following:

1. Set NODE_ENV=production

2. Configure a reverse proxy (Nginx, Apache, etc.)

3. Set up HTTPS with a valid SSL certificate

4. Configure proper logging and monitoring

5. 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

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

Frontend

Production Build

⚙️ Configuration

Backend Environment Variables

Create a .env file in the root directory with the following variables:

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

1. Login

   POST /api/auth/login

   Authenticate with username and password.

2. Refresh Token

   POST /api/auth/refresh

   Get a new access token using a refresh token.

RPC Endpoint

Example request:

📦 Deployment

PM2 (Recommended for Production)

Docker

Base URL

All API endpoints are prefixed with /api/v1.

Authentication

1. Login

   GET /auth/login

   Initiates the OAuth 2.0 flow.

2. Callback

   GET /auth/callback

   OAuth callback URL (handled automatically).

3. Refresh Token

   POST /auth/refresh

   Refresh an access token.

JSON-RPC 2.0 Endpoint

All RPC methods require a valid JWT token in the Authorization header:

Example Request

Example response:

🔐 Authentication

The server uses OAuth 2.0 with OpenID Connect for authentication. The flow is as follows:

1. Client redirects to /auth/login

2. User authenticates with the OAuth provider

3. Provider redirects to /auth/callback with an authorization code

4. Server exchanges the code for tokens

5. 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 check

• GET /auth/login - OAuth login

• GET /auth/callback - OAuth callback

• POST /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

Test Coverage

We aim to maintain high test coverage. Current coverage:

• Unit Tests: ~90%

• Integration Tests: ~80%

• E2E Tests: ~70%

Linting

🚀 Deployment

Docker (Recommended)

PM2 (Production)

Kubernetes

Example deployment:

📚 Documentation

• API Documentation

• Developer Guide

• API Reference

🤝 Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/AmazingFeature)

3. Commit your changes (git commit -m 'Add some AmazingFeature')

4. Push to the branch (git push origin feature/AmazingFeature)

5. Open a Pull Request