graph TD
subgraph "客户端应用程序"
A[gRPC 客户端]
H[HTTP/REST 客户端]
end
A -->|端口 8090 上的 gRPC 请求| B(主 MCP 服务器);
H -->|端口 8002 上的 HTTP/REST 请求| B;
B -->|gRPC 代理| C{Go 工具 1};
B -->|gRPC 代理| D{Go 工具 2};
B -->|gRPC 代理| E{Python 工具 3};
B -->|gRPC 代理| F[人桥];
subgraph "工具服务器"
C
D
E
F
end
style B fill:#ffa500,stroke:#333,stroke-width:2px,color:#000
<h3>关键组件</h3>
<ul>
<li><strong>主 MCP 服务器:</strong> 中心组件,负责发现、启动并将客户端请求路由到适当的工具服务器。它还监控每个工具的状态。</li>
<li><strong>工具服务器:</strong> 各自提供特定功能的独立 gRPC 服务器(例如,<code>计算器</code>,<code>网络搜索</code>)。这些可以使用任何语言编写,尽管当前实现包括用 Go 和 Python 编写的工具。</li>
<li><strong>人桥:</strong> 一个 WebSocket 服务器,用于异步与人类操作员通信,被 <code>human_input</code> 工具使用。</li>
<li><strong>gRPC 合同:</strong> API 在 <code>proto/mcp.proto</code> 中定义,作为所有服务的单一事实来源。</li>
</ul>
<h3>健康检查</h3>
<p>为了确保系统可靠性,我实现了一个全面的健康检查机制。主 MCP 服务器负责监控所有已注册工具的状态。</p>
<ul>
<li><strong>协议:</strong> 系统使用标准的 gRPC 健康检查协议。</li>
<li><strong>实现:</strong> 每个工具,无论用 Go 还是 Python 编写,都暴露一个 gRPC 健康检查端点。</li>
<li><strong>监控:</strong> 主 MCP 服务器在发现工具时进行初始健康检查,并定期继续监控。未处于“SERVING”状态的工具不会包含在返回给客户端的可用工具列表中,防止请求被路由到不健康的服务器。</li>
</ul>
<h2>文件夹结构</h2>
<p>项目组织如下目录:</p>
<pre><code>
.
├── MCP-NG/
│ ├── human_bridge/ # 用于人类互动的 WebSocket 服务器
│ ├── integration_tests/ # 工具的集成测试
│ ├── proto/ # gRPC 协议缓冲区定义
│ ├── server/ # 主 MCP 服务器实现
│ └── tools/ # 各个工具的源代码
│ ├── go/ # 基于 Go 的工具
│ └── python/ # 基于 Python 的工具
├── docs/ # 英文文档
│ └── tools/ # 每个工具的详细文档
├── docs_ru/ # 俄文文档
│ └── tools/ # 每个工具的详细俄文文档
├── README.md # 此文件
└── README_ru.md # 此文件的俄文版
</code></pre>
<h2>开始使用</h2>
<p>MCP-NG 项目支持三种主要环境:通过 Docker、原生 Windows 和原生 Linux/WSL。推荐且最简单的方法是使用 Docker。</p>
<h3>1. 使用 Docker 运行(推荐)</h3>
<p>借助 Docker,您可以使用一条命令构建并运行整个 MCP-NG 生态系统,包括主服务器和所有工具。这种方法确保了开发和部署环境的一致性。</p>
<ol>
<li><strong>确保安装并运行了 Docker 和 Docker Compose。</strong></li>
<li>从项目根目录运行以下命令:</li>
</ol>
<pre><code>docker-compose up --build -d</code></pre>
<p>此命令将构建一个多阶段 Docker 镜像,编译所有 Go 二进制文件,安装所有 Python 依赖项,并在后台启动容器。服务器将在 <code>grpc://localhost:8090</code> 和 <code>http://localhost:8002</code> 上可用。</p>
<p>要停止服务,请运行 <code>docker-compose down</code>。</p>
<h3>2. 在 Windows 上手动设置(原生)</h3>
<p>此指南适用于在 Windows 上直接运行项目而不使用 WSL。此方法为本地开发提供了最大性能。</p>
<h4>a. 安装所需软件(一次性设置)</h4>
<ul>
<li><strong>Go:</strong> 从官方网站 <a href="https://go.dev">go.dev</a> 下载并安装 Go。</li>
<li><strong>Python:</strong> 从 <a href="https://python.org">python.org</a> 下载并安装 Python。安装过程中,请确保选中“将 Python 添加到 PATH”。</li>
<li><strong>Git for Windows:</strong> 安装 Git <a href="https://git-scm.com">git-scm.com</a>。</li>
<li><strong>MinGW(C/C++ 编译器):</strong> 一些 Go 包需要 MinGW,例如 <code>go-sqlite3</code>。
<ul>
<li>从 <a href="https://msys2.org">msys2.org</a> 安装 MSYS2。</li>
<li>运行 MSYS2 MINGW64 终端并执行 <code>pacman -Syu</code>,然后 <code>pacman -S --needed base-devel mingw-w64-ucrt-x86_64-toolchain</code>。</li>
<li>将路径 <code>C:\msys64\ucrt64\bin</code> 添加到系统的 PATH 环境变量中。</li>
</ul>
</li>
</ul>
<h4>b. 克隆仓库</h4>
<pre><code>git clone https://github.com/Lotargo/MCP-NG.git
cd MCP-NG</code></pre>
<h4>c. 自动环境设置</h4>
<p>此步骤使用 PowerShell 脚本自动化。它将创建虚拟环境,安装所有依赖项,将所有 Go 应用程序(包括主服务器)编译到 <code>bin</code> 文件夹中,并自动配置 Windows 防火墙规则。</p>
<ol>
<li>以管理员身份打开 PowerShell 终端。</li>
<li>导航到项目根文件夹。</li>
<li>创建虚拟环境(仅需一次):</li>
</ol>
<pre><code>python -m venv .venv</code></pre>
<ol start="4">
<li>运行自动设置脚本:</li>
</ol>
<pre><code>PowerShell -ExecutionPolicy Bypass -File .\install_deps.ps1</code></pre>
<p>此脚本准备了启动所需的一切。在从 Git 拉取更新更改依赖项或添加新工具后,请重新运行此脚本。</p>
<h4>d. 运行服务器</h4>
<p>在 <code>install_deps.ps1</code> 脚本完成后,您的项目就可以运行了。</p>
<ol>
<li>打开一个新的普通 PowerShell 终端(非管理员)。</li>
<li>导航到项目根文件夹。</li>
<li>执行命令以运行编译后的服务器:</li>
</ol>
<pre><code>.\bin\server.exe</code></pre>
<p>服务器将启动并自动启动所有编译后的微服务。</p>
<h3>3. 在 Linux / WSL 上手动设置</h3>
<p>过程类似于 Windows 设置,并遵循“先构建,再运行”的原则。</p>
<h4>a. 安装所需软件</h4>
<p>安装 Go、Python 3.11+、Git 和 GCC(例如,通过 <code>sudo apt install build-essential</code>)。</p>
<h4>b. 克隆并安装依赖项</h4>
<pre><code>git clone https://github.com/Lotargo/MCP-NG.git
cd MCP-NG
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements_for_linux.txt</code></pre>
<h4>c. 构建项目</h4>
<p>将主服务器和所有 Go 工具编译到 <code>bin</code> 目录中。</p>
<pre><code>mkdir bin
go build -o ./bin/server ./MCP-NG/server/cmd/server
# 对每个 Go 工具重复
go build -o ./bin/api_caller ./MCP-NG/tools/go/api_caller
# 以此类推
</code></pre>
<h4>d. 运行服务器</h4>
<p>运行编译后的二进制文件。</p>
<pre><code>./bin/server</code></pre>
<h3>关于研发模块</h3>
<p>默认情况下,服务器不会启动资源密集型 Python 基础的 ML 工具(如 <code>hybrid_search</code> 等)。我将这些指定为 <strong>R&D(研究与发展)</strong> 模块,以确保核心系统快速稳定启动。它们的行为可以在服务器源代码中修改。</p>
<h3>工具配置</h3>
<p>每个工具都有自己的 <code>config.json</code> 文件。经过所有更改后,配置现在是通用的。它只指定了可执行文件的名称(例如,<code>"command": ["api_caller"]</code>)或脚本(<code>"command": ["server.py"]</code>)。主服务器现在根据操作系统智能构造正确的路径来运行它们。</p>
<p>请参阅详细的 <a href="https://github.com/Lotargo/MCP-NG-/tree/main/docs/tools">文档</a> 获取每个工具的具体配置说明。</p>
<h2>ReAct 工作流</h2>
<p>MCP-NG 设计为与大型语言模型(LLM)配合使用,采用 ReAct(推理和行动)模式。这使 LLM 能够智能选择并使用可用工具完成给定任务。</p>
sequenceDiagram
participant 用户
participant LLM
participant "MCP 服务器 (gRPC/HTTP)"
participant 工具
用户->>LLM: 提示
LLM->>"MCP 服务器 (gRPC/HTTP)": 列出工具() 通过 GET /v1/tools
"MCP 服务器 (gRPC/HTTP)"-->>LLM: 可用工具列表
LLM->>LLM: 推理应使用哪个工具
LLM->>"MCP 服务器 (gRPC/HTTP)": 运行工具(tool_name, 参数) 通过 POST /v1/tools:run
"MCP 服务器 (gRPC/HTTP)"->>工具: 通过 gRPC 执行工具
工具-->>"MCP 服务器 (gRPC/HTTP)": 工具输出
"MCP 服务器 (gRPC/HTTP)"-->>LLM: 观察结果 (工具结果)
LLM->>用户: 最终答案
有关如何将 MCP-NG 与 LLM 集成并使用 ReAct 模式的更多信息,请参阅 集成指南。可用工具列表