feat: Pass CallContext (with Request data) to MCP Tool invocation

src/Context.php

@@ -0,0 +1,15 @@
+<?php declare(strict_types = 1);
+namespace PhpMcp\Server;
+
+use PhpMcp\Server\Contracts\SessionInterface;
+use Psr\Http\Message\ServerRequestInterface;
+
+final class Context
+{
+    public function __construct(
+        public readonly ?ServerRequestInterface $request,
+        public readonly SessionInterface $session
+    )
+    {
+    }
+}

src/Dispatcher.php

@@ -61,7 +61,7 @@ public function __construct(
         $this->schemaValidator ??= new SchemaValidator($this->logger);
     }
 
-    public function handleRequest(Request $request, SessionInterface $session): Result
+    public function handleRequest(Request $request, SessionInterface $session, Context $requestContext): Result
     {
         switch ($request->method) {
             case 'initialize':
@@ -75,7 +75,7 @@ public function handleRequest(Request $request, SessionInterface $session): Resu
                 return $this->handleToolList($request);
             case 'tools/call':
                 $request = CallToolRequest::fromRequest($request);
-                return $this->handleToolCall($request);
+                return $this->handleToolCall($request, $requestContext);
             case 'resources/list':
                 $request = ListResourcesRequest::fromRequest($request);
                 return $this->handleResourcesList($request);
@@ -84,7 +84,7 @@ public function handleRequest(Request $request, SessionInterface $session): Resu
                 return $this->handleResourceTemplateList($request);
             case 'resources/read':
                 $request = ReadResourceRequest::fromRequest($request);
-                return $this->handleResourceRead($request);
+                return $this->handleResourceRead($request, $requestContext);
             case 'resources/subscribe':
                 $request = ResourceSubscribeRequest::fromRequest($request);
                 return $this->handleResourceSubscribe($request, $session);
@@ -96,7 +96,7 @@ public function handleRequest(Request $request, SessionInterface $session): Resu
                 return $this->handlePromptsList($request);
             case 'prompts/get':
                 $request = GetPromptRequest::fromRequest($request);
-                return $this->handlePromptGet($request);
+                return $this->handlePromptGet($request, $requestContext);
             case 'logging/setLevel':
                 $request = SetLogLevelRequest::fromRequest($request);
                 return $this->handleLoggingSetLevel($request, $session);
@@ -151,7 +151,7 @@ public function handleToolList(ListToolsRequest $request): ListToolsResult
         return new ListToolsResult(array_values($pagedItems), $nextCursor);
     }
 
-    public function handleToolCall(CallToolRequest $request): CallToolResult
+    public function handleToolCall(CallToolRequest $request, Context $requestContext): CallToolResult
     {
         $toolName = $request->name;
         $arguments = $request->arguments;
@@ -184,7 +184,7 @@ public function handleToolCall(CallToolRequest $request): CallToolResult
         }
 
         try {
-            $result = $registeredTool->call($this->container, $arguments);
+            $result = $registeredTool->call($this->container, $arguments, $requestContext);
 
             return new CallToolResult($result, false);
         } catch (JsonException $e) {
@@ -222,7 +222,7 @@ public function handleResourceTemplateList(ListResourceTemplatesRequest $request
         return new ListResourceTemplatesResult(array_values($pagedItems), $nextCursor);
     }
 
-    public function handleResourceRead(ReadResourceRequest $request): ReadResourceResult
+    public function handleResourceRead(ReadResourceRequest $request, Context $requestContext): ReadResourceResult
     {
         $uri = $request->uri;
 
@@ -233,7 +233,7 @@ public function handleResourceRead(ReadResourceRequest $request): ReadResourceRe
         }
 
         try {
-            $result = $registeredResource->read($this->container, $uri);
+            $result = $registeredResource->read($this->container, $uri, $requestContext);
 
             return new ReadResourceResult($result);
         } catch (JsonException $e) {
@@ -270,7 +270,7 @@ public function handlePromptsList(ListPromptsRequest $request): ListPromptsResul
         return new ListPromptsResult(array_values($pagedItems), $nextCursor);
     }
 
-    public function handlePromptGet(GetPromptRequest $request): GetPromptResult
+    public function handlePromptGet(GetPromptRequest $request, Context $requestContext): GetPromptResult
     {
         $promptName = $request->name;
         $arguments = $request->arguments;
@@ -289,7 +289,7 @@ public function handlePromptGet(GetPromptRequest $request): GetPromptResult
         }
 
         try {
-            $result = $registeredPrompt->get($this->container, $arguments);
+            $result = $registeredPrompt->get($this->container, $arguments, $requestContext);
 
             return new GetPromptResult($result, $registeredPrompt->schema->description);
         } catch (JsonException $e) {

src/Elements/RegisteredElement.php

@@ -6,6 +6,7 @@
 
 use InvalidArgumentException;
 use JsonSerializable;
+use PhpMcp\Server\Context;
 use PhpMcp\Server\Exception\McpServerException;
 use Psr\Container\ContainerInterface;
 use ReflectionException;
@@ -30,33 +31,33 @@ public function __construct(
         $this->isManual = $isManual;
     }
 
-    public function handle(ContainerInterface $container, array $arguments): mixed
+    public function handle(ContainerInterface $container, array $arguments, ?Context $requestContext = null): mixed
     {
         if (is_string($this->handler)) {
             if (class_exists($this->handler) && method_exists($this->handler, '__invoke')) {
                 $reflection = new \ReflectionMethod($this->handler, '__invoke');
-                $arguments = $this->prepareArguments($reflection, $arguments);
+                $arguments = $this->prepareArguments($reflection, $arguments, $requestContext);
                 $instance = $container->get($this->handler);
                 return call_user_func($instance, ...$arguments);
             }
 
             if (function_exists($this->handler)) {
                 $reflection = new \ReflectionFunction($this->handler);
-                $arguments = $this->prepareArguments($reflection, $arguments);
+                $arguments = $this->prepareArguments($reflection, $arguments, $requestContext);
                 return call_user_func($this->handler, ...$arguments);
             }
         }
 
         if (is_callable($this->handler)) {
             $reflection = $this->getReflectionForCallable($this->handler);
-            $arguments = $this->prepareArguments($reflection, $arguments);
+            $arguments = $this->prepareArguments($reflection, $arguments, $requestContext);
             return call_user_func($this->handler, ...$arguments);
         }
 
         if (is_array($this->handler)) {
             [$className, $methodName] = $this->handler;
             $reflection = new \ReflectionMethod($className, $methodName);
-            $arguments = $this->prepareArguments($reflection, $arguments);
+            $arguments = $this->prepareArguments($reflection, $arguments, $requestContext);
 
             $instance = $container->get($className);
             return call_user_func([$instance, $methodName], ...$arguments);
@@ -66,15 +67,22 @@ public function handle(ContainerInterface $container, array $arguments): mixed
     }
 
 
-    protected function prepareArguments(\ReflectionFunctionAbstract $reflection, array $arguments): array
+    protected function prepareArguments(\ReflectionFunctionAbstract $reflection, array $arguments, ?Context $requestContext): array
     {
         $finalArgs = [];
 
         foreach ($reflection->getParameters() as $parameter) {
             // TODO: Handle variadic parameters.
             $paramName = $parameter->getName();
+            $paramType = $parameter->getType();
             $paramPosition = $parameter->getPosition();
 
+            if ($paramType?->getName() === Context::class) {
+                $finalArgs[$paramPosition] = $requestContext;
+
+                continue;
+            }
+
             if (isset($arguments[$paramName])) {
                 $argument = $arguments[$paramName];
                 try {

src/Elements/RegisteredPrompt.php

@@ -15,6 +15,7 @@
 use PhpMcp\Schema\Content\TextResourceContents;
 use PhpMcp\Schema\Enum\Role;
 use PhpMcp\Schema\Result\CompletionCompleteResult;
+use PhpMcp\Server\Context;
 use PhpMcp\Server\Contracts\CompletionProviderInterface;
 use PhpMcp\Server\Contracts\SessionInterface;
 use Psr\Container\ContainerInterface;
@@ -43,9 +44,9 @@ public static function make(Prompt $schema, callable|array|string $handler, bool
      * @param  array  $arguments
      * @return PromptMessage[]
      */
-    public function get(ContainerInterface $container, array $arguments): array
+    public function get(ContainerInterface $container, array $arguments, Context $requestContext): array
     {
-        $result = $this->handle($container, $arguments);
+        $result = $this->handle($container, $arguments, $requestContext);
 
         return $this->formatResult($result);
     }

src/Elements/RegisteredResource.php

@@ -9,6 +9,7 @@
 use PhpMcp\Schema\Content\ResourceContents;
 use PhpMcp\Schema\Content\TextResourceContents;
 use PhpMcp\Schema\Resource;
+use PhpMcp\Server\Context;
 use Psr\Container\ContainerInterface;
 use Throwable;
 
@@ -32,9 +33,9 @@ public static function make(Resource $schema, callable|array|string $handler, bo
      *
      * @return array<TextResourceContents|BlobResourceContents> Array of ResourceContents objects.
      */
-    public function read(ContainerInterface $container, string $uri): array
+    public function read(ContainerInterface $container, string $uri, Context $requestContext): array
     {
-        $result = $this->handle($container, ['uri' => $uri]);
+        $result = $this->handle($container, ['uri' => $uri], $requestContext);
 
         return $this->formatResult($result, $uri, $this->schema->mimeType);
     }

src/Elements/RegisteredResourceTemplate.php

@@ -10,6 +10,7 @@
 use PhpMcp\Schema\Content\TextResourceContents;
 use PhpMcp\Schema\ResourceTemplate;
 use PhpMcp\Schema\Result\CompletionCompleteResult;
+use PhpMcp\Server\Context;
 use PhpMcp\Server\Contracts\SessionInterface;
 use Psr\Container\ContainerInterface;
 use Throwable;
@@ -41,11 +42,11 @@ public static function make(ResourceTemplate $schema, callable|array|string $han
      *
      * @return array<TextResourceContents|BlobResourceContents> Array of ResourceContents objects.
      */
-    public function read(ContainerInterface $container, string $uri): array
+    public function read(ContainerInterface $container, string $uri, Context $requestContext): array
     {
         $arguments = array_merge($this->uriVariables, ['uri' => $uri]);
 
-        $result = $this->handle($container, $arguments);
+        $result = $this->handle($container, $arguments, $requestContext);
 
         return $this->formatResult($result, $uri, $this->schema->mimeType);
     }

src/Elements/RegisteredTool.php

@@ -6,6 +6,7 @@
 
 use PhpMcp\Schema\Content\Content;
 use PhpMcp\Schema\Content\TextContent;
+use PhpMcp\Server\Context;
 use Psr\Container\ContainerInterface;
 use PhpMcp\Schema\Tool;
 use Throwable;
@@ -30,9 +31,9 @@ public static function make(Tool $schema, callable|array|string $handler, bool $
      *
      * @return Content[] The content items for CallToolResult.
      */
-    public function call(ContainerInterface $container, array $arguments): array
+    public function call(ContainerInterface $container, array $arguments, Context $requestContext): array
     {
-        $result = $this->handle($container, $arguments);
+        $result = $this->handle($container, $arguments, $requestContext);
 
         return $this->formatResult($result);
     }

src/Protocol.php

@@ -140,12 +140,17 @@ public function processMessage(Request|Notification|BatchRequest $message, strin
             $session->set('client_info', ['name' => 'stateless-client', 'version' => '1.0.0']);
         }
 
+        $requestContext = new Context(
+            $context['request'] ?? null,
+            $session,
+        );
+
         $response = null;
 
         if ($message instanceof BatchRequest) {
-            $response = $this->processBatchRequest($message, $session);
+            $response = $this->processBatchRequest($message, $session, $requestContext);
         } elseif ($message instanceof Request) {
-            $response = $this->processRequest($message, $session);
+            $response = $this->processRequest($message, $session, $requestContext);
         } elseif ($message instanceof Notification) {
             $this->processNotification($message, $session);
         }
@@ -168,7 +173,7 @@ public function processMessage(Request|Notification|BatchRequest $message, strin
     /**
      * Process a batch message
      */
-    private function processBatchRequest(BatchRequest $batch, SessionInterface $session): ?BatchResponse
+    private function processBatchRequest(BatchRequest $batch, SessionInterface $session, Context $requestContext): ?BatchResponse
     {
         $items = [];
 
@@ -177,7 +182,7 @@ private function processBatchRequest(BatchRequest $batch, SessionInterface $sess
         }
 
         foreach ($batch->getRequests() as $request) {
-            $items[] = $this->processRequest($request, $session);
+            $items[] = $this->processRequest($request, $session, $requestContext);
         }
 
         return empty($items) ? null : new BatchResponse($items);
@@ -186,7 +191,7 @@ private function processBatchRequest(BatchRequest $batch, SessionInterface $sess
     /**
      * Process a request message
      */
-    private function processRequest(Request $request, SessionInterface $session): Response|Error
+    private function processRequest(Request $request, SessionInterface $session, Context $requestContext): Response|Error
     {
         try {
             if ($request->method !== 'initialize') {
@@ -195,7 +200,7 @@ private function processRequest(Request $request, SessionInterface $session): Re
 
             $this->assertRequestCapability($request->method);
 
-            $result = $this->dispatcher->handleRequest($request, $session);
+            $result = $this->dispatcher->handleRequest($request, $session, $requestContext);
 
             return Response::make($request->id, $result);
         } catch (McpServerException $e) {

src/Transports/StreamableHttpServerTransport.php

@@ -367,6 +367,7 @@ private function handlePostRequest(ServerRequestInterface $request): PromiseInte
         }
 
         $context['stateless'] = $this->stateless;
+        $context['request'] = $request;
 
         $this->loop->futureTick(function () use ($message, $sessionId, $context) {
             $this->emit('message', [$message, $sessionId, $context]);

src/Utils/SchemaGenerator.php

@@ -4,6 +4,7 @@
 
 use phpDocumentor\Reflection\DocBlock\Tags\Param;
 use PhpMcp\Server\Attributes\Schema;
+use PhpMcp\Server\Context;
 use ReflectionEnum;
 use ReflectionIntersectionType;
 use ReflectionMethod;
@@ -417,6 +418,11 @@ private function parseParametersInfo(\ReflectionMethod|\ReflectionFunction $refl
             $paramTag = $paramTags['$' . $paramName] ?? null;
 
             $reflectionType = $rp->getType();
+
+            if ($reflectionType instanceof ReflectionNamedType && $reflectionType?->getName() === Context::class) {
+                continue;
+            }
+
             $typeString = $this->getParameterTypeString($rp, $paramTag);
             $description = $this->docBlockParser->getParamDescription($paramTag);
             $hasDefault = $rp->isDefaultValueAvailable();

tests/Fixtures/General/ToolHandlerFixture.php

@@ -5,6 +5,7 @@
 use PhpMcp\Schema\Content\TextContent;
 use PhpMcp\Schema\Content\ImageContent;
 use PhpMcp\Schema\Content\AudioContent;
+use PhpMcp\Server\Context;
 use PhpMcp\Server\Tests\Fixtures\Enums\BackedStringEnum;
 use Psr\Log\LoggerInterface;
 
@@ -132,4 +133,13 @@ public function toolUnencodableResult()
     {
         return fopen('php://memory', 'r');
     }
+
+    public function toolReadsContext(Context $context): string
+    {
+        if (!$context->request) {
+            return "No request instance present";
+        }
+
+        return $context->request->getHeaderLine('X-Test-Header') ?: "No X-Test-Header";
+    }
 }

tests/Fixtures/ServerScripts/StdioTestServer.php

@@ -29,6 +29,7 @@ public function log($level, \Stringable|string $message, array $context = []): v
         ->withServerInfo('StdioIntegrationTestServer', '0.1.0')
         ->withLogger($logger)
         ->withTool([ToolHandlerFixture::class, 'greet'], 'greet_stdio_tool')
+        ->withTool([ToolHandlerFixture::class, 'toolReadsContext'], 'tool_reads_context') // for Context testing
         ->withResource([ResourceHandlerFixture::class, 'getStaticText'], 'test://stdio/static', 'static_stdio_resource')
         ->withPrompt([PromptHandlerFixture::class, 'generateSimpleGreeting'], 'simple_stdio_prompt')
         ->build();

tests/Fixtures/ServerScripts/StreamableHttpTestServer.php

@@ -40,6 +40,7 @@ public function log($level, \Stringable|string $message, array $context = []): v
         ->withLogger($logger)
         ->withTool([ToolHandlerFixture::class, 'greet'], 'greet_streamable_tool')
         ->withTool([ToolHandlerFixture::class, 'sum'], 'sum_streamable_tool') // For batch testing
+        ->withTool([ToolHandlerFixture::class, 'toolReadsContext'], 'tool_reads_context') // for Context testing
         ->withResource([ResourceHandlerFixture::class, 'getStaticText'], "test://streamable/static", 'static_streamable_resource')
         ->withPrompt([PromptHandlerFixture::class, 'generateSimpleGreeting'], 'simple_streamable_prompt')
         ->build();