PHP Model Context Protocol Server SDK

PHP Model Context Protocol サーバー SDK

このプロジェクトは、Model Context Protocol（MCP）の PHP 実装を提供し、LLM（大規模言語モデル）にコンテキスト（データやツール）を提供するサーバーを構築できます。

MCP は、アプリケーションが LLM とどのように連携するかを標準化するオープンプロトコルです。MCP の詳細については、公式サイトをご覧ください：https://modelcontextprotocol.io

機能

この PHP MCP SDK では、以下の主要機能を利用できます。

• サーバー実装：MCP 準拠のサーバーを簡単に作成できます。
• 機能：
  • Tools：LLM が実行できる機能を公開します。
  • Resources：LLM にデータやコンテンツを提供します。
• トランスポート：
  • StdioTransport：コマンドラインベースの MCP サーバー向けです。
  • HttpTransport：HTTP 経由で MCP サーバーを公開します（Apache/Nginx と PHP-FPM/mod_php などの標準的な PHP ウェブサーバー環境に対応）。
• JSON-RPC 処理：リクエストの解析とレスポンスのフォーマットを処理します。
• 属性ベースの設定：PHP の属性を使って、ツール、リソース、およびそのパラメーターを定義できます。

はじめに

このガイドでは、この SDK を使って簡単な MCP サーバーを作成する手順を説明します。

前提条件

• PHP 8.1 以降
• 依存関係の管理に使用する Composer

インストール

Composer を使って依存関係をインストールします。

composer require james2037/mcp-php-server

STDIO サーバーの作成

STDIO サーバーは標準入力と標準出力を介して通信します。ローカルツールや開発用途で一般的に使われます。

以下の例では、次の機能を備えたサーバーを示します。

1. EchoTool：文字列を受け取り、そのまま返します。
2. GreetingResource：固定の挨拶メッセージを提供します。

この例の完全なコードは examples/stdio_server.php にあります。

examples/stdio_server.php の主な部分：

<?php

// Autoload dependencies
require_once __DIR__ . '/../vendor/autoload.php';

// Required MCP SDK classes
use MCP\Server\Server;
use MCP\Server\Transport\StdioTransport;
use MCP\Server\Capability\ToolsCapability;
use MCP\Server\Capability\ResourcesCapability;

// For defining the tool
use MCP\Server\Tool\Tool as BaseTool;
use MCP\Server\Tool\Attribute\Tool as ToolAttribute;
use MCP\Server\Tool\Attribute\Parameter;

// For defining the resource
use MCP\Server\Resource\Resource as BaseResource;
use MCP\Server\Resource\Attribute\ResourceUri;
use MCP\Server\Resource\ResourceContents;

// 1. Define a Tool
#[ToolAttribute(name: "echo", description: "Echoes back the provided message.")]
class EchoTool extends BaseTool
{
    protected function doExecute(array $arguments): array {
        // Access parameters from the $arguments array
        $message = $arguments['message'] ?? 'Default message if not provided';
        return [$this->createTextContent("Echo: " . $message)];
    }
}

// 2. Define a Resource
#[ResourceUri(uri: "greeting://welcome", description: "Provides a welcome greeting.")]
class GreetingResource extends BaseResource
{
    public function __construct()
    {
        parent::__construct("Welcome Greeting", "text/plain");
    }

    public function read(array $parameters = []): ResourceContents
    {
        return $this->text("Hello from your MCP server!");
    }
}

// 3. Instantiate the Server
$server = new Server('MySimpleServer (STDIO)', '1.0.0');

// 4. Setup and Add Tools Capability
$toolsCapability = new ToolsCapability();
$toolsCapability->addTool(new EchoTool());
$server->addCapability($toolsCapability);

// 5. Setup and Add Resources Capability
$resourcesCapability = new ResourcesCapability();
$resourcesCapability->addResource(new GreetingResource());
$server->addCapability($resourcesCapability);

// 6. Connect StdioTransport
$transport = new StdioTransport();
$server->connect($transport);

// 7. Run the Server
fwrite(STDERR, "STDIO Server listening...\n"); // Optional: message to stderr
$server->run();

(注：EchoTool::doExecute メソッドでは、パラメーターとして array $arguments を使用します。これは、基底の Tool クラスがすべての引数を連想配列としてこのメソッドに渡すためです。ツールのロジックでは、この配列から特定のパラメーターにアクセスしてください（例：$arguments['message']）。)

STDIO サーバーの実行：

ターミナルからスクリプトを実行します。

php examples/stdio_server.php

サーバーは標準入力で JSON-RPC メッセージを待ち受けます。

HTTP サーバーの作成

HttpTransport を使って、MCP サーバーを HTTP 経由で公開することもできます。この例では、同じ EchoTool と GreetingResource を使用します。

この例の完全なコードは examples/http_server.php にあります。このスクリプトには、PSR-7 および PSR-17 の HTTP メッセージ実装（nyholm/psr7 や nyholm/psr7-server など。これらは composer.json に含まれています）が必要です。

examples/http_server.php の主な部分：

<?php

// Autoload dependencies
require_once __DIR__ . '/../vendor/autoload.php';

// Required MCP SDK classes & PSR implementations
use MCP\Server\Server;
use MCP\Server\Transport\HttpTransport;
use MCP\Server\Capability\ToolsCapability;
use MCP\Server\Capability\ResourcesCapability;
use Nyholm\Psr7\Factory\Psr17Factory;
use Nyholm\Psr7Server\ServerRequestCreator;

// Tool and Resource definitions (e.g., EchoTool, GreetingResource)
// would be included here, same as in the STDIO example.
// For brevity, they are omitted from this snippet but are in the actual file.

// --- Assume EchoTool is defined as in the STDIO example ---
use MCP\Server\Tool\Tool as BaseTool;
use MCP\Server\Tool\Attribute\Tool as ToolAttribute;
// Parameter attribute is on the actual class, not repeated in every snippet.
// use MCP\Server\Tool\Attribute\Parameter;
#[ToolAttribute(name: "echo", description: "Echoes back the provided message.")]
class EchoTool extends BaseTool {
    protected function doExecute(array $arguments): array { // Changed signature
        $message = $arguments['message'] ?? 'Default message if not provided'; // Added logic
        return [$this->createTextContent("Echo: " . $message)];
    }
}

// --- Assume GreetingResource is defined as in the STDIO example ---
use MCP\Server\Resource\Resource as BaseResource;
use MCP\Server\Resource\Attribute\ResourceUri;
use MCP\Server\Resource\ResourceContents;
#[ResourceUri(uri: "greeting://welcome", description: "Provides a welcome greeting.")]
class GreetingResource extends BaseResource {
    public function __construct() { parent::__construct("Welcome Greeting", "text/plain"); }
    public function read(array $parameters = []): ResourceContents {
        return $this->text("Hello from your MCP server!");
    }
}


// 1. Create PSR-7 request and factories
$psr17Factory = new Psr17Factory();
$requestCreator = new ServerRequestCreator(
    $psr17Factory, // ServerRequestFactory
    $psr17Factory, // UriFactory
    $psr17Factory, // UploadedFileFactory
    $psr17Factory  // StreamFactory
);
$request = $requestCreator->fromGlobals();

// 2. Instantiate the Server
$server = new Server('MySimpleServer (HTTP)', '1.0.0');

// 3. Setup and Add Capabilities (Tools, Resources)
// Similar to STDIO example:
$toolsCapability = new ToolsCapability();
$toolsCapability->addTool(new EchoTool());
$server->addCapability($toolsCapability);

$resourcesCapability = new ResourcesCapability();
$resourcesCapability->addResource(new GreetingResource());
$server->addCapability($resourcesCapability);

// 4. Instantiate and connect HttpTransport
$transport = new HttpTransport($request, $psr17Factory, $psr17Factory);
$server->connect($transport);

// 5. Run the Server
// For HTTP, run() processes the current request and sends the response.
$server->run();

HTTP サーバーの実行：

開発には PHP の組み込みウェブサーバーを使用します。

php -S localhost:8000 examples/http_server.php

次に、curl などの HTTP クライアントを使って MCP リクエストを送信します。

echo ツールに対する curl リクエストの例：

curl -X POST -H "Content-Type: application/json"      -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"echo","arguments":{"message":"Hello HTTP"}},"id":1}'      http://localhost:8000/

JSON-RPC レスポンスの例：

{"jsonrpc":"2.0","result":{"content":[{"type":"text","text":"Echo: Hello HTTP"}],"isError":false},"id":1}

PHP-FPM または mod_php での使用

examples/http_server.php スクリプトは、PHP-FPM または mod_php を使用する Apache や Nginx など、一般的な PHP ウェブサーバー環境と互換性があるように設計されています。

要点：

• 単一リクエストの処理： このスクリプトは、特に (new HttpTransport(...))->run() が単一の HTTP リクエストを処理した後に終了します。このモデルは、PHP-FPM と mod_php が PHP リクエストを処理する方法に適しています。ウェブサーバーへの各 HTTP リクエストがこのスクリプトにルーティングされると、その都度新たに実行されます。
• PSR-7 の fromGlobals()： ServerRequestCreator::fromGlobals() を使用すると、ウェブサーバーによって設定された PHP のグローバル変数（例：$_SERVER、$_POST）から PSR-7 リクエストオブジェクトが正しく作成されます。
• 出力処理： SDK の HttpTransport は内部で SAPI エミッター（Laminas\HttpHandlerRunner\Emitter\SapiEmitter など）を使用し、ヘッダーと本文の内容をウェブサーバーに正しく送信して、クライアントに配信します。

ウェブサーバーの設定例：

ウェブサーバー（Nginx や Apache など）を設定し、リクエストを http_server.php スクリプトに渡します。

• Nginx の例（概念例）：

  server {
      listen 80;
      server_name your-mcp-server.example.com;
      root /path/to/your/project/examples; # または http_server.php の配置場所
  
      location / {
          try_files $uri /http_server.php$is_args$args;
      }
  
      location ~ \.php$ {
          include snippets/fastcgi-php.conf;
          fastcgi_pass unix:/var/run/php/php8.1-fpm.sock; # PHP-FPM のバージョン／ソケットに合わせて変更してください
          fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
          include fastcgi_params;
      }
  }
  

• Apache の例（概念例。AllowOverride が有効な場合に、examples ディレクトリで .htaccess を使用）：

  RewriteEngine On
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule ^(.*)$ http_server.php [L,QSA]
  

  mod_rewrite が有効になっていることを確認してください。また、Apache の VirtualHost で PHP スクリプトを実行するための設定も必要です。

サーバーの実行： PHP の組み込み開発サーバーを起動する php -S localhost:8000 examples/http_server.php コマンドとは異なり、PHP-FPM／mod_php の環境では、メインのウェブサーバー（Nginx／Apache）がリクエストを受け取り、PHP インタープリターに渡します。同じ方法でサーバーを「起動」するために、別途 PHP コマンドを実行する必要はありません。

HTTP サーバーのテスト用に前述した curl コマンドはそのまま使用でき、ウェブサーバーで設定した URL（例：http://your-mcp-server.example.com/）を指定します。

詳細情報

MCP の概念、機能、高度な使用方法について詳しくは、ソースコードと公式のModel Context Protocol ドキュメントを参照してください。