symfony-mcp-server

<h1 align="center">Symfony MCP Server</h1> <p align="center"> A powerful Symfony package to build a Model Context Protocol Server seamlessly and <strong>build Intelligent AI Agents.</strong><br> Transform your Symfony applications into powerful AI-driven systems </p> <p align="center"> <a href="https://github.com/klapaudius/symfony-mcp-server/actions"><img src="https://github.com/klapaudius/symfony-mcp-server/actions/workflows/tests.yml/badge.svg" alt="Build Status"></a> <a href="https://codecov.io/gh/klapaudius/symfony-mcp-server" > <img src="https://codecov.io/gh/klapaudius/symfony-mcp-server/graph/badge.svg?token=5FXOJVXPZ1" alt="Coverage"/></a> <a href="https://packagist.org/packages/klapaudius/symfony-mcp-server"><img src="https://img.shields.io/packagist/l/klapaudius/symfony-mcp-server" alt="License"></a> <a href="https://packagist.org/packages/klapaudius/symfony-mcp-server"><img src="https://img.shields.io/packagist/v/klapaudius/symfony-mcp-server" alt="Latest Stable Version"></a> [//]: # (<a href="https://packagist.org/packages/klapaudius/symfony-mcp-server"><img src="https://img.shields.io/packagist/dt/klapaudius/symfony-mcp-server" alt="Total Downloads"></a>) </p> ## 🤖 Unleash the Power of AI Agents in Your Symfony Apps Symfony MCP Server enables you to build **intelligent, context-aware AI agents** that can reason, make decisions, and interact with your application's business logic. By implementing the Model Context Protocol (MCP), your Symfony application becomes a platform for sophisticated AI-driven automation and intelligence. ### 🎯 Why Build Agents with Symfony MCP Server? **Transform Static Tools into Intelligent Agents:** - 🧠 **AI-Powered Reasoning**: Tools can consult LLMs mid-execution to make smart decisions - 🔄 **Dynamic Adaptation**: Agents adapt their behavior based on context and real-time analysis - 💡 **Complex Problem Solving**: Break down complex tasks and solve them iteratively with AI assistance - 🎨 **Creative Generation**: Generate content and solutions that evolve with user needs **Enterprise-Grade Security:** - 🔒 **Secure Transports**: StreamableHTTP and SSE instead of STDIO for production environments - 🛡️ **Protected APIs**: Keep your internal systems safe while exposing AI capabilities - 🎛️ **Fine-Grained Control**: Manage authentication, authorization, and access at every level **Key Features:** - 🛠️ **Tools**: Create powerful, executable functions that LLM can invoke to interact with your application - 💬 **Prompts**: Define conversation starters and templates to guide AI behavior and interactions - 📚 **Resources**: Expose structured data and documents that AI can read and reason about - 🧠 **Sampling**: Enable tools to consult AI models mid-execution for intelligent decision-making - 📊 **Progress Streaming**: Real-time progress notifications for long-running operations - 🎨 **Multi-Modal Results**: Support for Text, Image, Audio, and Resource outputs from tools - 🔌 **Flexible Architecture**: Adapter-based design with Pub/Sub messaging for scalable deployments ## 🚀 Agent-First Features ### 🧪 Sampling: The Core of Agentic Behavior (v1.4.0+) Transform your tools into autonomous agents that can think and reason: ```php class IntelligentAnalyzer implements SamplingAwareToolInterface { private SamplingClient $samplingClient; public function execute(array $arguments): ToolResultInterface { // Check if sampling is available if ($this->samplingClient !== null && $this->samplingClient->isEnabled()) { try { // Let AI analyze and reason about complex data $response = $this->samplingClient->createTextRequest( "Analyze this data and suggest optimizations: {$arguments['data']}", new ModelPreferences( [['name' => 'claude-3-sonnet']], 0.3, // costPriority 0.8, // intelligencePriority 0.2 // speedPriority ), 'You are a data analysis expert.', 2000 ); // Execute actions based on AI reasoning return new TextToolResult($response->getContent()->getText()); } catch (\Exception $e) { // Fallback to basic analysis return new TextToolResult('Basic analysis: Data structure appears valid.'); } } return new TextToolResult('Advanced analysis requires AI capabilities.'); } public function setSamplingClient(SamplingClient $samplingClient): void { $this->samplingClient = $samplingClient; } } ``` ### 🛠️ Tool System: Building Blocks for Agents Create powerful tools that AI agents can orchestrate: - **StreamableToolInterface**: Real-time progress updates for long-running operations - **Multi-Result Support**: Return text, images, audio, or resources - **Progress Notifications**: Keep users informed during complex agent operations - **Dynamic Tool Discovery**: Agents can discover and use tools based on capabilities ### 🎭 Prompt Engineering for Agent Behavior Define agent personalities and behaviors through sophisticated prompt systems: - **Context-Aware Prompts**: Guide agent behavior based on application state - **Multi-Modal Support**: Text, image, audio, and resource-based prompts - **Dynamic Prompt Generation**: Prompts that adapt based on user interaction ### 📚 Resource Management for Agent Memory Give your agents access to structured knowledge: - **Dynamic Resource Loading**: Agents can access and reason about your data - **Template-Based Resources**: Generate resources on-the-fly based on context - **Multi-Provider Support**: File system, database, API, or custom providers ## 🎯 Real-World Agent Examples ### 🔍 Intelligent Code Review Agent ```php class CodeReviewAgent implements SamplingAwareToolInterface { private SamplingClient $samplingClient; public function execute(array $arguments): ToolResultInterface { // Check if sampling is available if ($this->samplingClient !== null && $this->samplingClient->isEnabled()) { try { // AI analyzes code for patterns, security, and best practices $review = $this->samplingClient->createTextRequest( "Review this code for security vulnerabilities, performance issues, and suggest improvements: {$arguments['code']}", new ModelPreferences( [['name' => 'claude-3-sonnet']], 0.2, // costPriority 0.8, // intelligencePriority 0.2 // speedPriority ), 'You are a senior code reviewer with expertise in security and performance.', 2000 ); // Generate actionable recommendations return new TextToolResult($this->formatReview($review->getContent()->getText())); } catch (\Exception $e) { // Fallback to basic analysis return new TextToolResult('Basic code review: Structure appears valid.'); } } return new TextToolResult('Advanced code review requires AI capabilities.'); } public function setSamplingClient(SamplingClient $samplingClient): void { $this->samplingClient = $samplingClient; } } ``` ### 📊 Data Analysis Agent ```php class DataInsightAgent implements SamplingAwareToolInterface, StreamableToolInterface { private SamplingClient $samplingClient; private ?ProgressNotifierInterface $progressNotifier = null; public function execute(array $arguments): ToolResultInterface { // Check if sampling is available if ($this->samplingClient !== null && $this->samplingClient->isEnabled()) { try { // Multi-step reasoning process $steps = [ 'Identify patterns and anomalies', 'Generate statistical insights', 'Create visualizations', 'Recommend actions' ]; $this->progressNotifier?->sendProgress( progress: 0, total: count($steps)+1, message: "Analyzing dataset..." ); $insights = []; foreach ($steps as $i => $step) { $response = $this->samplingClient->createTextRequest( "$step for this data: {$arguments['data']}", new ModelPreferences( [['name' => 'claude-3-sonnet']], 0.2, // costPriority 0.8, // intelligencePriority 0.2 // speedPriority ), 'You are a data analysis expert.', 2000 ); $insights[] = $response->getContent()->getText(); $this->progressNotifier?->sendProgress( progress: $i+1, total: count($steps)+1, message: $step ); } return new TextToolResult($this->compileReport($insights)); } catch (\Exception $e) { return new TextToolResult('Basic data analysis: Dataset appears well-formed.'); } } return new TextToolResult('Advanced data analysis requires AI capabilities.'); } public function setSamplingClient(SamplingClient $samplingClient): void { $this->samplingClient = $samplingClient; } public function setProgressNotifier(ProgressNotifierInterface $progressNotifier): void { $this->progressNotifier = $progressNotifier; } } ``` ### 🤝 Customer Support Agent ```php class SupportAgent implements SamplingAwareToolInterface { private SamplingClient $samplingClient; public function execute(array $arguments): ToolResultInterface { // Check if sampling is available if ($this->samplingClient !== null && $this->samplingClient->isEnabled()) { try { // Load customer context $context = $this->loadCustomerHistory($arguments['customer_id']); // AI determines best response strategy $response = $this->samplingClient->createTextRequest( "Customer issue: {$arguments['issue']}\nHistory: $context\nDetermine the best resolution approach.", new ModelPreferences( [['name' => 'claude-3-sonnet']], 0.2, // costPriority 0.8, // intelligencePriority 0.2 // speedPriority ), 'You are an expert customer support agent.', 2000 ); // Send back the strategy for user approval return new TextToolResult($response->getContent()->getText()); } catch (\Exception $e) { return new TextToolResult('Standard support response: We will review your issue and respond within 24 hours.'); } } return new TextToolResult('Personalized support requires AI capabilities.'); } public function setSamplingClient(SamplingClient $samplingClient): void { $this->samplingClient = $samplingClient; } } ``` ## 🚀 Quick Start: Build Your First Agent ### 1. Requirements - PHP >=8.2 - Symfony >=6.4 ### 2. Install Symfony MCP Server #### Create the configuration file config/packages/klp_mcp_server.yaml and paste into it: ```yaml klp_mcp_server: enabled: true server: name: 'My MCP Server' version: '1.0.0' default_path: 'mcp' ping: enabled: true # Read the warning section in the default configuration file before disable it interval: 30 server_providers: ['streamable_http','sse'] sse_adapter: 'cache' adapters: cache: prefix: 'mcp_sse_' ttl: 100 tools: - KLP\KlpMcpServer\Services\ToolService\Examples\CodeAnalyzerTool # Agentic tool sample - KLP\KlpMcpServer\Services\ToolService\Examples\HelloWorldTool - KLP\KlpMcpServer\Services\ToolService\Examples\ProfileGeneratorTool - KLP\KlpMcpServer\Services\ToolService\Examples\StreamingDataTool - KLP\KlpMcpServer\Services\ToolService\Examples\VersionCheckTool prompts: - KLP\KlpMcpServer\Services\PromptService\Examples\CodeReviewPrompt # Agentic prompt sample - KLP\KlpMcpServer\Services\PromptService\Examples\HelloWorldPrompt resources: - KLP\KlpMcpServer\Services\ResourceService\Examples\HelloWorldResource - KLP\KlpMcpServer\Services\ResourceService\Examples\ProjectSummaryResource # Agentic resource sample resources_templates: - KLP\KlpMcpServer\Services\ResourceService\Examples\DynamicAnalysisResource # Agentic resource template sample - KLP\KlpMcpServer\Services\ResourceService\Examples\McpDocumentationResource ``` For more detailed explanations, you can open the default configuration file [from that link.](src/Resources/config/packages/klp_mcp_server.yaml) #### Install the package via Composer: ```bash composer require klapaudius/symfony-mcp-server ``` #### Add routes in your `config/routes.yaml` ```yaml klp_mcp_server: resource: '@KlpMcpServerBundle/Resources/config/routes.php' type: php ``` **You're all done!** Upon completing this setup, your project will include 3 new API endpoints: - **Streaming Endpoint for MCP Clients**: `GET /{default_path}/sse` - **Request Submission Endpoint**: `POST /{default_path}/messages` - **Streamable HTTP Endpoint**: `GET|POST /{default_path}` ### Docker Setup (Optional) The project includes a Docker setup that can be used for development. The Docker setup includes Nginx, PHP-FPM with Redis extension, and Redis server. For detailed instructions on how to set up and use the Docker containers, please refer to the [Development Guidelines](CONTRIBUTING.md#docker-setup). ### 3. Create Your First Tool ```bash # Generate a new tool php bin/console make:mcp-tool MyCustomTool # Test your tool locally php bin/console mcp:test-tool MyCustomTool --input='{"task":"analyze this code"}' ``` ### 4. Visualizing with Inspector You can use the Model Context Protocol Inspector to visualize and test your MCP tools: ```bash # Run the MCP Inspector without installation npx @modelcontextprotocol/inspector node build/index.js ``` This will typically open a web interface at `localhost:6274`. To test your MCP server: ### 5. Connect AI Clients Your agents are now accessible to: - 🤖 Claude Desktop / Claude.ai - 🧠 Custom AI applications - 🔗 Any MCP-compatible client ## 🏗️ Architecture for Agent Builders ### Secure Agent Communication - **StreamableHTTP**: Direct, secure agent-to-client communication - **SSE (Server-Sent Events)**: Real-time updates for long-running agent tasks - **No STDIO**: Enterprise-safe, no system exposure ### Scalable Agent Infrastructure - **Pub/Sub Messaging**: Handle multiple agent sessions concurrently - **Redis/Cache Adapters**: Scale your agent platform horizontally - **Progress Streaming**: Real-time feedback for complex agent operations ### Agent Development Tools - **MCP Inspector**: Visualize and debug agent behavior - **Test Commands**: Rapid agent development and testing ## 🎓 Agent Development Resources - 📖 **[Building Intelligent Tools](https://github.com/klapaudius/symfony-mcp-server/blob/master/docs/building_tools.md)**: Complete guide to creating AI-powered tools - 🧠 **[Sampling Documentation](https://github.com/klapaudius/symfony-mcp-server/blob/master/docs/sampling.md)**: Master agent reasoning capabilities - 🎭 **[Prompt Engineering](https://github.com/klapaudius/symfony-mcp-server/blob/master/docs/building_prompts.md)**: Design agent behaviors and personalities - 📚 **[Resource Management](https://github.com/klapaudius/symfony-mcp-server/blob/master/docs/building_resources.md)**: Give agents access to knowledge ## 🌟 Join the Agent Revolution Build the next generation of AI-powered applications with Symfony MCP Server. Your tools aren't just functions anymore – they're intelligent agents capable of reasoning, learning, and evolving. ### Community - 💬 [GitHub Discussions](https://github.com/klapaudius/symfony-mcp-server/discussions): Share your agent creations - 🐛 [Issue Tracker](https://github.com/klapaudius/symfony-mcp-server/issues): Report bugs and request features - 🌟 [Examples](https://github.com/klapaudius/symfony-mcp-server/tree/master/src/Services/ToolService/Examples): Learn from working agents ## 📜 License MIT License - Build freely! ## 📰 MCP Registries referencing - https://mcpreview.com/mcp-servers/klapaudius/symfony-mcp-server - https://mcp.so/server/symfony-mcp-server/klapaudius --- *Built with ❤️ by [Boris AUBE](https://github.com/klapaudius) and the [contributors](https://github.com/klapaudius/symfony-mcp-server/contributors) - Inspired by [OP.GG/laravel-mcp-server](https://github.com/opgginc/laravel-mcp-server)*