README

PHP implementation of the Model Context Protocol (MCP), enabling seamless integration between LLM applications and external data sources and tools.

✨ Features

• 🚀 Complete MCP Protocol Support - Full implementation of the MCP specification
• 🔧 Type-Safe - Leverages PHP 8.1+ type system with enums, union types, and strict typing
• ⚡ Async First - Built on Amphp for non-blocking I/O operations
• 🔌 Multiple Transports - STDIO, HTTP Streaming, and WebSocket
• 🔐 OAuth 2.0 Ready - Built-in authentication with PKCE support
• 🏗️ Framework Integration - Laravel, Symfony, and PSR-compatible design
• 📦 PSR Compliant - Follows PSR-4, PSR-7, PSR-12, and PSR-15 standards
• 🛡️ Production Ready - Comprehensive error handling, logging, and monitoring
• 🤖 Agentic AI Support - Build intelligent AI agents with MCP tool orchestration
• 🏭 Real-World Examples - Complete applications (Blog CMS, Task Manager, API Gateway)
• 📚 Comprehensive Documentation - Best-in-class documentation with tested examples
• 🧪 Automated Testing - All documentation examples are automatically tested

📋 Requirements

• PHP 8.1+ - Leverages modern PHP features
• Composer - For dependency management
• ext-json - JSON processing
• ext-mbstring - String handling

🚀 Installation

Via Composer

composer require dalehurley/php-mcp-sdk

Development Version

composer require dalehurley/php-mcp-sdk:dev-main

⚡ Quick Start

Creating an MCP Server

#!/usr/bin/env php
<?php
require_once __DIR__ . '/vendor/autoload.php';

use MCP\Server\McpServer;
use MCP\Server\Transport\StdioServerTransport;
use MCP\Types\Implementation;
use function Amp\async;

// Create the simplest possible MCP server
$server = new McpServer(
    new Implementation(
        'hello-world-server',
        '1.0.0'
    )
);

// Add a simple "say_hello" tool
$server->tool(
    'say_hello',
    'Says hello to someone',
    [
        'type' => 'object',
        'properties' => [
            'name' => [
                'type' => 'string',
                'description' => 'Name of the person to greet'
            ]
        ],
        'required' => ['name']
    ],
    function (array $args): array {
        $name = $args['name'] ?? 'World';

        return [
            'content' => [
                [
                    'type' => 'text',
                    'text' => "Hello, {$name}! 👋 Welcome to MCP!"
                ]
            ]
        ];
    }
);

// Start the server
async(function () use ($server) {
    echo "🚀 Hello World MCP Server starting...\n";

    $transport = new StdioServerTransport();
    $server->connect($transport)->await();
})->await();

Creating an MCP Client

#!/usr/bin/env php
<?php
require_once __DIR__ . '/vendor/autoload.php';

use MCP\Client\Client;
use MCP\Client\Transport\StdioClientTransport;
use MCP\Types\Implementation;
use Amp\Loop;

// Create client
$client = new Client(
    new Implementation('weather-client', '1.0.0')
);

// Connect to weather server
$transport = new StdioClientTransport([
    'command' => 'php',
    'args' => [__DIR__ . '/weather-server.php']
]);

Amp\async(function() use ($client, $transport) {
    try {
        // Connect to server
        yield $client->connect($transport);
        echo "✅ Connected to weather server\n";

        // List available tools
        $result = yield $client->listTools();
        echo "📋 Available tools:\n";
        foreach ($result['tools'] as $tool) {
            echo "  - {$tool['name']}: {$tool['description']}\n";
        }

        // Call the weather tool
        $result = yield $client->callTool('get-weather', [
            'location' => 'London, UK'
        ]);

        echo "\n🌤️  Weather result:\n";
        echo $result['content'][0]['text'] . "\n";

        yield $client->close();

    } catch (\Exception $error) {
        echo "❌ Error: " . $error->getMessage() . "\n";
    } finally {
        Loop::stop();
    }
});

Loop::run();

Test Your Implementation

# Run the hello-world server
php examples/getting-started/hello-world-server.php

# Test with Claude Desktop by adding to your configuration:
{
  "mcpServers": {
    "hello-world": {
      "command": "php",
      "args": ["/path/to/examples/getting-started/hello-world-server.php"]
    }
  }
}

# Or test with the MCP Inspector (Node.js required)
npx @modelcontextprotocol/inspector examples/getting-started/hello-world-server.php

🎯 Examples Overview

The PHP MCP SDK includes 20+ comprehensive examples across all skill levels:

🎓 Getting Started (4 examples)

• Hello World - Simplest possible server and client
• Calculator - Multi-tool server with math operations
• File Reader - Secure file system integration
• Weather Client - External API integration patterns

🏗️ Framework Integration (2 examples)

• Laravel Integration - Complete Laravel patterns with service container
• Symfony Integration - Full Symfony integration with DI container

🤖 Agentic AI (4 examples)

• Working Agentic Demo - Rule-based agent reasoning
• Personal Assistant - Multi-MCP server coordination
• Multi-Agent Orchestrator - Specialized agent coordination
• OpenAI Integration - LLM-powered intelligent agents

🏭 Real-World Applications (5 examples)

• Blog CMS - Complete content management system
• Task Manager - Project management with analytics
• API Gateway - Enterprise API orchestration
• Code Analyzer - Development quality tools
• Data Pipeline - ETL and data processing

🏢 Enterprise & Production (3 examples)

• Docker Deployment - Production containerization
• Microservices Architecture - Distributed systems patterns
• Monitoring & Observability - Production monitoring

All examples are tested and working! 🎉

Framework Integration

The PHP MCP SDK is designed to work with any PHP framework through its PSR-compliant architecture.

Laravel Integration

You can use the core PHP MCP SDK directly in Laravel applications:

composer require dalehurley/php-mcp-sdk

// In a Laravel controller or service
use MCP\Server\McpServer;
use MCP\Types\Implementation;

class McpController extends Controller
{
    public function createServer()
    {
        $server = new McpServer(
            new Implementation('my-laravel-app', '1.0.0')
        );

        // Register your tools, resources, and prompts
        $server->tool('search-users', 'Search for users', [
            'type' => 'object',
            'properties' => [
                'query' => ['type' => 'string', 'description' => 'Search query']
            ]
        ], function($params) {
            return [
                'content' => [
                    [
                        'type' => 'text',
                        'text' => json_encode(User::where('name', 'like', "%{$params['query']}%")->get())
                    ]
                ]
            ];
        });

        return $server;
    }
}

For a complete Laravel package with service providers, Artisan commands, and Laravel-specific features, see the separate laravel-mcp-sdk package.

📚 Documentation

The most comprehensive MCP SDK documentation in the ecosystem is available in the docs/ directory:

🎓 Getting Started (Beginner-Friendly)

• 📖 Complete Documentation - Start here for full overview
• ⚡ Quick Start Guide - Get up and running in 5 minutes
• 🏗️ First Server - Build your first server in 10 minutes
• 📱 First Client - Build your first client in 10 minutes
• 🧠 Understanding MCP - Deep dive into MCP protocol
• 💡 Core Concepts - Understand MCP fundamentals
• 🔧 Troubleshooting - Common issues and solutions

🏗️ Implementation Guides

• 📱 Creating Clients - Build MCP clients
• 🔐 Security Best Practices - OAuth 2.0 and security
• 🛠️ Tools Guide - Server development with tools
• 📚 Resources Guide - Server development with resources
• 🤖 OpenAI Integration - AI tool calling
• 📊 FullCX Integration - Product management

🤖 Agentic AI Development

• 🧠 Build Agentic AI Agents - Complete agentic AI tutorial
• 🎯 Agent Examples - Working agent implementations
• 🔗 Multi-Agent Systems - Agent coordination

🏭 Real-World Applications

• 📝 Blog CMS - Complete content management system
• 📋 Task Manager - Project management system
• 🚀 API Gateway - Enterprise API management
• 🔍 Code Analyzer - Development quality tools
• 🔄 Data Pipeline - ETL and data processing

🏢 Enterprise & Production

• 🐳 Docker Deployment - Containerization
• 🏗️ Microservices - Distributed systems
• 📊 Monitoring - Observability

📖 API Reference

• 🔧 Server API - Complete server API
• 📡 Client API - Complete client API
• 📋 Types & Schemas - Type system reference

🔄 Migration & Examples

• 💻 Working Examples - 20+ tested examples
• 🔄 TypeScript Migration - Migration guide

Testing

# Run tests
composer test

# Run tests with coverage
composer test-coverage

# Run static analysis
composer phpstan
composer psalm

# Fix code style
composer cs-fix

# Run all checks
composer check

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Changelog

All notable changes to this project are documented in the CHANGELOG.md. Please update it when making changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Based on the MCP TypeScript SDK
• Built with Amphp for async operations
• Uses Respect/Validation for schema validation