feat: MCP tools and prompt factory

composer.json

@@ -23,6 +23,7 @@
         "illuminate/collections": "^11.23",
         "mozex/anthropic-php": "^1.1",
         "openai-php/client": "^0.15",
+        "php-mcp/client": "^1.0",
         "psr-discovery/cache-implementations": "^1.2",
         "psr-discovery/event-dispatcher-implementations": "^1.1",
         "react/async": "^4.3",

config/cortex.php

@@ -193,6 +193,42 @@
         ],
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | MCP Servers
+    |--------------------------------------------------------------------------
+    |
+    | Specify any MCP servers that you wish to use.
+    |
+    */
+    'mcp_servers' => [
+        'default' => env('CORTEX_DEFAULT_MCP_SERVER', 'local_http'),
+
+        /*
+         * Example from https://github.com/modelcontextprotocol/servers/tree/main/src/everything
+         * Feel free to remove this and add something actually useful!
+         */
+        'local_http' => [
+            'transport' => 'http',
+            'url' => 'http://localhost:3001/sse',
+        ],
+
+        // 'tavily' => [
+        //     'transport' => 'http',
+        //     'url' => 'https://mcp.tavily.com/mcp/?tavilyApiKey=' . env('TAVILY_API_KEY'),
+        // ],
+
+        // 'tavily' => [
+        //     'transport' => 'stdio',
+        //     'command' => 'npx',
+        //     'args' => [
+        //         '-y',
+        //         'mcp-remote',
+        //         'https://mcp.tavily.com/mcp/?tavilyApiKey=' . env('TAVILY_API_KEY'),
+        //     ],
+        // ],
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | Prompt Factories
@@ -218,9 +254,10 @@
             ],
         ],
 
-        // 'mcp' => [
-        //     'base_uri' => env('MCP_BASE_URI', 'http://localhost:3000'),
-        // ],
+        'mcp' => [
+            /** References an MCP server defined above. */
+            'server' => env('CORTEX_MCP_PROMPT_SERVER', 'local_http'),
+        ],
     ],
 
     /*

src/CortexServiceProvider.php

@@ -6,6 +6,7 @@
 
 use Cortex\LLM\LLMManager;
 use Cortex\LLM\Contracts\LLM;
+use Cortex\Mcp\McpServerManager;
 use Cortex\ModelInfo\ModelInfoFactory;
 use Spatie\LaravelPackageTools\Package;
 use Cortex\Embeddings\EmbeddingsManager;
@@ -32,6 +33,9 @@ public function packageRegistered(): void
         $this->app->alias('cortex.embeddings', EmbeddingsManager::class);
         $this->app->bind(Embeddings::class, fn(Container $app) => $app->make('cortex.embeddings')->driver());
 
+        $this->app->singleton('cortex.mcp_server', fn(Container $app): McpServerManager => new McpServerManager($app));
+        $this->app->alias('cortex.mcp_server', McpServerManager::class);
+
         $this->app->singleton('cortex.prompt_factory', fn(Container $app): PromptFactoryManager => new PromptFactoryManager($app));
         $this->app->alias('cortex.prompt_factory', PromptFactoryManager::class);
         $this->app->bind(PromptFactory::class, fn(Container $app) => $app->make('cortex.prompt_factory')->driver());

src/Facades/McpServer.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cortex\Facades;
+
+use Illuminate\Support\Facades\Facade;
+
+/**
+ * @method static \PhpMcp\Client\Client driver(string $driver = null)
+ *
+ * @see \Cortex\Mcp\McpServerManager
+ */
+class McpServer extends Facade
+{
+    protected static function getFacadeAccessor(): string
+    {
+        return 'cortex.mcp_server';
+    }
+}

src/LLM/Contracts/Tool.php

@@ -37,7 +37,7 @@ public function format(): array;
      *
      * @param ToolCall|array<int, mixed> $arguments
      */
-    public function invoke(ToolCall|array $arguments): mixed;
+    public function invoke(ToolCall|array $arguments = []): mixed;
 
     /**
      * Invoke the tool as a tool message.

src/Mcp/McpServerManager.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cortex\Mcp;
+
+use Override;
+use PhpMcp\Client\Client;
+use Illuminate\Support\Arr;
+use InvalidArgumentException;
+use Illuminate\Support\Manager;
+use PhpMcp\Client\ServerConfig;
+
+class McpServerManager extends Manager
+{
+    public function getDefaultDriver(): string
+    {
+        return $this->config->get('cortex.mcp_servers.default');
+    }
+
+    #[Override]
+    protected function createDriver($driver): Client // @pest-ignore-type
+    {
+        $config = $this->config->get('cortex.mcp_servers.' . $driver);
+
+        if ($config === null) {
+            throw new InvalidArgumentException(sprintf('Driver [%s] not supported.', $driver));
+        }
+
+        $serverConfig = ServerConfig::fromArray($driver, [
+            'transport' => Arr::get($config, 'transport'),
+            'url' => Arr::get($config, 'url'),
+            'command' => Arr::get($config, 'command'),
+            'args' => Arr::get($config, 'args'),
+            'headers' => Arr::get($config, 'headers'),
+            'sessionId' => Arr::get($config, 'sessionId'),
+            'timeout' => Arr::get($config, 'timeout'),
+            'env' => Arr::get($config, 'env'),
+        ]);
+
+        $clientBuilder = Client::make()
+            ->withClientInfo('cortex-php', '1.0.0')
+            ->withServerConfig($serverConfig);
+
+        // if ($config['cache'] ?? false) {
+        //     $clientBuilder->withCache(
+        //         $this->container->make('cache')->store($config['cache']['store'] ?? null),
+        //         $config['cache']['ttl'] ?? 3600,
+        //     );
+        // }
+
+        return $clientBuilder->build();
+    }
+}

src/Prompts/Factories/McpPromptFactory.php

@@ -4,22 +4,143 @@
 
 namespace Cortex\Prompts\Factories;
 
+use Throwable;
+use PhpMcp\Client\Client;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Str;
+use Cortex\LLM\Contracts\Message;
+use Cortex\JsonSchema\SchemaFactory;
+use Cortex\Exceptions\PromptException;
+use Cortex\JsonSchema\Types\ObjectSchema;
+use Cortex\LLM\Data\Messages\UserMessage;
 use Cortex\Prompts\Contracts\PromptFactory;
 use Cortex\Prompts\Contracts\PromptTemplate;
-use Cortex\Prompts\Templates\ChatPromptTemplate;
+use Cortex\LLM\Data\Messages\AssistantMessage;
+use Cortex\Prompts\Builders\ChatPromptBuilder;
+use PhpMcp\Client\Model\Content\PromptMessage;
+use Cortex\LLM\Data\Messages\Content\TextContent;
+use Cortex\LLM\Data\Messages\Content\AudioContent;
+use Cortex\LLM\Data\Messages\Content\ImageContent;
+use PhpMcp\Client\JsonRpc\Results\GetPromptResult;
+use PhpMcp\Client\Model\Definitions\PromptDefinition;
+use PhpMcp\Client\Model\Definitions\PromptArgumentDefinition;
 
 /**
  * @link https://modelcontextprotocol.io/docs/concepts/prompts
  */
 class McpPromptFactory implements PromptFactory
 {
     public function __construct(
-        protected string $baseUri,
+        protected Client $client,
     ) {}
 
     public function make(string $name, array $config = []): PromptTemplate
     {
-        // TODO: Implement
-        return new ChatPromptTemplate([]);
+        try {
+            $this->client->initialize();
+            $promptDefinition = $this->getPromptDefinition($name);
+            $compiledPrompt = $this->getCompiledPrompt($promptDefinition);
+        } finally {
+            $this->client->disconnect();
+        }
+
+        $builder = new ChatPromptBuilder();
+
+        if ($promptDefinition->isTemplate()) {
+            $builder->inputSchema($this->buildInputSchema($promptDefinition));
+        }
+
+        return $builder->messages($this->buildMessages($compiledPrompt))->build();
+    }
+
+    /**
+     * Builds an input schema for the given prompt definition.
+     */
+    protected function buildInputSchema(PromptDefinition $prompt): ObjectSchema
+    {
+        $inputSchema = new ObjectSchema($prompt->name);
+
+        if ($prompt->description !== null) {
+            $inputSchema->description($prompt->description);
+        }
+
+        $properties = [];
+
+        foreach ($prompt->arguments as $argument) {
+            $property = SchemaFactory::string($argument->name)
+                ->description($argument->description);
+
+            if ($argument->required) {
+                $property = $property->required();
+            }
+
+            $properties[] = $property;
+        }
+
+        return $inputSchema->properties(...$properties);
+    }
+
+    /**
+     * Get the prompt definition for the given name.
+     *
+     * @throws \Cortex\Exceptions\PromptException
+     */
+    protected function getPromptDefinition(string $name): PromptDefinition
+    {
+        try {
+            /** @var array<array-key, \PhpMcp\Client\Model\Definitions\PromptDefinition> $prompts */
+            $prompts = $this->client->listPrompts();
+        } catch (Throwable $e) {
+            throw new PromptException('Failed to list prompts: ' . $e->getMessage(), previous: $e);
+        }
+
+        $prompt = collect($prompts)->firstWhere('name', $name);
+
+        if ($prompt === null) {
+            throw new PromptException('Prompt not found: ' . $name);
+        }
+
+        return $prompt;
+    }
+
+    /**
+     * Get the compiled prompt for the given prompt definition.
+     */
+    protected function getCompiledPrompt(PromptDefinition $prompt): GetPromptResult
+    {
+        if ($prompt->isTemplate()) {
+            $arguments = collect($prompt->arguments)->mapWithKeys(fn(PromptArgumentDefinition $argument) => [
+                $argument->name => Str::of($argument->name)->prepend('{')->append('}')->toString(),
+            ])->toArray();
+
+            return $this->client->getPrompt($prompt->name, $arguments);
+        }
+
+        return $this->client->getPrompt($prompt->name);
+    }
+
+    /**
+     * Build the messages from a given compiled prompt.
+     *
+     * @return array<array-key, \Cortex\LLM\Contracts\Message>
+     */
+    protected function buildMessages(GetPromptResult $compiledPrompt): array
+    {
+        return array_map(function (PromptMessage $message): Message {
+            $contentArray = $message->content->toArray();
+            $content = match ($message->content->getType()) {
+                'text' => new TextContent(Arr::get($contentArray, 'text')),
+                'image' => new ImageContent(Arr::get($contentArray, 'data'), Arr::get($contentArray, 'mimeType')),
+                'audio' => new AudioContent(Arr::get($contentArray, 'url'), Arr::get($contentArray, 'mimeType')),
+                // "resource" type not supported for now
+                default => throw new PromptException('Unsupported content type: ' . $message->content->getType()),
+            };
+
+            return match ($message->role) {
+                'user' => new UserMessage([$content]),
+                'assistant' => new AssistantMessage([$content]),
+                default => throw new PromptException('Unsupported role: ' . $message->role),
+            };
+        }, $compiledPrompt->messages);
     }
 }

src/Prompts/PromptFactoryManager.php

@@ -31,11 +31,11 @@ public function createLangfuseDriver(): LangfusePromptFactory
 
     public function createMcpDriver(): McpPromptFactory
     {
-        /** @var array{base_uri?: string} $config */
+        /** @var array{server?: string} $config */
         $config = $this->config->get('cortex.prompt_factory.mcp');
 
         return new McpPromptFactory(
-            $config['base_uri'] ?? 'http://localhost:3000',
+            $this->container->make('cortex.mcp_server')->driver($config['server'] ?? null),
         );
     }
 }

src/Support/helpers.php

@@ -19,6 +19,8 @@
  * Helper function to create a chat prompt builder.
  *
  * @param MessageCollection|array<int, \Cortex\LLM\Contracts\Message>|string|null $messages
+ *
+ * @return ($messages is null ? \Cortex\Prompts\Prompt : ($messages is string ? \Cortex\Prompts\Builders\TextPromptBuilder : \Cortex\Prompts\Builders\ChatPromptBuilder))
  */
 function prompt(MessageCollection|array|string|null $messages): Prompt|PromptBuilder
 {

src/Tools/ClosureTool.php

@@ -45,7 +45,7 @@ public function schema(): ObjectSchema
     /**
      * @param ToolCall|array<string, mixed> $toolCall
      */
-    public function invoke(ToolCall|array $toolCall): mixed
+    public function invoke(ToolCall|array $toolCall = []): mixed
     {
         // Get the arguments from the given tool call.
         $arguments = $this->getArguments($toolCall);

src/Tools/GoogleSerper.php

@@ -38,7 +38,7 @@ public function schema(): ObjectSchema
     /**
      * @param ToolCall|array<int, mixed> $toolCall
      */
-    public function invoke(ToolCall|array $toolCall): string
+    public function invoke(ToolCall|array $toolCall = []): string
     {
         $arguments = $this->getArguments($toolCall);
         $searchQuery = $arguments['query'];