Add attribute-based metadata system for MCP Server components

This commit introduces an attribute-based metadata system for defining MCP Server components (prompts, resources, and tools).

This approach replaces hardcoded lists with self-documenting metadata directly on implementing classes.

Author: butschster

context-generator

@@ -22,6 +22,7 @@ use Butschster\ContextGenerator\Lib\HttpClient\HttpClientFactory;
 use Butschster\ContextGenerator\Lib\HttpClient\HttpClientInterface;
 use Butschster\ContextGenerator\Lib\Logger\ConsoleLogger;
 use Butschster\ContextGenerator\Lib\Logger\LoggerFactory;
+use Butschster\ContextGenerator\McpServer\Registry\McpItemsRegistry;
 use Butschster\ContextGenerator\McpServer\Routing\McpResponseStrategy;
 use Butschster\ContextGenerator\McpServer\Routing\RouteRegistrar;
 use Butschster\ContextGenerator\Modifier\SourceModifierRegistry;
@@ -166,6 +167,7 @@ $container->bindSingleton(Router::class, static function (StrategyInterface $str
     return $router;
 });
 $container->bindSingleton(RouteRegistrar::class, RouteRegistrar::class);
+$container->bindSingleton(McpItemsRegistry::class, McpItemsRegistry::class);
 
 // Register all commands
 $application->add(

src/Console/MCPServerCommand.php

@@ -12,6 +12,7 @@
 use Butschster\ContextGenerator\DocumentCompilerFactory;
 use Butschster\ContextGenerator\McpServer\ServerFactory;
 use Monolog\Handler\RotatingFileHandler;
+use Monolog\Level;
 use Monolog\Logger;
 use Spiral\Core\Container;
 use Symfony\Component\Console\Attribute\AsCommand;
@@ -34,10 +35,17 @@ public function __construct(
     public function __invoke(
         DocumentCompilerFactory $documentCompilerFactory,
         ConfigurationProviderFactory $configurationProviderFactory,
-        ServerFactory $factory,
     ): int {
         $this->setLogger(new Logger('mcp', [
-            new RotatingFileHandler($this->dirs->rootPath . '/mcp.log'),
+            new RotatingFileHandler(
+                filename: $this->dirs->rootPath . '/mcp.log',
+                level: match (true) {
+                    $this->output->isVeryVerbose() => Level::Debug,
+                    $this->output->isVerbose() => Level::Info,
+                    $this->output->isQuiet() => Level::Error,
+                    default => Level::Warning,
+                },
+            ),
         ]));
 
         $this->logger->info('Starting MCP server...');
@@ -92,7 +100,7 @@ public function __invoke(
 
 
         // Create and run the MCP server
-        $server = $factory->create($this->logger);
+        $server = $this->container->get(ServerFactory::class)->create($this->logger);
 
         $server->run(name: $this->input->getOption('name'));
 

src/McpServer/Action/Prompts/AvailableContextPromptAction.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Butschster\ContextGenerator\McpServer\Action\Prompts;
+
+use Butschster\ContextGenerator\McpServer\Attribute\Prompt;
+use Butschster\ContextGenerator\McpServer\Routing\Attribute\Get;
+use Mcp\Types\GetPromptResult;
+use Mcp\Types\PromptMessage;
+use Mcp\Types\Role;
+use Mcp\Types\TextContent;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Log\LoggerInterface;
+
+#[Prompt(
+    name: 'available-context',
+    description: 'Provides a list of available contexts',
+)]
+final readonly class AvailableContextPromptAction
+{
+    public function __construct(
+        private LoggerInterface $logger,
+    ) {}
+
+    #[Get(path: '/prompt/available-context', name: 'prompts.available-context')]
+    public function __invoke(ServerRequestInterface $request): GetPromptResult
+    {
+        $this->logger->info('Getting available-context prompt');
+
+        return new GetPromptResult(
+            messages: [
+                new PromptMessage(
+                    role: Role::USER,
+                    content: new TextContent(
+                        text: "Provide list of available contexts in JSON format",
+                    ),
+                ),
+            ],
+        );
+    }
+}

src/McpServer/Action/Prompts/GetPromptAction.php

@@ -4,33 +4,29 @@
 
 namespace Butschster\ContextGenerator\McpServer\Action\Prompts;
 
+use Butschster\ContextGenerator\McpServer\Registry\McpItemsRegistry;
 use Butschster\ContextGenerator\McpServer\Routing\Attribute\Get;
 use Mcp\Types\ListPromptsResult;
-use Mcp\Types\Prompt;
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Log\LoggerInterface;
 
 final readonly class ListPromptsAction
 {
     public function __construct(
         private LoggerInterface $logger,
+        private McpItemsRegistry $registry,
     ) {}
 
     #[Get(path: '/prompts/list', name: 'prompts.list')]
     public function __invoke(ServerRequestInterface $request): ListPromptsResult
     {
         $this->logger->info('Listing available prompts');
 
-        // Return available prompts in a format that can be converted to ListPromptsResult
-        return new ListPromptsResult([
-            new Prompt(
-                name: 'available-context',
-                description: 'Provides a list of available contexts',
-            ),
-            new Prompt(
-                name: 'project-structure',
-                description: 'Tries to guess the project structure',
-            ),
-        ]);
+        $prompts = [];
+        foreach ($this->registry->getPrompts() as $prompt) {
+            $prompts[] = $prompt;
+        }
+
+        return new ListPromptsResult($prompts);
     }
 }

src/McpServer/Action/Prompts/ListPromptsAction.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Butschster\ContextGenerator\McpServer\Action\Prompts;
+
+use Butschster\ContextGenerator\McpServer\Attribute\Prompt;
+use Butschster\ContextGenerator\McpServer\Routing\Attribute\Get;
+use Mcp\Types\GetPromptResult;
+use Mcp\Types\PromptMessage;
+use Mcp\Types\Role;
+use Mcp\Types\TextContent;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Log\LoggerInterface;
+
+#[Prompt(
+    name: 'project-structure',
+    description: 'Tries to guess the project structure',
+)]
+final readonly class ProjectStructurePromptAction
+{
+    public function __construct(
+        private LoggerInterface $logger,
+    ) {}
+
+    #[Get(path: '/prompt/project-structure', name: 'prompts.project-structure')]
+    public function __invoke(ServerRequestInterface $request): GetPromptResult
+    {
+        $this->logger->info('Getting project-structure prompt');
+
+        return new GetPromptResult(
+            messages: [
+                new PromptMessage(
+                    role: Role::USER,
+                    content: new TextContent(
+                        text: "Look at available contexts and try to find the project structure. If there is no context for structure. Request structure from context using JSON schema. Provide the result in JSON format",
+                    ),
+                ),
+            ],
+        );
+    }
+}

src/McpServer/Action/Prompts/ProjectStructurePromptAction.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Butschster\ContextGenerator\McpServer\Action\Resources;
+
+use Butschster\ContextGenerator\Directories;
+use Butschster\ContextGenerator\FilesInterface;
+use Butschster\ContextGenerator\McpServer\Attribute\Resource;
+use Butschster\ContextGenerator\McpServer\Routing\Attribute\Get;
+use Mcp\Types\ReadResourceResult;
+use Mcp\Types\TextResourceContents;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Log\LoggerInterface;
+
+#[Resource(
+    name: 'Json Schema of context generator',
+    description: 'Returns a simplified JSON schema of the context generator',
+    uri: 'ctx://json-schema',
+    mimeType: 'application/json',
+)]
+final readonly class JsonSchemaResourceAction
+{
+    public function __construct(
+        private LoggerInterface $logger,
+        private FilesInterface $files,
+        private Directories $dirs,
+    ) {}
+
+    #[Get(path: '/resource/ctx/json-schema', name: 'resources.ctx.json-schema')]
+    public function __invoke(ServerRequestInterface $request): ReadResourceResult
+    {
+        $this->logger->info('Getting JSON schema');
+
+        return new ReadResourceResult([
+            new TextResourceContents(
+                text: $this->getJsonSchema(),
+                uri: 'ctx://json-schema',
+                mimeType: 'application/json',
+            ),
+        ]);
+    }
+
+    /**
+     * Get simplified JSON schema
+     */
+    private function getJsonSchema(): string
+    {
+        $schema = \json_decode(
+            $this->files->read($this->dirs->jsonSchemaPath),
+            associative: true,
+        );
+
+        unset(
+            $schema['properties']['import'],
+            $schema['properties']['settings'],
+            $schema['definitions']['document']['properties']['modifiers'],
+            $schema['definitions']['source']['properties']['modifiers'],
+            $schema['definitions']['urlSource'],
+            $schema['definitions']['githubSource'],
+            $schema['definitions']['textSource'],
+            $schema['definitions']['composerSource'],
+            $schema['definitions']['php-content-filter'],
+            $schema['definitions']['php-docs'],
+            $schema['definitions']['sanitizer'],
+            $schema['definitions']['modifiers'],
+            $schema['definitions']['visibilityOptions'],
+        );
+
+        $schema['definitions']['source']['properties']['type']['enum'] = ['file', 'tree', 'git_diff'];
+
+        return (string) \json_encode($schema);
+    }
+}

src/McpServer/Action/Resources/JsonSchemaResourceAction.php

@@ -5,6 +5,7 @@
 namespace Butschster\ContextGenerator\McpServer\Action\Resources;
 
 use Butschster\ContextGenerator\ConfigLoader\ConfigLoaderInterface;
+use Butschster\ContextGenerator\McpServer\Registry\McpItemsRegistry;
 use Butschster\ContextGenerator\McpServer\Routing\Attribute\Get;
 use Mcp\Types\ListResourcesResult;
 use Mcp\Types\Resource;
@@ -16,29 +17,23 @@
     public function __construct(
         private LoggerInterface $logger,
         private ConfigLoaderInterface $configLoader,
+        private McpItemsRegistry $registry,
     ) {}
 
     #[Get(path: '/resources/list', name: 'resources.list')]
     public function __invoke(ServerRequestInterface $request): ListResourcesResult
     {
         $this->logger->info('Listing available resources');
 
-        $documents = $this->configLoader->load();
-        $resources = [
-            new Resource(
-                name: 'List of available contexts',
-                uri: 'ctx://list',
-                description: 'Returns a list of available contexts of project in document format',
-                mimeType: 'text/markdown',
-            ),
-            new Resource(
-                name: 'Json Schema of context generator',
-                uri: 'ctx://json-schema',
-                description: 'Returns a simplified JSON schema of the context generator',
-                mimeType: 'application/json',
-            ),
-        ];
+        $resources = [];
+
+        // Get resources from registry
+        foreach ($this->registry->getResources() as $resource) {
+            $resources[] = $resource;
+        }
 
+        // Add document resources from config loader
+        $documents = $this->configLoader->load();
         foreach ($documents->getItems() as $document) {
             $resources[] = new Resource(
                 name: $document->outputPath,

src/McpServer/Action/Resources/ListResourcesAction.php

@@ -6,12 +6,24 @@
 
 use Butschster\ContextGenerator\Directories;
 use Butschster\ContextGenerator\FilesInterface;
+use Butschster\ContextGenerator\McpServer\Attribute\InputSchema;
+use Butschster\ContextGenerator\McpServer\Attribute\Tool;
 use Butschster\ContextGenerator\McpServer\Routing\Attribute\Post;
 use Mcp\Types\CallToolResult;
 use Mcp\Types\TextContent;
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Log\LoggerInterface;
 
+#[Tool(
+    name: 'file-info',
+    description: 'Get information about a file within the project directory structure',
+)]
+#[InputSchema(
+    name: 'path',
+    type: 'string',
+    description: 'Path to the file, relative to project root. Only files within project directory can be accessed.',
+    required: true,
+)]
 final readonly class FileInfoAction
 {
     public function __construct(