[Server][Conformance] Kicking off adoption of conformance testing (#181)

.github/workflows/pipeline.yaml

@@ -69,6 +69,46 @@ jobs:
       - name: Tests
         run: vendor/bin/phpunit --testsuite=inspector
 
+  conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          coverage: "none"
+
+      - name: Setup Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+
+      - name: Install Composer
+        uses: "ramsey/composer-install@v3"
+
+      - name: Run server
+        run: php -S localhost:8000 examples/server/conformance/server.php &
+
+      - name: Wait for server to start
+        run: sleep 5
+
+      - name: Tests
+        run: |
+          exit_code=0
+          OUTPUT=$(npx @modelcontextprotocol/conformance server --url http://localhost:8000/) || exit_code=1 
+          echo "$OUTPUT"
+          
+          # Example: "Total: 3 passed, 16 failed"
+          passedTests=$(echo "$OUTPUT" | sed -nE 's/.*Total: ([0-9]+) passed.*/\1/p')
+          passedTests=${passedTests:-0}
+          
+          REQUIRED_TESTS_TO_PASS=20
+          echo "Required tests to pass: $REQUIRED_TESTS_TO_PASS"
+          [ "$passedTests" -ge "$REQUIRED_TESTS_TO_PASS" ] || exit $exit_code
+
   qa:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -6,3 +6,4 @@ vendor
 examples/**/dev.log
 examples/**/cache
 examples/**/sessions
+results

Makefile

@@ -21,6 +21,12 @@ unit-tests:
 inspector-tests:
 	vendor/bin/phpunit --testsuite=inspector
 
+conformance-server:
+	php -S localhost:8000 examples/server/conformance/server.php
+
+conformance-tests:
+	npx @modelcontextprotocol/conformance server --url http://localhost:8000/
+
 coverage:
 	XDEBUG_MODE=coverage vendor/bin/phpunit --testsuite=unit --coverage-html=coverage
 

composer.json

@@ -56,6 +56,7 @@
       "Mcp\\Example\\Server\\ClientLogging\\": "examples/server/client-logging/",
       "Mcp\\Example\\Server\\CombinedRegistration\\": "examples/server/combined-registration/",
       "Mcp\\Example\\Server\\ComplexToolSchema\\": "examples/server/complex-tool-schema/",
+      "Mcp\\Example\\Server\\Conformance\\": "examples/server/conformance/",
       "Mcp\\Example\\Server\\CustomDependencies\\": "examples/server/custom-dependencies/",
       "Mcp\\Example\\Server\\CustomMethodHandlers\\": "examples/server/custom-method-handlers/",
       "Mcp\\Example\\Server\\DiscoveryCalculator\\": "examples/server/discovery-calculator/",

examples/server/conformance/Elements.php

@@ -0,0 +1,130 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Example\Server\Conformance;
+
+use Mcp\Schema\Content\Content;
+use Mcp\Schema\Content\EmbeddedResource;
+use Mcp\Schema\Content\ImageContent;
+use Mcp\Schema\Content\PromptMessage;
+use Mcp\Schema\Content\TextContent;
+use Mcp\Schema\Content\TextResourceContents;
+use Mcp\Schema\Enum\Role;
+use Mcp\Server\Protocol;
+use Mcp\Server\RequestContext;
+
+final class Elements
+{
+    // Sample base64 encoded 1x1 red PNG pixel for testing
+    public const TEST_IMAGE_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==';
+    // Sample base64 encoded minimal WAV file for testing
+    public const TEST_AUDIO_BASE64 = 'UklGRiYAAABXQVZFZm10IBAAAAABAAEAQB8AAAB9AAACABAAZGF0YQIAAAA=';
+
+    /**
+     * @return Content[]
+     */
+    public function toolMultipleTypes(): array
+    {
+        return [
+            new TextContent('Multiple content types test:'),
+            new ImageContent(self::TEST_IMAGE_BASE64, 'image/png'),
+            EmbeddedResource::fromText(
+                'test://mixed-content-resource',
+                '{ "test" = "data", "value" = 123 }',
+                'application/json',
+            ),
+        ];
+    }
+
+    public function toolWithLogging(RequestContext $context): string
+    {
+        $logger = $context->getClientLogger();
+
+        $logger->info('Tool execution started');
+        $logger->info('Tool processing data');
+        $logger->info('Tool execution completed');
+
+        return 'Tool with logging executed successfully';
+    }
+
+    public function toolWithProgress(RequestContext $context): ?string
+    {
+        $client = $context->getClientGateway();
+
+        $client->progress(0, 100, 'Completed step 0 of 100');
+        $client->progress(50, 100, 'Completed step 0 of 100');
+        $client->progress(100, 100, 'Completed step 0 of 100');
+
+        $meta = $context->getSession()->get(Protocol::SESSION_ACTIVE_REQUEST_META, []);
+
+        return $meta['progressToken'] ?? null;
+    }
+
+    /**
+     * @param string $prompt The prompt to send to the LLM
+     */
+    public function toolWithSampling(RequestContext $context, string $prompt): string
+    {
+        $result = $context->getClientGateway()->sample($prompt, 100);
+
+        return \sprintf('LLM response: %s', $result->content instanceof TextContent ? trim((string) $result->content->text) : '');
+    }
+
+    public function resourceTemplate(string $id): TextResourceContents
+    {
+        return new TextResourceContents(
+            uri: 'test://template/{id}/data',
+            mimeType: 'application/json',
+            text: json_encode([
+                'id' => $id,
+                'templateTest' => true,
+                'data' => \sprintf('Data for ID: %s', $id),
+            ]),
+        );
+    }
+
+    /**
+     * @param string $arg1 First test argument
+     * @param string $arg2 Second test argument
+     *
+     * @return PromptMessage[]
+     */
+    public function promptWithArguments(string $arg1, string $arg2): array
+    {
+        return [
+            new PromptMessage(Role::User, new TextContent(\sprintf('Prompt with arguments: arg1="%s", arg2="%s"', $arg1, $arg2))),
+        ];
+    }
+
+    /**
+     * @param string $resourceUri URI of the resource to embed
+     *
+     * @return PromptMessage[]
+     */
+    public function promptWithEmbeddedResource(string $resourceUri): array
+    {
+        return [
+            new PromptMessage(Role::User, EmbeddedResource::fromText($resourceUri, 'Embedded resource content for testing.')),
+            new PromptMessage(Role::User, new TextContent('Please process the embedded resource above.')),
+        ];
+    }
+
+    /**
+     * @return PromptMessage[]
+     */
+    public function promptWithImage(): array
+    {
+        return [
+            new PromptMessage(Role::User, new ImageContent(self::TEST_IMAGE_BASE64, 'image/png')),
+            new PromptMessage(Role::User, new TextContent('Please analyze the image above.')),
+        ];
+    }
+}

examples/server/conformance/server.php

@@ -0,0 +1,58 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+require_once dirname(__DIR__).'/bootstrap.php';
+chdir(__DIR__);
+
+use Mcp\Example\Server\Conformance\Elements;
+use Mcp\Schema\Content\AudioContent;
+use Mcp\Schema\Content\EmbeddedResource;
+use Mcp\Schema\Content\ImageContent;
+use Mcp\Schema\Content\TextContent;
+use Mcp\Schema\Result\CallToolResult;
+use Mcp\Server;
+use Mcp\Server\Session\FileSessionStore;
+
+logger()->info('Starting MCP Custom Dependencies Server...');
+
+$server = Server::builder()
+    ->setServerInfo('mcp-conformance-test-server', '1.0.0')
+    ->setSession(new FileSessionStore(__DIR__.'/sessions'))
+    ->setLogger(logger())
+    // Tools
+    ->addTool(fn () => 'This is a simple text response for testing.', 'test_simple_text', 'Tests simple text content response')
+    ->addTool(fn () => new ImageContent(Elements::TEST_IMAGE_BASE64, 'image/png'), 'test_image_content', 'Tests image content response')
+    ->addTool(fn () => new AudioContent(Elements::TEST_AUDIO_BASE64, 'audio/wav'), 'test_audio_content', 'Tests audio content response')
+    ->addTool(fn () => EmbeddedResource::fromText('test://embedded-resource', 'This is an embedded resource content.'), 'test_embedded_resource', 'Tests embedded resource content response')
+    ->addTool([Elements::class, 'toolMultipleTypes'], 'test_multiple_content_types', 'Tests response with multiple content types (text, image, resource)')
+    ->addTool([Elements::class, 'toolWithLogging'], 'test_tool_with_logging', 'Tests tool that emits log messages during execution')
+    ->addTool([Elements::class, 'toolWithProgress'], 'test_tool_with_progress', 'Tests tool that reports progress notifications')
+    ->addTool(fn () => CallToolResult::error([new TextContent('This tool intentionally returns an error for testing')]), 'test_error_handling', 'Tests error response handling')
+    // TODO: Sampling gets stuck
+    // ->addTool([Elements::class, 'toolWithSampling'], 'test_sampling', 'Tests server-initiated sampling (LLM completion request)')
+    // Resources
+    ->addResource(fn () => 'This is the content of the static text resource.', 'test://static-text', 'static-text', 'A static text resource for testing')
+    ->addResource(fn () => ''/* TODO: Missing Support for Binary? */, 'test://static-binary', 'static-binary', 'A static binary resource (image) for testing')
+    ->addResourceTemplate([Elements::class, 'resourceTemplate'], 'test://template/{id}/data', 'template', 'A resource template with parameter substitution', 'application/json')
+    // TODO: Handler for resources/subscribe and resources/unsubscribe
+    ->addResource(fn () => 'Watched resource content', 'test://watched-resource', 'watched-resource', 'A resource that auto-updates every 3 seconds')
+    // Prompts
+    ->addPrompt(fn () => [['role' => 'user', 'content' => 'This is a simple prompt for testing.']], 'test_simple_prompt', 'A simple prompt without arguments')
+    ->addPrompt([Elements::class, 'promptWithArguments'], 'test_prompt_with_arguments', 'A prompt with required arguments')
+    ->addPrompt([Elements::class, 'promptWithEmbeddedResource'], 'test_prompt_with_embedded_resource', 'A prompt that includes an embedded resource')
+    ->addPrompt([Elements::class, 'promptWithImage'], 'test_prompt_with_image', 'A prompt that includes image content')
+    ->build();
+
+$result = $server->run(transport());
+
+logger()->info('Server listener stopped gracefully.', ['result' => $result]);
+
+shutdown($result);