MCP Abstract Client System

A powerful, abstract interface for Model Context Protocol (MCP) that enables seamless switching between real and mock clients. Perfect for testing, development, and LLM-driven tool simulation.

🚀 Key Features

• 🔄 Dynamic Mock Creation - Automatically mirror real MCP servers
• 🎭 Abstract Interface - Same code works with real and mock clients
• 🤖 LLM-Compatible - Create sophisticated mock tools dynamically
• 🧪 Zero-Config Testing - Test workflows without real servers
• ⚡ Utility Functions - Simple operations for common tasks

📁 File Structure

├── abstract_client.py    # Abstract interface + MockMCPClient
├── client.py            # Real MCPExecutionClient implementation
├── utils.py             # Utility functions (work with both clients)
├── example_usage.py     # Complete examples and demos
└── dynamic_mock_demo.py # Quick demo of dynamic features

🛠️ Quick Start

Basic Usage

import asyncio
from utils import list_mcp_tools, execute_mcp_tool
from abstract_client import MockMCPClient

# Using real MCP server
tools = await list_mcp_tools()
result = await execute_mcp_tool("search", {"query": "example"})

# Using mock client
mock_client = MockMCPClient()
await mock_client.mirror_real_server("http://localhost:8000/sse")
result = await execute_mcp_tool("search", {"query": "example"}, client=mock_client)

Workflow Example

from client import execute_mcp_workflow
from abstract_client import MockMCPClient

async def my_workflow(client):
    tools = await client.list_available_tools()
    result = await client.call_tool("search", {"query": "test"})
    return result

# Works with real client
result = await execute_mcp_workflow(my_workflow)

# Works with mock client
mock_client = MockMCPClient()
await mock_client.auto_discover_and_mock()
result = await execute_mcp_workflow(my_workflow, client=mock_client)

🔄 Dynamic Mock Creation

The MockMCPClient can automatically replicate any real MCP server:

mock_client = MockMCPClient()

# Method 1: Mirror a real server
await mock_client.mirror_real_server("http://your-server:8000/sse")

# Method 2: Auto-discover from multiple sources
await mock_client.auto_discover_and_mock([
    "http://server1:8000/sse",
    "http://server2:8001/sse"
])

# Method 3: Clone using utility functions
await mock_client.clone_from_utils()

# Now has all the same tools as real servers!
tools = await mock_client.get_tool_names()

🎯 Use Cases

• 🧪 Testing - Test workflows without real MCP servers
• 🔧 Development - Develop against changing APIs safely
• 🎭 Simulation - LLM-driven tool behavior simulation
• ⚡ Prototyping - Rapid prototyping with realistic mock data
• 🏗️ CI/CD - Isolated testing environments

🛠️ Utility Functions

Three main utilities that work with both real and mock clients:

from utils import list_mcp_tools, get_mcp_tools_info, execute_mcp_tool

# List tool names
tools = await list_mcp_tools()

# Get detailed tool information
tools_info = await get_mcp_tools_info()

# Execute a single tool
result = await execute_mcp_tool("tool_name", {"arg": "value"})

# All functions accept optional client parameter
result = await execute_mcp_tool("tool_name", {"arg": "value"}, client=mock_client)

🤖 LLM Integration

Perfect for LLM-driven development:

# LLM can analyze requirements and create tools
llm_tools = [
    {
        "name": "web_search",
        "description": "Search the web for information",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string"}
            },
            "required": ["query"]
        }
    }
]

mock_client = MockMCPClient()
mock_client.create_mocks_from_schemas(llm_tools)

# LLMs can create custom mock functions
def custom_search_mock(args):
    return {"results": [f"Mock result for: {args['query']}"]}

mock_client.set_mock_function("web_search", custom_search_mock)

🏃 Running Examples

# Quick demo of dynamic mock creation
python dynamic_mock_demo.py

# Complete examples and demonstrations
python example_usage.py

# Test individual components
python abstract_client.py
python client.py  
python utils.py

⚙️ Configuration

Update the DEFAULT_URL in client.py to point to your MCP server:

DEFAULT_URL = "http://your-mcp-server:8000/sse"

🎉 Key Benefits

• 🔄 Seamless Switching - Same code works with real and mock clients
• 🎭 Realistic Mocks - Schema-based mock functions with intelligent responses
• 🤖 LLM-Ready - Perfect for AI-driven tool creation and testing
• ⚡ Fast Development - No need to wait for real servers during development
• 🧪 Reliable Testing - Predictable mock responses for consistent tests
• 📦 Portable - Export/import mock configurations

🔗 Dependencies

• mcp - Model Context Protocol library
• asyncio - Async/await support

🚀 Get Started

1. Clone this repository
2. Update DEFAULT_URL in client.py
3. Run python dynamic_mock_demo.py to see it in action
4. Use the abstract interface in your workflows!

The mock client will automatically discover and replicate your real MCP server's capabilities, making testing and development seamless! 🎯