Content
# MCP Server Implementation
A complete Flask-based implementation of Model Context Protocol (MCP) for enhancing Large Language Model capabilities with external tools.
## Overview
This repository demonstrates how to build a server that handles Model Context Protocol (MCP), a method for extending LLM capabilities through tool invocation directly in the model's text output. Unlike function calling, MCP places tool definitions directly in the context window and parses the model's natural language responses to identify tool usage.
## Features
- 🔧 **Complete MCP Implementation**: Full parsing, execution, and response handling
- 🌤️ **Sample Tools**: Weather and calculator tools with parameter validation
- 🔄 **Conversation Flow**: Maintains context across multiple interactions
- 🧩 **Regex-Based Parsing**: Flexible text parsing for tool invocations
- 🚀 **Flask API**: REST API endpoints for chat integration
## Project Structure
```
mcp_server/
├── app.py # Main Flask application
├── mcp_handler.py # MCP parsing and execution
├── mcp_example.py # Standalone MCP example
├── requirements.txt # Dependencies
├── tools/ # Tool implementations
│ ├── __init__.py
│ ├── weather.py # Weather API tool
│ └── calculator.py # Calculator tool
└── README.md # This file
```
## Installation
1. Clone the repository:
```bash
git clone https://github.com/yourusername/mcp-server.git
cd mcp-server
```
2. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install dependencies:
```bash
pip install -r requirements.txt
```
4. Set up environment variables:
```bash
# Create a .env file with:
LLM_API_KEY=your_llm_api_key_here
WEATHER_API_KEY=your_weather_api_key_here
FLASK_APP=app.py
FLASK_ENV=development
```
## Usage
### Running the Server
Start the Flask development server:
```bash
flask run
```
For production:
```bash
gunicorn app:app
```
### API Endpoints
- **POST /chat**: Process chat messages with MCP
```bash
curl -X POST http://localhost:5000/chat \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"role": "user",
"content": "What's the weather like in Boston?"
}
]
}'
```
### Standalone Example
Run the example script to see MCP in action:
```bash
python mcp_example.py
```
## How It Works
1. **Tool Registration**: Tools are registered with their parameters and execution logic
2. **Tool Definition Injection**: XML-formatted tool descriptions are added to the prompt
3. **LLM Response Processing**: Regex patterns identify tool calls in the LLM's text output
4. **Tool Execution**: Parameters are parsed and passed to appropriate tool handlers
5. **Result Injection**: Tool execution results are inserted back into the response
## MCP vs. Function Calling
| Feature | MCP | Function Calling |
|---------|-----|-----------------|
| Definition Location | In prompt text | In API parameters |
| Invocation Format | Natural language | Structured JSON |
| Implementation | Text parsing | API integration |
| Visibility | Visible in response | May be hidden |
| Platform Support | Any text-based LLM | Requires API support |
## Example Conversation
**User**: What's the weather like in Boston?
**LLM**:
```
I'll check the weather for you.
get_weather(location="Boston, MA", unit="fahrenheit")
```
**After Processing**:
```
I'll check the weather for you.
get_weather(location="Boston, MA", unit="fahrenheit")
Result from get_weather:
{
"location": "Boston, MA",
"temperature": 72,
"unit": "fahrenheit",
"conditions": "Partly Cloudy",
"humidity": 68,
"wind_speed": 5.8
}
```
## Adding Your Own Tools
1. Create a new class inheriting from `Tool`
2. Define parameters and execution logic
3. Register with the MCP handler
Example:
```python
class MyTool(Tool):
def __init__(self):
parameters = [
{
"name": "param1",
"type": "string",
"description": "Description of param1",
"required": True
}
]
super().__init__(
name="my_tool",
description="Description of my tool",
parameters=parameters
)
def execute(self, param1):
# Tool logic here
return {"result": "Processed " + param1}
```
## MCP Configuration and Invocation Flow
1. **Tool Registration**:
- MCP tools are registered with the handler
- Each tool provides its name, description, and parameter definitions
2. **Tool Definition Injection**:
- Tool definitions are added to the system message
- Format follows XML structure for MCP
3. **LLM Response Processing**:
- LLM generates responses that may include tool invocations
- Pattern matching identifies tool calls in the text
- Tool parameters are parsed and passed to tool execution methods
4. **Tool Execution**:
- Tools are executed with the provided parameters
- Results are injected back into the conversation
5. **Conversation Management**:
- Processed responses with tool results are added to conversation history
- Future LLM requests include this history for context
## Example Conversation
Here's an example of what a conversation might look like:
**User**: What's the weather like in Boston?
**System**: *Sends prompt with MCP tool definitions to LLM*
**LLM Response**:
```
I'll check the weather for you.
get_weather(location="Boston, MA", unit="fahrenheit")
```
**MCP Handler**: *Parses the response, finds the tool call, and executes the weather tool*
**Tool Execution Result**:
```
Result from get_weather:
{
"location": "Boston, MA",
"temperature": 72,
"unit": "fahrenheit",
"conditions": "Partly Cloudy",
"humidity": 68,
"wind_speed": 5.8
}
```
**Processed Response** (sent back to user):
```
I'll check the weather for you.
get_weather(location="Boston, MA", unit="fahrenheit")
Result from get_weather:
{
"location": "Boston, MA",
"temperature": 72,
"unit": "fahrenheit",
"conditions": "Partly Cloudy",
"humidity": 68,
"wind_speed": 5.8
}
```
**User**: Can you calculate the square root of 144?
**LLM Response**:
```
I can calculate that for you.
calculator(expression="sqrt(144)")
```
**MCP Handler**: *Parses response, executes calculator tool*
**Tool Execution Result**:
```
Result from calculator:
{
"expression": "sqrt(144)",
"result": 12.0
}
```
**Processed Response** (sent back to user):
```
I can calculate that for you.
calculator(expression="sqrt(144)")
Result from calculator:
{
"expression": "sqrt(144)",
"result": 12.0
}
The square root of 144 is 12.
```
This demonstrates the complete flow of MCP tool usage, from the LLM's text-based invocation through execution and response processing.
## License
MIT
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
