mcgravity

McGravity 项目介绍

概述

McGravity 是一个旨在连接多个 MCP (Model Context Protocol) 服务器并将它们整合成一个统一服务的工具。它使得用户可以复用同一个 MCP 服务器，并且几乎无限地扩展其底层 MCP 服务器的连接能力。

当前版本作为一个基础的命令行接口 (CLI) 工具运行。未来，McGravity 将发展成为一个功能齐全的 MCP 服务器代理，其定位类似于 Nginx 对于传统 Web 服务器的作用，但专注于现代生成式 AI 工具和服务器。

为何选择 McGravity？

在没有 McGravity 的场景下，客户端需要直接连接到每个单独的 MCP 服务器：

┌─────────┐ ┌─────────┐
│ 客户端 │────▶│MCP │
│ │ │服务器 1 │
└─────────┘ └─────────┘
│
│ ┌─────────┐
└──────────▶│MCP │
│服务器 2 │
└─────────┘

这种模式下，客户端需要管理多个连接和地址。

有了 McGravity 后，客户端只需连接到 McGravity 这一个端点：

┌─────────┐ ┌─────────┐ ┌─────────┐
│ 客户端 │────▶│McGravity│────▶│MCP │
│ │ │ │ │服务器 1 │
└─────────┘ └─────────┘ └─────────┘
│
│ ┌─────────┐
└─────────▶│MCP │
│服务器 2 │
└─────────┘

McGravity 负责在后台管理与各个 MCP 服务器的连接和通信。

McGravity 解决了以下问题：

1. 通过一个端点连接到多个 MCP 服务器： 客户端无需关心后端有多少个 MCP 服务器，只需连接 McGravity 的地址即可。
2. 在 MCP 服务器之间平衡负载： McGravity 可以在后端的多个 MCP 服务器之间分配客户端请求（尽管当前版本是基础代理，未来的高级负载均衡是明确计划）。
3. 为您的应用提供一个单一的访问点： 简化了客户端的连接和配置管理。

安装

可以通过两种主要方式安装 McGravity：

1. 从源代码构建：

   • 安装依赖：bun install
   • 构建项目并生成独立可执行文件：bun build src/index.ts --compile --outfile mcgravity

2. 使用 Docker：

   • McGravity 镜像发布在 Docker Hub 上：tigranbs/mcgravity
   • 拉取镜像：docker pull tigranbs/mcgravity

使用方法

• 基本命令行用法：
  运行构建好的可执行文件，直接在后面跟上一个或多个 MCP 服务器的地址。
  ./mcgravity <mcp-server-address 1> <mcp-server-address 2> ...

• 带选项的命令行用法：
  使用 --host 和 --port 选项自定义 McGravity 监听的主机和端口。
  ./mcgravity --host localhost --port 3001 http://mcp1.example.com http://mcp2.example.com

• 使用配置文件：
  通过指定 --config 选项加载 YAML 格式的配置文件。
  ./mcgravity --config config.yaml

命令行选项

• --host <host>：服务器绑定的主机地址 (默认: localhost)
• --port <port>：服务器绑定的端口 (默认: 3001)
• --config <path>：配置文件的路径 (默认: config.yaml)
• --mcp-version <version>：McGravity 作为 MCP 服务器向客户端报告的版本 (默认: 1.0.0)
• --mcp-name <name>：McGravity 作为 MCP 服务器向客户端报告的名称 (默认: mcgravity)
• --help：显示帮助信息

配置文件

McGravity 支持使用 YAML 文件进行配置，提供了更详细的设置选项。配置示例（参考 config.example.yaml）：

yaml
name: mcgravity # 服务名称
version: 1.0.0 # 服务版本
description: A simple MCP server # 服务描述
servers: # 后端 MCP 服务器列表
echo-server: # 服务器别名
url: http://localhost:3000/sse # 服务器地址
name: echo-server # 服务器名称
version: 1.0.0 # 服务器版本
description: A simple echo server # 服务器描述
tags: # 可选标签
- echo

项目提供了一个示例 echo-server.ts，可以先启动它用于测试 McGravity 的代理功能。

示例用法

• 使用默认设置启动 McGravity 并代理两个 MCP 服务器：
  ./mcgravity http://mcp1.example.com http://mcp2.example.com
• 指定主机和端口启动 McGravity：
  ./mcgravity --host 0.0.0.0 --port 4000 http://mcp1.example.com http://mcp2.example.com

运行测试

项目包含一套测试用例，用于验证 McGravity 的功能。

• 运行所有测试：bun test
• 仅运行集成测试：bun run test:integration

集成测试主要验证 McGravity 是否能成功连接到目标 MCP 服务器（例如示例中的 echo 服务器），正确代理其能力信息，并将客户端请求转发到目标服务器并返回响应。测试会自动在 GitHub Actions CI 中触发。

未来计划

McGravity 将持续发展，未来计划的功能包括：

• Web 界面用于监控和管理
• 更高级的负载均衡策略（如轮询、最小连接等）
• MCP 服务器健康检查和故障转移
• 身份验证和访问控制
• 用于自定义功能和集成的插件系统

开发

项目使用 TypeScript 语言和 Bun Runtime 开发，并强制执行代码规范：

• 使用 ESLint 进行代码检查 (包含 TypeScript 规则)。
• 使用 Prettier 进行代码格式化。

推荐运行以下命令来维护代码风格：

• 格式化代码：bun run format
• 检查代码格式：bun run format:check
• 检查代码错误：bun run lint
• 自动修复可修复的错误：bun run lint:fix

如果使用 VS Code 并安装推荐的扩展，可以配置在保存时自动格式化和显示 linting 信息。

贡献

欢迎任何形式的贡献！如果您有任何问题、建议或想提交代码改进，请随时创建 Issue 或提交 Pull Request。