README

A complete PHP implementation of the Model Context Protocol (MCP), providing both server and client functionality with support for multiple transport protocols.

Language: English | 简体中文

✨ Key Features

• 🚀 Latest MCP Protocol - Supports MCP 2025-03-26 specification
• 🔧 Complete Implementation - Tools, resources, and prompts support
• 🔌 Multiple Transports - STDIO ✅, HTTP ✅, Streamable HTTP 🚧
• 🌐 Framework Compatible - Works with any PSR-compliant framework, built-in Hyperf integration
• 📚 Well Documented - Comprehensive guides in English and Chinese

🚀 Quick Start

Installation

composer require dtyq/php-mcp

Hyperf Framework Quick Integration

If you're using Hyperf framework, integration is extremely simple:

// Just one line of code!
Router::addRoute(['POST', 'GET', 'DELETE'], '/mcp', function () {
    return \Hyperf\Context\ApplicationContext::getContainer()->get(HyperfMcpServer::class)->handle('default');
});

Annotation-Based Registration:

class CalculatorService
{
    #[McpTool(description: 'Mathematical calculations')]
    public function calculate(string $operation, int $a, int $b): array
    {
        return ['result' => match($operation) {
            'add' => $a + $b,
            'multiply' => $a * $b,
            default => 0
        }];
    }
    
    #[McpResource(description: 'System information')]
    public function systemInfo(): TextResourceContents
    {
        return new TextResourceContents('mcp://system/info', 
            json_encode(['php' => PHP_VERSION]), 'application/json');
    }
}

Advanced Options:

• 🔐 AuthenticatorInterface - Custom authentication
• 📊 HttpTransportAuthenticatedEvent - Dynamic tool/resource registration
• 📝 Annotation System - Auto-register tools, resources and prompts

👉 View Complete Hyperf Integration Guide

Basic Server Example

<?php
require_once 'vendor/autoload.php';

use Dtyq\PhpMcp\Server\McpServer;
use Dtyq\PhpMcp\Shared\Kernel\Application;

// Create server with simple container
$container = /* your PSR-11 container */;
$app = new Application($container, ['sdk_name' => 'my-server']);
$server = new McpServer('my-server', '1.0.0', $app);

// Add a tool
$server->registerTool(
    new \Dtyq\PhpMcp\Types\Tools\Tool('echo', [
        'type' => 'object',
        'properties' => ['message' => ['type' => 'string']],
        'required' => ['message']
    ], 'Echo a message'),
    function(array $args): array {
        return ['response' => $args['message']];
    }
);

// Start server
$server->stdio(); // or $server->http($request)

Basic Client Example

<?php
use Dtyq\PhpMcp\Client\McpClient;
use Dtyq\PhpMcp\Client\Configuration\StdioConfig;

$client = new McpClient('my-client', '1.0.0', $app);

// ✅ Recommended: Use shortcut methods with typed configuration
$config = new StdioConfig('php server.php');
$session = $client->stdio($config);
$session->initialize();

// Call a tool
$result = $session->callTool('echo', ['message' => 'Hello, MCP!']);
echo $result->getContent()[0]->getText();

Alternative Methods:

// HTTP shortcut method
use Dtyq\PhpMcp\Client\Configuration\HttpConfig;
$httpConfig = new HttpConfig('http://localhost:8080/mcp');
$session = $client->http($httpConfig);

// ⚠️ Legacy method (deprecated)
$session = $client->connect('stdio', ['command' => 'php server.php']);

📖 Documentation

• 📚 Complete Documentation - All guides and references
• 📖 Project Overview - Architecture, features, and use cases
• 🚀 Quick Start Guide - 5-minute tutorial
• 🔧 Server Guides - Build MCP servers
• 📡 Client Guides - Create MCP clients

Working Examples

Check the /examples directory:

• stdio-server-test.php - Complete STDIO server
• http-server-test.php - HTTP server with tools
• stdio-client-test.php - STDIO client example
• http-client-test.php - HTTP client example

🌟 Transport Protocols

🛠️ Requirements

• PHP: 7.4+ (8.0+ recommended)
• Extensions: json, mbstring, openssl, pcntl, curl
• Composer: For dependency management

🤝 Contributing

We welcome contributions! Please see our issues page for areas where you can help.

git clone https://github.com/dtyq/php-mcp.git
cd php-mcp
composer install
composer test

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol for the specification
• Anthropic for creating MCP
• The PHP community for excellent tooling and support

⭐ Star this repository if you find it useful!