Terminal-based Chat Client with MCP Server Integration

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

Prerequisites

• Python 3.8 or higher
• UV package manager (a fast, reliable Python package installer and resolver)

Installation

1. Install UV

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

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

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 required packages:

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

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 walk through how each component was built and what each part does.

Building the Chat Client (client.py)

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

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

2. MCPClient Class

The main client class handles:

Key methods:

3. Main Function

async def main():
       client = MCPClient()
       try:
           await client.connect_to_server(sys.argv[1])
           await client.chat_loop()
       finally:
           await client.cleanup()

Building the Weather Service (weather.py)

The weather service is built as an MCP server that provides weather information through the National Weather Service API:

1. Service Initialization

from mcp.server.fastmcp import FastMCP
   mcp = FastMCP("weather")

2. API Integration

NWS_API_BASE = "https://api.weather.gov"
   USER_AGENT = "weather-app/1.0"

3. Helper Functions

4. MCP Tools

Two main tools are implemented:

a. `get_alerts(state)`:

b. `get_forecast(latitude, longitude)`:

5. Server Execution

if __name__ == "__main__":
       mcp.run(transport="stdio")

Usage

1. Create a `.env` file with your OpenAI API key:

OPENAI_API_KEY=your_api_key_here

2. Start the MCP server:

python weather.py

3. In a separate terminal, run the chat client:

python client.py weather.py

4. Interact with the chat interface:

Using with Cursor's Agent Mode

This MCP server can be integrated directly with Cursor's Agent mode (Note: This is different from Cursor's Ask feature and only works in Agent mode). Here's how to set it up:

Adding the MCP Server to Cursor

1. Open Cursor Settings

2. Navigate to `Features` > `MCP`

3. Click `+ Add New MCP Server`

4. Fill out the form:

python /full/path/to/your/weather.py

Alternative: Project-Specific Configuration

You can also configure the MCP server for your project by creating a `.cursor/mcp.json` file:

1. Create the `.cursor` directory in your project root:

mkdir .cursor

2. Create `mcp.json` with the following content:

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": [
        "/full/path/to/your/weather.py"
      ]
    }
  }
}

Using the Weather Tools

1. Open Cursor's Composer (Agent mode)

2. The Agent will automatically detect when weather information is needed

3. Example queries:

Important Notes

• Tools are only available in Cursor's Agent mode (Composer), not in Ask mode
• By default, Cursor will ask for approval before using MCP tools
• You may need to click the refresh button in the MCP settings to see newly added tools
• The server must be running on your local machine (remote servers require SSE transport)

Features

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

Contributing

Feel free to submit issues and enhancement requests!