Introduce Capability Registry & Discovery

tests/Capability/Discovery/Fixtures/DiscoverablePromptHandler.php

@@ -0,0 +1,47 @@
+<?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\Tests\Capability\Discovery\Fixtures;
+
+use Mcp\Capability\Attribute\CompletionProvider;
+use Mcp\Capability\Attribute\McpPrompt;
+use Mcp\Tests\Capability\Attribute\CompletionProviderFixture;
+
+class DiscoverablePromptHandler
+{
+    /**
+     * Generates a creative story prompt.
+     *
+     * @param string $genre       the genre of the story
+     * @param int    $lengthWords approximate length in words
+     *
+     * @return array the prompt messages
+     */
+    #[McpPrompt(name: 'creative_story_prompt')]
+    public function generateStoryPrompt(
+        #[CompletionProvider(provider: CompletionProviderFixture::class)]
+        string $genre,
+        int $lengthWords = 200,
+    ): array {
+        return [
+            ['role' => 'user', 'content' => "Write a {$genre} story about a lost robot, approximately {$lengthWords} words long."],
+        ];
+    }
+
+    #[McpPrompt]
+    public function simpleQuestionPrompt(string $question): array
+    {
+        return [
+            ['role' => 'user', 'content' => $question],
+            ['role' => 'assistant', 'content' => 'I will try to answer that.'],
+        ];
+    }
+}

tests/Capability/Discovery/Fixtures/DiscoverableResourceHandler.php

@@ -0,0 +1,50 @@
+<?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\Tests\Capability\Discovery\Fixtures;
+
+use Mcp\Capability\Attribute\McpResource;
+use Mcp\Schema\Annotations;
+
+class DiscoverableResourceHandler
+{
+    /**
+     * Provides the application's current version.
+     *
+     * @return string the version string
+     */
+    #[McpResource(
+        uri: 'app://info/version',
+        name: 'app_version',
+        description: 'The current version of the application.',
+        mimeType: 'text/plain',
+        size: 10
+    )]
+    public function getAppVersion(): string
+    {
+        return '1.2.3-discovered';
+    }
+
+    #[McpResource(
+        uri: 'config://settings/ui',
+        name: 'ui_settings_discovered',
+        mimeType: 'application/json',
+        annotations: new Annotations(priority: 0.5)
+    )]
+    public function getUiSettings(): array
+    {
+        return ['theme' => 'dark', 'fontSize' => 14];
+    }
+
+    public function someOtherMethod(): void
+    {
+    }
+}

tests/Capability/Discovery/Fixtures/DiscoverableTemplateHandler.php

@@ -0,0 +1,51 @@
+<?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\Tests\Capability\Discovery\Fixtures;
+
+use Mcp\Capability\Attribute\CompletionProvider;
+use Mcp\Capability\Attribute\McpResourceTemplate;
+use Mcp\Tests\Capability\Attribute\CompletionProviderFixture;
+
+class DiscoverableTemplateHandler
+{
+    /**
+     * Retrieves product details based on ID and region.
+     *
+     * @param string $productId the ID of the product
+     * @param string $region    the sales region
+     *
+     * @return array product details
+     */
+    #[McpResourceTemplate(
+        uriTemplate: 'product://{region}/details/{productId}',
+        name: 'product_details_template',
+        mimeType: 'application/json'
+    )]
+    public function getProductDetails(
+        string $productId,
+        #[CompletionProvider(provider: CompletionProviderFixture::class)]
+        string $region,
+    ): array {
+        return [
+            'id' => $productId,
+            'name' => 'Product '.$productId,
+            'region' => $region,
+            'price' => ('EU' === $region ? '€' : '$').(hexdec(substr(md5($productId), 0, 4)) / 100),
+        ];
+    }
+
+    #[McpResourceTemplate(uriTemplate: 'file://{path}/{filename}.{extension}')]
+    public function getFileContent(string $path, string $filename, string $extension): string
+    {
+        return "Content of {$path}/{$filename}.{$extension}";
+    }
+}

tests/Capability/Discovery/Fixtures/DiscoverableToolHandler.php

@@ -0,0 +1,68 @@
+<?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\Tests\Capability\Discovery\Fixtures;
+
+use Mcp\Capability\Attribute\McpTool;
+use Mcp\Schema\ToolAnnotations;
+use Mcp\Tests\Fixtures\Enum\BackedStringEnum;
+
+class DiscoverableToolHandler
+{
+    /**
+     * A basic discoverable tool.
+     *
+     * @param string $name the name to greet
+     *
+     * @return string the greeting
+     */
+    #[McpTool(name: 'greet_user', description: 'Greets a user by name.')]
+    public function greet(string $name): string
+    {
+        return "Hello, {$name}!";
+    }
+
+    /**
+     * A tool with more complex parameters and inferred name/description.
+     *
+     * @param int              $count  the number of times to repeat
+     * @param bool             $loudly Should it be loud?
+     * @param BackedStringEnum $mode   the mode of operation
+     *
+     * @return array an array with results
+     */
+    #[McpTool(annotations: new ToolAnnotations(readOnlyHint: true))]
+    public function repeatAction(int $count, bool $loudly = false, BackedStringEnum $mode = BackedStringEnum::OptionA): array
+    {
+        return ['count' => $count, 'loudly' => $loudly, 'mode' => $mode->value, 'message' => 'Action repeated.'];
+    }
+
+    // This method should NOT be discovered as a tool
+    public function internalHelperMethod(int $value): int
+    {
+        return $value * 2;
+    }
+
+    #[McpTool(name: 'private_tool_should_be_ignored')] // On private method
+    private function aPrivateTool(): void
+    {
+    }
+
+    #[McpTool(name: 'protected_tool_should_be_ignored')] // On protected method
+    protected function aProtectedTool(): void
+    {
+    }
+
+    #[McpTool(name: 'static_tool_should_be_ignored')] // On static method
+    public static function aStaticTool(): void
+    {
+    }
+}

tests/Capability/Discovery/Fixtures/EnhancedCompletionHandler.php

@@ -0,0 +1,57 @@
+<?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\Tests\Capability\Discovery\Fixtures;
+
+use Mcp\Capability\Attribute\CompletionProvider;
+use Mcp\Capability\Attribute\McpPrompt;
+use Mcp\Capability\Attribute\McpResourceTemplate;
+use Mcp\Tests\Fixtures\Enum\PriorityEnum;
+use Mcp\Tests\Fixtures\Enum\StatusEnum;
+
+class EnhancedCompletionHandler
+{
+    /**
+     * Create content with list and enum completion providers.
+     */
+    #[McpPrompt(name: 'content_creator')]
+    public function createContent(
+        #[CompletionProvider(values: ['blog', 'article', 'tutorial', 'guide'])]
+        string $type,
+        #[CompletionProvider(enum: StatusEnum::class)]
+        string $status,
+        #[CompletionProvider(enum: PriorityEnum::class)]
+        string $priority,
+    ): array {
+        return [
+            ['role' => 'user', 'content' => "Create a {$type} with status {$status} and priority {$priority}"],
+        ];
+    }
+
+    /**
+     * Resource template with list completion for categories.
+     */
+    #[McpResourceTemplate(
+        uriTemplate: 'content://{category}/{slug}',
+        name: 'content_template'
+    )]
+    public function getContent(
+        #[CompletionProvider(values: ['news', 'blog', 'docs', 'api'])]
+        string $category,
+        string $slug,
+    ): array {
+        return [
+            'category' => $category,
+            'slug' => $slug,
+            'url' => "https://example.com/{$category}/{$slug}",
+        ];
+    }
+}

tests/Capability/Discovery/Fixtures/InvocablePromptFixture.php

@@ -0,0 +1,23 @@
+<?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\Tests\Capability\Discovery\Fixtures;
+
+use Mcp\Capability\Attribute\McpPrompt;
+
+#[McpPrompt(name: 'InvokableGreeterPrompt')]
+class InvocablePromptFixture
+{
+    public function __invoke(string $personName): array
+    {
+        return [['role' => 'user', 'content' => "Generate a short greeting for {$personName}."]];
+    }
+}

tests/Capability/Discovery/Fixtures/InvocableResourceFixture.php

@@ -0,0 +1,23 @@
+<?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\Tests\Capability\Discovery\Fixtures;
+
+use Mcp\Capability\Attribute\McpResource;
+
+#[McpResource(uri: 'invokable://config/status', name: 'invokable_app_status')]
+class InvocableResourceFixture
+{
+    public function __invoke(): array
+    {
+        return ['status' => 'OK', 'load' => rand(1, 100) / 100.0];
+    }
+}

tests/Capability/Discovery/Fixtures/InvocableResourceTemplateFixture.php

@@ -0,0 +1,23 @@
+<?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\Tests\Capability\Discovery\Fixtures;
+
+use Mcp\Capability\Attribute\McpResourceTemplate;
+
+#[McpResourceTemplate(uriTemplate: 'invokable://user-profile/{userId}')]
+class InvocableResourceTemplateFixture
+{
+    public function __invoke(string $userId): array
+    {
+        return ['id' => $userId, 'email' => "user{$userId}@example-invokable.com"];
+    }
+}

tests/Capability/Discovery/Fixtures/InvocableToolFixture.php

@@ -0,0 +1,26 @@
+<?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\Tests\Capability\Discovery\Fixtures;
+
+use Mcp\Capability\Attribute\McpTool;
+
+#[McpTool(name: 'InvokableCalculator', description: 'An invokable calculator tool.')]
+class InvocableToolFixture
+{
+    /**
+     * Adds two numbers.
+     */
+    public function __invoke(int $a, int $b): int
+    {
+        return $a + $b;
+    }
+}

tests/Capability/Discovery/Fixtures/NonDiscoverableClass.php

@@ -0,0 +1,36 @@
+<?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\Tests\Capability\Discovery\Fixtures;
+
+class NonDiscoverableClass
+{
+    public function someMethod(): string
+    {
+        return 'Just a regular method.';
+    }
+}
+
+interface MyDiscoverableInterface
+{
+}
+
+trait MyDiscoverableTrait
+{
+    public function traitMethod()
+    {
+    }
+}
+
+enum MyDiscoverableEnum
+{
+    case Alpha;
+}

tests/Capability/Discovery/Fixtures/SubDir/HiddenTool.php

@@ -0,0 +1,22 @@
+<?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\Tests\Capability\Discovery\Fixtures\SubDir;
+
+use Mcp\Capability\Attribute\McpTool;
+
+class HiddenTool
+{
+    #[McpTool(name: 'hidden_subdir_tool')]
+    public function run()
+    {
+    }
+}