MCPHub

MCPHub 是一个可嵌入的 AI 服务模型上下文协议 (MCP) 解决方案。它能够将 MCP 服务器无缝集成到任何 AI 框架中，使开发人员能够轻松地在其应用程序中配置、设置和管理 MCP 服务器。无论您使用 OpenAI Agents、LangChain 还是 Autogen，MCPHub 都提供了一种统一的方式，将您的 AI 服务与 MCP 工具和资源连接起来。

快速开始

前提条件

确保您已安装以下工具：

# 安装 uv (Python 包管理器)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装 git (用于克隆存储库)
sudo apt-get install git  # Ubuntu/Debian
brew install git         # macOS

# 安装 npx (随 Node.js 一起提供)
npm install -g npx

# 安装 MCPHub
pip install mcphub  # 基本安装

# 可选：安装特定于框架的依赖项
pip install mcphub[openai]    # 用于 OpenAI Agents 集成
pip install mcphub[langchain] # 用于 LangChain 集成
pip install mcphub[autogen]   # 用于 Autogen 集成
pip install mcphub[all]       # 安装所有可选依赖项

配置

在您的项目根目录中创建一个 .mcphub.json 文件：

{
    "mcpServers": {
        "sequential-thinking-mcp": {
            "package_name": "smithery-ai/server-sequential-thinking",
            "command": "npx",
            "args": [
                "-y",
                "@smithery/cli@latest",
                "run",
                "@smithery-ai/server-sequential-thinking"
            ]
        }
    }
}

与 OpenAI Agents 一起使用

import asyncio
import json
from agents import Agent, Runner
from mcphub import MCPHub

async def main():
    """
    使用 MCPHub 将 MCP 服务器与 OpenAI Agents 集成的示例。
    
    此示例演示：
    1. 初始化 MCPHub
    2. 获取和使用 MCP 服务器
    3. 列出可用工具
    4. 创建和运行带有 MCP 工具的代理
    """
    
    # 步骤 1：初始化 MCPHub
    # MCPHub 将自动执行以下操作：
    # - 在您的项目中查找 .mcphub.json
    # - 加载服务器配置
    # - 设置服务器（克隆存储库，如果需要，运行设置脚本）
    hub = MCPHub()
    
    # 步骤 2：使用异步上下文管理器创建 MCP 服务器实例
    # 参数：
    # - mcp_name：.mcphub.json 中服务器的名称
    # - cache_tools_list：缓存工具列表以获得更好的性能
    async with hub.fetch_openai_mcp_server(
        mcp_name="sequential-thinking-mcp",
        cache_tools_list=True
    ) as server:
        # 步骤 3：列出 MCP 服务器中的可用工具
        # 这显示了您的代理可用的功能
        tools = await server.list_tools()
        
        # 漂亮地打印工具以获得更好的可读性
        tools_dict = [
            dict(tool) if hasattr(tool, "__dict__") else tool for tool in tools
        ]
        print("可用 MCP 工具：")
        print(json.dumps(tools_dict, indent=2))

        # 步骤 4：使用 MCP 服务器创建 OpenAI Agent
        # 该代理现在可以使用 MCP 服务器提供的所有工具
        agent = Agent(
            name="Assistant",
            instructions="使用可用工具完成给定的任务",
            mcp_servers=[server]  # 将 MCP 服务器提供给代理
        )
        
        # 步骤 5：使用复杂的任务运行您的代理
        # 该代理将自动访问所有 MCP 工具
        complex_task = """请帮助我分析以下复杂问题：
                      我们需要为我们的产品设计一项新功能，该功能在用户隐私与数据收集之间取得平衡，以改进服务。
                      考虑伦理影响、技术可行性和业务影响。
                      逐步分解您的思考过程，并提供详细的建议，并为每个决策点提供明确的理由。"""
        
        # 执行任务并获取结果
        result = await Runner.run(agent, complex_task)
        print("\n代理响应：")
        print(result)

if __name__ == "__main__":
    # 运行异步 main 函数
    asyncio.run(main())

功能和指南

服务器配置

• 基于 JSON 的配置：简单的 .mcphub.json 配置文件
• 环境变量支持：在配置中使用环境变量
• 预定义服务器：访问不断增长的预配置 MCP 服务器列表
• 自定义服务器支持：轻松集成自定义 MCP 服务器

在 .mcphub.json 中配置您的 MCP 服务器：

{
    "mcpServers": {
        // 使用 NPX 的基于 TypeScript 的 MCP 服务器
        "sequential-thinking-mcp": {
            "package_name": "smithery-ai/server-sequential-thinking",  // NPM 包名称
            "command": "npx",                                         // 运行服务器的命令
            "args": [                                                // 命令参数
                "-y",
                "@smithery/cli@latest",
                "run",
                "@smithery-ai/server-sequential-thinking"
            ]
        },
        // 来自 GitHub 的基于 Python 的 MCP 服务器
        "azure-storage-mcp": {
            "package_name": "mashriram/azure_mcp_server",            // 包标识符
            "repo_url": "https://github.com/mashriram/azure_mcp_server", // GitHub 存储库
            "command": "uv",                                         // Python 包管理器
            "args": ["run", "mcp_server_azure_cmd"],                // 运行命令
            "setup_script": "uv pip install -e .",                  // 安装脚本
            "env": {                                                // 环境变量
                "AZURE_STORAGE_CONNECTION_STRING": "${AZURE_STORAGE_CONNECTION_STRING}",
                "AZURE_STORAGE_CONTAINER_NAME": "${AZURE_STORAGE_CONTAINER_NAME}",
                "AZURE_STORAGE_BLOB_NAME": "${AZURE_STORAGE_BLOB_NAME}"
            }
        }
    }
}

MCP 服务器安装和管理

• 灵活的服务器设置：支持基于 TypeScript 和 Python 的 MCP 服务器
• 多个安装来源：
  • 通过 npx 的 NPM 包
  • 通过 GitHub 存储库 URL 的 Python 包
  • 本地开发服务器
• 自动设置：处理存储库克隆、依赖项安装和服务器初始化

传输支持

• stdio 传输：将 MCP 服务器作为本地子进程运行
• 自动路径管理：管理服务器路径和工作目录
• 环境变量处理：每个服务器的可配置环境变量

框架集成

为流行的 AI 框架提供适配器：

• OpenAI Agents (示例)
• LangChain (示例)
• Autogen (示例)

from mcphub import MCPHub

async def framework_quick_examples():
    hub = MCPHub()
    
    # 1. OpenAI Agents 集成
    async with hub.fetch_openai_mcp_server(
        mcp_name="sequential-thinking-mcp",
        cache_tools_list=True
    ) as server:
        # 将服务器与 OpenAI agents 一起使用
        agent = Agent(
            name="Assistant",
            mcp_servers=[server]
        )
    
    # 2. LangChain 工具集成
    langchain_tools = await hub.fetch_langchain_mcp_tools(
        mcp_name="sequential-thinking-mcp",
        cache_tools_list=True
    )
    # 将工具与 LangChain 一起使用
    
    # 3. Autogen 适配器集成
    autogen_adapters = await hub.fetch_autogen_mcp_adapters(
        mcp_name="sequential-thinking-mcp"
    )
    # 将适配器与 Autogen 一起使用

工具管理

• 工具发现：自动列出和管理来自 MCP 服务器的可用工具
• 工具缓存：可选的工具列表缓存，以提高性能
• 特定于框架的适配器：将 MCP 工具转换为特定于框架的格式

发现和管理 MCP 服务器工具：

from mcphub import MCPHub

async def tool_management():
    hub = MCPHub()
    
    # 列出所有服务器
    servers = hub.list_servers()

    # 列出特定 MCP 服务器中的所有工具
    tools = await hub.list_tools(mcp_name="sequential-thinking-mcp")
    
    # 打印工具信息
    for tool in tools:
        print(f"工具名称：{tool.name}")
        print(f"描述：{tool.description}")
        print(f"参数：{tool.parameters}")
        print("---")
    
    # 工具可以是：
    # - 使用 cache_tools_list=True 缓存以获得更好的性能
    # - 自动转换为特定于框架的格式
    # - 通过适配器直接与 AI 框架一起使用

MCPHub：高级概述

MCPHub 通过四个主要组件简化了模型上下文协议 (MCP) 服务器与 AI 应用程序的集成：

核心组件

1. 参数中心 (Params Hub)

   • 管理来自 .mcphub.json 的配置
   • 定义要使用哪些 MCP 服务器以及如何设置它们
   • 存储服务器参数，如命令、参数和环境变量

2. MCP 服务器管理器 (MCP Servers Manager)

   • 处理服务器安装和设置
   • 支持两种类型的服务器：
     • 基于 TypeScript 的服务器（通过 npx 安装）
     • 基于 Python 的服务器（通过 uv 从 GitHub 安装）
   • 管理服务器生命周期和环境

3. MCP 客户端 (MCP Client)

   • 建立与 MCP 服务器的通信
   • 使用 stdio 传输进行服务器交互
   • 处理两个主要操作：
     • list_tools：发现可用的服务器工具
     • call_tool：执行服务器工具

4. 框架适配器 (Framework Adapters)

   • 将 MCP 工具转换为特定于框架的格式
   • 支持多个 AI 框架：
     • OpenAI Agents
     • LangChain
     • Autogen

工作流程

1. 配置和设置

   • 参数中心读取配置
   • 服务器管理器设置所需的服务器
   • 服务器启动并变为可用

2. 通信

   • MCP 客户端通过 stdio 连接到服务器
   • 发现工具并使其可用
   • 请求和响应在客户端和服务器之间流动

3. 集成

   • 框架适配器转换 MCP 工具
   • AI 应用程序通过其首选框架使用适配的工具
   • 通过已建立的通信通道执行工具

此架构提供了一种将 MCP 功能无缝集成到任何 AI 应用程序中的方法，同时保持清晰的关注点分离和框架灵活性。

开发

测试

使用 pytest 运行单元测试：

pytest tests/ -v

CI/CD 管道

本项目使用 GitHub Actions 进行持续集成和部署：

1. 自动化测试：对于每次推送到 main 和 release 分支以及拉取请求，都会在 Python 3.10、3.11 和 3.12 上运行测试。

2. 自动版本递增和标记：当代码推送到 release 分支时：

   • pyproject.toml 中的补丁版本会自动递增
   • 为发布创建一个新的 Git 标签（例如，v0.1.2）
   • 更改将提交回存储库

3. PyPI 发布：当代码推送到 release 分支并且测试通过时，该软件包会自动构建并发布到 PyPI。

设置 PyPI 部署

要启用自动 PyPI 部署，您需要将 PyPI API 令牌添加为 GitHub Secret：

1. 在 https://pypi.org/manage/account/token/ 生成一个 PyPI API 令牌
2. 转到您的 GitHub 存储库设置 → Secrets and variables → Actions
3. 添加一个名为 PYPI_API_TOKEN 的新存储库密钥，其中包含来自 PyPI 的令牌值

贡献

我们欢迎贡献！请查看我们的 贡献指南，了解如何进行操作的指南。

许可证

本项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。