feat(mcp): support STDIO transport

Author: EdouardCourty

CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2025-07-28
+
+### Added
+
+- Added support for STDIO transport through a Symfony Command : `mcp:stdio`
+- Added a new CommandTestCase for handling tests of the Symfony command
+
+### Updated
+
+- Updated the test to be more reusable, by creating a trait that contains DataProviders and assertion logic
+
 ## [1.3.0] - 2025-07-27
 
 ### Updated

README.md

@@ -19,11 +19,14 @@ The current MCP protocol supported version is `2025-06-18`, which is the latest
 > This bundle will evolve along with the specification, so please ensure you are using the latest version of the bundle.  
 > The CHANGELOG can be found [here](CHANGELOG.md).
 
+The MCP Server Bundle currently supports HTTP & STDIO as transports. 
+
 ## Table of Contents
 
 - [Getting Started](#getting-started)
   - [Installation](#installation)
   - [Configuration](#configuration)
+  - [Transports](#transports)
 - [Tools](#tools)
   - [Creating Tools](#creating-tools)
   - [Tool Results](#tool-results)
@@ -93,6 +96,30 @@ mcp_server:
     version: '1.0.0' # The version of your MCP server, used in the initialization response
 ```
 
+### Transports
+
+This bundle adds support for HTTP and STDIO transports.
+
+#### HTTP
+
+HTTP support is featured using a controller, as stated in the [configuration](#configuration).
+
+#### STDIO
+
+STDIO transport is featured through a Symfony command:
+```bash
+$ bin/console mcp:stdio
+
+Description:
+  MCP server STDIO entrypoint
+
+Usage:
+  mcp:stdio <jsonrpc_request>
+
+Arguments:
+  jsonrpc_request       JSON-RPC request
+```
+
 ## Tools
 
 Tools are the core components of the MCP Server Bundle. They allow you to define and manage custom logic that can be triggered by clients.

src/Command/EntrypointCommand.php

@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ecourty\McpServerBundle\Command;
+
+use Ecourty\McpServerBundle\Controller\EntrypointController;
+use Ecourty\McpServerBundle\EventListener\ExceptionListener;
+use Ecourty\McpServerBundle\HttpFoundation\JsonRpcRequest;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestStack;
+use Symfony\Component\HttpKernel\Event\ExceptionEvent;
+use Symfony\Component\HttpKernel\HttpKernelInterface;
+use Symfony\Component\HttpKernel\KernelInterface;
+use Symfony\Component\Serializer\SerializerInterface;
+
+#[AsCommand(
+    name: 'mcp:stdio',
+    description: 'MCP server STDIO entrypoint',
+)]
+class EntrypointCommand extends Command
+{
+    public function __construct(
+        private readonly SerializerInterface $serializer,
+        private readonly EntrypointController $entrypointController,
+        private readonly ExceptionListener $exceptionListener,
+        private readonly KernelInterface $kernel,
+        private readonly RequestStack $requestStack,
+    ) {
+        parent::__construct();
+    }
+
+    protected function configure(): void
+    {
+        $this->addArgument('jsonrpc_request', InputArgument::REQUIRED, 'JSON-RPC request');
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $jsonRpcRequestString = (string) $input->getArgument('jsonrpc_request');
+        if (empty($jsonRpcRequestString) === true) {
+            throw new \UnexpectedValueException('Missing request argument');
+        }
+
+        $jsonRpcRequest = $this->serializer->deserialize($jsonRpcRequestString, JsonRpcRequest::class, 'json');
+        $request = new Request(content: $jsonRpcRequestString);
+
+        try {
+            $response = $this->entrypointController->__invoke($jsonRpcRequest, $request);
+        } catch (\Throwable $exception) {
+            $this->requestStack->push($request);
+            $exceptionEvent = new ExceptionEvent(
+                kernel: $this->kernel,
+                request: $request,
+                requestType: HttpKernelInterface::MAIN_REQUEST,
+                e: $exception,
+            );
+            $this->exceptionListener->onKernelException($exceptionEvent);
+
+            $response = $exceptionEvent->getResponse();
+        }
+
+        if ($response === null) {
+            throw new \RuntimeException('No response received');
+        }
+
+        $output->write((string) $response->getContent());
+
+        return self::SUCCESS;
+    }
+}

src/EventListener/ExceptionListener.php

@@ -7,8 +7,10 @@
 use Ecourty\McpServerBundle\Enum\McpErrorCode;
 use Ecourty\McpServerBundle\Exception\MethodHandlerNotFoundException;
 use Ecourty\McpServerBundle\Exception\RequestHandlingException;
+use Ecourty\McpServerBundle\Exception\ToolNotFoundException;
 use Ecourty\McpServerBundle\Service\ResponseFactory;
 use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
+use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\HttpFoundation\RequestStack;
 use Symfony\Component\HttpKernel\Event\ExceptionEvent;
 use Symfony\Component\HttpKernel\Exception\UnprocessableEntityHttpException;
@@ -38,13 +40,28 @@ public function onKernelException(ExceptionEvent $event): void
 
         $response = match (true) {
             $exception instanceof UnprocessableEntityHttpException => $this->responseFactory->error($jsonRpcRequestId, McpErrorCode::PARSE_ERROR),
-            $exception instanceof MethodHandlerNotFoundException => $this->responseFactory->error($jsonRpcRequestId, McpErrorCode::TOOL_NOT_FOUND),
-            $exception instanceof RequestHandlingException => $this->responseFactory->error($jsonRpcRequestId, McpErrorCode::INTERNAL_ERROR),
+            $exception instanceof MethodHandlerNotFoundException => $this->responseFactory->error($jsonRpcRequestId, McpErrorCode::METHOD_NOT_FOUND),
+            $exception instanceof RequestHandlingException => $this->handleRequestHandlingException($exception, $jsonRpcRequestId),
             default => null,
         };
 
         if ($response !== null) {
             $event->setResponse($response);
         }
     }
+
+    private function handleRequestHandlingException(
+        RequestHandlingException $exception,
+        string|int|null $jsonRpcRequestId = null,
+    ): JsonResponse {
+        $previous = $exception->getPrevious();
+        if ($previous instanceof ToolNotFoundException === true) {
+            return $this->responseFactory->error(
+                id: $jsonRpcRequestId,
+                errorCode: McpErrorCode::TOOL_NOT_FOUND,
+            );
+        }
+
+        return $this->responseFactory->error($jsonRpcRequestId, McpErrorCode::INTERNAL_ERROR);
+    }
 }

src/Exception/ToolNotFoundException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ecourty\McpServerBundle\Exception;
+
+class ToolNotFoundException extends \Exception
+{
+}

src/MethodHandler/ToolsCallMethodHandler.php

@@ -10,6 +10,7 @@
 use Ecourty\McpServerBundle\Event\ToolCallExceptionEvent;
 use Ecourty\McpServerBundle\Event\ToolResultEvent;
 use Ecourty\McpServerBundle\Exception\ToolCallException;
+use Ecourty\McpServerBundle\Exception\ToolNotFoundException;
 use Ecourty\McpServerBundle\HttpFoundation\JsonRpcRequest;
 use Ecourty\McpServerBundle\IO\ToolResult;
 use Ecourty\McpServerBundle\Service\InputSanitizer;
@@ -53,7 +54,7 @@ public function handle(JsonRpcRequest $request): array
         $toolDefinition = $this->toolRegistry->getToolDefinition($toolName);
 
         if ($tool === null) {
-            throw new \InvalidArgumentException(\sprintf('Tool "%s" not found.', $request->params['name']));
+            throw new ToolNotFoundException(\sprintf('Tool "%s" not found.', $request->params['name']));
         }
 
         if ($toolDefinition === null) {