Download the PHP package ecourty/mcp-server-bundle without Composer

MCP Server Bundle

A powerful Symfony bundle for handling MCP (Model Context Protocol) server implementations, providing tools for JSON-RPC request handling and tool management.
Read the official MCP specification.

MCP Servers provide the fundamental building blocks for adding context to language models via MCP.
These primitives enable rich interactions between clients, servers, and language models:

• Prompts: Pre-defined templates or instructions that guide language model interactions
• Resources: Structured data or content that provides additional context to the model
• Tools: Executable functions that allow models to perform actions or retrieve information

The current MCP protocol supported version is 2025-06-18, which is the latest stable version as of June 2025.

[!WARNING]
The specification of the Model Context Protocol (MCP) changes frequently. This bundle will evolve along with the specification, so please ensure you are using the latest version of the bundle.
The CHANGELOG can be found here.

Table of Contents

• Getting Started
  • Installation
  • Configuration
• Tools
  • Creating Tools
  • Tool Results
  • Tool Events
  • Input Schema Management
  • JSON-RPC Integration
• Resources
  • Creating Resources
  • Static Resources
  • Templated Resources
  • Multiple Parameters
  • Parameter Type Casting
  • Resource Results
  • Resource Events
  • JSON-RPC Integration
• Prompts
  • Creating Prompts
  • Prompt Results
  • Prompt Events
  • JSON-RPC Integration
• JSON-RPC Methods
  • Built-in Methods
  • Custom Methods
• Developer Experience
• Contributing
• License

Getting Started

The MCP Server Bundle provides a structured way to create and manage tools that can be used by clients via JSON-RPC requests.
It includes features for MCP tool management, and JSON-RPC method handling.

This bundle is designed to be flexible and extensible, allowing developers to create custom tool handlers and method handlers as needed.
MethodHandlers and ToolHandlers are registered and autowired using attributes, making it easy to define and manage your own tools.

Installation

1. Install the MCP Server Bundle via Composer:

2. Add the bundle to your config/bundles.php (if not using Symfony Flex):

3. Configure the routes in config/routes/mcp.yaml:

Configuration

You can customize the MCP Server Bundle configuration in config/packages/mcp_server.yaml:

Tools

Tools are the core components of the MCP Server Bundle. They allow you to define and manage custom logic that can be triggered by clients.

Creating Tools

1. Create a new class that will handle your tool logic
2. Use the #[AsTool] attribute to register your tool
3. Optionally, define the input schema for your tool using a class with validation constraints and OpenAPI attributes
4. Implement the __invoke method to handle the tool logic and return a ToolResult

As Tool classes are services within the Symfony application, any dependency can be injected in it, using the constructor, like any other service.

Example:

• Tool input schema class:

• Tool class:

Tool Results

The MCP specification states that tool results should consist of an array of objects.
The bundle provides several result types that can be combined in a single ToolResult object:

• TextToolResult: For text-based results
• ImageToolResult: For image results
• AudioToolResult: For audio results
• ResourceToolResult: For file or resource results

All tool results must be wrapped in a ToolResult object, which can contain multiple results and handle error state.

Example:

Error handling example:

The ToolResult class provides the following features:

• Combine multiple results of different types
• Handle error state
• Automatic serialization to the correct format
• Type safety for all results

Tool Events

The bundle provides several events that you can listen to:

• ToolCallEvent: Dispatched before a tool is called, contains the tool name and input data
• ToolResultEvent: Dispatched after a tool has been called, contains the result of the tool call
• ToolCallExceptionEvent: Dispatched when a tool throws an exception, contains the tool name, input data and throwable

Example of event listener:

Input Schema Management

The bundle provides robust input validation and sanitization through schema-based deserialization.
Input schemas are extracted from the __invoke method of classes with the #[AsTool] attribute, allowing you to define the expected input structure and validation rules.

1. Define your input schema class:

2. The bundle will automatically:
   • Understand the OA attributes for OpenAPI-based documentation in tools/list
   • Deserialize incoming JSON data into your schema class
   • Validate all constraints defined in your schema
   • Sanitize input data

This ensures that your tool handlers always receive properly validated and sanitized data.

JSON-RPC Integration

• tools/list: Lists all available tools and their definitions.
• tools/call: Executes a tool by name, with the provided input data.

Resources

Resources are data sources that can be accessed by clients via their URI.
They can represent files, database records, or any other data that can be identified by a URI.

Creating Resources

1. Create a new class that will handle your resource logic
2. Use the #[AsResource] attribute to register your resource
3. Define the URI pattern for your resource (static or templated)
4. Implement the __invoke method to handle the resource logic and return a ResourceResult

As Resource classes are services within the Symfony application, any dependency can be injected in it, using the constructor, like any other service.

Static Resources

Static resources have a fixed URI that doesn't change. They are useful for resources that don't require parameters.

Example:

Templated Resources

Templated resources use URI templates with parameters enclosed in curly braces (e.g., {id}). These parameters are automatically extracted from the URI and passed to the __invoke method as arguments.

Example:

In this example:

• The URI template database://user/{id} defines a parameter named id
• When a client requests database://user/123, the parameter 123 is extracted
• The __invoke method receives 123 as an int parameter (automatic type casting is performed)
• The resource returns user data for ID 123

Multiple Parameters

You can define multiple parameters in a single URI template:

Parameter Type Casting

The bundle automatically casts URI parameters to the appropriate types based on the method signature:

• int parameters are cast to integers
• float parameters are cast to floats
• bool parameters are cast to booleans
• string parameters remain as strings
• array parameters are JSON-decoded into arrays using json_decode if they are JSON strings

Resource Results

The MCP specification states that resource results should consist of an array of resource objects.
The bundle provides several result types that can be combined in a single ResourceResult object:

• TextResource: For text-based content (JSON, XML, plain text, etc.)
• BinaryResource: For binary content (images, audio, video, files, etc.), should be base-64 encoded

All resource results must be wrapped in a ResourceResult object, which can contain multiple resources.

Example:

The ResourceResult class provides the following features:

• Combine multiple resources of different types
• Automatic serialization to the correct format
• Type safety for all resources

Resource Events

The bundle provides several events that you can listen to:

• ResourceReadEvent: Dispatched before a resource is read, contains the URI
• ResourceReadResultEvent: Dispatched after a resource has been read, contains the URI and results

Example of event listener:

JSON-RPC Integration

• resources/list: Lists all available direct (static) resources and their definitions.
• resources/templates/list: Lists all available templated resources and their definitions.
• resources/read: Retrieves a resource by its URI, automatically matching templated resources and extracting parameters.

Prompts

Prompts are reusable templates that can be dynamically generated and returned by the MCP server.
They are useful for providing context, instructions, or any structured message to clients, and can accept arguments for dynamic content.

Creating Prompts

1. Define a prompt class
   • Use the #[AsPrompt] attribute to register your prompt.
   • The class should implement the __invoke method, which optionally receives an ArgumentCollection and returns a PromptResult.
   • Arguments are defined using the Argument class (name, description, required, allowUnsafe), within the #[AsPrompt] declaration.

Example:

Prompt Results

A prompt must return an instance of PromptResult, which contains:

• A description (string)
• An array of PromptMessage objects (each with a role and content)

Example:

Prompt Events

The bundle provides several events for prompts:

• PromptGetEvent: Dispatched before a prompt is generated
• PromptResultEvent: Dispatched after a prompt is generated
• PromptExceptionEvent: Dispatched if an error occurs during prompt generation

Example of event listener:

JSON-RPC Integration

• prompts/list: Lists all available prompts and their definitions.
• prompts/get: Retrieves and generates a prompt by name, with arguments.

JSON-RPC Methods

The bundle provides a robust system for handling JSON-RPC requests.

Built-in Methods

1. initialize

   • Called when a client first connects to the server
   • Returns server information and capabilities
   • Essential for client-server handshake

2. tools/list

   • Lists all available tools on the server
   • Returns tool metadata including names, descriptions, and input schemas
   • Used by clients to discover available tools

3. tools/call

   • Executes a specific tool
   • Handles input validation and tool execution
   • Returns the tool's result or error information

4. prompts/list

   • Lists all available prompts and their definitions
   • Returns prompt names, descriptions, and argument schemas
   • Useful for clients to discover available prompts

5. prompts/get

   • Retrieves a specific prompt by its name and generates it with the provided arguments
   • Validates and sanitizes arguments, then returns the generated prompt content
   • Returns an error if the prompt is not found or arguments are invalid

6. resources/list

   • Lists all available static resources and their definitions
   • Returns resource URIs, descriptions, and metadata
   • Useful for clients to discover available resources

7. resources/templates/list

   • Lists all available static and templated resources
   • Returns resource URIs, descriptions, and metadata
   • Useful for clients to discover available template resources
8. resources/read
   • Reads a specific resource by its URI
   • Automatically matches templated resources and extracts parameters
   • Returns the resource content or an error if the resource is not found

These methods are automatically registered and handled by the bundle. You don't need to implement them yourself.

Custom Methods

You can create your own JSON-RPC method handlers for additional functionality:

1. Create a new class that implements the MethodHandlerInterface
2. Use the #[AsMethodHandler] attribute to register your handler

Example:

Method Handler Attributes

The #[AsMethodHandler] attribute supports:

• method (string, required): The JSON-RPC method name

Developer Experience

The bundle provides several tools to help you during development:

Debug Command

1. The debug:mcp-tools command helps you inspect and debug your MCP tools:

This command is particularly useful for:

• Verifying tool registration
• Checking input schemas
• Validating tool annotations

2. The debug:mcp-prompts command helps you inspect and debug your MCP prompts:

This command is particularly useful for:

• Verifying prompt registration
• Checking argument

3. The debug:mcp-resources command helps you inspect and debug your MCP resources:

This command is particularly useful for:

• Verifying resource registration
• Checking URI patterns

Contributing

Contributions to the MCP Server Bundle are welcome! Here's how you can help:

1. Fork the repository
2. Create a new branch for your feature
3. Make your changes
4. Submit a pull request

Please ensure your code follows our coding standards and includes appropriate tests.

Development Setup

1. Fork and clone the repository

2. Install dependencies

3. Make your chages

4. Fix the code style and run PHPStan

5. Run the tests

License

This bundle is licensed under the MIT License. See the LICENSE file for details.