diff --git a/CHANGELOG.md b/CHANGELOG.md index 23f55bb4..b6667b03 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ All notable changes to `mcp/sdk` will be documented in this file. * Add validation of the input parameters given to a Tool. * Rename `Mcp\Capability\Registry\ResourceReference::$schema` to `Mcp\Capability\Registry\ResourceReference::$resource`. * Introduce `SchemaGeneratorInterface` and `DiscovererInterface` to allow custom schema generation and discovery implementations. +* Remove `DocBlockParser::getSummary()` method, use `DocBlockParser::getDescription()` instead. 0.2.2 ----- diff --git a/src/Capability/Discovery/Discoverer.php b/src/Capability/Discovery/Discoverer.php index b880a89d..3b9ed3a9 100644 --- a/src/Capability/Discovery/Discoverer.php +++ b/src/Capability/Discovery/Discoverer.php @@ -222,7 +222,7 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun case McpTool::class: $docBlock = $this->docBlockParser->parseDocBlock($method->getDocComment() ?? null); $name = $instance->name ?? ('__invoke' === $methodName ? $classShortName : $methodName); - $description = $instance->description ?? $this->docBlockParser->getSummary($docBlock) ?? null; + $description = $instance->description ?? $this->docBlockParser->getDescription($docBlock) ?? null; $inputSchema = $this->schemaGenerator->generate($method); $outputSchema = $this->schemaGenerator->generateOutputSchema($method); $tool = new Tool( @@ -241,7 +241,7 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun case McpResource::class: $docBlock = $this->docBlockParser->parseDocBlock($method->getDocComment() ?? null); $name = $instance->name ?? ('__invoke' === $methodName ? $classShortName : $methodName); - $description = $instance->description ?? $this->docBlockParser->getSummary($docBlock) ?? null; + $description = $instance->description ?? $this->docBlockParser->getDescription($docBlock) ?? null; $resource = new Resource( $instance->uri, $name, @@ -260,7 +260,7 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun case McpPrompt::class: $docBlock = $this->docBlockParser->parseDocBlock($method->getDocComment() ?? null); $name = $instance->name ?? ('__invoke' === $methodName ? $classShortName : $methodName); - $description = $instance->description ?? $this->docBlockParser->getSummary($docBlock) ?? null; + $description = $instance->description ?? $this->docBlockParser->getDescription($docBlock) ?? null; $arguments = []; $paramTags = $this->docBlockParser->getParamTags($docBlock); foreach ($method->getParameters() as $param) { @@ -280,7 +280,7 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun case McpResourceTemplate::class: $docBlock = $this->docBlockParser->parseDocBlock($method->getDocComment() ?? null); $name = $instance->name ?? ('__invoke' === $methodName ? $classShortName : $methodName); - $description = $instance->description ?? $this->docBlockParser->getSummary($docBlock) ?? null; + $description = $instance->description ?? $this->docBlockParser->getDescription($docBlock) ?? null; $mimeType = $instance->mimeType; $annotations = $instance->annotations; $meta = $instance->meta ?? null; diff --git a/src/Capability/Discovery/DocBlockParser.php b/src/Capability/Discovery/DocBlockParser.php index 91f417f2..5c867e80 100644 --- a/src/Capability/Discovery/DocBlockParser.php +++ b/src/Capability/Discovery/DocBlockParser.php @@ -55,19 +55,6 @@ public function parseDocBlock(string|false|null $docComment): ?DocBlock } } - /** - * Gets the summary line from a DocBlock. - */ - public function getSummary(?DocBlock $docBlock): ?string - { - if (!$docBlock) { - return null; - } - $summary = trim($docBlock->getSummary()); - - return $summary ?: null; // Return null if empty after trimming - } - /** * Gets the description from a DocBlock (summary + description body). */ diff --git a/src/Capability/Registry/Loader/ArrayLoader.php b/src/Capability/Registry/Loader/ArrayLoader.php index cd327b66..7be19b64 100644 --- a/src/Capability/Registry/Loader/ArrayLoader.php +++ b/src/Capability/Registry/Loader/ArrayLoader.php @@ -108,7 +108,7 @@ public function load(RegistryInterface $registry): void $docBlock = $docBlockParser->parseDocBlock($reflection->getDocComment() ?? null); $name = $data['name'] ?? ('__invoke' === $methodName ? $classShortName : $methodName); - $description = $data['description'] ?? $docBlockParser->getSummary($docBlock) ?? null; + $description = $data['description'] ?? $docBlockParser->getDescription($docBlock) ?? null; } $inputSchema = $data['inputSchema'] ?? $schemaGenerator->generate($reflection); @@ -149,7 +149,7 @@ public function load(RegistryInterface $registry): void $docBlock = $docBlockParser->parseDocBlock($reflection->getDocComment() ?? null); $name = $data['name'] ?? ('__invoke' === $methodName ? $classShortName : $methodName); - $description = $data['description'] ?? $docBlockParser->getSummary($docBlock) ?? null; + $description = $data['description'] ?? $docBlockParser->getDescription($docBlock) ?? null; } $resource = new Resource( @@ -189,7 +189,7 @@ public function load(RegistryInterface $registry): void $docBlock = $docBlockParser->parseDocBlock($reflection->getDocComment() ?? null); $name = $data['name'] ?? ('__invoke' === $methodName ? $classShortName : $methodName); - $description = $data['description'] ?? $docBlockParser->getSummary($docBlock) ?? null; + $description = $data['description'] ?? $docBlockParser->getDescription($docBlock) ?? null; } $template = new ResourceTemplate( @@ -228,7 +228,7 @@ public function load(RegistryInterface $registry): void $docBlock = $docBlockParser->parseDocBlock($reflection->getDocComment() ?? null); $name = $data['name'] ?? ('__invoke' === $methodName ? $classShortName : $methodName); - $description = $data['description'] ?? $docBlockParser->getSummary($docBlock) ?? null; + $description = $data['description'] ?? $docBlockParser->getDescription($docBlock) ?? null; } $arguments = []; diff --git a/tests/Inspector/Http/snapshots/HttpCombinedRegistrationTest-resources_list.json b/tests/Inspector/Http/snapshots/HttpCombinedRegistrationTest-resources_list.json index 2d0c6ce2..2c7912e4 100644 --- a/tests/Inspector/Http/snapshots/HttpCombinedRegistrationTest-resources_list.json +++ b/tests/Inspector/Http/snapshots/HttpCombinedRegistrationTest-resources_list.json @@ -3,7 +3,7 @@ { "name": "priority_config_discovered", "uri": "config://priority", - "description": "A resource discovered via attributes." + "description": "A resource discovered via attributes.\n\nThis will be overridden by a manual registration with the same URI." } ] } diff --git a/tests/Inspector/Http/snapshots/HttpComplexToolSchemaTest-tools_list.json b/tests/Inspector/Http/snapshots/HttpComplexToolSchemaTest-tools_list.json index 58815df7..2a7698a8 100644 --- a/tests/Inspector/Http/snapshots/HttpComplexToolSchemaTest-tools_list.json +++ b/tests/Inspector/Http/snapshots/HttpComplexToolSchemaTest-tools_list.json @@ -2,7 +2,7 @@ "tools": [ { "name": "schedule_event", - "description": "Schedules a new event.", + "description": "Schedules a new event.\n\nThe inputSchema for this tool will reflect all parameter types and defaults.", "inputSchema": { "type": "object", "properties": { diff --git a/tests/Inspector/Http/snapshots/HttpDiscoveryUserProfileTest-tools_list.json b/tests/Inspector/Http/snapshots/HttpDiscoveryUserProfileTest-tools_list.json index f515430e..205ad0ce 100644 --- a/tests/Inspector/Http/snapshots/HttpDiscoveryUserProfileTest-tools_list.json +++ b/tests/Inspector/Http/snapshots/HttpDiscoveryUserProfileTest-tools_list.json @@ -25,7 +25,7 @@ }, { "name": "send_welcome", - "description": "Sends a welcome message to a user.", + "description": "Sends a welcome message to a user.\n\n(This is a placeholder - in a real app, it might queue an email).", "inputSchema": { "type": "object", "properties": { diff --git a/tests/Inspector/Http/snapshots/HttpSchemaShowcaseTest-tools_list.json b/tests/Inspector/Http/snapshots/HttpSchemaShowcaseTest-tools_list.json index 9b9b90e7..f79bfeba 100644 --- a/tests/Inspector/Http/snapshots/HttpSchemaShowcaseTest-tools_list.json +++ b/tests/Inspector/Http/snapshots/HttpSchemaShowcaseTest-tools_list.json @@ -32,7 +32,7 @@ }, { "name": "calculate_range", - "description": "Performs mathematical operations with numeric constraints.", + "description": "Performs mathematical operations with numeric constraints.\n\nDemonstrates: METHOD-LEVEL Schema", "inputSchema": { "type": "object", "properties": { diff --git a/tests/Inspector/Stdio/snapshots/StdioDiscoveryCalculatorTest-tools_list.json b/tests/Inspector/Stdio/snapshots/StdioDiscoveryCalculatorTest-tools_list.json index 5f184117..8ada3477 100644 --- a/tests/Inspector/Stdio/snapshots/StdioDiscoveryCalculatorTest-tools_list.json +++ b/tests/Inspector/Stdio/snapshots/StdioDiscoveryCalculatorTest-tools_list.json @@ -2,7 +2,7 @@ "tools": [ { "name": "calculate", - "description": "Performs a calculation based on the operation.", + "description": "Performs a calculation based on the operation.\n\nSupports 'add', 'subtract', 'multiply', 'divide'.\nObeys the 'precision' and 'allow_negative' settings from the config resource.", "icons": [ { "mimeType": "image/svg+xml", @@ -37,7 +37,7 @@ }, { "name": "update_setting", - "description": "Updates a specific configuration setting.", + "description": "Updates a specific configuration setting.\n\nNote: This requires more robust validation in a real app.", "inputSchema": { "type": "object", "properties": { diff --git a/tests/Inspector/Stdio/snapshots/StdioEnvVariablesTest-tools_list.json b/tests/Inspector/Stdio/snapshots/StdioEnvVariablesTest-tools_list.json index f5d19c41..cfa18f09 100644 --- a/tests/Inspector/Stdio/snapshots/StdioEnvVariablesTest-tools_list.json +++ b/tests/Inspector/Stdio/snapshots/StdioEnvVariablesTest-tools_list.json @@ -2,7 +2,7 @@ "tools": [ { "name": "process_data_by_mode", - "description": "Performs an action that can be modified by an environment variable.", + "description": "Performs an action that can be modified by an environment variable.\n\nThe MCP client should set 'APP_MODE' in its 'env' config for this server.", "inputSchema": { "type": "object", "properties": { diff --git a/tests/Unit/Capability/Discovery/DocBlockParserTest.php b/tests/Unit/Capability/Discovery/DocBlockParserTest.php index df914755..ce924b57 100644 --- a/tests/Unit/Capability/Discovery/DocBlockParserTest.php +++ b/tests/Unit/Capability/Discovery/DocBlockParserTest.php @@ -27,19 +27,6 @@ protected function setUp(): void $this->parser = new DocBlockParser(); } - public function testGetSummaryReturnsCorrectSummary() - { - $method = new \ReflectionMethod(DocBlockTestFixture::class, 'methodWithSummaryOnly'); - $docComment = $method->getDocComment() ?: null; - $docBlock = $this->parser->parseDocBlock($docComment); - $this->assertEquals('Simple summary line.', $this->parser->getSummary($docBlock)); - - $method2 = new \ReflectionMethod(DocBlockTestFixture::class, 'methodWithSummaryAndDescription'); - $docComment2 = $method2->getDocComment() ?: null; - $docBlock2 = $this->parser->parseDocBlock($docComment2); - $this->assertEquals('Summary line here.', $this->parser->getSummary($docBlock2)); - } - public function testGetDescriptionReturnsCorrectDescription() { $method = new \ReflectionMethod(DocBlockTestFixture::class, 'methodWithSummaryAndDescription'); @@ -129,7 +116,6 @@ public function testHandlesMethodWithNoDocblockGracefully() $docBlock = $this->parser->parseDocBlock($docComment); $this->assertNull($docBlock); - $this->assertNull($this->parser->getSummary($docBlock)); $this->assertNull($this->parser->getDescription($docBlock)); $this->assertEmpty($this->parser->getParamTags($docBlock)); }