WongJingGitt/mcp_bridge_server

🌉 MCP Bridge Server

📖 简介

MCP Bridge Server 是 MCP Bridge 浏览器扩展 的本地桥接服务，负责管理和调用遵循 MCP (Model Context Protocol) 协议的工具服务。

通过标准的 HTTP REST API 与浏览器扩展通信，本服务在后台动态启动、管理和调用一个或多个 MCP 服务进程，并将它们的能力统一暴露给网页版 AI 平台（DeepSeek、通义千问、腾讯元宝、豆包等）。

架构示意图

┌─────────────────┐                    ┌──────────────────────┐
│  浏览器扩展     │ ◄── HTTP/REST ──► │  MCP Bridge Server   │
│  (前端界面)     │                    │  (本项目)            │
└─────────────────┘                    └──────────┬───────────┘
                                                  │ MCP Protocol
                                                  │ (stdio)
                                       ┌──────────▼───────────┐
                                       │  MCP 工具服务进程     │
                                       │  • filesystem        │
                                       │  • git               │
                                       │  • database          │
                                       │  • ...               │
                                       └──────────────────────┘

✨ 核心特性

🎯 核心能力

• 统一管理 - 通过简单的 JSON 配置同时管理多个 MCP 服务
• 分层工具发现 - 两阶段发现机制：先获取服务概览，再按需查询工具详情，节省 Token
• 动态配置 - 支持热重载，无需重启服务即可应用新配置
• 跨平台兼容 - 自动适配 Windows/macOS/Linux，配置存储在标准用户目录

🛡️ 高级特性

• 零依赖运行 - 可打包为单一可执行文件，无需安装 Python 环境
• 智能端口管理 - 自动检测端口占用，提供交互式处理方案
• 服务热重启 - 支持单独重启某个服务，不影响其他服务
• 错误追踪 - 返回详细的错误堆栈信息，帮助 AI 自主诊断和修正
• 熔断保护 - 内置重试和熔断机制，防止故障服务影响整体稳定性

🚀 性能优化特性

• 智能缓存系统 - 大结果自动缓存，支持内存和文件两级缓存
• 流式搜索 - 在大文件中快速搜索关键词，内存占用恒定
• 分段获取 - 支持按需分段获取大结果，避免一次性传输过多数据
• 精确定位 - 快速获取指定行的上下文内容

🚀 快速开始

前置要求

• 运行环境:
  • 使用可执行文件：无需任何依赖
  • 从源码运行：Python 3.8+

1️⃣ 下载服务

方式一：下载可执行文件（推荐）

从 Releases 下载对应平台的可执行文件：

• Windows: mcp-bridge-server.exe
• macOS: mcp-bridge-server-macos
• Linux: mcp-bridge-server-linux

方式二：克隆源码

git clone https://github.com/WongJingGitt/mcp_bridge_server.git
cd mcp_bridge_server
pip install -r requirements.txt

2️⃣ 启动服务

使用启动脚本（推荐）

# 双击运行或在命令行执行
start.bat

MCP Bridge Server v1.0.0
请选择启动方式:
  1. 默认启动 (端口 3849, 交互式处理端口占用)
  2. 自动处理端口占用 (强制结束占用进程)
  3. 使用自定义端口
  4. 查看帮助
  5. 退出

# 赋予执行权限（首次）
chmod +x start.sh

# 运行
./start.sh

直接运行（开发者）

# 默认启动（端口 3849）
python utils/mcp_bridge.py

# 自动处理端口占用
python utils/mcp_bridge.py --auto-kill-port

# 使用自定义端口
python utils/mcp_bridge.py --port 8080

# 组合参数
python utils/mcp_bridge.py --port 8080 --auto-kill-port

命令行参数：

环境变量：

端口占用处理

首次运行时自动检测端口占用：

MCP Bridge Server v1.0.0
正在检查端口 3849...

⚠️  端口 3849 已被占用
   占用进程: python.exe (PID: 12345)

请选择操作:
  1. 结束占用进程并继续
  2. 使用其他端口
  3. 退出程序

请输入选项 (1/2/3): 

详细说明请参考 。

3️⃣ 首次运行

服务启动后，会在系统用户目录自动创建默认配置文件：

• Windows: %APPDATA%\mcp-bridge\config\mcp-config.json
• macOS: ~/Library/Application Support/mcp-bridge/config/mcp-config.json
• Linux: ~/.config/mcp-bridge/config/mcp-config.json

成功启动后会显示：

✓ 配置文件已创建: C:\Users\YourName\AppData\Roaming\mcp-bridge\config\mcp-config.json
✓ MCP Bridge Server 正在运行于 http://localhost:3849
✓ 服务已就绪，等待浏览器扩展连接...

⚙️ 配置指南

这是使用本项目的核心步骤。您需要告诉桥接服务去哪里找到并启动您的 MCP 工具。

配置文件位置

首次运行后自动创建在：

配置文件结构

打开 mcp-config.json，您会看到默认结构：

{
  "mcpServers": {
    "example_service": {
      "enabled": true,
      "command": "path/to/your/mcp/server/executable",
      "args": ["--port", "8080"],
      "description": "这是一个示例服务，请替换成你自己的配置",
      "env": {}
    }
  }
}

配置示例

示例 1：文件系统工具

{
  "mcpServers": {
    "filesystem": {
      "enabled": true,
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\YourName\\Documents"],
      "description": "提供文件系统访问能力，可以读写指定目录下的文件"
    }
  }
}

示例 2：Git 仓库管理

{
  "mcpServers": {
    "git": {
      "enabled": true,
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "C:\\myrepo"],
      "description": "管理 Git 仓库，查看提交历史、分支、差异等"
    }
  }
}

示例 3：多服务配置

{
  "mcpServers": {
    "filesystem": {
      "enabled": true,
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:\\data"],
      "description": "文件系统访问工具"
    },
    "weather": {
      "enabled": true,
      "command": "python",
      "args": ["C:\\tools\\weather_server.py"],
      "description": "提供实时天气信息和未来天气预报",
      "env": {
        "API_KEY": "your_api_key_here"
      }
    },
    "calculator": {
      "enabled": false,
      "command": "C:\\tools\\calculator.exe",
      "args": [],
      "description": "执行复杂数学计算和表达式求值"
    }
  }
}

字段说明

应用新配置

配置修改后，有两种方式应用：

方式 1：重启服务

# 停止服务 (Ctrl+C)
# 重新运行启动脚本
./start.sh  # 或 start.bat

方式 2：热重载（推荐）

# 重载所有服务
curl -X POST http://localhost:3849/reload

# 或使用浏览器扩展的设置页面
# Options → 服务配置 → 保存并重载服务

方式 3：单独重启某个服务

curl -X POST http://localhost:3849/restart-server \
  -H "Content-Type: application/json" \
  -d '{"serverName": "filesystem"}'

详细说明请参考 。

验证配置

配置成功后，在命令行窗口应该看到：

✓ 服务器 filesystem 初始化成功 (5 个工具)
✓ 服务器 weather 初始化成功 (3 个工具)
✗ 服务器 calculator 已禁用

也可以通过 API 验证：

# 查看所有服务
curl http://localhost:3849/tools

# 查看特定服务的工具
curl http://localhost:3849/tools?serverName=filesystem

服务启动后，默认监听本地的 3849 端口（可通过 --port 参数修改）。

核心接口

工具执行接口

GET /health

• 功能: 健康检查。
• 返回: { "status": "ok", "timestamp": 1678886400000 }

GET /tools

• 功能: (第一层发现) 获取所有已加载服务的列表及其描述。
• 返回:

  {
    "success": true,
    "services": [
      { "name": "weather_service", "description": "..." },
      { "name": "calculator_service", "description": "..." }
    ]
  }
  

GET /tools?serverName=<name>

• 功能: (第二层发现) 根据服务名称，获取该服务下的所有具体工具的详细信息。
• 参数: serverName - 您在配置文件中定义的服务名称。
• 返回:

  {
    "success": true,
    "tools": [
      {
        "name": "get_current_weather",
        "description": "获取指定城市的当前天气",
        "parameters": { /* JSON Schema */ },
        "serverName": "weather_service"
      }
    ]
  }
  

POST /execute

• 功能: 执行一个指定的工具。
• 请求体: { "name": "tool_name", "arguments": { "param": "value" } }
• 成功返回: { "success": true, "result": [...] }
• 错误返回:

  {
    "detail": {
      "error": "错误消息",
      "type": "ErrorType",
      "traceback": "完整的 Python 调用堆栈"
    }
  }
  

  错误处理增强: 从 v1.1 开始,执行失败时会返回详细的错误信息,包括错误类型和完整的 Python 调用堆栈,帮助快速定位问题。浏览器扩展会将这些信息展示给 AI 模型,以便模型分析错误原因并尝试修正。

POST /reload

• 功能: 重新加载并初始化配置文件中的所有服务。当您修改了 mcp-config.json 后，调用此接口可使配置生效，无需重启主服务。
• 返回: { "success": true, "message": "配置已重载" }

POST /config

• 功能: 直接通过 API 更新 mcp-config.json 文件的内容，并自动执行重载。
• 请求体: { "config": { "mcpServers": { ... } } }
• 返回: { "success": true, "message": "配置已保存并重载" }

服务管理接口

POST /restart-server

• 功能: 重启指定的单个服务，而不影响其他服务。
• 请求体:

  {
    "serverName": "weather_service",
    "config": { /* 可选，提供新配置 */ }
  }
  

• 返回: { "success": true, "message": "服务 xxx 已重启", "toolCount": 5 }
• 详细文档: 参见

POST /shutdown-server

• 功能: 关闭指定的服务。
• 请求体: { "serverName": "weather_service" }
• 返回: { "success": true, "message": "服务 xxx 已关闭" }

POST /reset-history

• 功能: 重置所有工具的失败调用计数器。
• 返回: { "success": true, "message": "调用历史已重置" }

缓存管理接口

GET /result/{cache_id}

• 功能: 获取缓存的结果内容（支持分段获取）。
• 参数:
  • cache_id - 缓存ID（从工具执行结果中获取）
  • start - 可选，起始字符位置（默认0）
  • end - 可选，结束字符位置（默认全部）
• 返回:

  {
    "success": true,
    "result": "缓存内容",
    "metadata": {
      "total_length": 30520,
      "start": 0,
      "end": 10000,
      "has_more": true
    }
  }
  

POST /search-cache

• 功能: 在缓存内容中搜索关键词（流式处理，性能优化）。
• 请求体:

  {
    "cache_id": "缓存ID",
    "keyword": "搜索关键词",
    "case_sensitive": false,
    "max_results": 50
  }
  

• 返回:

  {
    "success": true,
    "result": {
      "keyword": "搜索关键词",
      "total_matches": 15,
      "matches": [
        {
          "line": 23,
          "column": 45,
          "content": "...匹配的内容片段..."
        }
      ],
      "truncated": false
    }
  }
  

• 性能特点:
  • 流式读取，内存占用恒定（~10MB）
  • 支持任意大小文件
  • 10MB 文件搜索 < 100ms

POST /get-cache-context

• 功能: 获取缓存中指定行的上下文内容。
• 请求体:

  {
    "cache_id": "缓存ID",
    "line_num": 23,
    "context_lines": 5
  }
  

• 返回:

  {
    "success": true,
    "result": {
      "target_line": 23,
      "context_start": 18,
      "context_end": 28,
      "total_lines": 500,
      "content": "...上下文内容..."
    }
  }
  

缓存系统说明

当工具返回的结果超过阈值（默认 1000 字节）时，服务端会自动缓存结果并返回缓存引用：

{
  "success": true,
  "result_type": "cached_reference",
  "cache_id": "uuid-string",
  "cache_type": "memory",  // 或 "file"
  "total_size": 30520,
  "message": "结果过大，已缓存"
}

缓存策略：

• 内存缓存: 结果 ≤ 10KB，快速访问
• 文件缓存: 结果 > 10KB，节省内存
• 自动过期: TTL = 5 分钟（可配置）
• LRU 淘汰: 内存缓存最多保留 100 项

配置参数（在服务配置中设置）：

{
  "mcpServers": {
    "your_service": {
      "max_output_bytes": 1000,        // 触发缓存的阈值
      "cache_large_results": true,      // 是否启用缓存
      "result_cache_ttl": 300,          // 缓存过期时间（秒）
      "max_memory_cache_size": 10240    // 内存缓存阈值（字节）
    }
  }
}

使用场景：

1. 大文件读取 - 读取几MB的文件，先搜索定位再精确获取
2. 日志分析 - 在大量日志中搜索错误信息
3. 数据查询 - 返回大量数据时分段展示

� 文档

• - 端口检测和处理
• - 单独重启服务功能

�🔧 开发者指南 (从源码运行)

如果您想修改源码或从源码运行：

Python 版本

1. 环境要求: Python 3.8+
2. 克隆仓库: git clone <repository_url>
3. 安装依赖:

   cd mcp-bridge-server
   pip install -r requirements.txt
   

4. 运行:

   # 默认启动
   python utils/mcp_bridge.py
   
   # 使用启动脚本
   ./start.sh  # Linux/Mac
   start.bat   # Windows
   

Node.js 版本（如有）

1. 环境: 确保您已安装 Node.js (建议 v18 或更高版本)。
2. 克隆仓库: git clone <repository_url>
3. 安装依赖: cd mcp-bridge-server && npm install
4. 运行: node mcp-bridge-server.js

📄 许可证

本项目采用 MIT 许可证。