koya-rama/mcp-server-test

MCP Server Test

A comprehensive Model Context Protocol (MCP) server implementation with multiple tools including calculator, weather, and file operations.

Features

🧮 Calculator Tool

• Perform mathematical calculations
• Safe expression evaluation
• Support for basic math functions (sin, cos, sqrt, etc.)

🌤️ Weather Tool

• Get weather information for any city
• Mock weather data for demonstration
• Includes temperature, humidity, wind speed, and conditions

📁 File Operations Tool

• Create, read, list, and delete files
• Directory operations
• Safe file handling with error management

Architecture

This project includes two implementations:

1. mcp_server.py - Standard MCP protocol server using stdin/stdout
2. app.py - FastAPI-based REST API server for easier testing and deployment

Installation

Prerequisites

• Python 3.8+
• pip

Setup

1. Clone the repository:

git clone <repository-url>
cd mcp-server-test

2. Create and activate virtual environment:

python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

Usage

Running the FastAPI Server

python app.py

The server will start on http://localhost:8000

Available Endpoints

• GET / - Server information
• GET /tools - List available tools
• POST /tools/call - Call a specific tool
• POST /mcp - MCP protocol endpoint
• GET /docs - Interactive API documentation (Swagger UI)

Testing the Server

Run the test client to see all tools in action:

python test_client.py

Example API Calls

Calculator Tool

curl -X POST "http://localhost:8000/tools/call" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "calculator",
    "arguments": {"expression": "2 + 3 * 4"}
  }'

Weather Tool

curl -X POST "http://localhost:8000/tools/call" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "weather",
    "arguments": {"city": "New York"}
  }'

File Operations Tool

curl -X POST "http://localhost:8000/tools/call" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "file_operations",
    "arguments": {
      "operation": "create",
      "filename": "hello.txt",
      "content": "Hello, World!"
    }
  }'

Running the Standard MCP Server

For the standard MCP protocol implementation:

python mcp_server.py

This version communicates via stdin/stdout and follows the MCP protocol specification.

Development

Project Structure

mcp-server-test/
├── app.py              # FastAPI server implementation
├── mcp_server.py       # Standard MCP protocol server
├── test_client.py      # Test client for demonstration
├── requirements.txt    # Python dependencies
├── README.md          # This file
└── venv/              # Virtual environment

Adding New Tools

1. Define the tool schema in the TOOLS dictionary
2. Implement the tool function
3. Add the tool call handling in the appropriate endpoint
4. Update tests in test_client.py

Deployment

Local Development

uvicorn app:app --reload --host 0.0.0.0 --port 8000

Docker Deployment

Create a Dockerfile:

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 8000

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

Cloud Deployment Options

Railway

1. Connect your GitHub repository to Railway
2. Railway will automatically detect the Python app
3. Set the start command: uvicorn app:app --host 0.0.0.0 --port $PORT

Render

1. Connect your GitHub repository to Render
2. Choose "Web Service"
3. Set the start command: uvicorn app:app --host 0.0.0.0 --port $PORT

Heroku

1. Create a Procfile:

web: uvicorn app:app --host 0.0.0.0 --port $PORT

2. Deploy using Heroku CLI or GitHub integration

API Documentation

When running the FastAPI server, visit http://localhost:8000/docs for interactive API documentation.

MCP Protocol Compliance

This server implements the MCP (Model Context Protocol) specification:

• JSON-RPC 2.0 based communication
• Tool discovery and execution
• Error handling and response formatting
• Protocol version negotiation

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

This project is licensed under the MIT License.

Support

For issues and questions, please open an issue on the GitHub repository.

Note: The weather tool uses mock data for demonstration purposes. In a production environment, you would integrate with a real weather API service.