feat: MCP SDK with server implementation

Author: chr-hertel

.github/workflows/pipeline.yml

@@ -0,0 +1,74 @@
+name: pipeline
+on: pull_request
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        php: ['8.2', '8.3', '8.4']
+        dependencies: ['lowest', 'highest']
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: "none"
+
+      - name: Install Composer
+        uses: "ramsey/composer-install@v3"
+        with:
+          dependency-versions: "${{ matrix.dependencies }}"
+
+      - name: Composer Validation
+        run: composer validate --strict
+
+      - name: Install PHP Dependencies
+        run: composer install --no-scripts
+
+      - name: Tests
+        run: vendor/bin/phpunit
+
+  qa:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Conventional Commit
+        uses: ytanikin/[email protected]
+        with:
+          task_types: '["feat", "fix", "docs", "test", "ci", "style", "refactor", "perf", "chore", "revert"]'
+          add_label: 'true'
+          custom_labels: '{"feat": "feature", "fix": "bug", "docs": "documentation", "test": "test", "ci": "CI/CD", "style": "codestyle", "refactor": "refactor", "perf": "performance", "chore": "chore", "revert": "revert"}'
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          coverage: "none"
+
+      - name: Install Composer
+        uses: "ramsey/composer-install@v3"
+
+      - name: Composer Validation
+        run: composer validate --strict
+
+      - name: Install PHP Dependencies
+        run: composer install --no-scripts
+
+      - name: Code Style PHP
+        run: vendor/bin/php-cs-fixer fix --dry-run
+
+      - name: Rector
+        run: vendor/bin/rector --dry-run
+
+      - name: PHPStan
+        run: vendor/bin/phpstan analyse

.gitignore

@@ -0,0 +1,4 @@
+.phpunit.cache
+.php-cs-fixer.cache
+composer.lock
+vendor

.php-cs-fixer.dist.php

@@ -0,0 +1,13 @@
+<?php
+
+$finder = (new PhpCsFixer\Finder())
+    ->in(__DIR__)
+    ->exclude('var')
+;
+
+return (new PhpCsFixer\Config())
+    ->setRules([
+        '@Symfony' => true,
+    ])
+    ->setFinder($finder)
+;

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Christopher Hertel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

Makefile

@@ -0,0 +1,28 @@
+.PHONY: deps-stable deps-low cs rector phpstan tests coverage run-examples ci ci-stable ci-lowest
+
+deps-stable:
+	composer update --prefer-stable
+
+deps-low:
+	composer update --prefer-lowest
+
+cs:
+	PHP_CS_FIXER_IGNORE_ENV=true vendor/bin/php-cs-fixer fix --diff --verbose
+
+rector:
+	vendor/bin/rector
+
+phpstan:
+	vendor/bin/phpstan --memory-limit=-1
+
+tests:
+	vendor/bin/phpunit
+
+coverage:
+	XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-html=coverage
+
+ci: ci-stable
+
+ci-stable: deps-stable rector cs phpstan tests
+
+ci-lowest: deps-low rector cs phpstan tests

README.md

@@ -0,0 +1,98 @@
+# Model Context Protocol PHP SDK [WIP]
+
+Model Context Protocol SDK for Client and Server applications in PHP.
+
+See [Demo App](https://github.com/php-llm/mcp-demo) for a working example.
+
+## Installation
+
+```bash
+composer require php-llm/mcp-sdk
+```
+
+## Usage with Symfony
+
+Server integration points for are tailored to Symfony Console and HttpFoundation (Laravel compatible).
+
+### Console Command for STDIO Server
+
+```php
+namespace App\Command;
+
+use PhpLlm\McpSdk\Server;
+use PhpLlm\McpSdk\Server\Transport\Stdio\SymfonyConsoleTransport;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+#[AsCommand('mcp', 'Starts an MCP server')]
+final class McpCommand extends Command
+{
+    public function __construct(
+        private readonly Server $server,
+    ) {
+        parent::__construct();
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $this->server->connect(
+            new SymfonyConsoleTransport($input, $output)
+        );
+
+        return Command::SUCCESS;
+    }
+}
+```
+
+### Controller for Server-Sent Events Server
+
+```php
+namespace App\Controller;
+
+use PhpLlm\McpSdk\Server;
+use PhpLlm\McpSdk\Server\Transport\Sse\Store\CachePoolStore;
+use PhpLlm\McpSdk\Server\Transport\Sse\StreamTransport;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpFoundation\StreamedResponse;
+use Symfony\Component\HttpKernel\Attribute\AsController;
+use Symfony\Component\Routing\Attribute\Route;
+use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
+use Symfony\Component\Uid\Uuid;
+
+#[AsController]
+#[Route('/mcp', name: 'mcp_')]
+final readonly class McpController
+{
+    public function __construct(
+        private Server $server,
+        private CachePoolStore $store,
+        private UrlGeneratorInterface $urlGenerator,
+    ) {
+    }
+
+    #[Route('/sse', name: 'sse', methods: ['GET'])]
+    public function sse(): StreamedResponse
+    {
+        $id = Uuid::v4();
+        $endpoint = $this->urlGenerator->generate('mcp_messages', ['id' => $id], UrlGeneratorInterface::ABSOLUTE_URL);
+        $transport = new StreamTransport($endpoint, $this->store, $id);
+
+        return new StreamedResponse(fn() => $this->server->connect($transport), headers: [
+            'Content-Type' => 'text/event-stream',
+            'Cache-Control' => 'no-cache',
+            'X-Accel-Buffering' => 'no',
+        ]);
+    }
+
+    #[Route('/messages/{id}', name: 'messages', methods: ['POST'])]
+    public function messages(Request $request, Uuid $id): Response
+    {
+        $this->store->push($id, $request->getContent());
+
+        return new Response();
+    }
+}
+```

composer.json

@@ -0,0 +1,38 @@
+{
+    "name": "php-llm/mcp-sdk",
+    "type": "library",
+    "description": "Model Context Protocol SDK for Client and Server applications in PHP",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Christopher Hertel",
+            "email": "[email protected]"
+        }
+    ],
+    "require": {
+        "php": "^8.2",
+        "psr/log": "^3.0",
+        "symfony/uid": "^7.2",
+        "php-llm/llm-chain": "^0.17.0"
+    },
+    "require-dev": {
+        "php-cs-fixer/shim": "^3.70",
+        "phpstan/phpstan": "^2.1",
+        "phpunit/phpunit": "^11.5",
+        "symfony/console": "^6.4 || ^7.0",
+        "rector/rector": "^2.0"
+    },
+    "suggest": {
+        "symfony/console": "To use SymfonyConsoleTransport for STDIO"
+    },
+    "autoload": {
+        "psr-4": {
+            "PhpLlm\\McpSdk\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "PhpLlm\\McpSdk\\Tests\\": "tests/"
+        }
+    }
+}

phpstan.dist.neon

@@ -0,0 +1,5 @@
+parameters:
+    level: 6
+    paths:
+        - src/
+        - tests/

phpunit.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.0/phpunit.xsd"
+         cacheDirectory=".phpunit.cache"
+         colors="true"
+         executionOrder="depends,defects"
+         beStrictAboutOutputDuringTests="true"
+         failOnRisky="true"
+         failOnWarning="true">
+
+    <testsuites>
+        <testsuite name="default">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <source ignoreIndirectDeprecations="true" restrictNotices="true" restrictWarnings="true">
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+</phpunit>

rector.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+use Rector\Config\RectorConfig;
+use Rector\Php74\Rector\Closure\ClosureToArrowFunctionRector;
+use Rector\PHPUnit\CodeQuality\Rector\Class_\PreferPHPUnitSelfCallRector;
+use Rector\PHPUnit\CodeQuality\Rector\Class_\PreferPHPUnitThisCallRector;
+use Rector\PHPUnit\CodeQuality\Rector\MethodCall\AssertCountWithZeroToAssertEmptyRector;
+use Rector\PHPUnit\Set\PHPUnitSetList;
+
+return RectorConfig::configure()
+    ->withPaths([
+        __DIR__.'/src',
+        __DIR__.'/tests',
+    ])
+    ->withPhpSets(php82: true)
+    ->withSets([
+        PHPUnitSetList::PHPUNIT_110,
+        PHPUnitSetList::ANNOTATIONS_TO_ATTRIBUTES,
+        PHPUnitSetList::PHPUNIT_CODE_QUALITY,
+    ])
+    ->withRules([
+        PreferPHPUnitSelfCallRector::class,
+    ])
+    ->withImportNames(importShortClasses: false)
+    ->withSkip([
+        AssertCountWithZeroToAssertEmptyRector::class,
+        ClosureToArrowFunctionRector::class,
+        PreferPHPUnitThisCallRector::class,
+    ])
+    ->withTypeCoverageLevel(0);