UniMCPSim - 通用MCP模拟器

UniMCPSim是一个通用的MCP（Model Context Protocol）模拟器，可以动态模拟各种产品的API接口，为开发和测试提供便利。

🌟 主要特性

• 通用MCP模拟器：基于FastMCP框架，支持标准MCP协议
• 多产品支持：预置9个常用产品模拟器，涵盖安全、通讯、网络、工单等领域
• MCP Playground ⭐ NEW v2.9.0：交互式MCP测试工具，通过大模型对话验证MCP Server是否正常工作
• AI增强响应：兼容OpenAI API接口（支持OpenAI、Qwen、Deepseek、Claude、Gemini等），生成真实的模拟响应数据
• 智能动作生成：基于数据库提示词模板，AI自动生成API动作定义
• 配置导入导出 (v2.8.0)：应用配置一键导入导出，支持批量迁移和备份
• Web界面配置 (v2.6.0)：通过可视化界面配置大模型参数，无需手动编辑配置文件
• 增强日志系统：详细记录所有MCP调用、AI调用、认证失败等，支持DEBUG模式
• Web管理界面：提供完整的Web后台管理系统
• Token权限管理：支持Token认证和细粒度权限控制
• 模板驱动：支持自定义提示词模板，快速创建新的应用模拟器
• 容器化部署 (v2.12.3)：支持Docker Compose、SQLite数据卷持久化和GitHub Actions自动构建发布

📁 项目结构

UniMCPSim/
├── README.md                 # 项目说明文档
├── requirements.txt          # Python依赖包
├── mcp_server.py            # MCP服务器主程序
├── admin_server.py          # Web管理后台
├── models.py                # 数据库模型定义
├── auth_utils.py            # 认证工具
├── ai_generator.py          # AI响应生成器
├── mcp_client.py            # MCP客户端（Playground用）
├── playground_service.py    # Playground服务
├── logger_utils.py          # 增强日志系统
├── start_servers.py         # 服务启动脚本
├── data/                    # 数据目录
│   └── unimcp.db           # SQLite数据库 (自动创建)
├── logs/                    # 日志目录 (自动创建)
│   ├── unimcp_all.log      # 所有日志
│   ├── unimcp_error.log    # 错误日志
│   └── unimcp_debug.log    # DEBUG详细日志
├── static/                  # 静态资源
│   └── css/
│       └── main.css        # 统一CSS样式
├── templates/               # HTML模板
│   ├── _navigation.html     # 导航组件
│   ├── _footer.html         # 页脚组件
│   ├── login.html           # 登录页
│   ├── dashboard.html       # 仪表板
│   ├── apps.html            # 应用管理
│   ├── tokens.html          # Token管理
│   ├── prompts.html         # 提示词管理
│   ├── playground.html      # MCP Playground
│   ├── logs.html            # 审计日志
│   └── change_password.html # 密码修改
└── tests/                   # 测试文件
    ├── simple_test.py       # 核心功能测试
    └── test_e2e.py         # 端到端测试
├── docs/                    # 文档目录
│   └── images/              # 图片资源
│       ├── diagrams/        # 架构图
│       │   ├── technical-architecture.svg  # 技术架构图 (SVG格式)
│       │   └── technical-architecture.png  # 技术架构图 (PNG格式)
│       └── screenshots/     # 功能截图

🏗️ 系统架构

UniMCPSim采用分层架构设计，清晰划分各组件职责，确保系统的可扩展性和可维护性。

技术架构图也提供 SVG格式 供高清查看

架构层次

系统整体分为四个核心层次，各层之间通过标准化接口进行交互：

1. 客户端层 (Client Layer)

• MCP客户端: 支持Claude Desktop、Cline、Continue等标准MCP客户端
• HTTP客户端: 兼容cURL、Postman等REST API工具
• Web浏览器: 提供友好的管理界面访问
• 测试客户端: 内置自动化测试脚本
• 外部系统: 支持CI/CD集成和自动化流程

2. 应用层 (Application Layer)

• MCP服务器 (mcp_server.py, 端口9090)

  • 基于FastMCP框架实现标准MCP协议
  • 支持动态工具注册和调用
  • 实现Token认证机制
  • 提供RESTful API接口

• 管理服务器 (admin_server.py, 端口9091)

  • 基于Flask框架构建
  • 提供Web管理界面
  • 用户认证和会话管理
  • 权限控制和审计功能

• 产品模拟器集合: 预置9个高频使用场景的模拟器

• 启动脚本 (start_servers.py): 一键启动所有服务

3. 服务层 (Service Layer)

• AI响应生成器 (ai_generator.py)

  • 兼容OpenAI API接口（支持OpenAI、Qwen、Deepseek、Claude、Gemini等）
  • 智能生成模拟响应数据
  • 基于提示词模板动态生成动作定义
  • 详细记录AI调用信息（耗时、token使用量等）

• 增强日志系统 (logger_utils.py)

  • 多层级日志文件（all/error/debug）
  • 详细记录MCP调用、AI调用、工具调用等
  • 支持DEBUG模式，记录完整调用详情
  • 日志自动轮转（10MB/文件，保留5个备份）

• 认证工具 (auth_utils.py)

  • 密码哈希和验证
  • JWT Token生成和验证
  • 会话管理

• 数据模型 (models.py)

  • SQLAlchemy ORM映射
  • 数据库抽象层
  • 业务实体定义

4. 数据层 (Data Layer)

• SQLite数据库: 轻量级本地存储，零配置
• 静态资源: CSS/JavaScript文件
• HTML模板: Jinja2模板引擎
• 环境配置: .env文件管理敏感配置

核心工作流程

1. 请求流程: 客户端 → MCP服务器 → 服务层 → 数据层
2. 认证流程: Token验证 → 权限检查 → 资源访问
3. AI增强流程: 请求解析 → 提示词构建 → OpenAI调用 → 响应格式化

技术优势

• 标准化协议: 完整支持MCP协议规范，确保与各类MCP客户端的兼容性
• 模块化设计: 各组件职责单一，便于独立开发和测试
• AI驱动: 利用大语言模型能力，动态生成真实的模拟数据
• 易于扩展: 通过Web界面或配置文件即可添加新的模拟器
• 零依赖部署: SQLite数据库无需额外配置，开箱即用

🚀 快速开始

1. 环境准备

确保已安装Python 3.8+

# 克隆项目
git clone <repository-url>
cd UniMCPSim

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Linux/Mac:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 设置环境变量（重要！）
unset HTTPS_PROXY
unset HTTP_PROXY

2. 环境变量配置

推荐方式： 通过Web界面配置大模型（v2.6.0+）

从 v2.6.0 开始，您可以通过 Web 管理界面配置大模型参数，无需手动编辑 .env 文件：

1. 启动服务后访问：http://localhost:9091/admin/
2. 登录（默认：admin / admin123）
3. 点击"大模型配置"菜单
4. 填写配置并点击"测试连接"验证
5. 保存配置即可使用

v2.11.0+ 多配置管理： 支持预注册多个大模型配置，一键切换活跃配置，配置热切换无需重启服务。

传统方式： 通过 .env 文件配置（可选，向后兼容）

如果您更喜欢使用配置文件，也可以创建 .env 文件：

# 创建.env文件
cat > .env << 'EOF'
# ===== AI大模型配置 =====
# 注意：v2.6.0+ 推荐通过Web界面配置，此处配置为备用方式
# 配置优先级：数据库配置（Web界面）> .env文件

# AI API配置（可选 - 推荐通过Web界面配置）
# 支持OpenAI、Qwen、Deepseek、Claude、Gemini等所有兼容OpenAI API的服务
OPENAI_API_KEY=your_api_key_here
OPENAI_MODEL=gpt-4o-mini
OPENAI_API_BASE_URL=https://api.openai.com/v1
OPENAI_ENABLE_THINKING=false  # 禁用思考模式,防止影响JSON输出(默认false)
OPENAI_STREAM=false  # 控制stream模式,某些模型如qwq-32b强制要求true(默认false)

# ===== 服务端口配置 =====
MCP_SERVER_PORT=9090
ADMIN_SERVER_PORT=9091

# ===== 日志配置 =====
DEBUG=false              # 启用DEBUG模式记录详细调用信息
LOG_LEVEL=INFO          # 日志级别: DEBUG, INFO, WARNING, ERROR
LOG_DIR=logs            # 日志文件存储目录
EOF

配置优先级说明（v2.6.0+）：

• 🥇 数据库配置（通过Web界面设置）- 最高优先级
• 🥈 .env 文件（传统方式）- 备用方案

⚠️ 注意：

• v2.6.0+ 推荐使用Web界面配置大模型（更安全、更方便）
• 如果数据库中已有配置，将优先使用数据库配置
• .env 文件作为备用方案，确保向后兼容
• 支持任何兼容OpenAI API接口的服务（OpenAI、Qwen、Deepseek、Claude、Gemini等）
• 如果没有配置AI API，新建应用的AI辅助生成功能将无法使用
• 启用DEBUG=true可记录完整的调用详情，包括完整token、headers、AI prompt等（仅用于排查问题）

OPENAI_ENABLE_THINKING配置说明：

• 默认值: false (禁用thinking模式)
• 用途: 控制大模型是否启用思考过程输出
• 重要性: 许多支持thinking模式的大模型(如qwen-thinking、DeepSeek-R1、QwQ等)在启用thinking时会在响应中包含思考过程,这会干扰JSON格式的解析,导致API响应生成失败
• 建议: 保持默认值false,除非你明确知道使用的模型不会因thinking模式影响JSON输出
• 设置为true: 仅在需要调试或使用特定模型时启用

OPENAI_STREAM配置说明：

• 默认值: false (禁用stream模式)
• 用途: 控制是否使用stream模式调用AI API
• 重要性: 某些模型(如qwq-32b)强制要求使用stream模式,否则会返回400错误:"This model only support stream mode"
• 适用模型: qwq-32b、部分deepseek-r1变体等
• 建议: 根据使用的模型调整
  • 常规模型(gpt-4o-mini、qwen3-max等): 保持false
  • 强制stream模型(qwq-32b等): 设置为true
• 注意: Stream模式下无法获取token使用量统计信息

3. 启动服务

方式一：一键启动（推荐）

python start_servers.py

方式二：分别启动

# 启动MCP服务器（端口9090）
python mcp_server.py

# 启动Web管理后台（端口9091）
python admin_server.py

看到以下输出表示启动成功：

==========================================================
UniMCPSim - Universal MCP Simulator
==========================================================

初始化默认模拟器...
✅ 已创建默认管理员用户

启动服务...
服务已启动:
----------------------------------------------------------
MCP服务器: http://localhost:9090/<Category>/<Product>?token=<token>
管理后台: http://localhost:9091/admin/
默认账号: admin / admin123
----------------------------------------------------------

按 Ctrl+C 停止服务

4. 访问服务

启动成功后，可以访问以下服务：

• MCP服务器: http://localhost:9090
• Web管理后台: http://localhost:9091/admin/
• 默认管理员账号:
  • 用户名: admin
  • 密码: admin123

🐳 Docker部署

使用Docker Compose（推荐）

# 构建并启动
docker compose up -d --build

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f unimcpsim

默认会挂载以下目录，容器升级或重建不会丢失数据：

./data  -> /app/data   # SQLite数据库
./logs  -> /app/logs   # 运行日志

使用已发布镜像

GitHub Actions 会在推送 main 或 v* 标签时构建并发布镜像到 GHCR：

docker pull ghcr.io/flagify-com/unimcpsim:latest
docker run -d --name unimcpsim \
  --restart unless-stopped \
  -p 9090:9090 \
  -p 9091:9091 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  -e TZ=Asia/Shanghai \
  ghcr.io/flagify-com/unimcpsim:latest

也可以使用指定提交对应的镜像标签，便于在生产环境锁定版本：

docker pull ghcr.io/flagify-com/unimcpsim:sha-8ff8e19

注意：GitHub Packages 的网页详情页可能因登录状态、组织权限或包权限配置显示 404；部署时以 docker pull ghcr.io/flagify-com/unimcpsim:<tag> 为准。如果 docker pull 返回 denied / unauthorized，请检查 GHCR 包是否已设置为 Public；如果返回超时或 TLS 握手失败，通常是网络或企业出口未放行 GHCR 相关域名。

企业内网离线交付

客户环境不能直连 GitHub / GHCR 时，可以在可联网环境先拉取官方镜像并导出离线包：

docker pull ghcr.io/flagify-com/unimcpsim:sha-8ff8e19

docker save ghcr.io/flagify-com/unimcpsim:sha-8ff8e19 \
  | gzip > unimcpsim-sha-8ff8e19.tar.gz

sha256sum unimcpsim-sha-8ff8e19.tar.gz > SHA256SUMS

将 unimcpsim-sha-8ff8e19.tar.gz 和 SHA256SUMS 传入内网后：

sha256sum -c SHA256SUMS
gunzip -c unimcpsim-sha-8ff8e19.tar.gz | docker load

docker tag ghcr.io/flagify-com/unimcpsim:sha-8ff8e19 unimcpsim:sha-8ff8e19

内网部署示例：

docker run -d --name unimcpsim \
  --restart unless-stopped \
  -p 9090:9090 \
  -p 9091:9091 \
  -v /opt/unimcpsim/data:/app/data \
  -v /opt/unimcpsim/logs:/app/logs \
  -e TZ=Asia/Shanghai \
  unimcpsim:sha-8ff8e19

如果客户有 Harbor / Nexus / 私有 Docker Registry，建议将官方镜像同步到内网镜像仓库，再由客户服务器从内网仓库拉取：

docker tag ghcr.io/flagify-com/unimcpsim:sha-8ff8e19 \
  harbor.example.com/security/unimcpsim:sha-8ff8e19

docker push harbor.example.com/security/unimcpsim:sha-8ff8e19

内网/国内环境构建

Dockerfile 支持构建参数，可使用国内镜像源或复用已有基础镜像加速构建：

docker build \
  --build-arg USE_CHINA_MIRRORS=true \
  --build-arg PYTHON_IMAGE=python:3.11-slim \
  -t unimcpsim:local .

# 如果内网已有基础镜像，也可以复用：
docker build \
  --build-arg USE_CHINA_MIRRORS=true \
  --build-arg PYTHON_IMAGE=deepsocx-backend:latest \
  -t unimcpsim:local .

🧪 功能验证测试

1. 测试核心功能

打开新终端，运行功能测试：

cd UniMCPSim
source venv/bin/activate
unset HTTPS_PROXY && unset HTTP_PROXY

# 运行核心功能测试
python tests/simple_test.py

期望输出：

############################################################
# UniMCPSim 功能验证测试
############################################################

============================================================
测试应用列表功能
============================================================
✅ 找到 9 个已启用的应用:
   - VirusTotal威胁情报 (/Security/VirusTotal)
   - 微步在线威胁情报 (/Security/ThreatBook)
   - 青藤云HIDS (/Security/QingTengHIDS)
   - 企业微信 (/IM/WeChat)
   - 腾讯会议 (/Meeting/TencentMeeting)
   - Jira工单系统 (/Ticket/Jira)
   - 华为交换机 (/Network/HuaweiSwitch)
   - Cisco路由器 (/Network/CiscoRouter)
   - 深信服防火墙 (/Firewall/Sangfor)

============================================================
UniMCPSim 核心功能测试
============================================================
✅ 使用Token: dbb02af0...a525

测试 1: 企业微信发送消息 ✅ 成功
测试 2: VirusTotal IP扫描 ✅ 成功
测试 3: Jira创建工单 ✅ 成功
测试 4: 深信服防火墙封禁IP ✅ 成功
测试 5: 华为交换机查看接口 ✅ 成功

============================================================
测试总结
============================================================
🎉 所有测试通过!

2. Web管理后台验证

浏览器访问：http://localhost:9091/admin/

• 用户名：admin
• 密码：admin123

可以查看：

• 📊 系统概览
• 🔧 应用管理
• 🎫 Token管理
• 📋 审计日志

3. API接口测试

# 获取Demo Token - 方法1：从管理后台复制
# 访问 http://localhost:9091/admin/tokens 复制Demo Token

# 获取Demo Token - 方法2：使用脚本
TOKEN=$(python -c "
import sys
sys.path.append('.')
from models import db_manager, Token
session = db_manager.get_session()
try:
    demo_token = session.query(Token).filter_by(name='Demo Token').first()
    if demo_token:
        print(demo_token.token)
finally:
    session.close()
")

# 测试企业微信发送消息
curl "http://localhost:9090/IM/WeChat?token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "send_text_message",
    "parameters": {
      "to_user": "test_user",
      "content": "Hello from UniMCPSim!"
    }
  }'

🔧 配置说明

预置模拟器列表

系统预置了以下9个产品模拟器：

分类	产品名称	路径	功能描述
Security	VirusTotal威胁情报	/Security/VirusTotal	IP/域名威胁检测
Security	微步在线威胁情报	/Security/ThreatBook	威胁情报查询
Security	青藤云HIDS	/Security/QingTengHIDS	主机入侵检测
IM	企业微信	/IM/WeChat	企业即时通讯
Meeting	腾讯会议	/Meeting/TencentMeeting	视频会议管理
Ticket	Jira工单系统	/Ticket/Jira	工单管理
Network	华为交换机	/Network/HuaweiSwitch	网络设备管理
Network	Cisco路由器	/Network/CiscoRouter	路由器配置
Firewall	深信服防火墙	/Firewall/Sangfor	防火墙策略管理

API使用示例

企业微信发送消息示例

# 获取Demo Token (在管理后台获取或使用脚本)
TOKEN="demo-token-here"

# 直接调用企业微信API端点
curl "http://localhost:9090/IM/WeChat?token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "send_text_message",
    "parameters": {
      "to_user": "test_user",
      "content": "Hello from UniMCPSim!"
    }
  }'

其他产品示例

VirusTotal IP扫描

curl "http://localhost:9090/Security/VirusTotal?token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "scan_ip",
    "parameters": {
      "ip": "8.8.8.8"
    }
  }'

Jira创建工单

curl "http://localhost:9090/Ticket/Jira?token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_issue",
    "parameters": {
      "project_key": "TEST",
      "issue_type": "Task",
      "summary": "测试工单",
      "description": "这是一个测试工单",
      "priority": "High"
    }
  }'

深信服防火墙封禁IP

curl "http://localhost:9090/Firewall/Sangfor?token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "block_ip_address",
    "parameters": {
      "ip_address": "192.168.1.100",
      "reason": "可疑活动"
    }
  }'

📚 MCP客户端接入指南

Cherry Studio 集成示例

UniMCPSim 完美支持 Cherry Studio 等 MCP 客户端，以下是详细的集成步骤：

1. 在 Cherry Studio 中创建 MCP 服务器

在 Cherry Studio 中：

1. 打开设置页面
2. 选择 "MCP 服务器" 选项
3. 点击 "添加新服务器"

2. 配置 UniMCPSim 服务器

配置参数：

• 服务器名称: UniMCPSim
• 服务器地址: http://localhost:9090/{Category}/{Product}?token={your-token}
• 协议: HTTP
• 认证: Token认证

示例配置：

• 企业微信: http://localhost:9090/IM/WeChat?token=your-demo-token
• 威胁情报: http://localhost:9090/Security/VirusTotal?token=your-demo-token

3. 查看可用工具列表

配置成功后，Cherry Studio 会自动识别 UniMCPSim 提供的所有工具：

• ✅ 企业微信消息发送
• ✅ 威胁情报查询
• ✅ 工单管理
• ✅ 网络设备控制
• ✅ 防火墙策略管理

4. 在对话中使用 MCP 工具

在 Cherry Studio 的对话界面中：

1. 自然语言描述需求
2. AI自动选择合适的工具
3. 执行具体操作
4. 获取真实的模拟响应

MCP Playground 测试工具 ⭐ NEW v2.9.0

UniMCPSim v2.9.0 新增 MCP Playground 功能，无需外部客户端即可直接在 Web 界面中测试 MCP Server。

功能特点

• 可视化配置: 通过 JSON 编辑器配置任意 MCP Server
• 实时连接测试: 一键测试连接并查看可用工具列表
• AI 对话交互: 通过自然语言与大模型对话，自动调用 MCP 工具
• 工具调用可视化: 实时显示工具调用过程和返回结果
• 自定义系统提示词: 可编辑系统提示词控制 AI 行为

使用方法

1. 登录管理后台，点击导航栏的"MCP Playground"
2. 在左侧配置区粘贴 MCP Server 配置（JSON 格式）
3. 点击"测试连接"验证配置并获取工具列表
4. 在右侧对话区输入指令，AI 将自动调用相应的 MCP 工具

MCP 配置示例

{
  "mcpServers": {
    "QAXFW": {
      "name": "奇安信防火墙",
      "type": "streamableHttp",
      "description": "奇安信防火墙MCP服务",
      "isActive": true,
      "baseUrl": "http://127.0.0.1:9090/Firewall/QAXFW?token=YOUR_TOKEN_HERE"
    }
  }
}

适用场景

• 🔧 快速验证新建的 MCP Server 是否正常工作
• 🧪 测试 MCP 工具的参数和返回值
• 📚 学习和了解 MCP 协议的工作方式
• 🔍 调试 MCP 工具调用问题

🛠️ 管理后台使用指南

Web管理界面功能

1. 登录系统

   • 访问 http://localhost:9091/admin/
   • 使用默认账号登录（admin / admin123）

2. 仪表板

   • 查看系统运行状态和统计信息
   • 监控应用数量、Token数量、今日调用量
   • 显示系统启动时间和健康状态

3. 应用管理 ⭐ 增强功能

   • 查看所有可用应用列表
   • 创建新的应用模拟器
   • 编辑应用配置和动作定义
   • 点击应用名称查看详细信息：完整的应用信息和动作列表
   • 一键生成MCP配置：自动生成标准MCP客户端配置，支持复制到Cherry Studio、Claude Desktop或Cline
   • 配置导入导出 (v2.8.0)：
     • 📤 导出：支持导出全部应用或选择性导出指定应用，自动生成时间戳文件名
     • 📥 导入：从JSON文件导入应用配置，导入前预览新建/覆盖应用列表
     • 自动识别同名应用（按category+name匹配）并直接覆盖
     • 完整的JSON格式验证和友好错误提示
     • 导入成功后提醒手动设置Token权限
   • 使用AI自动生成动作定义

4. Token管理 ⭐ 增强功能

   • 创建新的访问Token
   • 可视化权限管理：通过模态框查看和编辑Token权限
   • 批量权限设置：全选/取消全选功能，快速配置应用访问权限
   • 查看Token使用记录和授权应用数量
   • 启用/禁用Token

5. 提示词管理

   • 管理AI生成提示词模板
   • 自定义动作生成和响应模拟模板
   • 支持系统变量（app_name, action_name等）

6. 审计日志

   • 查看所有API调用记录
   • 监控系统使用情况
   • 追踪操作历史

7. 账户管理

   • 修改管理员密码
   • 安全退出

创建新应用示例

以下是在管理后台创建新应用的截图示例：

创建安恒网络安全扫描器应用

创建微步在线威胁情报应用

通过Web界面可以轻松：

• 📝 填写应用基本信息
• 🔧 配置API动作定义
• 🤖 使用AI自动生成动作
• ✅ 实时验证配置

3. Token管理

   • 创建新的访问Token
   • 配置Token权限
   • 查看Token使用记录

4. 审计日志

   • 查看所有API调用记录
   • 监控系统使用情况

添加新的模拟器

通过Web管理界面添加（推荐）

1. 访问 http://localhost:9091/admin/
2. 登录管理后台
3. 进入"应用管理"页面
4. 点击"创建新应用"按钮
5. 填写应用信息：
   • 应用名称（英文）
   • 显示名称（中文）
   • 分类
   • 描述
6. 配置动作定义或使用AI自动生成

动作定义格式

在创建应用时，动作定义使用以下JSON格式：

[
  {
    "name": "your_action",
    "display_name": "动作显示名称",
    "description": "动作描述",
    "parameters": [
      {
        "key": "param_name",
        "type": "String",
        "required": true,
        "description": "参数描述"
      }
    ]
  }
]

访问新的模拟器

创建完成后，即可通过以下URL访问：

http://localhost:9090/{Category}/{ProductName}?token=<your-token>

🎯 MCP协议详细使用说明

MCP服务器地址

产品特定端点（推荐）

URL格式: http://localhost:9090/<Category>/<Product>?token=<your-token>

示例端点:

• 企业微信: http://localhost:9090/IM/WeChat?token=<your-token>
• 华为交换机: http://localhost:9090/Network/HuaweiSwitch?token=<your-token>
• 深信服防火墙: http://localhost:9090/Firewall/Sangfor?token=<your-token>

完整MCP使用示例

步骤1：初始化MCP连接

curl -X POST "http://localhost:9090/IM/WeChat?token=f1bb3770-6e46-4fe6-b518-e1c738c7b6a4" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "0.1.0",
      "capabilities": {},
      "clientInfo": {
        "name": "demo-client",
        "version": "1.0.0"
      }
    },
    "id": 1
  }' \
  -D headers.txt

响应示例:

event: message
data: {
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "experimental": {},
      "prompts": {"listChanged": true},
      "resources": {"subscribe": false, "listChanged": true},
      "tools": {"listChanged": true}
    },
    "serverInfo": {
      "name": "UniMCPSim",
      "version": "1.0.0"
    },
    "instructions": "Universal MCP Simulator - 通用MCP模拟器，可动态模拟各种产品的API接口"
  }
}

重要: 从响应头中提取mcp-session-id：

session_id=$(grep -i 'mcp-session-id:' headers.txt | tr -d '\r' | cut -d' ' -f2-)
echo "会话ID: $session_id"

步骤2：企业微信发送消息示例

# 使用提取的会话ID
curl -X POST "http://localhost:9090/IM/WeChat?token=f1bb3770-6e46-4fe6-b518-e1c738c7b6a4" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $session_id" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "execute_action",
      "arguments": {
        "token": "f1bb3770-6e46-4fe6-b518-e1c738c7b6a4",
        "category": "IM",
        "product": "WeChat",
        "action": "send_message",
        "parameters": {
          "to_user": "zhang.san",
          "text": "项目会议将于明天下午2点在A会议室举行，请准时参加。"
        }
      }
    },
    "id": 2
  }'

Python客户端示例

import asyncio
import httpx
import json

class UniMCPSimClient:
    def __init__(self, base_url="http://localhost:9090", token=None, product_path=None):
        self.base_url = base_url
        self.token = token
        self.product_path = product_path  # 例如: "IM/WeChat"
        self.session_id = None

    @property
    def endpoint_url(self):
        """获取完整的端点URL"""
        if self.product_path:
            return f"{self.base_url}/{self.product_path}"
        else:
            return f"{self.base_url}/mcp"

    async def initialize(self):
        """初始化MCP连接"""
        async with httpx.AsyncClient() as client:
            payload = {
                "jsonrpc": "2.0",
                "method": "initialize",
                "params": {
                    "protocolVersion": "0.1.0",
                    "capabilities": {},
                    "clientInfo": {"name": "python-client", "version": "1.0.0"}
                },
                "id": 1
            }

            response = await client.post(
                f"{self.endpoint_url}?token={self.token}",
                json=payload,
                headers={
                    "Content-Type": "application/json",
                    "Accept": "application/json, text/event-stream"
                }
            )

            # 提取会话ID
            self.session_id = response.headers.get('mcp-session-id')
            return response.status_code == 200

    async def execute_action(self, category, product, action, parameters):
        """执行模拟器动作"""
        if not self.session_id:
            raise Exception("请先调用initialize()初始化连接")

        async with httpx.AsyncClient() as client:
            payload = {
                "jsonrpc": "2.0",
                "method": "tools/call",
                "params": {
                    "name": "execute_action",
                    "arguments": {
                        "token": self.token,
                        "category": category,
                        "product": product,
                        "action": action,
                        "parameters": parameters
                    }
                },
                "id": 2
            }

            response = await client.post(
                f"{self.endpoint_url}?token={self.token}",
                json=payload,
                headers={
                    "Content-Type": "application/json",
                    "Accept": "application/json, text/event-stream",
                    "mcp-session-id": self.session_id
                }
            )

            return response.text

# 使用示例
async def main():
    # 使用产品特定端点（推荐）
    client = UniMCPSimClient(
        token="f1bb3770-6e46-4fe6-b518-e1c738c7b6a4",
        product_path="IM/WeChat"
    )

    # 初始化连接
    if await client.initialize():
        print("✅ MCP连接初始化成功")

        # 企业微信发送消息
        result = await client.execute_action(
            category="IM",
            product="WeChat",
            action="send_message",
            parameters={
                "to_user": "zhang.san",
                "text": "Python客户端测试消息"
            }
        )
        print("发送消息结果:", result)
    else:
        print("❌ MCP连接初始化失败")

# 运行示例
if __name__ == "__main__":
    asyncio.run(main())

🧪 测试

核心功能测试

# 运行核心功能测试
python tests/simple_test.py

测试内容包括：

• ✅ 应用列表功能
• ✅ 企业微信发送消息
• ✅ VirusTotal IP扫描
• ✅ Jira创建工单
• ✅ 深信服防火墙封禁IP
• ✅ 华为交换机查看接口

端到端测试

# 运行端到端测试（需要服务器运行）
python tests/test_e2e.py

一键测试脚本

创建文件 test_wechat.sh：

#!/bin/bash

# 设置变量
MCP_SERVER="http://localhost:9090/IM/WeChat"
TOKEN="f1bb3770-6e46-4fe6-b518-e1c738c7b6a4"

echo "=== UniMCPSim 企业微信测试 ==="

# 步骤1：初始化连接
echo "1. 初始化MCP连接..."
init_response=$(curl -s -X POST "${MCP_SERVER}?token=${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "0.1.0",
      "capabilities": {},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    },
    "id": 1
  }' \
  -D /tmp/headers.txt)

# 提取会话ID
session_id=$(grep -i 'mcp-session-id:' /tmp/headers.txt | tr -d '\r' | cut -d' ' -f2-)

if [ -z "$session_id" ]; then
    echo "❌ 获取会话ID失败"
    exit 1
fi

echo "✅ 连接成功，会话ID: $session_id"

# 步骤2：发送消息
echo ""
echo "2. 测试企业微信发送消息..."
msg_response=$(curl -s -X POST "${MCP_SERVER}?token=${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $session_id" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "execute_action",
      "arguments": {
        "token": "'$TOKEN'",
        "category": "IM",
        "product": "WeChat",
        "action": "send_message",
        "parameters": {
          "to_user": "test.user",
          "text": "这是一条测试消息"
        }
      }
    },
    "id": 2
  }')

if echo "$msg_response" | grep -q "event: message"; then
    echo "✅ 消息发送成功"
    echo "$msg_response" | grep "data:" | sed 's/data: //'
else
    echo "❌ 消息发送失败"
    echo "$msg_response"
fi

echo ""
echo "=== 测试完成 ==="

使用方法：

chmod +x test_wechat.sh
./test_wechat.sh

🔍 故障排除

常见问题

1. 端口被占用

# 检查端口占用
lsof -i :9090
lsof -i :9091

# 杀死占用进程
kill -9 <PID>

2. 依赖安装失败

# 升级pip
pip install --upgrade pip

# 清除缓存重新安装
pip cache purge
pip install -r requirements.txt

3. 数据库错误

# 完全重置
rm -rf data/
mkdir data
python init_simulators.py

4. 网络代理干扰

# 确保取消代理设置
unset HTTPS_PROXY
unset HTTP_PROXY
unset http_proxy
unset https_proxy

# 验证
echo $HTTPS_PROXY  # 应该为空

调试和故障排除

常见错误

1. HTTP 406 Not Acceptable

   • 缺少正确的Accept头
   • 解决：添加 Accept: application/json, text/event-stream

2. HTTP 400 Bad Request: Missing session ID

   • 未先进行initialize或session ID丢失
   • 解决：先调用initialize方法获取session ID

3. HTTP 401 Unauthorized

   • Token无效或已过期
   • 解决：检查Token是否正确

4. 工具调用返回error

   • 参数不正确或缺少必填参数
   • 解决：检查API文档确认参数格式

查看详细日志

启动服务器时可以看到详细的请求日志：

python mcp_server.py

获取可用Token

# 通过Web管理后台
curl "http://localhost:9091/admin/api/tokens" -H "Authorization: Bearer <session>"

# 或直接查询数据库
python -c "
from models import db_manager, Token
session = db_manager.get_session()
tokens = session.query(Token).filter_by(enabled=True).all()
for token in tokens:
    print(f'{token.name}: {token.token}')
session.close()
"

常用操作

重启服务

# 停止服务 (Ctrl+C)
# 重新启动
python start_servers.py

重置数据库

# 删除现有数据库
rm -f data/unimcp.db

# 重新初始化
python init_simulators.py

🎯 成功标志

看到以下输出表示系统运行正常：

1. 服务启动成功：

   • MCP服务器运行在9090端口
   • Web管理后台运行在9091端口
   • 无错误日志输出

2. 功能测试通过：

   • python tests/simple_test.py 显示 "🎉 所有测试通过!"
   • 9个应用模拟器全部可用
   • Demo Token正常工作

3. Web界面正常：

   • 能够正常登录管理后台
   • 各个页面加载正常
   • 数据显示正确

🔧 开发说明

技术栈

• 后端框架: FastMCP (MCP服务) + Flask (Web管理)
• 数据库: SQLite + SQLAlchemy ORM
• AI集成: OpenAI API
• 前端: HTML + CSS + JavaScript (原生)
• 认证: JWT Token + 会话管理

扩展开发

1. 添加新的MCP工具

@mcp.tool()
async def your_new_tool(param1: str, param2: int) -> str:
    """工具描述"""
    # 实现逻辑
    return "result"

2. 自定义AI响应模板 编辑 ai_generator.py 中的响应模板

3. 添加新的Web页面 在 templates/ 目录添加HTML模板，在 admin_server.py 添加路由

📊 日志系统

UniMCPSim v2.3+ 引入了增强的日志系统，帮助您更好地诊断和监控系统运行。

日志文件

所有日志文件存储在 logs/ 目录（可通过环境变量 LOG_DIR 自定义）：

• unimcp_all.log - 所有日志（INFO及以上级别）

  • 记录所有成功和失败的请求
  • 包含基本的调用信息（路径、方法、token前8位等）
  • 适合日常监控和审计

• unimcp_error.log - 错误日志

  • 只记录错误和警告
  • 快速定位问题
  • 包含详细的错误堆栈信息

• unimcp_debug.log - DEBUG详细日志（仅在DEBUG模式下生成）

  • 记录完整的调用详情
  • 包含完整token、HTTP headers、完整请求/响应内容
  • AI调用的完整prompt和response
  • 数据库操作详情
  • 仅用于排查复杂问题

记录内容

1. MCP Server调用

2025-09-30 16:05:12 - INFO - MCP Request: POST:tools/list /ThreatIntelligence/Threatbook - SUCCESS

记录信息：

• 请求方法和MCP方法名
• 应用路径
• Token（默认只记录前8位）
• 请求参数
• 是否成功
• 错误信息（如果失败）

2. AI模型调用

2025-09-30 16:10:30 - INFO - AI Call: OpenAI/qwen3-max - SUCCESS (duration: 1.23s)

记录信息：

• AI提供商和模型
• 调用耗时
• Token使用量（prompt_tokens、completion_tokens）
• DEBUG模式下记录完整的prompt和response

3. 工具调用

2025-09-30 16:12:15 - INFO - Tool Call: query_ip_threat_intel (app: ThreatIntelligence/Threatbook) - SUCCESS

记录信息：

• 工具名称
• 所属应用
• 参数
• 执行结果
• 错误信息（如果失败）

4. 认证失败

2025-09-30 16:15:00 - WARNING - Auth Failure: Token required (path: /IM/WeChat, ip: 127.0.0.1)

记录信息：

• 失败原因
• 访问路径
• 客户端IP
• Token信息（如有）

DEBUG模式

启用DEBUG模式可记录更详细的诊断信息：

# 在 .env 文件中设置
DEBUG=true
LOG_LEVEL=DEBUG

DEBUG模式额外记录：

• ✅ 完整的API Token（非DEBUG只记录前8位）
• ✅ 完整的HTTP Headers
• ✅ 完整的请求和响应内容
• ✅ AI调用的完整prompt和response
• ✅ 数据库操作详情

⚠️ 安全提醒：

• DEBUG模式会记录敏感信息（token、prompt等），仅在开发和排查问题时启用
• 生产环境请使用 DEBUG=false
• 日志文件已自动添加到 .gitignore，不会被提交到版本控制

日志轮转

日志系统自动进行文件轮转：

• 单个日志文件最大 10MB
• 保留最近 5 个备份文件
• 自动压缩和清理旧日志

使用场景

1. 监控MCP调用

   # 实时查看所有请求
   tail -f logs/unimcp_all.log
   
   # 只看错误
   tail -f logs/unimcp_error.log
   

2. 排查Cherry Studio调用问题

   • 启用DEBUG模式
   • 查看 unimcp_debug.log 中的完整headers和session ID
   • 确认是否真正调用了MCP Server

3. 诊断AI响应问题

   • 启用DEBUG模式
   • 查看AI调用的完整prompt和response
   • 检查token使用量和耗时

4. 审计和安全

   • 查看认证失败记录
   • 追踪特定token的使用情况
   • 监控异常访问模式

🤝 贡献

欢迎提交Issue和Pull Request来改进项目！

📄 许可证

本项目采用MIT许可证 - 查看 LICENSE 文件了解详情

📞 支持

如有问题或建议，请：

• 提交GitHub Issue
• 联系项目维护者

---

UniMCPSim - 让API模拟变得简单高效！🚀

现在您可以：

• 🔌 通过MCP协议连接各种客户端如Cherry Studio
• 🌐 使用Web界面管理应用和Token
• 🧪 开发和测试需要多种API的应用
• 🔧 根据需要添加自定义模拟器
• 🤖 利用AI智能生成真实的模拟响应