MCP Server

A medium-level Model Context Protocol (MCP) Server implementation - A reusable, installable Python package for building MCP applications.

Features

• Full MCP Protocol Support: JSON-based stdio protocol for seamless communication
• Dynamic Tool System: Extensible architecture for custom tool development
• Comprehensive Logging: Multi-level logging with context tracking
• Configuration Management: Environment-based configuration with .env support
• Request Validation: Server-side validation with detailed error reporting
• Session Management: In-memory session tracking with configurable timeouts
• CLI Interface: User-friendly command-line interface with graceful shutdown

Installation

From Wheel File

pip install mcp_server-1.0.0-py3-none-any.whl

From Source

git clone <repository-url>
cd medium_Level_MCP
pip install .

Development Installation

pip install -e ".[dev]"

Quick Start

Starting the Server

# Start the server (stdio mode)
mcp-server

# Show version
mcp-server --version

# Show help
mcp-server --help

Configuration

Create a .env file in your working directory:

# Server Configuration
MAX_ACTIVE_SESSIONS=1000
SESSION_TIMEOUT_MINUTES=30

# Tool Configuration
TOOLS_AUTO_LOAD=true
MAX_CONCURRENT_TOOLS=5

# Logging Configuration
LOG_LEVEL=INFO
LOG_TO_CONSOLE=true
LOG_TO_FILE=true

# Validation Configuration
STRICT_VALIDATION=true

See .env.example for all available options.

Example Request

Send JSON requests via stdin:

{
  "session_id": "session_123",
  "user_id": "user_001",
  "query": "What is the weather in London?",
  "metadata": {}
}

Response:

{
  "session_id": "session_123",
  "response": "Tool 'get_weather' executed successfully.",
  "tool_results": [
    {
      "tool_name": "get_weather",
      "success": true,
      "result": {
        "location": "London",
        "temperature": 22,
        "conditions": "Partly Cloudy"
      },
      "error": null,
      "execution_time": 0.001
    }
  ],
  "error": null,
  "metadata": {}
}

Architecture

app.py (CLI Entry Point)
  ↓
core/server.py (MCP Server)
  ↓
core/dispatcher.py (Request Router)
  ↓
tools/* (Tool Implementations)

Core Components

• app.py: Lightweight CLI application entry point
• core/server.py: MVP MCP server with stdio protocol
• core/dispatcher.py: Request routing and tool orchestration
• core/config.py: Configuration management
• core/logger.py: Comprehensive logging system
• core/models.py: Pydantic data models
• utils/validation.py: Server-side validation

Tools System

• tools/base.py: Abstract base class for tools
• tools/loader.py: Dynamic tool discovery and loading
• tools/weather/: Example weather tool
• tools/search/: Example search tool

Creating Custom Tools

from tools.base import BaseTool
from typing import Dict, Any

class MyCustomTool(BaseTool):
    def get_name(self) -> str:
        return "my_custom_tool"
    
    def get_description(self) -> str:
        return "Description of what my tool does"
    
    def get_parameters_schema(self) -> Dict[str, Any]:
        return {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "First parameter"
                }
            },
            "required": ["param1"]
        }
    
    async def execute(self, **kwargs) -> Dict[str, Any]:
        # Your tool implementation
        return {"result": "success"}

Place your tool in tools/<category>/your_tool.py and it will be auto-loaded.

Testing

# Run all tests
python test_phase1.py
python tests/test_dispatcher.py
python tests/test_server.py
python tests/test_app.py

# Run tools tests
python test_tools.py

Logging

Logs are written to:

• logs/mcp_server.log - General logs
• logs/mcp_errors.log - Errors only
• logs/mcp_tools.log - Tool executions

API Reference

See PACKAGE_ARCHITECTURE.txt for detailed documentation on:

• Module architecture
• Workflow diagrams
• API references
• Implementation guides

Requirements

• Python >= 3.9
• pydantic >= 2.0.0
• python-dotenv >= 1.0.0
• typing-extensions >= 4.0.0

License

MIT License

Contributing

Contributions are welcome! Please ensure:

• All tests pass
• Code follows the existing style
• Documentation is updated
• New tools include tests

Future Enhancements

Documented areas for improvement:

• Dedicated error handling module
• Database-backed session management
• HTTP/WebSocket protocol support
• Request queuing and rate limiting
• Advanced monitoring and health checks

See PACKAGE_ARCHITECTURE.txt for detailed roadmap.

Version

Current version: 1.0.0

Support

For issues, questions, or contributions, please refer to:

• Documentation: PACKAGE_ARCHITECTURE.txt
• Tools Guide: tools/TOOLS_README.md
• Configuration: .env.example