PHP MCP Server

PHP MCP Server

英語版

これは、PHP で実装された MCP（Model Control Protocol）サーバーフレームワークです。アノテーションを使って、MCP サービスを簡潔に定義できます。

プロジェクト概要

本プロジェクトでは、以下の機能を備えた完全な MCP サーバーを提供します。

• アノテーションによる MCP サービス定義
• Tool、Prompt、Resource の 3 種類のハンドラーをサポート
• Stdio、Sse の 2 種類のトランスポート方式をサポート
• Swow と Swoole の 2 種類の環境をサポート
• 完全なログシステム
• Docker をサポート

システム要件

• PHP >= 8.1
• Composer
• Swow 拡張 > 1.5 または Swoole > 5.1
• Docker（任意）

クイックスタート

インストール

# 1. 克隆项目
git clone https://github.com/he426100/php-mcp-server
cd php-mcp-server

# 2. 安装依赖
composer install

# 3. 可选，安装 Swow 扩展（如果没有）
./vendor/bin/swow-builder --install

Swow 拡張の詳しいインストール方法については、Swow 公式ドキュメントを参照してください。

サンプルサーバーの実行

php bin/console mcp:test-server

共通コマンドパラメーター

パラメーター	説明	デフォルト値	オプション
--transport	トランスポートタイプ	stdio	stdio, sse
--port	SSE のリッスンポート	8000

アノテーションの使用ガイド

本フレームワークでは、MCP サービスを定義するための 3 種類のコアアノテーションを提供します。

1. Tool アノテーション

ツールクラスのハンドラーを定義するために使用します。

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 アノテーション

プロンプトテンプレートのハンドラーを定義するために使用します。

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 アノテーション

リソースハンドラーを定義するために使用します。

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!";
    }
}

カスタムサービスの作成

1. サービスクラスを作成します。

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";
    }
}

2. コマンドクラスを作成します。

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 服务器');
    }
}

アノテーションパラメーターの説明

Tool アノテーションのパラメーター

パラメーター	型	説明	必須
name	string	ツール名	はい
description	string	ツールの説明	はい
parameters	array	パラメーター定義	いいえ

Prompt アノテーションのパラメーター

パラメーター	型	説明	必須
name	string	プロンプトテンプレート名	はい
description	string	プロンプトテンプレートの説明	はい
arguments	array	パラメーター定義	いいえ

Resource アノテーションのパラメーター

パラメーター	型	説明	必須
uri	string	リソース URI	はい
name	string	リソース名	はい
description	string	リソースの説明	はい
mimeType	string	MIME タイプ	いいえ

アノテーション関数の戻り値の型に関する説明

Tool アノテーション関数がサポートする戻り値の型

戻り値の型	説明	変換結果
TextContent/ImageContent/EmbeddedResource	内容オブジェクトを直接返す	そのまま保持
TextContent/ImageContent/EmbeddedResource の配列	内容オブジェクトの配列	そのまま保持
ResourceContents	リソース内容オブジェクト	EmbeddedResource に変換
文字列またはスカラー型	string、int、float、bool など	TextContent に変換
null	空値	空文字列の TextContent に変換
配列またはオブジェクト	複雑なデータ構造	JSON 形式の TextContent に変換

Prompt アノテーション関数がサポートする戻り値の型

戻り値の型	説明	変換結果
PromptMessage	メッセージオブジェクト	そのまま保持
PromptMessage の配列	メッセージオブジェクトの配列	そのまま保持
Content オブジェクト	TextContent/ImageContent など	ユーザーロールの PromptMessage に変換
文字列またはスカラー型	string、int、float、bool など	TextContent を含むユーザーメッセージに変換
null	空値	内容が空のユーザーメッセージに変換
配列またはオブジェクト	複雑なデータ構造	JSON 形式のユーザーメッセージに変換

Resource アノテーション関数がサポートする戻り値の型

戻り値の型	説明	変換結果
TextResourceContents/BlobResourceContents	リソース内容オブジェクト	そのまま保持
ResourceContents の配列	リソース内容オブジェクトの配列	そのまま保持
文字列または文字列に変換可能なオブジェクト	テキスト内容	MIME タイプに応じたリソース内容に変換
null	空値	空の TextResourceContents に変換
配列またはオブジェクト	複雑なデータ構造	JSON 形式のリソース内容に変換

注意事項：

• 2 MB を超える大きなファイル内容は自動的に切り詰められます
• テキストタイプ（text/*）の MIME タイプには TextResourceContents が使用されます
• それ以外の MIME タイプには BlobResourceContents が使用されます

ログ設定

サーバーログはデフォルトで runtime/server_log.txt に保存されます。AbstractMcpServerCommand を継承して変更できます。

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

Docker のサポート

コンテナをビルドして実行します。

docker build -t php-mcp-server .
docker run --name=php-mcp-server -p 8000:8000 -itd php-mcp-server mcp:test-server --transport sse

SSE アドレス：http://127.0.0.1:8000/sse

CPX を使った実行

CPX (Composer Package Executor) を使うと、事前にインストールせずに本プロジェクトを直接実行できます。

前提条件

1. CPX をグローバルにインストールします。

composer global require cpx/cpx

2. Composer のグローバル bin ディレクトリが PATH に含まれていることを確認します。

使用方法

# 运行测试服务器
cpx he426100/php-mcp-server mcp:test-server

# 使用 SSE 传输模式
cpx he426100/php-mcp-server mcp:test-server --transport=sse

# 查看可用命令
cpx he426100/php-mcp-server list

ライセンス

MIT ライセンス

貢献

Issue や Pull Request の投稿を歓迎します。

作者

he426100
logiscape