dalehurley/php-mcp-sdk

Model Context Protocol (MCP) implementation for PHP

Maintainers

Details

github.com/dalehurley/php-mcp-sdk

Homepage

Source

Issues

Installs: 36

Dependents: 1

Suggesters: 0

Security: 0

Stars: 15

Watchers: 1

Forks: 1

Open Issues: 0

v0.1.7 2025-09-17 13:24 UTC

Requires

Requires (Dev)

Suggests

MIT fbd73495b2725d007c29d68f33f44af68c6194e4

  • Your Name <your.email.woop@example.com>

aimcpllmmodel-context-protocol

This package is auto-updated.

Last update: 2025-09-17 13:25:26 UTC

README

Latest Version PHP Version Total Downloads License Documentation

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)

🏗️ Implementation Guides

🤖 Agentic AI Development

🏭 Real-World Applications

🏢 Enterprise & Production

📖 API Reference

🔄 Migration & Examples

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