IBX-11536: MCP Servers

code_samples/mcp/config/packages/mcp.yaml

@@ -0,0 +1,20 @@
+ibexa:
+    repositories:
+        default:
+            mcp:
+                example:
+                    path: /mcp/example
+                    enabled: true
+                    description: 'Example MCP Server'
+                    instructions: 'Use this server to greet someone.'
+                    tools:
+                        - App\Mcp\ExampleTools
+                    discovery_cache: cache.tagaware.filesystem
+                    session:
+                        type: file
+                        directory: '%kernel.cache_dir%/mcp/sessions'
+    system:
+        default:
+            mcp:
+                servers:
+                    - example

code_samples/mcp/mcp.sh

@@ -0,0 +1,60 @@
+baseUrl='http://localhost' # Adapt to your test case
+
+jwtToken=$(curl -s -X 'POST' \
+  "$baseUrl/api/ibexa/v2/user/token/jwt" \
+  -H 'Content-Type: application/json' \
+  -d '{
+        "JWTInput": {
+          "_media-type": "application/vnd.ibexa.api.JWTInput",
+          "username": "admin",
+          "password": "publish"
+        }
+      }' | jq -r .JWT.token)
+
+mcpSessionId=$(curl -s -i -X 'POST' "$baseUrl/mcp/example" \
+  -H "Authorization: Bearer $jwtToken" \
+  -d '{
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+          "protocolVersion": "2025-03-26",
+          "capabilities": {},
+          "clientInfo": {
+            "name": "test-curl-client",
+            "version": "1.0.0"
+          }
+        }
+      }' | grep 'Mcp-Session-Id:' | sed 's/Mcp-Session-Id: \([0-9a-f-]*\).*/\1/')
+
+curl -s -i -X 'POST' "$baseUrl/mcp/example" \
+  -H "Authorization: Bearer $jwtToken" \
+  -H "Mcp-Session-Id: $mcpSessionId" \
+  -d '{
+        "jsonrpc": "2.0",
+        "method": "notifications/initialized"
+      }'
+
+curl -s -X 'POST' "$baseUrl/mcp/example" \
+  -H "Authorization: Bearer $jwtToken" \
+  -H "Mcp-Session-Id: $mcpSessionId" \
+  -d '{
+        "jsonrpc": "2.0",
+        "id": 2,
+        "method": "tools/list"
+      }' | jq
+
+curl -s -X 'POST' "$baseUrl/mcp/example" \
+  -H "Authorization: Bearer $jwtToken" \
+  -H "Mcp-Session-Id: $mcpSessionId" \
+  -d '{
+        "jsonrpc": "2.0",
+        "id": 3,
+        "method": "tools/call",
+        "params": {
+          "name": "greet",
+          "arguments": {
+            "name": "World"
+          }
+        }
+      }' | jq

code_samples/mcp/src/Command/McpServerListCommand.php

@@ -0,0 +1,26 @@
+<?php declare(strict_types=1);
+
+namespace App\mcp\src\Command;
+
+use Ibexa\Contracts\Mcp\McpServerConfigurationRegistryInterface;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Style\SymfonyStyle;
+
+#[AsCommand(name: 'app:mcp:server_list', description: 'List MCP servers')]
+class McpServerListCommand
+{
+    public function __construct(private readonly McpServerConfigurationRegistryInterface $configRegistry)
+    {
+    }
+
+    public function __invoke(SymfonyStyle $io): int
+    {
+        foreach($this->configRegistry->getServerConfigurations() as $serverConfiguration) {
+            $io->title($serverConfiguration->identifier);
+            dump($serverConfiguration);
+        }
+
+        return Command::SUCCESS;
+    }
+}

code_samples/mcp/src/Mcp/ExampleTools.php

@@ -0,0 +1,29 @@
+<?php declare(strict_types=1);
+
+namespace App\Mcp;
+
+use Ibexa\Contracts\Mcp\Attribute\McpTool;
+use Ibexa\Contracts\Mcp\McpCapabilityInterface;
+use Mcp\Schema\Icon;
+use Mcp\Schema\ToolAnnotations;
+
+final readonly class ExampleTools implements McpCapabilityInterface
+{
+    #[McpTool(
+        name: 'greet',
+        description: 'Greet a user by name',
+        icons: [new Icon(
+            src: 'https://openmoji.org/data/color/svg/1F44B.svg',
+        )],
+        annotations: new ToolAnnotations(
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        ),
+    )]
+    public function greetByName(string $name): string
+    {
+        return sprintf('Hello, %s!', $name);
+    }
+}

composer.json

@@ -34,6 +34,7 @@
         "ibexa/core-persistence": "5.0.x-dev",
         "ibexa/connector-ai": "5.0.x-dev",
         "ibexa/connector-openai": "5.0.x-dev",
+        "ibexa/mcp": "5.0.x-dev",
         "ibexa/migrations": "5.0.x-dev",
         "ibexa/cart": "5.0.x-dev",
         "ibexa/installer": "5.0.x-dev",

docs/ai/ai.md

@@ -0,0 +1,19 @@
+---
+description: AI interactions with Ibexa DXP
+page_type: landing_page
+month_change: true
+---
+
+# Artificial Intelligence (AI)
+
+[[= product_name =]] embed AI capabilities, for example,
+to make recommendations to product customers and content readers with [Raptor connector][[#(raptor_connector_guide.md)#]],
+or to help editors in the back office with [AI Actions](ai_actions_guide.md).
+It's also opened to external AI capabilities with the exposition of [Model Context Protocol (MCP) servers](mcp_guide.md) to allow agents to interact with the system.
+It's extensible. For example, new AI actions or MCP servers can be implemented.
+To go further, an AI can learn to use the REST API, or learn the PHP API and help you in your development.
+
+[[= cards([
+    "ai/ai_actions/ai_actions",
+    "ai/mcp/mcp",
+], columns=2) =]]

docs/ai_actions/ai_actions.md → docs/ai/ai_actions/ai_actions.md

@@ -14,8 +14,8 @@ You can also extend it to perform other tasks or support additional AI services.
 ##  Getting Started
 
 [[= cards([
-"ai_actions/ai_actions_guide",
-"ai_actions/configure_ai_actions",
+"ai/ai_actions/ai_actions_guide",
+"ai/ai_actions/configure_ai_actions",
 ("content_management/taxonomy/taxonomy#taxonomy-suggestions", "Taxonomy suggestions", "Learn how to use AI to suggest tags and categories"),
 ("permissions/policies#ai-actions", "Policies", "Learn about the available AI Actions policies"),
 ("https://doc.ibexa.co/projects/userguide/en/5.0/ai_actions/work_with_ai_actions/"),
@@ -24,12 +24,11 @@ You can also extend it to perform other tasks or support additional AI services.
 ## Development
 
 [[= cards([
-"ai_actions/extend_ai_actions",
+"ai/ai_actions/extend_ai_actions",
 "api/event_reference/ai_action_events",
 ("https://doc.ibexa.co/en/5.0/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Connector-AI", "REST API Reference", "See the available endpoints for AI Actions"),
 "templating/twig_function_reference/ai_actions_twig_functions",
 "search/ai_actions_search_reference/action_configuration_criteria",
 "search/ai_actions_search_reference/action_configuration_sort_clauses",
 ("content_management/data_migration/importing_data#ai-action-configurations", "Importing AI actions", "Learn how to manage Action Configurations using data migrations"),
 ], columns=4) =]]
-

docs/ai_actions/ai_actions_guide.md → docs/ai/ai_actions/ai_actions_guide.md

@@ -115,7 +115,7 @@ Procedures are straightforward and intuitive, ensuring that users can quickly ac
 
 AI Actions feature exposes a REST API interface that allows for programmatic execution of AI actions.
 With the API, developers can automate tasks and execute actions on batches of content by integrating them into workflows.
-For more information, see the [AI actions section in the REST API Reference](../api/rest_api/rest_api_reference/rest_api_reference.html#ai-actions-execute-ai-action).
+For more information, see the [AI actions section in the REST API Reference](/api/rest_api/rest_api_reference/rest_api_reference.html#ai-actions-execute-ai-action).
 
 ## Capabilities
 

docs/ai_actions/extend_ai_actions.md → docs/ai/ai_actions/extend_ai_actions.md

@@ -244,7 +244,7 @@ The Action Type options provided in the Action Context dictate whether the times
 ### Integrate with the REST API
 
 At this point the custom Action Type can already be executed by using the PHP API.
-To integrate it with the [AI Actions execute endpoint](../api/rest_api/rest_api_reference/rest_api_reference.html#ai-actions-execute-ai-action) you need to create additional classes responsible for parsing the request and response data.
+To integrate it with the [AI Actions execute endpoint](/api/rest_api/rest_api_reference/rest_api_reference.html#ai-actions-execute-ai-action) you need to create additional classes responsible for parsing the request and response data.
 See [adding custom media type](adding_custom_media_type.md) and [creating new REST resource](creating_new_rest_resource.md) to learn more about extending the REST API.
 
 #### Handle input data

docs/ai/mcp/mcp.md

@@ -0,0 +1,15 @@
+---
+description: TODO.
+page_type: landing_page
+month_change: true
+---
+
+# MCP Servers
+
+MCP servers allow AI interactions with the system.
+Learn more about this protocol and [[= product_name_base =]] MCP Servers:
+
+[[= cards([
+    ("ai/mcp/mcp_guide", "MCP Servers guide", "TODO."),
+    "ai/mcp/mcp_config",
+], columns=2) =]]