appdevlpr/universal-mcp-server

Universal MCP Server Framework

An open-source, modular MCP (Model Context Protocol) server designed to connect Large Language Models to various real-world applications. This project provides a core engine, pluggable service connectors, and a Vite+React frontend for testing.

This monorepo contains:

• /backend: The Node.js MCP server.
• /frontend: A Vite+React control panel.

Features

• Modular Architecture: Easily add new service connectors (e.g., Discord, Slack).
• Secure by Default: Uses .env files to keep all secrets out of version control.
• Stateful WhatsApp Connection: Maintains your WhatsApp Web session.
• Real-time Telegram Bot: Connects instantly to the Telegram Bot API.
• React Control Panel: A simple UI to test your server's tools.

Project Setup

Prerequisites

• Node.js (LTS version, e.g., v20.x)
• Git

Installation & Configuration

1. Clone the repository:

   git clone <your-repo-url>
   cd universal-mcp-project
   

2. Set Up Backend:

   cd backend
   npm install
   cp .env.example .env
   

   Now, open backend/.env with a text editor (nano .env) and add your API keys.

3. Set Up Frontend:

   cd ../frontend
   npm install
   cp .env.example .env
   

   The default settings in frontend/.env should work for local development.

Running the Application

You will need two separate terminal sessions for this.

1. Start the Backend Server: Open your first terminal, navigate to the backend folder, and run:

   npm run dev
   

   On the first run for WhatsApp, a QR code will appear. Scan it with your phone.

2. Start the Frontend App: Open a second terminal, navigate to the frontend folder, and run:

   npm run dev
   

   Open your web browser on your phone and go to the URL shown in the terminal (usually http://localhost:5173).

You should now see the control panel and be able to execute commands through your backend server.