mcp_server

This MCP server provides a Python-based implementation of the Model Context Protocol (MCP) built on FastAPI. It exposes a JSON-RPC 2.0 API at /api for request/response interactions, and an SSE endpoint at /sse for real-time notifications. The server supports initialization, sampling, and session management to enable standardized context interaction between AI models and development environments. A provided test client (mcp_client.py) demonstrates how to send JSON-RPC requests to /api and how to handle responses and streaming updates via SSE. To try it out, start the server locally and use the client to send a sample request, then observe the server’s response along with any real-time updates over SSE.

Typical usage includes starting the server, optionally configuring the host and port via environment variables, and then using the client to perform initialization, submit sampling prompts, and gracefully shut down sessions. The server is designed with a modular architecture to simplify extending methods or integrating actual AI models in the handle_sample routine.

Prerequisites:

• Python 3.8+ (recommended 3.9+)
• Git

Installation steps:

1. Clone the repository: git clone https://github.com/freedanfan/mcp_server.git cd mcp_server

2. Create and activate a Python virtual environment (optional but recommended): python -m venv venv source venv/bin/activate # On Windows use: venv\Scripts\activate

3. Install dependencies: pip install -r requirements.txt

4. Run the server: python mcp_server.py

5. (Optional) Configure host/port via environment variables before starting the server: export MCP_SERVER_HOST=0.0.0.0 export MCP_SERVER_PORT=12000 python mcp_server.py

Tips and notes:

• The server exposes three main endpoints: / (server info), /api (JSON-RPC), and /sse (server-sent events). Ensure requests are directed to /api for MCP methods like initialize, sample, and shutdown.
• If you modify or extend methods, update the MCPServer class and register new handlers in the _register_methods section as shown in the documentation.
• For real AI integration, implement actual model inference inside handle_sample. The example demonstrates how to call an external model API and format the response with content and usage stats before returning to clients.
• Common issues: verify the server process is running, confirm the correct URL (especially if using a non-default host/port), and ensure the client uses the /api endpoint for JSON-RPC calls.
• Environment variables MCP_SERVER_HOST and MCP_SERVER_PORT can be used to customize binding address and port; you can also override the default address in client configurations by setting MCP_SERVER_URL.