refactor: make context required at internal layers, optional at MCPServer

Addresses review feedback asking when Context could be None. The answer:
only via direct calls (tests, programmatic use). Rather than guard at
the leaf layers, make the internal layers type-honest.

- MCPServer.call_tool/read_resource/get_prompt: keep context optional,
  auto-construct Context(mcp_server=self) when None (restores the
  behavior get_context() used to provide)
- ToolManager/Tool, PromptManager/Prompt, ResourceManager/ResourceTemplate:
  context is now required — type signature matches production reality
  where _handle_* always provides it
- Guards removed from Tool.run/Prompt.render/ResourceTemplate.create_resource;
  no longer reachable since context is required
- Prompt.render and PromptManager.render_prompt: arguments parameter no
  longer has a default (both arguments and context are now required positional)
- Added TODO noting Context constructor nullability is vestigial (follow-up)

Author: maxisbey

docs/migration.md

@@ -315,9 +315,9 @@ async def my_tool(x: int, ctx: Context) -> str:
 
 ### `MCPServer.call_tool()`, `read_resource()`, `get_prompt()` now accept a `context` parameter
 
-`MCPServer.call_tool()`, `MCPServer.read_resource()`, and `MCPServer.get_prompt()` now accept an optional `context: Context | None = None` parameter. The framework passes this automatically during normal request handling — you only need to supply it when calling these methods directly.
+`MCPServer.call_tool()`, `MCPServer.read_resource()`, and `MCPServer.get_prompt()` now accept an optional `context: Context | None = None` parameter. The framework passes this automatically during normal request handling. If you call these methods directly and omit `context`, a Context with no active request is constructed for you — tools that don't use `ctx` work normally, but any attempt to use `ctx.session`, `ctx.request_id`, etc. will raise.
 
-If the tool, resource template, or prompt you're invoking declares a `ctx: Context` parameter, you must pass a `Context`. Calling without one raises `ToolError` for tools or `ValueError` for prompts and resource templates.
+The internal layers (`ToolManager.call_tool`, `Tool.run`, `Prompt.render`, `ResourceTemplate.create_resource`, etc.) now require `context` as a positional argument.
 
 ### Replace `RootModel` by union types with `TypeAdapter` validation
 

src/mcp/server/mcpserver/context.py

@@ -58,6 +58,7 @@ async def my_tool(x: int, ctx: Context) -> str:
     _request_context: ServerRequestContext[LifespanContextT, RequestT] | None
     _mcp_server: MCPServer | None
 
+    # TODO(maxisbey): Consider making request_context/mcp_server required, or refactor Context entirely.
     def __init__(
         self,
         *,

src/mcp/server/mcpserver/prompts/base.py

@@ -135,17 +135,14 @@ def from_function(
 
     async def render(
         self,
-        arguments: dict[str, Any] | None = None,
-        context: Context[LifespanContextT, RequestT] | None = None,
+        arguments: dict[str, Any] | None,
+        context: Context[LifespanContextT, RequestT],
     ) -> list[Message]:
         """Render the prompt with arguments.
 
         Raises:
-            ValueError: If the prompt requires a Context but none was provided,
-                if required arguments are missing, or if rendering fails.
+            ValueError: If required arguments are missing, or if rendering fails.
         """
-        if self.context_kwarg is not None and context is None:
-            raise ValueError(f"Prompt {self.name!r} requires a Context, but none was provided")
         # Validate required arguments
         if self.arguments:
             required = {arg.name for arg in self.arguments if arg.required}

src/mcp/server/mcpserver/prompts/manager.py

@@ -48,12 +48,12 @@ def add_prompt(
     async def render_prompt(
         self,
         name: str,
-        arguments: dict[str, Any] | None = None,
-        context: Context[LifespanContextT, RequestT] | None = None,
+        arguments: dict[str, Any] | None,
+        context: Context[LifespanContextT, RequestT],
     ) -> list[Message]:
         """Render a prompt by name with arguments."""
         prompt = self.get_prompt(name)
         if not prompt:
             raise ValueError(f"Unknown prompt: {name}")
 
-        return await prompt.render(arguments, context=context)
+        return await prompt.render(arguments, context)

src/mcp/server/mcpserver/resources/resource_manager.py

@@ -80,9 +80,7 @@ def add_template(
         self._templates[template.uri_template] = template
         return template
 
-    async def get_resource(
-        self, uri: AnyUrl | str, context: Context[LifespanContextT, RequestT] | None = None
-    ) -> Resource:
+    async def get_resource(self, uri: AnyUrl | str, context: Context[LifespanContextT, RequestT]) -> Resource:
         """Get resource by URI, checking concrete resources first, then templates."""
         uri_str = str(uri)
         logger.debug("Getting resource", extra={"uri": uri_str})

src/mcp/server/mcpserver/resources/templates.py

@@ -99,16 +99,13 @@ async def create_resource(
         self,
         uri: str,
         params: dict[str, Any],
-        context: Context[LifespanContextT, RequestT] | None = None,
+        context: Context[LifespanContextT, RequestT],
     ) -> Resource:
         """Create a resource from the template with the given parameters.
 
         Raises:
-            ValueError: If the template requires a Context but none was provided,
-                or if creating the resource fails.
+            ValueError: If creating the resource fails.
         """
-        if self.context_kwarg is not None and context is None:
-            raise ValueError(f"Resource template {self.name!r} requires a Context, but none was provided")
         try:
             # Add context to params if needed
             params = inject_context(self.fn, params, context, self.context_kwarg)

src/mcp/server/mcpserver/server.py

@@ -392,7 +392,9 @@ async def call_tool(
         self, name: str, arguments: dict[str, Any], context: Context[LifespanResultT, Any] | None = None
     ) -> Sequence[ContentBlock] | dict[str, Any]:
         """Call a tool by name with arguments."""
-        return await self._tool_manager.call_tool(name, arguments, context=context, convert_result=True)
+        if context is None:
+            context = Context(mcp_server=self)
+        return await self._tool_manager.call_tool(name, arguments, context, convert_result=True)
 
     async def list_resources(self) -> list[MCPResource]:
         """List all available resources."""
@@ -432,8 +434,10 @@ async def read_resource(
         self, uri: AnyUrl | str, context: Context[LifespanResultT, Any] | None = None
     ) -> Iterable[ReadResourceContents]:
         """Read a resource by URI."""
+        if context is None:
+            context = Context(mcp_server=self)
         try:
-            resource = await self._resource_manager.get_resource(uri, context=context)
+            resource = await self._resource_manager.get_resource(uri, context)
         except ValueError:
             raise ResourceError(f"Unknown resource: {uri}")
 
@@ -1081,12 +1085,14 @@ async def get_prompt(
         self, name: str, arguments: dict[str, Any] | None = None, context: Context[LifespanResultT, Any] | None = None
     ) -> GetPromptResult:
         """Get a prompt by name with arguments."""
+        if context is None:
+            context = Context(mcp_server=self)
         try:
             prompt = self._prompt_manager.get_prompt(name)
             if not prompt:
                 raise ValueError(f"Unknown prompt: {name}")
 
-            messages = await prompt.render(arguments, context=context)
+            messages = await prompt.render(arguments, context)
 
             return GetPromptResult(
                 description=prompt.description,

src/mcp/server/mcpserver/tools/base.py

@@ -92,17 +92,14 @@ def from_function(
     async def run(
         self,
         arguments: dict[str, Any],
-        context: Context[LifespanContextT, RequestT] | None = None,
+        context: Context[LifespanContextT, RequestT],
         convert_result: bool = False,
     ) -> Any:
         """Run the tool with arguments.
 
         Raises:
-            ToolError: If the tool requires a Context but none was provided,
-                or if the tool function raises during execution.
+            ToolError: If the tool function raises during execution.
         """
-        if self.context_kwarg is not None and context is None:
-            raise ToolError(f"Tool {self.name!r} requires a Context, but none was provided")
         try:
             result = await self.fn_metadata.call_fn_with_arg_validation(
                 self.fn,

src/mcp/server/mcpserver/tools/tool_manager.py

@@ -81,12 +81,12 @@ async def call_tool(
         self,
         name: str,
         arguments: dict[str, Any],
-        context: Context[LifespanContextT, RequestT] | None = None,
+        context: Context[LifespanContextT, RequestT],
         convert_result: bool = False,
     ) -> Any:
         """Call a tool by name with arguments."""
         tool = self.get_tool(name)
         if not tool:
             raise ToolError(f"Unknown tool: {name}")
 
-        return await tool.run(arguments, context=context, convert_result=convert_result)
+        return await tool.run(arguments, context, convert_result=convert_result)

tests/server/mcpserver/prompts/test_base.py

@@ -14,23 +14,27 @@ def fn() -> str:
             return "Hello, world!"
 
         prompt = Prompt.from_function(fn)
-        assert await prompt.render() == [UserMessage(content=TextContent(type="text", text="Hello, world!"))]
+        assert await prompt.render(None, Context()) == [
+            UserMessage(content=TextContent(type="text", text="Hello, world!"))
+        ]
 
     @pytest.mark.anyio
     async def test_async_fn(self):
         async def fn() -> str:
             return "Hello, world!"
 
         prompt = Prompt.from_function(fn)
-        assert await prompt.render() == [UserMessage(content=TextContent(type="text", text="Hello, world!"))]
+        assert await prompt.render(None, Context()) == [
+            UserMessage(content=TextContent(type="text", text="Hello, world!"))
+        ]
 
     @pytest.mark.anyio
     async def test_fn_with_args(self):
         async def fn(name: str, age: int = 30) -> str:
             return f"Hello, {name}! You're {age} years old."
 
         prompt = Prompt.from_function(fn)
-        assert await prompt.render(arguments={"name": "World"}) == [
+        assert await prompt.render({"name": "World"}, Context()) == [
             UserMessage(content=TextContent(type="text", text="Hello, World! You're 30 years old."))
         ]
 
@@ -41,23 +45,27 @@ async def fn(name: str, age: int = 30) -> str:  # pragma: no cover
 
         prompt = Prompt.from_function(fn)
         with pytest.raises(ValueError):
-            await prompt.render(arguments={"age": 40})
+            await prompt.render({"age": 40}, Context())
 
     @pytest.mark.anyio
     async def test_fn_returns_message(self):
         async def fn() -> UserMessage:
             return UserMessage(content="Hello, world!")
 
         prompt = Prompt.from_function(fn)
-        assert await prompt.render() == [UserMessage(content=TextContent(type="text", text="Hello, world!"))]
+        assert await prompt.render(None, Context()) == [
+            UserMessage(content=TextContent(type="text", text="Hello, world!"))
+        ]
 
     @pytest.mark.anyio
     async def test_fn_returns_assistant_message(self):
         async def fn() -> AssistantMessage:
             return AssistantMessage(content=TextContent(type="text", text="Hello, world!"))
 
         prompt = Prompt.from_function(fn)
-        assert await prompt.render() == [AssistantMessage(content=TextContent(type="text", text="Hello, world!"))]
+        assert await prompt.render(None, Context()) == [
+            AssistantMessage(content=TextContent(type="text", text="Hello, world!"))
+        ]
 
     @pytest.mark.anyio
     async def test_fn_returns_multiple_messages(self):
@@ -71,7 +79,7 @@ async def fn() -> list[Message]:
             return expected
 
         prompt = Prompt.from_function(fn)
-        assert await prompt.render() == expected
+        assert await prompt.render(None, Context()) == expected
 
     @pytest.mark.anyio
     async def test_fn_returns_list_of_strings(self):
@@ -84,7 +92,7 @@ async def fn() -> list[str]:
             return expected
 
         prompt = Prompt.from_function(fn)
-        assert await prompt.render() == [UserMessage(t) for t in expected]
+        assert await prompt.render(None, Context()) == [UserMessage(t) for t in expected]
 
     @pytest.mark.anyio
     async def test_fn_returns_resource_content(self):
@@ -103,7 +111,7 @@ async def fn() -> UserMessage:
             )
 
         prompt = Prompt.from_function(fn)
-        assert await prompt.render() == [
+        assert await prompt.render(None, Context()) == [
             UserMessage(
                 content=EmbeddedResource(
                     type="resource",
@@ -137,7 +145,7 @@ async def fn() -> list[Message]:
             ]
 
         prompt = Prompt.from_function(fn)
-        assert await prompt.render() == [
+        assert await prompt.render(None, Context()) == [
             UserMessage(content=TextContent(type="text", text="Please analyze this file:")),
             UserMessage(
                 content=EmbeddedResource(
@@ -170,7 +178,7 @@ async def fn() -> dict[str, Any]:
             }
 
         prompt = Prompt.from_function(fn)
-        assert await prompt.render() == [
+        assert await prompt.render(None, Context()) == [
             UserMessage(
                 content=EmbeddedResource(
                     type="resource",
@@ -182,13 +190,3 @@ async def fn() -> dict[str, Any]:
                 )
             )
         ]
-
-
-@pytest.mark.anyio
-async def test_render_raises_when_context_required_but_not_provided():
-    def fn(name: str, ctx: Context) -> str:
-        raise NotImplementedError
-
-    prompt = Prompt.from_function(fn)
-    with pytest.raises(ValueError, match="requires a Context"):
-        await prompt.render({"name": "world"})