Introducing Capability Registry & Discovery

composer.json

@@ -8,28 +8,33 @@
             "name": "Christopher Hertel",
             "email": "[email protected]"
         },
-        {
-            "name": "Tobias Nyholm",
-            "email": "[email protected]"
-        },
         {
             "name": "Kyrian Obikwelu",
             "email": "[email protected]"
+        },
+        {
+            "name": "Tobias Nyholm",
+            "email": "[email protected]"
         }
     ],
     "require": {
         "php": "^8.1",
         "ext-fileinfo": "*",
+        "opis/json-schema": "^2.4",
+        "phpdocumentor/reflection-docblock": "^5.6",
+        "psr/event-dispatcher": "^1.0",
         "psr/log": "^1.0 || ^2.0 || ^3.0",
-        "symfony/uid": "^6.4 || ^7.0"
+        "symfony/finder": "^6.4 || ^7.2",
+        "symfony/uid": "^6.4 || ^7.2"
     },
     "require-dev": {
+        "nyholm/nsa": "^1.3",
+        "php-cs-fixer/shim": "^3.84",
         "phpstan/phpstan": "^2.1",
         "phpunit/phpunit": "^10.5",
-        "symfony/console": "^6.4 || ^7.0",
         "psr/cache": "^3.0",
-        "php-cs-fixer/shim": "^3.84",
-        "nyholm/nsa": "^1.3"
+        "symfony/console": "^6.4 || ^7.0",
+        "symfony/event-dispatcher": "^6.4 || ^7.0"
     },
     "suggest": {
         "symfony/console": "To use SymfonyConsoleTransport for STDIO",
@@ -44,5 +49,8 @@
         "psr-4": {
             "Mcp\\Tests\\": "tests/"
         }
+    },
+    "config": {
+        "sort-packages": true
     }
 }

phpstan.dist.neon

@@ -6,7 +6,14 @@ parameters:
         - tests/
     excludePaths:
         - examples/cli/vendor/* (?)
+        - tests/Capability/Discovery/Fixtures/
+        - tests/Capability/Discovery/SchemaGeneratorFixture.php
     treatPhpDocTypesAsCertain: false
     ignoreErrors:
         -
             message: "#^Method .*::test.*\\(\\) has no return type specified\\.$#"
+        # This errors should actually be fixed, but are ignored for now
+        -
+            identifier: missingType.iterableValue
+            path: src/Capability/Discovery/SchemaGenerator.php
+            count: 12

src/Capability/Attribute/CompletionProvider.php

@@ -0,0 +1,38 @@
+<?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\Capability\Attribute;
+
+use Mcp\Capability\Prompt\Completion\ProviderInterface;
+use Mcp\Exception\InvalidArgumentException;
+
+/**
+ * @author Kyrian Obikwelu <[email protected]>
+ */
+#[\Attribute(\Attribute::TARGET_PARAMETER)]
+class CompletionProvider
+{
+    /**
+     * @param class-string<ProviderInterface>|ProviderInterface|null $provider if a class-string, it will be resolved
+     *                                                                         from the container at the point of use
+     * @param ?array<int, int|float|string>                          $values   a list of values to use for completion
+     */
+    public function __construct(
+        public ?string $providerClass = null,
+        public string|ProviderInterface|null $provider = null,
+        public ?array $values = null,
+        public ?string $enum = null,
+    ) {
+        if (1 !== \count(array_filter([$provider, $values, $enum]))) {
+            throw new InvalidArgumentException('Only one of provider, values, or enum can be set.');
+        }
+    }
+}

src/Capability/Attribute/McpPrompt.php

@@ -0,0 +1,32 @@
+<?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\Capability\Attribute;
+
+/**
+ * Marks a PHP method as an MCP Prompt generator.
+ * The method should return the prompt messages, potentially using arguments for templating.
+ *
+ * @author Kyrian Obikwelu <[email protected]>
+ */
+#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_CLASS)]
+final class McpPrompt
+{
+    /**
+     * @param ?string $name        overrides the prompt name (defaults to method name)
+     * @param ?string $description Optional description of the prompt. Defaults to method DocBlock summary.
+     */
+    public function __construct(
+        public ?string $name = null,
+        public ?string $description = null,
+    ) {
+    }
+}

src/Capability/Attribute/McpResource.php

@@ -0,0 +1,42 @@
+<?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\Capability\Attribute;
+
+use Mcp\Schema\Annotations;
+
+/**
+ * Marks a PHP class as representing or handling a specific MCP Resource instance.
+ * Used primarily for the 'resources/list' discovery.
+ *
+ * @author Kyrian Obikwelu <[email protected]>
+ */
+#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_CLASS)]
+final class McpResource
+{
+    /**
+     * @param string           $uri         The specific URI identifying this resource instance. Must be unique within the server.
+     * @param ?string          $name        A human-readable name for this resource. If null, a default might be generated from the method name.
+     * @param ?string          $description An optional description of the resource. Defaults to class DocBlock summary.
+     * @param ?string          $mimeType    the MIME type, if known and constant for this resource
+     * @param ?int             $size        the size in bytes, if known and constant
+     * @param Annotations|null $annotations optional annotations describing the resource
+     */
+    public function __construct(
+        public string $uri,
+        public ?string $name = null,
+        public ?string $description = null,
+        public ?string $mimeType = null,
+        public ?int $size = null,
+        public ?Annotations $annotations = null,
+    ) {
+    }
+}

src/Capability/Attribute/McpResourceTemplate.php

@@ -0,0 +1,40 @@
+<?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\Capability\Attribute;
+
+use Mcp\Schema\Annotations;
+
+/**
+ * Marks a PHP class definition as representing an MCP Resource Template.
+ * This is informational, used for 'resources/templates/list'.
+ *
+ * @author Kyrian Obikwelu <[email protected]>
+ */
+#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_CLASS)]
+final class McpResourceTemplate
+{
+    /**
+     * @param string       $uriTemplate the URI template string (RFC 6570)
+     * @param ?string      $name        A human-readable name for the template type.  If null, a default might be generated from the method name.
+     * @param ?string      $description Optional description. Defaults to class DocBlock summary.
+     * @param ?string      $mimeType    optional default MIME type for matching resources
+     * @param ?Annotations $annotations optional annotations describing the resource template
+     */
+    public function __construct(
+        public string $uriTemplate,
+        public ?string $name = null,
+        public ?string $description = null,
+        public ?string $mimeType = null,
+        public ?Annotations $annotations = null,
+    ) {
+    }
+}

src/Capability/Attribute/McpTool.php

@@ -0,0 +1,33 @@
+<?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\Capability\Attribute;
+
+use Mcp\Schema\ToolAnnotations;
+
+/**
+ * @author Kyrian Obikwelu <[email protected]>
+ */
+#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_CLASS)]
+class McpTool
+{
+    /**
+     * @param string|null          $name        The name of the tool (defaults to the method name)
+     * @param string|null          $description The description of the tool (defaults to the DocBlock/inferred)
+     * @param ToolAnnotations|null $annotations Optional annotations describing tool behavior
+     */
+    public function __construct(
+        public ?string $name = null,
+        public ?string $description = null,
+        public ?ToolAnnotations $annotations = null,
+    ) {
+    }
+}