What is Mcp Base

mcp-base is a clean implementation of Model Context Protocol (MCP) servers and clients, utilizing both Server-Sent Events (SSE) and StdioServer approaches to facilitate communication between clients and servers.

Use cases

Use cases for mcp-base include building real-time applications like weather updates, mathematical computation services, and integrating with GitHub to fetch repository information.

How to use

To use mcp-base, set up a virtual environment, install the required dependencies from ‘requirements.txt’, configure environment variables in a ‘.env’ file, and then run the desired server scripts in separate terminals.

Key features

Key features of mcp-base include support for multiple server implementations (math, weather, GitHub), the ability to handle single and multi-server clients, and integration with various APIs such as OpenAI and Google.

Where to use

mcp-base can be used in various fields such as web development, data analysis, and any application requiring real-time data processing and interaction between clients and servers.

MCP Project

A clean implementation of Model Context Protocol (MCP) servers and clients using both SSE and StdioServer approaches.

Project Structure

mcp_project/
│
├── .env                  # Environment variables
├── requirements.txt      # Dependencies
├── README.md             # This file
│
├── servers/              # Server implementations
│   ├── math_server.py    # Math server using SSE
│   ├── weather_server.py # Weather server using SSE
│   └── github_server.py  # Info on Github server using stdio (Docker)
│
├── clients/              # Client implementations 
│   ├── sse_client.py     # Single SSE client
│   ├── multi_sse_client.py # Multi-server SSE client
│   └── stdio_client.py   # StdioServer client (Docker)
│
├── tests/                # Test suite
│   ├── test_math.py      # Math server tests
│   ├── test_weather.py   # Weather server tests
│   ├── test_github.py    # GitHub server tests
│   ├── test_combined.py  # Combined servers test
│   └── run_all_tests.py  # Test runner
│
└── utils/                # Helper utilities
    └── __init__.py       # Empty init file

Getting Started

1. Set Up Environment

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Configure Environment Variables

Create a .env file in the project root with the following keys:

OPENAI_API_KEY="your-openai-api-key"
ANTHROPIC_API_KEY="your-anthropic-api-key"
GOOGLE_API_KEY="your-google-api-key"  # Required for Gemini model
GROQ_API_KEY="your-groq-api-key"
GITHUB_PERSONAL_ACCESS_TOKEN="your-github-personal-access-token"
USE_GEMINI="true"  # Set to "true" to use Gemini, "false" to use OpenAI

3. Running SSE Servers

Start each server in a separate terminal:

# Start Math Server (Port 8001)
python servers/math_server.py

# Start Weather Server (Port 8000)
python servers/weather_server.py

4. Running Combined Client

After setting up all servers (including the GitHub Docker server), you can run the combined client:

# Combined client with all servers (Math, Weather, and GitHub)
python clients/multi_sse_client.py

This client connects to both SSE-based servers (Math and Weather) and the GitHub server via stdio transport simultaneously, giving you access to all tools in a single interface.

Running Tests

The project includes a comprehensive test suite for all server types:

# Run all tests from the project root directory
python -m tests.run_all_tests

# Run specific tests
python -m tests.run_all_tests --tests math weather
python -m tests.run_all_tests --tests github
python -m tests.run_all_tests --tests combined

# Run individual test files
python -m tests.test_math
python -m tests.test_weather
python -m tests.test_github
python -m tests.test_combined

Make sure all servers are running before executing the tests:

1. Math server on port 8001
2. Weather server on port 8000
3. GitHub server via Docker (for github and combined tests)

5. Setting Up GitHub Server (Docker)

For the GitHub server:

1. Install Docker
2. Clone the MCP servers repository:

   git clone https://github.com/modelcontextprotocol/servers.git
   cd servers
   

3. Build the Docker image:

   docker build -t mcp/github -f src/github/Dockerfile .
   

6. Running StdioServer Client (GitHub)

After building the Docker image:

# Run the GitHub client
python clients/stdio_client.py

Key Concepts

SSE (Server-Sent Events)

• Used for real-time communication over HTTP
• Servers run as web services on specific ports
• Clients connect via HTTP to the server endpoints
• Multiple servers can run simultaneously on different ports

StdioServer (stdio)

• Used for communication via standard input/output
• Commonly used with Docker containers or external processes
• Useful for integrating with existing tools and services
• In this project, used for the GitHub MCP server

Understanding the Code

Servers

• Create a FastMCP instance with a name
• Define tools as Python functions with decorators
• Specify transport type when running the server

Clients

• Connect to servers using appropriate client classes
• Load tools from the servers
• Create a ReAct agent using the loaded tools
• Submit questions to the agent

Resources

• LangChain MCP Adapters
• LangGraph
• Model Context Protocol
• MCP GitHub Server