MCPHub

MCPHub

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

文档

• CLI 文档 - 用于管理 MCP 服务的命令行界面
• API 文档 - Python API 参考
• 配置指南 - 服务配置详情
• 示例 - 用法示例和教程

快速开始

先决条件

请确保已安装以下工具：

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install git (for repository cloning)
sudo apt-get install git  # Ubuntu/Debian
brew install git         # macOS

# Install npx (comes with Node.js)
npm install -g npx

# Install MCPHub
pip install mcphub  # Basic installation

# Optional: Install with framework-specific dependencies
pip install mcphub[openai]    # For OpenAI Agents integration
pip install mcphub[langchain] # For LangChain integration
pip install mcphub[autogen]   # For Autogen integration
pip install mcphub[all]       # Install all optional dependencies

配置

在项目根目录下创建一个 .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"
            ]
        }
    }
}

添加新的 MCP 服务

你可以通过以下两种方式添加新的 MCP 服务：

1. 手动配置：直接将服务配置添加到 .mcphub.json 文件中。

2. 从 GitHub 自动配置：使用 add_server_from_repo 方法，根据服务的 GitHub 仓库自动配置服务：

from mcphub import MCPHub

# Initialize MCPHub
hub = MCPHub()

# Add a new server from GitHub
hub.servers_params.add_server_from_repo(
    server_name="my-server",
    repo_url="https://github.com/username/repo"
)

自动配置会：

• 从 GitHub 仓库获取 README
• 使用 OpenAI 分析 README 并提取服务配置
• 将配置添加到 .mcphub.json 文件中
• 需要 OpenAI API 密钥（通过 OPENAI_API_KEY 环境变量设置）

与 OpenAI Agents 配合使用

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

async def main():
    """
    Example of using MCPHub to integrate MCP servers with OpenAI Agents.
    
    This example demonstrates:
    1. Initializing MCPHub
    2. Fetching and using an MCP server
    3. Listing available tools
    4. Creating and running an agent with MCP tools
    """
    
    # Step 1: Initialize MCPHub
    # MCPHub will automatically:
    # - Find .mcphub.json in your project
    # - Load server configurations
    # - Set up servers (clone repos, run setup scripts if needed)
    hub = MCPHub()
    
    # Step 2: Create an MCP server instance using async context manager
    # Parameters:
    # - mcp_name: The name of the server from your .mcphub.json
    # - cache_tools_list: Cache the tools list for better performance
    async with hub.fetch_openai_mcp_server(
        mcp_name="sequential-thinking-mcp",
        cache_tools_list=True
    ) as server:
        # Step 3: List available tools from the MCP server
        # This shows what capabilities are available to your agent
        tools = await server.list_tools()
        
        # Pretty print the tools for better readability
        tools_dict = [
            dict(tool) if hasattr(tool, "__dict__") else tool for tool in tools
        ]
        print("Available MCP Tools:")
        print(json.dumps(tools_dict, indent=2))

        # Step 4: Create an OpenAI Agent with MCP server
        # The agent can now use all tools provided by the MCP server
        agent = Agent(
            name="Assistant",
            instructions="Use the available tools to accomplish the given task",
            mcp_servers=[server]  # Provide the MCP server to the agent
        )
        
        # Step 5: Run your agent with a complex task
        # The agent will automatically have access to all MCP tools
        complex_task = """Please help me analyze the following complex problem: 
                      We need to design a new feature for our product that balances user privacy 
                      with data collection for improving the service. Consider the ethical implications, 
                      technical feasibility, and business impact. Break down your thinking process 
                      step by step, and provide a detailed recommendation with clear justification 
                      for each decision point."""
        
        # Execute the task and get the result
        result = await Runner.run(agent, complex_task)
        print("\nAgent Response:")
        print(result)

if __name__ == "__main__":
    # Run the async main function
    asyncio.run(main())

功能和指南

服务配置

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

在 .mcphub.json 中配置 MCP 服务：

{
    "mcpServers": {
        // TypeScript-based MCP server using NPX
        "sequential-thinking-mcp": {
            "package_name": "smithery-ai/server-sequential-thinking",  // NPM package name
            "command": "npx",                                         // Command to run server
            "args": [                                                // Command arguments
                "-y",
                "@smithery/cli@latest",
                "run",
                "@smithery-ai/server-sequential-thinking"
            ]
        },
        // Python-based MCP server from GitHub
        "azure-storage-mcp": {
            "package_name": "mashriram/azure_mcp_server",            // Package identifier
            "repo_url": "https://github.com/mashriram/azure_mcp_server", // GitHub repository
            "command": "uv",                                         // Python package manager
            "args": ["run", "mcp_server_azure_cmd"],                // Run command
            "setup_script": "uv pip install -e .",                  // Installation script
            "env": {                                                // Environment variables
                "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 服务作为本地子进程运行
• SSE 传输：使用 supergateway 运行支持服务器发送事件（SSE）的 MCP 服务
• 自动路径管理：管理服务路径和工作目录
• 环境变量处理：为每个服务配置环境变量

运行支持 SSE 的服务

你可以使用 mcphub run 命令运行支持 SSE 的 MCP 服务：

# Basic usage with default settings
mcphub run your-server-name --sse

# Advanced usage with custom settings
mcphub run your-server-name --sse \
    --port 8000 \
    --base-url http://localhost:8000 \
    --sse-path /sse \
    --message-path /message

在以下情况下，SSE 支持非常实用：

• 从 Web 应用连接到 MCP 服务
• 与 MCP 服务进行实时通信
• 与支持 SSE 的客户端集成

SSE 服务提供两个端点：

• /sse：用于实时更新的 SSE 端点
• /message：用于发送消息的 HTTP 端点

.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",
                "--key",
                "your-api-key"
            ]
        }
    }
}

框架集成

为常用 AI 框架提供适配器：

• OpenAI Agents（示例）
• LangChain（示例）
• Autogen（示例）

from mcphub import MCPHub

async def framework_quick_examples():
    hub = MCPHub()
    
    # 1. OpenAI Agents Integration
    async with hub.fetch_openai_mcp_server(
        mcp_name="sequential-thinking-mcp",
        cache_tools_list=True
    ) as server:
        # Use server with OpenAI agents
        agent = Agent(
            name="Assistant",
            mcp_servers=[server]
        )
    
    # 2. LangChain Tools Integration
    langchain_tools = await hub.fetch_langchain_mcp_tools(
        mcp_name="sequential-thinking-mcp",
        cache_tools_list=True
    )
    # Use tools with LangChain
    
    # 3. Autogen Adapters Integration
    autogen_adapters = await hub.fetch_autogen_mcp_adapters(
        mcp_name="sequential-thinking-mcp"
    )
    # Use adapters with Autogen

工具管理

• 工具发现：自动列出并管理 MCP 服务提供的可用工具
• 工具缓存：可选择缓存工具列表以提升性能
• 框架专用适配器：将 MCP 工具转换为特定框架的格式

发现并管理 MCP 服务工具：

from mcphub import MCPHub

async def tool_management():
    hub = MCPHub()
    
    # List all servers
    servers = hub.list_servers()

    # List all tools from a specific MCP server
    tools = await hub.list_tools(mcp_name="sequential-thinking-mcp")
    
    # Print tool information
    for tool in tools:
        print(f"Tool Name: {tool.name}")
        print(f"Description: {tool.description}")
        print(f"Parameters: {tool.parameters}")
        print("---")
    
    # Tools can be:
    # - Cached for better performance using cache_tools_list=True
    # - Converted to framework-specific formats automatically
    # - Used directly with AI frameworks through adapters

MCPHub：高级概览

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

核心组件

1. 参数中心

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

2. MCP 服务管理器

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

3. MCP 客户端

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

4. 框架适配器

   • 将 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 的新代码库 Secret，并填入来自 PyPI 的令牌值

贡献

欢迎贡献！请查看我们的贡献指南，了解如何参与。

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。