Content
# 🔨 MCP Forge
**MCP Forge** — an extensible set of tools based on the Model Context Protocol (MCP).
The language model (local or cloud) accesses email, search, weather,
currency exchange rates, clipboard, and other tools through a unified TCP protocol.
---
## 📂 Project Structure
```
mcp_forge/
├── mcp_forge_server.py # MCP server — registers and executes tools
├── mcp_forge_host.py # Host — connects LLM to MCP server
├── mcp_forge_client.py # TCP client MCP (JSON-RPC + \nEND\n)
├── mcp_forge_terminal.py # Terminal REPL (entry point for CLI)
├── mcp_forge_host_openai.py # Simplified host for OpenAI API only
├── gradio_forge_gui.py # Web interface — 10 tabs for all tools
├── lmstudio_client.py # LM Studio client (streaming, model management)
├── vsegpt_client.py # VseGPT API client (cloud models)
├── prompt_config.yaml # External system prompt configuration
├── mcp.json # MCP server manifest (for compatible hosts)
├── .env # Configuration (created from env.example)
├── env.example # Configuration template
├── requirements.txt # Python dependencies
├── start_mcp_forge.cmd # Autostart: server + host (Windows)
└── _run_mcp_forge_server.bat # Server only (Windows)
```
---
## 📚 Documentation
| File | Content |
|---|---|
| **README.md** | Overview, architecture, quick start |
| **INSTALL.md** | Installation, `.env` setup, first run, diagnostics |
| **TOOLS.md** | Reference of all tools and GUI |
| **CHAT_INTEGRATION.md** | Telegram bot, REST API, Open WebUI, LibreChat |
| **PROMPTS.md** | Customization of system prompt (`prompt_config.yaml`) |
---
## 🏗 Architecture
```
┌──────────────────────────────────────────────────────┐
│ User │
│ Terminal · Telegram · Web chat · Gradio GUI │
└─────────────────────┬────────────────────────────────┘
│
┌─────────────────────▼────────────────────────────────┐
│ mcp_forge_host.py │
│ ┌──────────────────────────────────────────────┐ │
│ │ AI_MODE=LOCAL AI_MODE=CLOUD │ │
│ │ lmstudio_client.py vsegpt_client.py │ │
│ │ (LM Studio / Ollama) (VseGPT / OpenAI) │ │
│ └──────────────────────────────────────────────┘ │
│ Request analysis → tool_choice → function calling │
└─────────────────────┬────────────────────────────────┘
│ TCP :8000 (JSON-RPC + \nEND\n)
┌─────────────────────▼────────────────────────────────┐
│ mcp_forge_server.py │
│ send_email search_web get_news │
│ get_weather get_time get_exchange_rate │
│ fetch_url generate_password generate_qr │
│ clipboard_read clipboard_write launch_gui │
└─────────────────────┬────────────────────────────────┘
│
┌─────────────────────▼────────────────────────────────┐
│ gradio_forge_gui.py :7860 │
│ 10 tabs · web interface for all tools │
└──────────────────────────────────────────────────────┘
```
### AI Backend Modes
| Mode | Provider | Client File | Features |
|---|---|---|---|
| `LOCAL` | LM Studio | `lmstudio_client.py` | Streaming, model management, free |
| `LOCAL` | Ollama | `lmstudio_client.py` | OpenAI-compatible API, free |
| `CLOUD` | VseGPT | `vsegpt_client.py` | Claude, GPT-4, Gemini via one key |
| `CLOUD` | OpenAI | built-in host | Direct access to GPT-4o, gpt-4.1 |
### User Interface Modes
| Mode | How to Launch | Description |
|---|---|---|
| **Terminal** | `python mcp_forge_terminal.py` | Readline REPL in console |
| **GUI** | command "open GUI" or `python gradio_forge_gui.py` | Browser, 10 tabs |
| **Telegram** | `python telegram_bot.py` | Bot (see CHAT_INTEGRATION.md) |
| **REST API** | `python api_server.py` | FastAPI (see CHAT_INTEGRATION.md) |
---
## ⚡ Quick Start
```bash
# 1. Create .env from template
cp env.example .env # Linux / macOS
copy env.example .env # Windows
# 2. Fill .env: EMAIL_*, AI_MODE, API keys
# 3. Install dependencies
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
# 4. Run
start_mcp_forge.cmd # Windows — automatically
python mcp_forge_server.py # Linux — Terminal 1
python mcp_forge_terminal.py # Linux — Terminal 2
```
Details → **INSTALL.md**
---
## 🔌 MCP Protocol
Server and client communicate over TCP via JSON-RPC 2.0 with `\nEND\n` delimiter.
This ensures clear message boundaries even with large attachments.
Supported protocol version: `2024-11-05`.
---
## 📄 License
MIT
