MCP Service Node

中文文档

System Synopsis

Leveraging FastAPI alongside the MCP (Model Context Protocol), this utility establishes a standardized conduit for contextual data flow linking AI constructs with their operational software frameworks. It significantly improves the robustness and manageability of AI-driven applications by streamlining the deployment lifecycle of models, furnishing efficient network access points, and guaranteeing uniform structure for all model inputs and outputs, thereby simplifying integration and governance for development teams.

MCP (Model Context Protocol) dictates a singular standard for interaction context bridging AI mechanisms and hosting environments. This repository furnishes a Python-based server implementation adhering to core MCP specifications, encompassing setup procedures, inference execution, and session lifecycle management.

Key Capabilities

• JSON-RPC 2.0 Adherence: Utilizes the standard JSON-RPC 2.0 specification for request-response communication patterns.
• Real-time Data Streams: Native support for Server-Sent Events (SSE) to broadcast instantaneous updates.
• Decoupled Architecture: A modular blueprint designed for straightforward extension and bespoke configuration.
• Asynchronous Performance: High-throughput service powered by FastAPI's non-blocking I/O paradigm.
• Integrated Client Utility: Ships with a fully functional auxiliary client for testing and verification.

Component Layout

mcp_server/ ├── mcp_server.py # Primary execution script for the MCP server ├── mcp_client.py # Auxiliary testing client program ├── routers/ │ ├── init.py # Initialization script for the routing module │ └── base_router.py # Core routing logic implementation ├── requirements.txt # Manifest of project dependencies └── README.md # Project documentation source file

Setup Instructions

1. Obtain the repository sources:

bash git clone https://github.com/freedanfan/mcp_server.git cd mcp_server

1. Install prerequisite libraries:

bash pip install -r requirements.txt

Operational Guide

Initiating the Server Daemon

Execute the main application file:

bash python mcp_server.py

The service defaults to binding on 127.0.0.1:12000. Parameters for network interface and port are configurable via environmental variables:

bash export MCP_SERVER_HOST=0.0.0.0 export MCP_SERVER_PORT=8000 python mcp_server.py

Executing the Client Utility

Launch the testing client in a separate terminal session:

bash python mcp_client.py

If the service is not operating on the default network address, specify the target location using an environmental variable:

bash export MCP_SERVER_URL="http://your-server-address:port" python mcp_client.py

Gateway Interfaces

The service exposes the subsequent network access points:

• Root Path (/): Supplies metadata regarding the server's operational status.
• API Endpoint (/api): Serves as the reception point for all structured JSON-RPC communications.
• SSE Endpoint (/sse): Manages persistent bidirectional streams for event notifications.

MCP Protocol Execution Details

Connection Establishment Sequence

1. The client initiates a persistent connection utilizing the SSE mechanism.
2. The server replies by transmitting the URI pointing to the primary API endpoint.
3. The client dispatches an initial handshake message detailing the protocol version and its operational proficiencies.
4. The server acknowledges the handshake, returning its own specification capabilities.

Inference Request Processing

Clients transmit inference requests containing the textual input:

{ "jsonrpc": "2.0", "id": "request-id", "method": "sample", "params": { "prompt": "Hello, please introduce yourself." } }

The server responds with the derived output data:

{ "jsonrpc": "2.0", "id": "request-id", "result": { "content": "This is a response to the prompt...", "usage": { "prompt_tokens": 10, "completion_tokens": 50, "total_tokens": 60 } } }

Session Termination Command

Clients can issue a formal request to cease operations gracefully:

{ "jsonrpc": "2.0", "id": "request-id", "method": "shutdown", "params": {} }

The server confirms system quiescence with a status response:

{ "jsonrpc": "2.0", "id": "request-id", "result": { "status": "shutting_down" } }

Extending Functionality

Incorporating Novel Operations

To introduce new methods governed by the MCP standard, define a dedicated handler function within the MCPServer class structure and formally register it within the _register_methods invocation sequence:

python def handle_new_method(self, params: dict) -> dict: """Process execution for a novel method""" logger.info(f"New method request received: {params}") # Insert custom processing logic here return {"result": "success"}

def _register_methods(self): # Register established operations self.router.register_method("initialize", self.handle_initialize) self.router.register_method("sample", self.handle_sample) self.router.register_method("shutdown", self.handle_shutdown) # Register the newly defined operation self.router.register_method("new_method", self.handle_new_method)

Wiring Up External AI Engines

Integration of production-grade AI models necessitates modification of the handle_sample method's body:

python async def handle_sample(self, params: dict) -> dict: """Process for token generation requests""" logger.info(f"Sampling operation initiated with parameters: {params}")

# Extract the user-provided textual input
prompt = params.get("prompt", "")

# Interface with the external AI model service (e.g., OpenAI)
response = await openai.ChatCompletion.acreate(
    model="gpt-4",
    messages=[{"role": "user", "content": prompt}]
)

content = response.choices[0].message.content
usage = response.usage

return {
    "content": content,
    "usage": {
        "prompt_tokens": usage.prompt_tokens,
        "completion_tokens": usage.completion_tokens,
        "total_tokens": usage.total_tokens
    }
}

Diagnostics and Debugging

Frequent Pitfalls

1. Connectivity Failures: Verify the server process is active and the client endpoint specification is correct.
2. HTTP 405 Status: Confirm client requests are targeting the recognized API interface path.
3. SSE Stream Interruption: Inspect network pathways and any intervening security measures (firewalls).

Verbose Output

Both the service and client components offer granular logging output. Adjust the verbosity level to gather deeper operational insights:

bash

Elevate logging verbosity

export PYTHONPATH=. python -m logging -v DEBUG -m mcp_server

Supporting Documentation

• MCP Protocol Specification
• FastAPI Framework Documentation
• JSON-RPC 2.0 Official Standard
• Server-Sent Events Web Standard

Licensing

This codebase is distributed under the terms of the MIT License. Refer to the LICENSE file for the full disclosure.

WIKIPEDIA: XMLHttpRequest (XHR) represents an interface within JavaScript, structured as an object whose methods facilitate the dispatching of HTTP queries from a web browser to a backend server. These methods empower browser-based software modules to submit requests post-page-load and subsequently acquire data in return. XMLHttpRequest is a foundational element of the Ajax programming methodology. Before Ajax gained traction, interaction with the server primarily relied on standard hyperlinks or form submissions, often resulting in a complete replacement of the currently displayed page.

== Origin Story == The fundamental concept underpinning XMLHttpRequest was first conceived in the year 2000 by the engineering team responsible for Microsoft Outlook. This concept was subsequently realized within the Internet Explorer 5 browser release (1999). However, the initial programmatic notation deviated from the identifier XMLHttpRequest, instead employing constructs like ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). Since the debut of Internet Explorer 7 (2006), comprehensive browser support for the standardized XMLHttpRequest identifier has been universal. The XMLHttpRequest identifier has since solidified its status as the prevailing convention across all major browser engines, including Mozilla's Gecko rendering pipeline (starting 2002), Apple's Safari (version 1.2, released 2004), and Opera (version 8.0, released 2005).

=== Formalization === The World Wide Web Consortium (W3C) issued a preliminary specification draft for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the Level 2 Working Draft, which introduced enhancements such as mechanisms for monitoring the progression of events, enabling requests across different security domains (cross-site access), and managing binary data streams. By the close of 2011, the Level 2 extensions were merged back into the primary specification document. In late 2012, the WHATWG organization assumed custodianship of the standard's evolution, maintaining a continuously updated specification documented using Web IDL syntax.

== Operational Steps == Typically, dispatching a request using XMLHttpRequest involves a prescribed sequence of programming actions.

1. Instantiate an XMLHttpRequest object via its constructor:
2. Invoke the "open" method to define the request method (e.g., GET/POST), specify the target Uniform Resource Identifier (URI), and select either synchronous or asynchronous execution mode:
3. For asynchronous operations, attach an event handler function designed to trigger upon changes in the request's status:
4. Commence the transmission process by calling the "send" method, optionally including payload data:
5. Process state transitions within the registered event listener. Server-provided response data is usually stored by default in the "responseText" attribute. Once the object completes processing the response entirely, its state transitions to 4, designated as the "done" state. Beyond these fundamental steps, XMLHttpRequest offers extensive configuration options governing transmission behavior and response handling. Custom header fields can be appended to the outbound request to guide server fulfillment logic, and data can be uploaded synchronously with the "send" call. The received response payload can be automatically deserialized from JSON into native JavaScript objects, or it can be processed incrementally as data packets arrive rather than awaiting the full response body. Furthermore, the operation can be terminated prematurely or configured to time out if completion is not achieved within a defined interval.

== Inter-domain Communications ==

During the nascent stages of the World Wide Web's evolution, it became apparent that unrestricted access between documents hosted on disparate origins posed a potential security vulnerability, leading to restrictions that XMLHttpRequest initially inherited.