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 SessionInterface $session,
+        public readonly ?ServerRequestInterface $request = null,
+    )
+    {
+    }
+}

src/Dispatcher.php

@@ -61,12 +61,12 @@ public function __construct(
         $this->schemaValidator ??= new SchemaValidator($this->logger);
     }
 
-    public function handleRequest(Request $request, SessionInterface $session): Result
+    public function handleRequest(Request $request, Context $context): Result
     {
         switch ($request->method) {
             case 'initialize':
                 $request = InitializeRequest::fromRequest($request);
-                return $this->handleInitialize($request, $session);
+                return $this->handleInitialize($request, $context->session);
             case 'ping':
                 $request = PingRequest::fromRequest($request);
                 return $this->handlePing($request);
@@ -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, $context);
             case 'resources/list':
                 $request = ListResourcesRequest::fromRequest($request);
                 return $this->handleResourcesList($request);
@@ -84,25 +84,25 @@ 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, $context);
             case 'resources/subscribe':
                 $request = ResourceSubscribeRequest::fromRequest($request);
-                return $this->handleResourceSubscribe($request, $session);
+                return $this->handleResourceSubscribe($request, $context->session);
             case 'resources/unsubscribe':
                 $request = ResourceUnsubscribeRequest::fromRequest($request);
-                return $this->handleResourceUnsubscribe($request, $session);
+                return $this->handleResourceUnsubscribe($request, $context->session);
             case 'prompts/list':
                 $request = ListPromptsRequest::fromRequest($request);
                 return $this->handlePromptsList($request);
             case 'prompts/get':
                 $request = GetPromptRequest::fromRequest($request);
-                return $this->handlePromptGet($request);
+                return $this->handlePromptGet($request, $context);
             case 'logging/setLevel':
                 $request = SetLogLevelRequest::fromRequest($request);
-                return $this->handleLoggingSetLevel($request, $session);
+                return $this->handleLoggingSetLevel($request, $context->session);
             case 'completion/complete':
                 $request = CompletionCompleteRequest::fromRequest($request);
-                return $this->handleCompletionComplete($request, $session);
+                return $this->handleCompletionComplete($request, $context->session);
             default:
                 throw McpServerException::methodNotFound("Method '{$request->method}' not found.");
         }
@@ -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 $context): 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, $context);
 
             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 $context): 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, $context);
 
             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 $context): 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, $context);
 
             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 $context): 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, $context);
                 $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, $context);
                 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, $context);
             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, $context);
 
             $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 $context): array
     {
         $finalArgs = [];
 
         foreach ($reflection->getParameters() as $parameter) {
             // TODO: Handle variadic parameters.
             $paramName = $parameter->getName();
+            $paramType = $parameter->getType();
             $paramPosition = $parameter->getPosition();
 
+            if ($paramType instanceof ReflectionNamedType && $paramType->getName() === Context::class) {
+                $finalArgs[$paramPosition] = $context;
+
+                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 $context): array
     {
-        $result = $this->handle($container, $arguments);
+        $result = $this->handle($container, $arguments, $context);
 
         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 $context): array
     {
-        $result = $this->handle($container, ['uri' => $uri]);
+        $result = $this->handle($container, ['uri' => $uri], $context);
 
         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 $context): array
     {
         $arguments = array_merge($this->uriVariables, ['uri' => $uri]);
 
-        $result = $this->handle($container, $arguments);
+        $result = $this->handle($container, $arguments, $context);
 
         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 $context): array
     {
-        $result = $this->handle($container, $arguments);
+        $result = $this->handle($container, $arguments, $context);
 
         return $this->formatResult($result);
     }

src/Protocol.php

@@ -113,39 +113,44 @@ public function unbindTransport(): void
      *
      * Processes via Processor, sends Response/Error.
      */
-    public function processMessage(Request|Notification|BatchRequest $message, string $sessionId, array $context = []): void
+    public function processMessage(Request|Notification|BatchRequest $message, string $sessionId, array $messageContext = []): void
     {
         $this->logger->debug('Message received.', ['sessionId' => $sessionId, 'message' => $message]);
 
         $session = $this->sessionManager->getSession($sessionId);
 
         if ($session === null) {
             $error = Error::forInvalidRequest('Invalid or expired session. Please re-initialize the session.', $message->id);
-            $context['status_code'] = 404;
+            $messageContext['status_code'] = 404;
 
-            $this->transport->sendMessage($error, $sessionId, $context)
-                ->then(function () use ($sessionId, $error, $context) {
-                    $this->logger->debug('Response sent.', ['sessionId' => $sessionId, 'payload' => $error, 'context' => $context]);
+            $this->transport->sendMessage($error, $sessionId, $messageContext)
+                ->then(function () use ($sessionId, $error, $messageContext) {
+                    $this->logger->debug('Response sent.', ['sessionId' => $sessionId, 'payload' => $error, 'context' => $messageContext]);
                 })
-                ->catch(function (Throwable $e) use ($sessionId, $error, $context) {
+                ->catch(function (Throwable $e) use ($sessionId) {
                     $this->logger->error('Failed to send response.', ['sessionId' => $sessionId, 'error' => $e->getMessage()]);
                 });
 
             return;
         }
 
-        if ($context['stateless'] ?? false) {
+        if ($messageContext['stateless'] ?? false) {
             $session->set('initialized', true);
             $session->set('protocol_version', self::LATEST_PROTOCOL_VERSION);
             $session->set('client_info', ['name' => 'stateless-client', 'version' => '1.0.0']);
         }
 
+        $context = new Context(
+            $session,
+            $messageContext['request'] ?? null,
+        );
+
         $response = null;
 
         if ($message instanceof BatchRequest) {
-            $response = $this->processBatchRequest($message, $session);
+            $response = $this->processBatchRequest($message, $session, $context);
         } elseif ($message instanceof Request) {
-            $response = $this->processRequest($message, $session);
+            $response = $this->processRequest($message, $session, $context);
         } elseif ($message instanceof Notification) {
             $this->processNotification($message, $session);
         }
@@ -156,7 +161,7 @@ public function processMessage(Request|Notification|BatchRequest $message, strin
             return;
         }
 
-        $this->transport->sendMessage($response, $sessionId, $context)
+        $this->transport->sendMessage($response, $sessionId, $messageContext)
             ->then(function () use ($sessionId, $response) {
                 $this->logger->debug('Response sent.', ['sessionId' => $sessionId, 'payload' => $response]);
             })
@@ -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 $context): ?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, $context);
         }
 
         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 $context): 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, $context);
 
             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]);