readme

Author: CamDavidsonPilon

README.md

@@ -6,32 +6,6 @@ A Python utility package for building Model Context Protocol (MCP) servers.
 
 
 
-## Table of Contents
-
-- [mcp-utils](#mcp-utils)
-  - [Table of Contents](#table-of-contents)
-  - [Overview](#overview)
-  - [Key Features](#key-features)
-  - [Installation](#installation)
-  - [Requirements](#requirements)
-    - [Optional Dependencies](#optional-dependencies)
-  - [Usage](#usage)
-    - [Basic MCP Server](#basic-mcp-server)
-    - [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)
-  - [Contributing](#contributing)
-  - [Related Projects](#related-projects)
-  - [License](#license)
-  - [Testing with MCP Inspector](#testing-with-mcp-inspector)
-    - [Installation](#installation-1)
-    - [Usage](#usage-1)
-
 ## Overview
 
 `mcp-utils` provides utilities and helpers for building MCP-compliant servers in Python, with a focus on synchronous implementations using Flask. This package is designed for developers who want to implement MCP servers in their existing Python applications without the complexity of asynchronous code.
@@ -43,39 +17,37 @@ A Python utility package for building Model Context Protocol (MCP) servers.
 - Simple decorators for MCP endpoints
 - Synchronous implementation
 - HTTP protocol support
-- Redis response queue
-- Comprehensive Pydantic models for MCP schema
+- SQLite response queue
+- Comprehensive msgspec models for MCP schema
 - Built-in validation and documentation
 
 ## Installation
 
-```bash
-pip install mcp-utils
-```
+Install from this repo
 
 ## Requirements
 
 - Python 3.10+
-- Pydantic 2
+- msgspec >= 0.18
 
 ### Optional Dependencies
 
 - Flask (for web server)
-- Gunicorn (for production deployment)
-- Redis (for response queue)
+
 
 ## Usage
 
 ### Basic MCP Server
 
-Here's a simple example of creating an MCP server:
+Here's a simple example of creating an MCP server (using the built-in SQLite queue):
 
 ```python
 from mcp_utils.core import MCPServer
+from mcp_utils.queue import SQLiteResponseQueue
 from mcp_utils.schema import GetPromptResult, Message, TextContent, CallToolResult
 
-# Create a basic MCP server
-mcp = MCPServer("example", "1.0")
+# Create a basic MCP server with SQLite-backed queue
+mcp = MCPServer("example", "1.0", response_queue=SQLiteResponseQueue("responses.db"))
 
 @mcp.prompt()
 def get_weather_prompt(city: str) -> GetPromptResult:
@@ -104,55 +76,20 @@ from version 2025-06-18.
 
 
 ```python
-from flask import Flask, Response, url_for, request
+from flask import Flask, jsonify, request
+import msgspec
+from mcp_utils.core import MCPServer
+from mcp_utils.queue import SQLiteResponseQueue
 
-# Create Flask app and MCP server with Redis queue
+# Create Flask app and MCP server with SQLite-backed queue
 app = Flask(__name__)
-mcp = MCPServer(
-    "example",
-    "1.0",
-)
+mcp = MCPServer("example", "1.0", response_queue=SQLiteResponseQueue("responses.db"))
 
 @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__":
-    app.run(debug=True)
-```
-
-### SQLAlchemy Transaction Handling Example
-
-For production use, you can integrate the MCP server with Flask, Redis, and SQLAlchemy for better message handling and database transaction management:
-
-```python
-from flask import Flask, request
-from sqlalchemy.orm import Session
-from sqlalchemy import create_engine
-
-# Create engine for PostgreSQL database
-engine = create_engine("postgresql://user:pass@localhost/dbname")
-
-# Create Flask app and MCP server with Redis queue
-app = Flask(__name__)
-mcp = MCPServer(
-    "example",
-    "1.0",
-)
-
-@app.route("/mcp", methods=["POST"])
-def mcp_route():
-    with Session(engine) as session:
-        try:
-            response = mcp.handle_message(request.get_json())
-            session.commit()
-        except:
-            session.rollback()
-            raise
-        else:
-            return jsonify(response.model_dump(exclude_none=True))
+    # Convert msgspec Struct to builtin types for jsonify
+    return jsonify(msgspec.to_builtins(response))
 
 
 if __name__ == "__main__":
@@ -201,69 +138,13 @@ if __name__ == "__main__":
     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
-
-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:
-
-```json
-{
-  "mcpServers": {
-    "weather": {
-      "command": "/Users/yourname/.local/bin/mcp-proxy",
-      "args": ["http://127.0.0.1:9000/sse"]
-    }
-  }
-}
-```
-
-#### Installing via Smithery
-
-To install MCP Proxy for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-proxy):
-
-```bash
-npx -y @smithery/cli install mcp-proxy --client claude
-```
-
-#### Installing via PyPI
-
-The stable version of the package is available on the PyPI repository. You can install it using the following command:
-
-```bash
-# Option 1: With uv (recommended)
-uv tool install mcp-proxy
-
-# Option 2: With pipx (alternative)
-pipx install mcp-proxy
-```
-
-Once installed, you can run the server using the `mcp-proxy` command.
-
-## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## Related Projects
 
 - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - The official async Python SDK for MCP
 - [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) - A proxy tool to connect Claude Desktop with MCP servers
+- [mcp-utils](https://github.com/fulfilio/mcp-utils) -  Original version with Pydantic support
 
 ## License
 

examples/flask_app.py

@@ -1,25 +1,26 @@
 """
 Example Flask application implementing an MCP server.
 
-`pip install mcp-utils flask gunicorn redis`
+`pip install mcp-utils flask gunicorn`
 
-* Needs Redis to be running
-* Needs Gunicorn to be installed
-
-In addition to the requirements for the simple example, this example also:
+This example also:
 
 * Demonstrates logging setup
 * Demonstrates session management
 * Demonstrates SSE stream handling
+
+Uses the built-in SQLite-backed response queue.
 """
 
 import logging
 import sys
 
 from flask import Flask, jsonify, request
+import msgspec
 from gunicorn.app.base import BaseApplication
 
 from mcp_utils.core import MCPServer
+from mcp_utils.queue import SQLiteResponseQueue
 from mcp_utils.schema import (
     CallToolResult,
     CompletionValues,
@@ -29,14 +30,14 @@
 )
 
 app = Flask(__name__)
-mcp = MCPServer("weather", "1.0")
+mcp = MCPServer("weather", "1.0", response_queue=SQLiteResponseQueue("responses.db"))
 
 logger = logging.getLogger("mcp_utils")
 logger.setLevel(logging.DEBUG)
 
 
 @mcp.tool()
-def get_weather(city: str) -> CallToolResult:
+def get_weather(city: str) -> str:
     return "sunny"
 
 
@@ -80,7 +81,8 @@ def get_cities(city_name: str) -> CompletionValues:
 @app.route("/mcp", methods=["POST"])
 def mcp_route():
     response = mcp.handle_message(request.get_json())
-    return jsonify(response.model_dump(exclude_none=True))
+    # Convert msgspec Struct to builtin types for jsonify
+    return jsonify(msgspec.to_builtins(response))
 
 
 class FlaskApplication(BaseApplication):

src/mcp_utils/core.py

@@ -509,17 +509,6 @@ def handle_message(
     def _handle_message(
         self, message: dict, session_id: str | None = None
     ) -> MCPResponse | None:
-        try:
-            message_id = message["id"]
-        except KeyError:
-            return MCPResponse(
-                jsonrpc="2.0",
-                id=0,
-                error=ErrorResponse(
-                    code=-32600,
-                    message="Missing message id",
-                ),
-            )
         try:
             mcp_request = msgspec.convert({**message}, MCPRequest)
         except Exception as e:
@@ -556,6 +545,7 @@ def _handle_message(
         if handler := handlers.get(mcp_request.method):
             return handler(mcp_request)
         else:
+            message_id = message["id"]
             return MCPResponse(
                 jsonrpc="2.0",
                 id=message_id,

tests/test_core.py

@@ -470,3 +470,19 @@ def test_pagination_helper() -> None:
     page_items, next_page = get_page_of_items(items, page=0, page_size=3)
     assert page_items == []
     assert next_page == "1"
+
+
+def test_notifications_initialized_is_ignored(server: MCPServer) -> None:
+    """Server ignores `notifications/initialized` and queues no response."""
+    session_id = server.generate_session_id()
+    message = {
+        "jsonrpc": "2.0",
+        "id": "init-1",
+        "method": "notifications/initialized",
+        "params": None,
+    }
+
+    rv = server.handle_message(message, session_id=session_id)
+    assert rv is None
+    # No response should be queued for notifications
+    assert server.wait_for_queued_response(session_id, timeout=0.1) is None