MCP EXP

🚀 Terminal-based Chat Client Integrated with MCP Server

This project demonstrates how to build a terminal-based chat client interface that connects to an MCP server and integrates the OpenAI API. It also includes a simple weather service as an example of MCP functionality.

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• UV Package Manager (a fast and reliable Python package installation and resolution tool)

Installation

1. Install UV

UV is a modern Python package manager that offers significant performance improvements over traditional tools like pip. It is written in Rust and provides:

• Faster package installation
• Reliable dependency resolution
• Built-in virtual environment management
• Compatibility with existing Python tools

To install UV, run:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Project Setup

1. Initialize a new project:

uv init

2. Create and activate a virtual environment:

uv venv
source .venv/bin/activate  # On Unix/macOS
# Or
.venv\Scripts\activate  # On Windows

3. Install the required packages:

uv pip install httpx mcp[cli] openai python-dotenv

✨ Features

• Real-time chat interface integrated with OpenAI
• MCP server integration for extensible functionality
• Weather service with alerts and forecasts
• Asynchronous operations for improved performance
• Proper error handling and resource cleanup
• Environment variable configuration for API keys

💻 Usage Examples

Basic Usage

1. Start the weather server:

python weather.py

2. Start the chat client and connect to the weather server:

python client.py weather.py

3. Enter messages in the chat interface, for example:
   • “What's the weather in California?”
   • “Are there any alerts in New York?”

📚 Documentation

Project Structure and Implementation Guide

The project consists of two main components: a chat client (client.py) and a weather service (weather.py). Let's understand how each component is built and the function of each part.

Building the Chat Client (client.py)

The chat client is an asynchronous Python application that connects to the MCP server and integrates the OpenAI API. Here's how it's built:

1. Imports and Setup

import asyncio
import os
import sys
from typing import Optional
from contextlib import AsyncExitStack
from dotenv import load_dotenv
import openai
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

• asyncio: For asynchronous programming
• os and sys: For interacting with the operating system
• typing.Optional: For type hints
• AsyncExitStack: For managing asynchronous contexts
• dotenv: For loading environment variables
• openai: OpenAI API client
• mcp: MCP protocol library

2. Chat Client Class

class ChatClient:
    def __init__(self, server_address):
        self.server_address = server_address
        self.loop = None
        self.client_session = None

    async def run(self):
        self.loop = asyncio.get_event_loop()
        self.client_session = await ClientSession.create(
            loop=self.loop,
            server_address=self.server_address
        )
        # Connection handling logic
        await self.client_session.connect()

    async def send_message(self, message):
        if self.client_session.is_connected:
            await self.client_session.send(message)

    async def close(self):
        if self.client_session:
            await self.client_session.close()

3. Using the Chat Client

import logging

logging.basicConfig(level=logging.INFO)
client = ChatClient('weather.py')
try:
    await client.run()
    while True:
        message = input('> ')
        await client.send_message(message)
except KeyboardInterrupt:
    await client.close()

Building the Weather Service (weather.py)

The weather service is an MCP server that provides weather-related functionality:

1. Imports and Setup

import asyncio
from mcp_server import MCPServer
from weather_api import WeatherAPI

2. Weather Service Class

class WeatherService:
    def __init__(self):
        self.server = None
        self.weather_api = WeatherAPI()

    async def start(self, host='127.0.0.1', port=8000):
        self.server = await MCPServer.create(
            host=host,
            port=port,
            handlers={
                'get_weather': self.get_weather,
                'get_alerts': self.get_alerts
            }
        )
        await self.server.start()

    async def get_weather(self, location):
        return await self.weather_api.get_weather(location)

    async def get_alerts(self, location):
        return await self.weather_api.get_alerts(location)

3. Running the Weather Service

import logging

logging.basicConfig(level=logging.INFO)
service = WeatherService()
try:
    await service.start()
except KeyboardInterrupt:
    await service.stop()

🔧 Technical Details

Project Structure

chat_client/
├── client.py          # Chat client implementation
├── requirements.txt   # List of dependencies
└── README.md           # Project description

weather_service/
├── weather.py         # Weather service implementation
├── weather_api.py     # Third-party weather API interface
└── setup.py            # Installation script

🤝 Contribution

Welcome to submit issues and enhancement requests!