Model Context Protocol (MCP) Server

A modular Model Context Protocol server for AI services with multiple transport options and dynamic service selection. Built with SOLID principles for maintainability and extensibility.

Features

- Multiple AI Services: Support for Claude, OpenAI, and mock services
- Dynamic Service Selection: Choose AI service on a per-request basis
- Multiple Transports:
- stdio: For command-line usage and scripting
- TCP: For network-based applications
- WebSocket: For web browsers and real-time applications
- JSON-RPC 2.0: Compliant interface for predictable interactions
- Modular Architecture: Easy to extend with new services and transports
- Environment Configuration: Simple setup via .env file
- Streaming Support: Real-time response streaming for supported transports

Repository Structure

basic-mcp-server/
├── .env                      # Environment configuration
├── .gitignore                # Git ignore rules
├── README.md                 # Project documentation
├── examples/                 # Example clients
│   ├── example_client.py     # Command-line client example
│   └── websocket_client.html # Browser WebSocket client
├── mcp_server.py             # Main entry point
└── mcp_server/               # Core package
    ├── config/               # Configuration management
    │   ├── settings.py       # Environment and settings handling
    │   └── __init__.py
    ├── core/                 # Core server logic
    │   ├── server.py         # Main server implementation
    │   └── __init__.py
    ├── handlers/             # Method handlers
    │   ├── base_handlers.py  # Standard MCP handlers
    │   ├── system_handlers.py # System info handlers
    │   └── __init__.py
    ├── models/               # Data models
    │   ├── json_rpc.py       # JSON-RPC data structures
    │   └── __init__.py
    ├── services/             # AI service implementations
    │   ├── claude_service.py # Anthropic Claude API
    │   ├── openai_service.py # OpenAI API
    │   └── __init__.py       # Service registry
    ├── transports/           # Communication protocols
    │   ├── base.py           # Transport interfaces
    │   ├── websocket.py      # WebSocket implementation
    │   └── __init__.py
    └── __init__.py

Installation

1. Clone the repository:

   git clone https://github.com/shaswata56/basic-mcp-server.git

   cd basic-mcp-server

   

2. Create a virtual environment and install dependencies:

   python -m venv venv

   source venv/bin/activate  # On Windows: venv\Scripts\activate

   pip install -e .

   

3. Configure your environment by editing the .env file with your API keys and settings.

Configuration

Environment Variables

The server can be configured using environment variables in the .env file:

| Variable | Description | Default |
|----------|-------------|---------|
| AI_SERVICE_TYPE | Default AI service to use ("claude", "openai", "mock") | "claude" |
| SECRETS_FILE | Path to JSON file with API secrets | None |
| ANTHROPIC_API_KEY | Your Anthropic API key | None |
| OPENAI_API_KEY | Your OpenAI API key | None |
| MCP_SERVER_NAME | Name of the server | "ai-mcp-server" |
| MCP_SERVER_VERSION | Server version | "1.0.0" |
| MCP_TRANSPORT_TYPE | Transport type ("stdio", "tcp", or "websocket") | "stdio" |
| MCP_TCP_HOST | TCP/WebSocket host address | "127.0.0.1" |
| MCP_TCP_PORT | TCP server port | 9000 |
| MCP_WS_PORT | WebSocket server port | 8765 |
| MCP_WS_PATH | WebSocket server path | "/" |
| MCP_WS_ORIGINS | Comma-separated list of allowed origins | None (all allowed) |
| CLAUDE_DEFAULT_MODEL | Default Claude model | "claude-3-opus-20240229" |
| CLAUDE_DEFAULT_MAX_TOKENS | Default max tokens for Claude | 4096 |
| CLAUDE_DEFAULT_TEMPERATURE | Default temperature for Claude | 0.7 |
| OPENAI_DEFAULT_MODEL | Default OpenAI model | "gpt-4o" |
| OPENAI_DEFAULT_MAX_TOKENS | Default max tokens for OpenAI | 1024 |
| OPENAI_DEFAULT_TEMPERATURE | Default temperature for OpenAI | 0.7 |

| EMBEDDINGS_3_LARGE_API_URL | Azure endpoint for text-embedding-3-large | None |
| EMBEDDINGS_3_LARGE_API_KEY | API key for text-embedding-3-large | None |
| EMBEDDINGS_3_SMALL_API_URL | Azure endpoint for text-embedding-3-small | None |
| EMBEDDINGS_3_SMALL_API_KEY | API key for text-embedding-3-small | None |
| AZURE_OPENAI_EMBEDDING_DEPLOYMENT | Azure deployment name for embeddings | <model name> |
| QDRANT_URL | URL of the Qdrant server (use :memory: for in-memory) | None |
| QDRANT_API_KEY | API key for Qdrant Cloud | None |

When embedding API credentials are not provided, the server will generate
deterministic mock embeddings so that testing can proceed without external
services.

For production deployments, configure QDRANT_URL to point to a dedicated
Qdrant server. Using a remote server provides persistent storage and improved
vector search performance compared to the default in-memory mode.

The optional SECRETS_FILE variable allows you to store API keys in a JSON
file instead of environment variables. Values defined in the secrets file are
used when corresponding environment variables are not set. If a secret value is
an array, the server will rotate through the values each time the key is
requested, enabling simple key rotation strategies.

Usage

Running the Server

Standard stdio Mode

python mcp_server.py

TCP Server Mode

python mcp_server.py --tcp --host 127.0.0.1 --port 9000

WebSocket Server Mode

python mcp_server.py --websocket --host 127.0.0.1 --port 8765 --ws-path /

Command Line Options

usage: mcp_server.py [-h] [--tcp | --websocket] [--host HOST] [--port PORT]
                     [--ws-path WS_PATH] [--service-type {claude,openai,mock}]
                     [--claude-api-key CLAUDE_API_KEY]
                     [--openai-api-key OPENAI_API_KEY]
                     [--qdrant-url QDRANT_URL]
                     [--qdrant-api-key QDRANT_API_KEY] [--mock]
                     [--log-level {DEBUG,INFO,WARNING,ERROR}]
                     [--env-file ENV_FILE]
AI MCP Server with JSON-RPC
options:

  -h, --help            show this help message and exit

  --log-level {DEBUG,INFO,WARNING,ERROR}

                        Logging level

  --env-file ENV_FILE   Path to .env file (default: .env in project root)
Transport Options:

  --tcp                 Run as TCP server

  --websocket           Run as WebSocket server

  --host HOST           Host to bind server

  --port PORT           Port for server

  --ws-path WS_PATH     URL path for WebSocket server (default: /)
AI Service Options:

  --service-type {claude,openai,mock}

                        AI service to use

  --claude-api-key CLAUDE_API_KEY

                        Anthropic API key

  --openai-api-key OPENAI_API_KEY

                          OpenAI API key

  --qdrant-url QDRANT_URL

                          Qdrant server URL

  --qdrant-api-key QDRANT_API_KEY

                          Qdrant API key

  --mock                Use mock AI service (for testing)

Client Examples

Command Line Client

The examples/example_client.py provides a simple way to interact with the server:

```bash