This PR implements MCP (Multi-Channel Protocol) integration for the HelpingAI SDK, enabling seamless connection to external tools and services through MCP servers.

Overview

Users can now configure MCP servers directly in the tools parameter using the following format:

from HelpingAI import HAI

client = HAI(api_key="your-api-key")

tools = [
    {
        'mcpServers': {
            'time': {
                'command': 'uvx',
                'args': ['mcp-server-time', '--local-timezone=Asia/Shanghai']
            },
            "fetch": {
                "command": "uvx",
                "args": ["mcp-server-fetch"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="HelpingAI2.5-10B",
    messages=[{"role": "user", "content": "What time is it in Shanghai?"}],
    tools=tools
)

Key Features

• Multiple Transport Types: Supports stdio, SSE, and streamable-http MCP servers
• Automatic Tool Discovery: MCP tools are automatically converted to OpenAI-compatible format
• Mixed Tools Support: Can combine MCP servers with regular OpenAI-format tools
• Resource Support: Handles MCP resources with automatic list_resources and read_resource tools
• Graceful Error Handling: Works without MCP package installed, provides helpful error messages
• Process Management: Automatic cleanup of MCP server processes on exit
• Reconnection Logic: Handles server disconnections automatically

Implementation Details

Core Components Added

• HelpingAI/tools/mcp_client.py - Individual MCP server connection handling
• HelpingAI/tools/mcp_manager.py - Singleton manager for orchestrating multiple MCP servers
• Extended HelpingAI/tools/compatibility.py - Added MCP server detection and conversion logic
• Updated setup.py - Added optional MCP dependency (pip install HelpingAI[mcp])

Architecture

The implementation leverages the existing HelpingAI tools infrastructure:

1. MCP configurations are detected in the tools parameter
2. MCPManager initializes and manages server connections
3. MCP tools are converted to Fn objects (existing tool format)
4. Fn objects are converted to OpenAI tool format via existing compatibility layer
5. Tools work seamlessly with existing chat completion functionality

Supported Server Types

# Stdio-based servers (most common)
{
    'command': 'uvx',
    'args': ['mcp-server-time'],
    'env': {'TIMEZONE': 'UTC'}  # optional
}

# HTTP SSE servers
{
    'url': 'https://api.example.com/mcp',
    'headers': {'Authorization': 'Bearer token'},
    'sse_read_timeout': 300
}

# Streamable HTTP servers
{
    'type': 'streamable-http',
    'url': 'http://localhost:8000/mcp'
}

Testing

• Comprehensive test suite covering configuration validation, tool conversion, and error handling
• Integration tests ensuring compatibility with existing client functionality
• Example code demonstrating real-world usage patterns

Documentation

• Complete usage guide in docs/mcp_integration.md
• Working examples in examples/mcp_example.py
• Implementation summary in MCP_IMPLEMENTATION.md

Backward Compatibility

✅ Fully backward compatible - no breaking changes to existing functionality
✅ Optional dependency - MCP features only available when mcp package is installed
✅ Graceful degradation - helpful error messages when MCP package is missing

Popular MCP Servers Supported

• mcp-server-time - Time and timezone operations
• mcp-server-fetch - HTTP requests and web scraping
• mcp-server-filesystem - File system operations
• mcp-server-memory - Persistent memory across conversations
• mcp-server-sqlite - SQLite database operations
• Custom servers - Any MCP-compliant server

Installation

# Install with MCP support
pip install HelpingAI[mcp]

# Or install MCP separately
pip install -U mcp

This implementation makes HelpingAI SDK significantly more powerful by enabling integration with the growing ecosystem of MCP tools and services, while maintaining the simplicity and reliability of the existing API.

Created from VS Code via the GitHub Pull Request extension.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.