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

dalehurley/php-mcp-sdk

包简介

关键字：

README 文档