Merge branch 'main' into mime-type-validation-1756

Author: sighthon

CONTRIBUTING.md

@@ -2,6 +2,43 @@
 
 Thank you for your interest in contributing to the MCP Python SDK! This document provides guidelines and instructions for contributing.
 
+## Before You Start
+
+We welcome contributions! These guidelines exist to save everyone time, yours included. Following them means your work is more likely to be accepted.
+
+**All pull requests require a corresponding issue.** Unless your change is trivial (typo, docs tweak, broken link), create an issue first. Every merged feature becomes ongoing maintenance, so we need to agree something is worth doing before reviewing code. PRs without a linked issue will be closed.
+
+Having an issue doesn't guarantee acceptance. Wait for maintainer feedback or a `ready for work` label before starting. PRs for issues without buy-in may also be closed.
+
+Use issues to validate your idea before investing time in code. PRs are for execution, not exploration.
+
+### The SDK is Opinionated
+
+Not every contribution will be accepted, even with a working implementation. We prioritize maintainability and consistency over adding capabilities. This is at maintainers' discretion.
+
+### What Needs Discussion
+
+These always require an issue first:
+
+- New public APIs or decorators
+- Architectural changes or refactoring
+- Changes that touch multiple modules
+- Features that might require spec changes (these need a [SEP](https://github.com/modelcontextprotocol/modelcontextprotocol) first)
+
+Bug fixes for clear, reproducible issues are welcome—but still create an issue to track the fix.
+
+### Finding Issues to Work On
+
+| Label | For | Description |
+|-------|-----|-------------|
+| [`good first issue`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) | Newcomers | Can tackle without deep codebase knowledge |
+| [`help wanted`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) | Experienced contributors | Maintainers probably won't get to this |
+| [`ready for work`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22ready+for+work%22) | Maintainers | Triaged and ready for a maintainer to pick up |
+
+Issues labeled `needs confirmation` or `needs maintainer action` are **not** ready for work—wait for maintainer input first.
+
+Before starting, comment on the issue so we can assign it to you. This prevents duplicate effort.
+
 ## Development Setup
 
 1. Make sure you have Python 3.10+ installed
@@ -76,13 +113,29 @@ pre-commit run --all-files
 - Add type hints to all functions
 - Include docstrings for public APIs
 
-## Pull Request Process
+## Pull Requests
+
+By the time you open a PR, the "what" and "why" should already be settled in an issue. This keeps reviews focused on implementation.
+
+### Scope
+
+Small PRs get reviewed fast. Large PRs sit in the queue.
+
+A few dozen lines can be reviewed in minutes. Hundreds of lines across many files takes real effort and things slip through. If your change is big, break it into smaller PRs or get alignment from a maintainer first.
+
+### What Gets Rejected
+
+- **No prior discussion**: Features or significant changes without an approved issue
+- **Scope creep**: Changes that go beyond what was discussed
+- **Misalignment**: Even well-implemented features may be rejected if they don't fit the SDK's direction
+- **Overengineering**: Unnecessary complexity for simple problems
+
+### Checklist
 
 1. Update documentation as needed
 2. Add tests for new functionality
 3. Ensure CI passes
-4. Maintainers will review your code
-5. Address review feedback
+4. Address review feedback
 
 ## Code of Conduct
 

src/mcp/server/streamable_http_manager.py

@@ -22,6 +22,7 @@
     StreamableHTTPServerTransport,
 )
 from mcp.server.transport_security import TransportSecuritySettings
+from mcp.types import INVALID_REQUEST, ErrorData, JSONRPCError
 
 logger = logging.getLogger(__name__)
 
@@ -276,10 +277,21 @@ async def run_server(*, task_status: TaskStatus[None] = anyio.TASK_STATUS_IGNORE
 
                 # Handle the HTTP request and return the response
                 await http_transport.handle_request(scope, receive, send)
-        else:  # pragma: no cover
-            # Invalid session ID
+        else:
+            # Unknown or expired session ID - return 404 per MCP spec
+            # TODO: Align error code once spec clarifies
+            # See: https://github.com/modelcontextprotocol/python-sdk/issues/1821
+            error_response = JSONRPCError(
+                jsonrpc="2.0",
+                id="server-error",
+                error=ErrorData(
+                    code=INVALID_REQUEST,
+                    message="Session not found",
+                ),
+            )
             response = Response(
-                "Bad Request: No valid session ID provided",
-                status_code=HTTPStatus.BAD_REQUEST,
+                content=error_response.model_dump_json(by_alias=True, exclude_none=True),
+                status_code=HTTPStatus.NOT_FOUND,
+                media_type="application/json",
             )
             await response(scope, receive, send)

tests/server/test_streamable_http_manager.py

@@ -1,5 +1,6 @@
 """Tests for StreamableHTTPSessionManager."""
 
+import json
 from typing import Any
 from unittest.mock import AsyncMock, patch
 
@@ -11,6 +12,7 @@
 from mcp.server.lowlevel import Server
 from mcp.server.streamable_http import MCP_SESSION_ID_HEADER, StreamableHTTPServerTransport
 from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+from mcp.types import INVALID_REQUEST
 
 
 @pytest.mark.anyio
@@ -262,3 +264,52 @@ async def mock_receive():
 
             # Verify internal state is cleaned up
             assert len(transport._request_streams) == 0, "Transport should have no active request streams"
+
+
+@pytest.mark.anyio
+async def test_unknown_session_id_returns_404():
+    """Test that requests with unknown session IDs return HTTP 404 per MCP spec."""
+    app = Server("test-unknown-session")
+    manager = StreamableHTTPSessionManager(app=app)
+
+    async with manager.run():
+        sent_messages: list[Message] = []
+        response_body = b""
+
+        async def mock_send(message: Message):
+            nonlocal response_body
+            sent_messages.append(message)
+            if message["type"] == "http.response.body":
+                response_body += message.get("body", b"")
+
+        # Request with a non-existent session ID
+        scope = {
+            "type": "http",
+            "method": "POST",
+            "path": "/mcp",
+            "headers": [
+                (b"content-type", b"application/json"),
+                (b"accept", b"application/json, text/event-stream"),
+                (b"mcp-session-id", b"non-existent-session-id"),
+            ],
+        }
+
+        async def mock_receive():
+            return {"type": "http.request", "body": b"{}", "more_body": False}  # pragma: no cover
+
+        await manager.handle_request(scope, mock_receive, mock_send)
+
+        # Find the response start message
+        response_start = next(
+            (msg for msg in sent_messages if msg["type"] == "http.response.start"),
+            None,
+        )
+        assert response_start is not None, "Should have sent a response"
+        assert response_start["status"] == 404, "Should return HTTP 404 for unknown session ID"
+
+        # Verify JSON-RPC error format
+        error_data = json.loads(response_body)
+        assert error_data["jsonrpc"] == "2.0"
+        assert error_data["id"] == "server-error"
+        assert error_data["error"]["code"] == INVALID_REQUEST
+        assert error_data["error"]["message"] == "Session not found"