Add support for protocol 2025-06-18

Author: sharoonthomas

README.md

@@ -17,9 +17,11 @@ A Python utility package for building Model Context Protocol (MCP) servers.
     - [Optional Dependencies](#optional-dependencies)
   - [Usage](#usage)
     - [Basic MCP Server](#basic-mcp-server)
-    - [Flask with Redis Example](#flask-with-redis-example)
+    - [Flask Example](#flask-example)
     - [SQLAlchemy Transaction Handling Example](#sqlalchemy-transaction-handling-example)
+    - [Running with Gunicorn](#running-with-gunicorn)
   - [Connecting with MCP Clients](#connecting-with-mcp-clients)
+    - [Cursor](#cursor)
     - [Claude Desktop](#claude-desktop)
       - [Installing via Smithery](#installing-via-smithery)
       - [Installing via PyPI](#installing-via-pypi)
@@ -94,40 +96,27 @@ def get_weather(city: str) -> str:
     return "sunny"
 ```
 
-### Flask with Redis Example
+### Flask Example
+
+For production use, you can use a simple Flask app with the mcp server and
+support [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http)
+from version 2025-06-18.
 
-For production use, you can integrate the MCP server with Flask and Redis for better message handling:
 
 ```python
 from flask import Flask, Response, url_for, request
-import redis
-from mcp_utils.queue import RedisResponseQueue
-
-# Setup Redis client
-redis_client = redis.Redis(host="localhost", port=6379, db=0)
 
 # Create Flask app and MCP server with Redis queue
 app = Flask(__name__)
 mcp = MCPServer(
     "example",
     "1.0",
-    response_queue=RedisResponseQueue(redis_client)
 )
 
-@app.route("/sse")
-def sse():
-    session_id = mcp.generate_session_id()
-    messages_endpoint = url_for("message", session_id=session_id)
-    return Response(
-        mcp.sse_stream(session_id, messages_endpoint),
-        mimetype="text/event-stream"
-    )
-
-
-@app.route("/message/<session_id>", methods=["POST"])
-def message(session_id):
-    mcp.handle_message(session_id, request.get_json())
-    return "", 202
+@app.route("/mcp", methods=["POST"])
+def mcp_route():
+    response = mcp.handle_message(request.get_json())
+    return jsonify(response.model_dump(exclude_none=True))
 
 
 if __name__ == "__main__":
@@ -142,11 +131,6 @@ For production use, you can integrate the MCP server with Flask, Redis, and SQLA
 from flask import Flask, request
 from sqlalchemy.orm import Session
 from sqlalchemy import create_engine
-import redis
-from mcp_utils.queue import RedisResponseQueue
-
-# Setup Redis client
-redis_client = redis.Redis(host="localhost", port=6379, db=0)
 
 # Create engine for PostgreSQL database
 engine = create_engine("postgresql://user:pass@localhost/dbname")
@@ -156,31 +140,86 @@ app = Flask(__name__)
 mcp = MCPServer(
     "example",
     "1.0",
-    response_queue=RedisResponseQueue(redis_client)
 )
 
-@app.route("/message/<session_id>", methods=["POST"])
-def message(session_id):
+@app.route("/mcp", methods=["POST"])
+def mcp_route():
     with Session(engine) as session:
         try:
-            mcp.handle_message(session_id, request.get_json())
+            response = mcp.handle_message(request.get_json())
             session.commit()
-            return "", 202
-        except Exception as e:
+        except:
             session.rollback()
             raise
+        else:
+            return jsonify(response.model_dump(exclude_none=True))
+
 
 if __name__ == "__main__":
     app.run(debug=True)
 ```
 
 For a more comprehensive example including logging setup and session management, check out the [example Flask application](https://github.com/fulfilio/mcp-utils/blob/main/examples/flask_app.py) in the repository.
 
+### Running with Gunicorn
+
+Gunicorn is a better approach to running even locally. To run the app with gunicorn
+
+```python
+from gunicorn.app.base import BaseApplication
+
+class FlaskApplication(BaseApplication):
+    def __init__(self, app, options=None):
+        self.options = options or {}
+        self.application = app
+        super().__init__()
+
+    def load_config(self):
+        config = {
+            key: value
+            for key, value in self.options.items()
+            if key in self.cfg.settings
+        }
+        for key, value in config.items():
+            self.cfg.set(key.lower(), value)
+
+    def load(self):
+        return self.application
+
+
+if __name__ == "__main__":
+    handler = logging.StreamHandler(sys.stdout)
+    formatter = logging.Formatter("[%(asctime)s] [%(levelname)s] %(name)s: %(message)s")
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    options = {
+        "bind": "0.0.0.0:9000",
+        "workers": 1,
+        "worker_class": "gevent",
+        "loglevel": "debug",
+    }
+    FlaskApplication(app, options).run()
+```
+
 ## Connecting with MCP Clients
 
+### Cursor
+
+* Edit MCP settings and add to configuration
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "url": "http://localhost:9000/mcp"
+    }
+  }
+}
+```
+
 ### Claude Desktop
 
-Currently, only Claude Desktop (not claude.ai) can connect to MCP servers. As of this writing, Claude Desktop does not support MCP through SSE and only supports stdio. To connect Claude Desktop with an MCP server, you'll need to use [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy).
+As of this writing, Claude Desktop does not support MCP through SSE and only supports stdio. To connect Claude Desktop with an MCP server, you'll need to use [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy).
 
 Configuration example for Claude Desktop:
 

examples/flask_app.py

@@ -17,7 +17,7 @@
 import sys
 
 import redis
-from flask import Flask, Response, request, url_for
+from flask import Flask, Response, jsonify, request, url_for
 from gunicorn.app.base import BaseApplication
 
 from mcp_utils.core import MCPServer
@@ -30,14 +30,9 @@
     TextContent,
 )
 
-redis_client = redis.Redis(
-    host="localhost",
-    port=6379,
-    db=0,
-)
 
 app = Flask(__name__)
-mcp = MCPServer("weather", "1.0", response_queue=RedisResponseQueue(redis_client))
+mcp = MCPServer("weather", "1.0")
 
 logger = logging.getLogger("mcp_utils")
 logger.setLevel(logging.DEBUG)
@@ -85,27 +80,10 @@ def get_cities(city_name: str) -> CompletionValues:
     return [city for city in all_cities if city.lower().startswith(city_name.lower())]
 
 
-@app.route("/sse")
-def sse():
-    session_id = mcp.generate_session_id()
-    messages_endpoint = url_for("message", session_id=session_id)
-    logger.info(f"SSE endpoint: {messages_endpoint}")
-    logger.info(f"Session ID: {session_id}")
-
-    return Response(
-        mcp.sse_stream(session_id, messages_endpoint), mimetype="text/event-stream"
-    )
-
-
-@app.route("/message", methods=["POST"])
-def message():
-    """
-    Messages from the client are received as a POST
-    request with a JSON body.
-    """
-    logger.debug(f"Received message: {request.get_json()}")
-    mcp.handle_message(request.args["session_id"], request.get_json())
-    return "", 202
+@app.route("/mcp", methods=["POST"])
+def mcp_route():
+    response = mcp.handle_message(request.get_json())
+    return jsonify(response.model_dump(exclude_none=True))
 
 
 class FlaskApplication(BaseApplication):

src/mcp_utils/core.py

@@ -54,8 +54,8 @@ class MCPServer:
     # by the server.
     # The client is responsible to disconnect if the version is
     # not supported.
-    # https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle/#version-negotiation
-    protocol_version: str = "2024-11-05"
+    # https://spec.modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle/#version-negotiation
+    protocol_version: str = "2025-06-18"
 
     # server capabilities can be:
     # - prompts
@@ -200,7 +200,7 @@ def generate_session_id(self) -> str:
         """
         return str(uuid.uuid4())
 
-    def sse_stream(self, session_id: str, messages_endpoint: str | None = None):
+    def sse_stream(self, session_id: str, messages_endpoint: str):
         """
         Create a Server-Sent Events (SSE) stream for a session
 
@@ -211,11 +211,10 @@ def sse_stream(self, session_id: str, messages_endpoint: str | None = None):
         Returns:
             Iterator yielding SSE formatted strings
         """
-        if messages_endpoint is not None:
-            # The first message is the endpoint itself
-            endpoint_response = f"event: endpoint\ndata: {messages_endpoint}\n\n"
-            logger.debug(f"Sending endpoint: {endpoint_response}")
-            yield endpoint_response
+        # The first message is the endpoint itself
+        endpoint_response = f"event: endpoint\ndata: {messages_endpoint}\n\n"
+        logger.debug(f"Sending endpoint: {endpoint_response}")
+        yield endpoint_response
 
         # Now loop and block forever and keep yielding responses
         try:
@@ -484,16 +483,20 @@ def _handle_tools_call(self, request: MCPRequest) -> MCPResponse:
                 ),
             )
 
-    def handle_message(self, session_id: str, message: dict) -> MCPResponse | None:
+    def handle_message(
+        self, message: dict, session_id: str | None = None
+    ) -> MCPResponse | None:
         """Handle incoming MCP messages."""
         logger.debug(f"Handling message: {message}")
-        response = self._handle_message(session_id, message)
+        response = self._handle_message(message, session_id)
         logger.debug(f"Response: {response}")
-        if response is not None:
+        if response is not None and session_id is not None:
             self.response_queue.push_response(session_id, response)
         return response
 
-    def _handle_message(self, session_id: str, message: dict) -> MCPResponse | None:
+    def _handle_message(
+        self, message: dict, session_id: str | None = None
+    ) -> MCPResponse | None:
         try:
             message_id = message["id"]
         except KeyError:

tests/test_core.py

@@ -307,7 +307,7 @@ def test_message_handling(server: MCPServer) -> None:
             "clientInfo": {"name": "Test Client", "version": "1.0.0"},
         },
     }
-    server.handle_message(session_id, init_request)
+    server.handle_message(message=init_request, session_id=session_id)
     response = json.loads(server.wait_for_queued_response(session_id))
     assert response["jsonrpc"] == "2.0"
     assert response["id"] == "1"
@@ -326,7 +326,7 @@ def echo(message: str) -> dict[str, str]:
         "method": "tools/call",
         "params": {"name": "echo", "arguments": {"message": "hello"}},
     }
-    server.handle_message(session_id, tool_request)
+    server.handle_message(tool_request, session_id)
     response = json.loads(server.wait_for_queued_response(session_id))
     assert response["jsonrpc"] == "2.0"
     assert response["id"] == "2"
@@ -344,7 +344,7 @@ def echo_str(message: str) -> str:
         "method": "tools/call",
         "params": {"name": "echo_str", "arguments": {"message": "hello"}},
     }
-    server.handle_message(session_id, tool_request)
+    server.handle_message(tool_request, session_id)
     response = json.loads(server.wait_for_queued_response(session_id))
     assert response["jsonrpc"] == "2.0"
     assert response["id"] == "2"
@@ -362,7 +362,7 @@ def echo_dict(message: str) -> dict:
         "method": "tools/call",
         "params": {"name": "echo_dict", "arguments": {"message": "hello"}},
     }
-    server.handle_message(session_id, tool_request)
+    server.handle_message(tool_request, session_id)
     response = json.loads(server.wait_for_queued_response(session_id))
     assert response["jsonrpc"] == "2.0"
     assert response["id"] == "3"
@@ -380,7 +380,7 @@ def echo_result(message: str) -> CallToolResult:
         "method": "tools/call",
         "params": {"name": "echo_result", "arguments": {"message": "hello"}},
     }
-    server.handle_message(session_id, tool_request)
+    server.handle_message(tool_request, session_id)
     response = json.loads(server.wait_for_queued_response(session_id))
     assert response["jsonrpc"] == "2.0"
     assert response["id"] == "4"
@@ -393,7 +393,7 @@ def test_error_handling(server: MCPServer) -> None:
 
     # Test invalid message format
     invalid_message = {"not": "valid"}
-    server.handle_message(session_id, invalid_message)
+    server.handle_message(invalid_message, session_id)
     response = json.loads(server.wait_for_queued_response(session_id))
     assert response["error"]["code"] == -32600  # Invalid Request
 
@@ -404,7 +404,7 @@ def test_error_handling(server: MCPServer) -> None:
         "method": "unknown",
         "params": {},
     }
-    server.handle_message(session_id, unknown_method)
+    server.handle_message(unknown_method, session_id)
     response = json.loads(server.wait_for_queued_response(session_id))
     assert response["error"]["code"] == -32601  # Method not found
 
@@ -415,7 +415,7 @@ def test_error_handling(server: MCPServer) -> None:
         "method": "tools/call",
         "params": {"name": "nonexistent", "arguments": {}},
     }
-    server.handle_message(session_id, invalid_tool)
+    server.handle_message(invalid_tool, session_id)
     response = json.loads(server.wait_for_queued_response(session_id))
     assert response["error"]["code"] == -32601  # Method not found
 
@@ -431,7 +431,7 @@ def test_tool(message: str) -> None:
         "method": "tools/call",
         "params": {"name": "test_tool", "arguments": {"wrong_arg": "value"}},
     }
-    server.handle_message(session_id, invalid_args)
+    server.handle_message(invalid_args, session_id)
     response = json.loads(server.wait_for_queued_response(session_id))
     assert response["error"]["code"] == -32602  # Invalid params