PHP-Based MCP Server Framework

Overview

This project provides a complete implementation of an MCP (Model Control Protocol) server framework in PHP. It allows developers to define MCP services elegantly using annotations and supports various handlers such as Tool, Prompt, and Resource. The framework also includes a comprehensive logging system and Docker support.

Key Features

• Annotation-based MCP service definition
• Support for Tool, Prompt, and Resource handlers
• Comprehensive logging system
• Docker support

System Requirements

• PHP >= 8.1
• Composer
• Docker (optional)

Quick Start

Installation

git clone https://github.com/he426100/php-mcp-server
cd php-mcp-server
composer install

Running the Example Server

php bin/console mcp:test-server

Annotation Usage Guide

The framework provides three core annotations for defining MCP services:

1. Tool Annotation

Used to define tool handlers:

use Mcp\Annotation\Tool;

class MyService {
    #[Tool(
        name: 'calculate-sum',
        description: '计算两个数的和',
        parameters: [
            'num1' => [
                'type' => 'number',
                'description' => '第一个数字',
                'required' => true
            ],
            'num2' => [
                'type' => 'number',
                'description' => '第二个数字',
                'required' => true
            ]
        ]
    )]
    public function sum(int $num1, int $num2): int 
    {
        return $num1 + $num2;
    }
}

2. Prompt Annotation

Used to define prompt template handlers:

use Mcp\Annotation\Prompt;

class MyService {
    #[Prompt(
        name: 'greeting',
        description: '生成问候语',
        arguments: [
            'name' => [
                'description' => '要问候的人名',
                'required' => true
            ]
        ]
    )]
    public function greeting(string $name): string 
    {
        return "Hello, {$name}!";
    }
}

3. Resource Annotation

Used to define resource handlers:

use Mcp\Annotation\Resource;

class MyService {
    #[Resource(
        uri: 'example://greeting',
        name: 'Greeting Text',
        description: '问候语资源',
        mimeType: 'text/plain'
    )]
    public function getGreeting(): string 
    {
        return "Hello from MCP server!";
    }
}

Creating Custom Services

1. Create a service class:

namespace Your\Namespace;

use Mcp\Annotation\Tool;
use Mcp\Annotation\Prompt;
use Mcp\Annotation\Resource;

class CustomService 
{
    #[Tool(name: 'custom-tool', description: '自定义工具')]
    public function customTool(): string 
    {
        return "Custom tool result";
    }
}

1. Create a command class:

namespace Your\Namespace\Command;

use He426100\McpServer\Command\AbstractMcpServerCommand;
use Your\Namespace\CustomService;

class CustomServerCommand extends AbstractMcpServerCommand 
{
    protected string $serverName = 'custom-server';
    protected string $serviceClass = CustomService::class;

    protected function configure(): void 
    {
        parent::configure();
        $this->setName('custom:server')
            ->setDescription('运行自定义 MCP 服务器');
    }
}

1. Register the command:

In composer.json, add:

{
    "autoload": {
        "psr-4": {
            "Your\\Namespace\\": "src/"
        }
    }
}

Annotation Parameter Details

Tool Annotation Parameters

Prompt Annotation Parameters

Resource Annotation Parameters

Log Configuration

Server logs are saved by default in runtime/server_log.txt. You can modify this by extending AbstractMcpServerCommand:

protected string $logFilePath = '/custom/path/to/log.txt';

Docker Support

Build and run the container:

docker build -t php-mcp-server .
docker run -i --rm php-mcp-server

License

MIT License

Contributing

Issues and Pull Requests are welcome.

Author

he426100

Changelog

v1.0.0

• Initial version release
• Basic MCP server functionality implemented
• Docker support added