PHPackages                             anvilm/mcp-php-boilerplate - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. anvilm/mcp-php-boilerplate

ActiveProject[Utility & Helpers](/categories/utility)

anvilm/mcp-php-boilerplate
==========================

MCP PHP boilerplate

v1.0.3(4mo ago)01MITPHPPHP ^8.5

Since Dec 30Pushed 4mo agoCompare

[ Source](https://github.com/AnvilM/mcp-php-boilerplate)[ Packagist](https://packagist.org/packages/anvilm/mcp-php-boilerplate)[ RSS](/packages/anvilm-mcp-php-boilerplate/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (10)Versions (6)Used By (0)

MCP PHP Boilerplate
===================

[](#mcp-php-boilerplate)

PHP Boilerplate Powered by **MCP PHP SDK**

[![php-version-shield](https://camo.githubusercontent.com/e6be9be2d6c112d69942a7892365d45a2fa1716748e31d27aa8d7368fc337d3b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e352d626c75653f6c6f676f3d706870266c6162656c436f6c6f723d626c61636b267374796c653d666c61742d737175617265)](https://github.com/AnvilM/mcp-php-boilerplate/)[![phpstan-shield](https://camo.githubusercontent.com/d95ca8c1374155b698b09cb18815becd5693673b622918005c2a4eede03daac2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d4c6576656c253230382d626c75653f6c6f676f3d706870266c6162656c436f6c6f723d626c61636b267374796c653d666c61742d737175617265)](https://github.com/AnvilM/mcp-php-boilerplate/)[![](https://camo.githubusercontent.com/f81c2f5e27a0fd6aba60b48bee7ae74ff788c23f1f0933eab100cc54e023bb51/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f616e76696c6d2f6d63702d7068702d626f696c6572706c6174653f7374796c653d666c61742d73717561726526736f72743d73656d766572266c6f676f3d676974687562266c6162656c436f6c6f723d626c61636b)](https://github.com/anvilm/mcp-php-boilerplate/releases)

[![status-shield](https://camo.githubusercontent.com/f90603b7cb64db4e06b624d3c3454b6fb37eabcff2bf56ab5a906613b8975220/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7374617475732d6163746976652d627269676874677265656e3f6c6162656c436f6c6f723d626c61636b267374796c653d666c61742d737175617265)](https://github.com/AnvilM/mcp-php-boilerplate/)[![last-commit-shield](https://camo.githubusercontent.com/2850a20e62bf0ec4b9e1c0d0f3edd519e92248b435a6fc0ceff6d45c6dada830/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f616e76696c6d2f6d63702d7068702d626f696c6572706c6174653f6c6162656c436f6c6f723d626c61636b267374796c653d666c61742d737175617265)](https://github.com/AnvilM/mcp-php-boilerplate/commits)[![](https://camo.githubusercontent.com/514805f9b4e49276029c898c5b63150c41f8805f966248cc5a3c915ded5bc400/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652d646174652f616e76696c6d2f6d63702d7068702d626f696c6572706c6174653f6c6162656c436f6c6f723d626c61636b267374796c653d666c61742d737175617265)](https://github.com/anvilm/mcp-php-boilerplate/releases)[![github-license-shield](https://camo.githubusercontent.com/0897948daa5e06131c0c22d554182d3cc932f07ca4c43dace45920c4e046f4fa/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f616e76696c6d2f6d63702d7068702d626f696c6572706c6174653f636f6c6f723d7768697465266c6162656c436f6c6f723d626c61636b267374796c653d666c61742d737175617265)](https://github.com/anvilm/mcp-php-boilerplate/blob/master/LICENSE)

Project Overview
----------------

[](#project-overview)

This template is designed for the development of AI-agent platforms utilizing the [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) standard and the [MCP PHP SDK](https://github.com/modelcontextprotocol/php-sdk). The project incorporates tools for building scalable PHP applications capable of exposing Tools, Resources, and Prompts to LLM-based agents.

Core Components
---------------

[](#core-components)

- **Container**: [PHP-DI](https://php-di.org/)
- **PSR-7**: [nyholm/psr7](https://github.com/Nyholm/psr7)
- **Logger**: [Monolog](https://seldaek.github.io/monolog/)
- **Testing**: [Pest](https://pestphp.com/)
- **Static Analysis**: [PHPStan](https://phpstan.org/)

Getting Started
---------------

[](#getting-started)

### Installation

[](#installation)

#### Via Composer

[](#via-composer)

Create a new project using Composer:

```
composer create-project anvilm/mcp-php-boilerplate my-project
```

#### Via GitHub

[](#via-github)

Clone the repository and install dependencies:

```
git clone https://github.com/anvilm/mcp-php-boilerplate.git my-project
cd my-project
composer install
```

### Running the Application

[](#running-the-application)

#### HTTP Mode (e.g. with built-in php server)

[](#http-mode-eg-with-built-in-php-server)

```
php -S 127.0.0.1:8080 entrypoint/http.php
```

#### Stdio Mode (direct communication via stdin/stdout)

[](#stdio-mode-direct-communication-via-stdinstdout)

```
php entrypoint/stdio.php
```

### Directory Structure

[](#directory-structure)

```
.
├── app/                          # Core application logic and infrastructure
│   ├── Bootloaders/            # Classes for initializing application components
│   ├── Config/                   # Configuration files
│   ├── Tools/                    # MCP Tools definitions
│   ├── Resources/                # MCP resources definitions
│   ├── Prompts/                  # MCP prompts definitions
│   ├── Providers/                # Dependency injection container providers
│   │   ├── ApplicationProviders/ # Providers for application functionality
│   │   └── Providers/            # Custom providers
│   └── Kernel.php                # Application entry point and bootstrap management
├── entrypoint/
│   ├── http.php                  # HTTP entry point
│   └── stdio.php                 # Stdio (stdin/stdout) entry point
├── src/                          # Source code for custom logic
└── tests/                        # Pest tests

```

### Directory Organization

[](#directory-organization)

The boilerplate is structured to separate infrastructural logic from user-defined code:

- **Directory `app/`**: Contains the core infrastructure of the application, including [configurations](#configuration), [providers](#providers), [tools](#tools), [resources](#resources), [prompts](#prompts)and [bootloaders](#bootloaders). This directory is intended for foundational application setup and operation.
- **Directory `src/`**: Designated for user-defined source code, where developers can implement the primary business logic of the application.

### Configuration

[](#configuration)

Application configurations are organized in the `app/Config/` directory and provide type-safe access to settings via classes with static methods. For further details, refer to the [Configuration](#configuration-1) section.

#### Environment Variables

[](#environment-variables)

Environment variables are loaded from a `.env` file in the project root during the bootstrapping process (specifically within the `InfrastructureBootloader`).

After loading, all variables are available globally via the `$_ENV` superglobal array.

Predefined environment variables:

- **APP\_ENV**: Defines the application environment (e.g., `production`, `development`), affecting logging levels.
- **APP\_DEBUG**: Enables or disables debug mode, influencing the display of detailed error information.
- **APP\_NAME**: Name of the application.
- **APP\_DESCRIPTION**: Short description of the application.

Additional custom variables can be added as needed.

#### Application Configuration

[](#application-configuration)

The `ApplicationConfig` class provides the following parameters:

- **baseDir**: The root directory of the project.
- **appEnv**: The application environment, determined by the `APP_ENV` variable. Available environments are listed in the `ApplicationEnvironmentEnum` enumeration. To add a new environment, update this enumeration and the `ApplicationConfig` class.
- **appDebug**: Debug mode, determined by the `APP_DEBUG` variable.
- **appName**: Application name, determined by the `APP_NAME` variable.
- **appDescription**: Application description, determined by the `APP_DESCRIPTION` variable.

#### Logging Configuration

[](#logging-configuration)

The `LoggerConfig` class configures logging parameters using Monolog. It includes the path to log files (in the `logs/`directory) and the logging level, which depends on the `appEnv` value.

Architectural Concepts
----------------------

[](#architectural-concepts)

### Configuration

[](#configuration-1)

Configurations are stored in the `app/Config/` directory. Each configuration is implemented as a class with static methods, ensuring type-safe access to settings.

Example:

```
namespace Application\Config\ApplicationConfig;

use function Env\env;

final readonly class ApplicationConfig
{
    public static function baseDir(): string
    {
        return dirname(__DIR__, 3);
    }
}
```

### Tools

[](#tools)

Tools are defined in the `app/Tools/` directory.

Example of creating a tool:

```
namespace Application\Tools;

use Mcp\Capability\Attribute\McpTool;

class ExampleTool
{
    #[McpTool("example_tool", "Example tool description")]
    public function handle(string $name): string
    {
        return "Hello $name";
    }
}
```

### Resources

[](#resources)

Resources are defined in the `app/Resources/` directory.

Example of creating a resource:

```
namespace Application\Resources;

use Mcp\Capability\Attribute\McpResource;

final class ExampleResource
{
    #[McpResource("example://example", "example_resource", "Example resource description", "text/plain")]
    public function handle(): string
    {
        return "example resource";
    }

}
```

### Prompts

[](#prompts)

Prompts are defined in the `app/Prompts/` directory.

Example of creating a prompt:

```
namespace Application\Prompts;

use ...

final class ExamplePrompt
{
    #[McpPrompt("example_prompt")]
    public function handle(): PromptMessage
    {
        return new PromptMessage(
            Role::User,
            new TextContent("example prompt message"),
        );
    }
}
```

### Providers

[](#providers)

Service providers, located in the `app/Providers/` directory, are responsible for registering dependencies in the PHP-DI container, making them accessible to the application. Providers are categorized as follows:

- `ApplicationProviders/`: Providers essential for application functionality. **They are loaded first.**
- `Providers/`: Custom providers for specific logic.

Each provider must implement the `ProviderInterface` and be registered in the `app/Providers/Registry.php` file.

ApplicationProviders must be registered in the `$appProviders` array, other Providers in the `$providers` array.

Example of creating a provider:

```
namespace App\Providers;

final readonly class DBALProvider implements ProviderInterface
{
    public static function register(): array
    {
        return [DatabaseManager::class => new DatabaseManager(
            new CycleDatabaseConfig(
                DatabaseConfig::config()
            )
        )];
    }
}
```

Example of registration in the `app/Providers/Registry.php` file:

```
private static array $appProviders = [
    \App\Providers\LoggerProvider::class,
    \App\Providers\DBALProvider::class,
];

private static array $providers = [
    // Other providers
];
```

### Bootloaders

[](#bootloaders)

The application bootstrapping process is divided into distinct stages to ensure a scalable, ordered, and predictable initialization of components. Each stage is managed by a dedicated bootloader, allowing components to be loaded sequentially rather than in a single monolithic location.

All bootloaders are located in the `app/Bootloaders/` directory and must implement the `BootloaderInterface`. The `Kernel` class orchestrates the entire bootstrapping process by executing bootloaders in a strictly defined order.

#### Directory Structure

[](#directory-structure-1)

```
app/Bootloaders/
├── Application/
│   ├── ApplicationBootloader.php
│   └── Server.php
├── Infrastructure/
│   ├── Container.php
│   ├── Providers.php
│   └── InfrastructureBootloader.php
├── Environment/
│   └── EnvironmentBootloader.php
├── BootloaderInterface.php
└── Context.php

```

#### Boot Sequence

[](#boot-sequence)

The bootloaders are executed in the following order:

1. **EnvironmentBootloader**
    Loads environment variables from the `.env` file in the project root.
2. **InfrastructureBootloader**
    Configures core infrastructure components, including the PHP-DI container and service providers.
3. **ApplicationBootloader**
    Initializes the MCP server and other application-level components.

Additional bootloaders can be inserted at appropriate positions in the sequence as the application evolves.

#### Extending the Boot Process

[](#extending-the-boot-process)

To add a new bootloader:

1. Create a new directory and class under `app/Bootloaders/`, for example:
    `app/Bootloaders/OneMoreBootloader/OneMoreBootloader.php`
2. Implement the `BootloaderInterface` in the new class. Bootloaders are expected to be static, receive a `Context` object, perform configuration, and return a (possibly updated) `Context`:

```