内容
# 🔨 MCP Forge
**MCP Forge** — 可扩展的工具集，基于 Model Context Protocol (MCP) 协议。
语言模型（本地或云端）通过统一的 TCP 协议访问邮件、搜索、天气、
汇率、剪贴板和其他工具。
---
## 📂 项目结构
```
mcp_forge/
├── mcp_forge_server.py # MCP 服务器 — 注册和执行工具
├── mcp_forge_host.py # 主机 — 连接 LLM 和 MCP 服务器
├── mcp_forge_client.py # MCP 的 TCP 客户端（JSON-RPC + \nEND\n）
├── mcp_forge_terminal.py # 终端 REPL（CLI 入口）
├── mcp_forge_host_openai.py # 简化主机，仅适用于 OpenAI API
├── gradio_forge_gui.py # 网页界面 — 10 个标签页用于所有工具
├── lmstudio_client.py # LM Studio 客户端（流媒体，模型管理）
├── vsegpt_client.py # VseGPT API 客户端（云端模型）
├── prompt_config.yaml # 系统提示词外部配置
├── mcp.json # MCP 服务器清单（兼容主机）
├── .env # 配置文件（从 env.example 创建）
├── env.example # 配置文件模板
├── requirements.txt # Python 依赖项
├── start_mcp_forge.cmd # 自动启动：服务器 + 主机（Windows）
└── _run_mcp_forge_server.bat # 启动服务器（Windows）
```
---
## 📚 文档
| 文件 | 内容 |
|---|---|
| **README.md** | 概述、架构、快速入门 |
| **INSTALL.md** | 安装、配置 `.env`、首次启动、诊断 |
| **TOOLS.md** | 所有工具和 GUI 的参考手册 |
| **CHAT_INTEGRATION.md** | Telegram 机器人、REST API、Open WebUI、LibreChat |
| **PROMPTS.md** | 自定义系统提示词 (`prompt_config.yaml`) |
---
## 🏗 架构
```
┌──────────────────────────────────────────────────────┐
│ 用户 │
│ 终端 · Telegram · 网页聊天 · Gradio GUI │
└─────────────────────┬────────────────────────────────┘
│
┌─────────────────────▼────────────────────────────────┐
│ mcp_forge_host.py │
│ ┌──────────────────────────────────────────────┐ │
│ │ AI_MODE=LOCAL AI_MODE=CLOUD │ │
│ │ lmstudio_client.py vsegpt_client.py │ │
│ │ (LM Studio / Ollama) (VseGPT / OpenAI) │ │
│ └──────────────────────────────────────────────┘ │
│ 请求分析 → tool_choice → 函数调用 │
└─────────────────────┬────────────────────────────────┘
│ 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 个标签页 · 网页界面用于所有工具 │
└──────────────────────────────────────────────────────┘
```
### AI 后端模式
| 模式 | 提供商 | 客户端文件 | 特性 |
|---|---|---|---|
| `LOCAL` | LM Studio | `lmstudio_client.py` | 流媒体，模型管理，免费 |
| `LOCAL` | Ollama | `lmstudio_client.py` | OpenAI 兼容 API，免费 |
| `CLOUD` | VseGPT | `vsegpt_client.py` | Claude, GPT-4, Gemini，通过一个密钥 |
| `CLOUD` | OpenAI | 内置于主机 | 直接访问 GPT-4o, gpt-4.1 |
### 用户界面模式
| 模式 | 启动方式 | 描述 |
|---|---|---|
| **终端** | `python mcp_forge_terminal.py` | Readline REPL 在控制台 |
| **GUI** | 命令“打开 GUI”或 `python gradio_forge_gui.py` | 浏览器，10 个标签页 |
| **Telegram** | `python telegram_bot.py` | 机器人（参见 CHAT_INTEGRATION.md） |
| **REST API** | `python api_server.py` | FastAPI（参见 CHAT_INTEGRATION.md） |
---
## ⚡ 快速入门
```bash
# 1. 从模板创建 .env
cp env.example .env # Linux / macOS
copy env.example .env # Windows
# 2. 填写 .env：EMAIL_*, AI_MODE, API 密钥
# 3. 安装依赖项
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
# 4. 启动
start_mcp_forge.cmd # Windows — 自动
python mcp_forge_server.py # Linux — 终端 1
python mcp_forge_terminal.py # Linux — 终端 2
```
详情 → **INSTALL.md**
---
## 🔌 MCP 协议
服务器和客户端通过 TCP 使用 JSON-RPC 2.0，带有 `\nEND\n` 分隔符。
这确保了消息边界清晰，即使传输大附件。
支持的协议版本：`2024-11-05`.
---
## 📄 许可证
MIT
