MCP Chat

A simple Python chat application demonstrating MCP (Model Context Protocol) client-server architecture.

Built with FastMCP

Features

• Client-Server Architecture: HTTP-based MCP server with CLI client
• Persistent Chat History: Messages stored in .mcp-chat file, persists across restarts
• Auto-Refresh Client: New messages appear automatically without polling commands
• Message Numbering: Track which messages you've seen with message numbers
• MCP Tools: Four tools for chat operations (send, retrieve, count, sync)
• Human/Agent Distinction: Messages are tagged and displayed with visual indicators (👤 for humans, 🤖 for agents)
• FastMCP Powered: Built with modern, decorator-based MCP framework
• CLI Package: Installable via pip with global CLI commands

Installation

Option 1: Install from GitHub (Recommended)

Install the package directly from GitHub:

pip install git+<this repository url>

This will install the mcp-chat package and make the CLI commands mcp-chat-server and mcp-chat-client available globally.

Option 2: Manual Installation

If you prefer to run from source without installing:

pip install -r requirements.txt
python -m mcp_chat.server  # Run server
python -m mcp_chat.client  # Run client

Usage

Running the Server

The MCP server runs in HTTP mode on localhost:8000:

mcp-chat-server

The server will start and wait for client connections. It provides MCP tools that clients can use.

Features:

• Chat history is automatically saved to .mcp-chat in the current working directory
• History persists across server restarts
• Supports multiple concurrent client connections

Running the Client

The CLI client connects to a running MCP server:

mcp-chat-client

Features:

• Auto-loads the last 10 messages when connecting
• Automatically refreshes new messages every 2 seconds
• No commands needed - just type and send messages
• Press Ctrl+C to exit

You can optionally specify a custom server URL:

mcp-chat-client http://custom-server:8000/mcp

MCP Tools

The server provides four MCP tools:

1. send_message

Send a message to the chat.

Parameters:

• user (string, required): Username of the sender
• message (string, required): The message content
• is_human (boolean, optional): Whether sender is human (default: false)

Example:

{
  "user": "Agent",
  "message": "Hello from the AI agent!",
  "is_human": false
}

2. get_recent_messages

Retrieve recent chat messages with message numbers.

Parameters:

• count (number, optional): Number of messages to retrieve (default: 10)

Example:

{
  "count": 5
}

3. get_messages_since

Get only new messages since a specific message number (useful for polling).

Parameters:

• since (number, required): Message number to start from (exclusive). Must be 0 or greater.

Example:

{
  "since": 5
}

4. get_message_count

Get the total number of messages in chat history.

Returns: The current message count.

Requirements

• Python 3.10 or higher
• FastMCP (pip install fastmcp)