MCP SDK for Laravel

Laravel 的 MCP SDK

一个用于与模型上下文协议（MCP）服务交互和实现 MCP 服务的 Laravel 软件包。

安装

你可以通过 composer 安装该软件包：

composer require ronydebnath/mcp-sdk

该软件包会自动注册其服务提供程序。

你可以发布配置文件：

php artisan vendor:publish --provider="Ronydebnath\MCP\MCPServiceProvider" --tag="config"

这将在你的配置目录中创建一个 config/mcp.php 文件。

配置

该软件包的配置文件包含客户端和服务端功能的相关设置：

return [
    'default' => env('MCP_CONNECTION', 'default'),
    
    'connections' => [
        'default' => [
            'host' => env('MCP_HOST', 'localhost'),
            'port' => env('MCP_PORT', 8000),
            'timeout' => env('MCP_TIMEOUT', 30),
            'verify' => env('MCP_VERIFY_SSL', true),
        ],
    ],

    'server' => [
        'session_expiry' => env('MCP_SESSION_EXPIRY', 60),
        'max_connections' => env('MCP_MAX_CONNECTIONS', 100),
        'allowed_origins' => explode(',', env('MCP_ALLOWED_ORIGINS', '*')),
    ],

    'auth' => [
        'token_expiry' => env('MCP_TOKEN_EXPIRY', 60),
        'token_length' => env('MCP_TOKEN_LENGTH', 32),
    ],

    'memory' => [
        'max_size' => env('MCP_MEMORY_MAX_SIZE', 100),
        'persist' => env('MCP_MEMORY_PERSIST', false),
        'storage_path' => env('MCP_MEMORY_STORAGE_PATH', storage_path('app/mcp/memory')),
    ],

    'message' => [
        'default_type' => 'text',
        'max_length' => env('MCP_MAX_MESSAGE_LENGTH', 4096),
    ],
];

使用 MCP 客户端

使用依赖注入

use Ronydebnath\MCP\Client\MCPClient;
use Ronydebnath\MCP\Types\Message;
use Ronydebnath\MCP\Types\Role;

class YourController
{
    public function __construct(private MCPClient $client)
    {}

    public function handle()
    {
        $message = new Message(
            role: Role::USER,
            content: 'Hello, how are you?',
            type: 'text'
        );

        $response = $this->client->send($message);
    }
}

使用 Facade

use Ronydebnath\MCP\Facades\MCP;
use Ronydebnath\MCP\Types\Message;
use Ronydebnath\MCP\Types\Role;

$message = new Message(
    role: Role::USER,
    content: 'Hello, how are you?',
    type: 'text'
);

$response = MCP::send($message);

发送多条消息

use Ronydebnath\MCP\Client\MCPClient;
use Ronydebnath\MCP\Types\Message;
use Ronydebnath\MCP\Types\Role;

$messages = [
    new Message(role: Role::USER, content: 'First message', type: 'text'),
    new Message(role: Role::USER, content: 'Second message', type: 'text'),
];

$responses = $client->sendMultiple($messages);

使用流式传输

use Ronydebnath\MCP\Client\StreamingMCPClient;
use Ronydebnath\MCP\Types\Message;
use Ronydebnath\MCP\Types\Role;

// Using Dependency Injection
class YourController
{
    public function __construct(private StreamingMCPClient $client)
    {}

    public function handle()
    {
        $message = new Message(
            role: Role::USER,
            content: 'Hello, how are you?',
            type: 'text'
        );

        $this->client->stream($message, function ($chunk) {
            // Handle each chunk of the response
            echo $chunk['content'];
        });
    }
}

// Using the Facade
MCP::stream($message, function ($chunk) {
    echo $chunk['content'];
});

// Streaming multiple messages
$messages = [
    new Message(role: Role::USER, content: 'First message', type: 'text'),
    new Message(role: Role::USER, content: 'Second message', type: 'text'),
];

$client->streamMultiple($messages, function ($chunk) {
    echo $chunk['content'];
});

使用 MCP 服务

设置路由

将以下路由添加到你的 routes/api.php：

use Ronydebnath\MCP\Server\MCPServer;

Route::post('/mcp', function (Request $request, MCPServer $server) {
    return $server->handle($request);
});

注册消息处理程序

use Ronydebnath\MCP\Server\MCPServer;
use Ronydebnath\MCP\Types\Message;
use Ronydebnath\MCP\Types\Role;

$server->registerHandler('text', function (Message $message) {
    return [
        'role' => Role::ASSISTANT->value,
        'content' => 'This is a response to: ' . $message->content,
        'type' => 'text',
    ];
});

使用身份验证

该软件包内置了身份验证支持：

use Ronydebnath\MCP\Server\Auth\AuthMiddleware;
use Ronydebnath\MCP\Server\Auth\AuthProvider;

// Generate a token
$token = $authProvider->generateToken();

// Register the authentication middleware
$server->registerMiddleware(function ($request) use ($authMiddleware) {
    return $authMiddleware->handle($request);
});

客户端可以通过以下任一方式进行身份验证：

1. 在 Authorization 标头中使用 Bearer 令牌：

Authorization: Bearer your-token-here

2. 将令牌作为查询参数：

/mcp?token=your-token-here

处理流式请求

当客户端设置 Accept: text/event-stream 标头时，服务会自动处理流式请求。服务将：

1. 创建新会话或使用现有会话
2. 发送初始连接消息
3. 在响应块可用时将其流式传输
4. 在连接期间维持会话

内存与上下文管理

该软件包包含内存与上下文管理功能，用于维护对话状态：

使用内存

use Ronydebnath\MCP\Shared\Memory;
use Ronydebnath\MCP\Types\Message;
use Ronydebnath\MCP\Types\Role;

$memory = app(Memory::class);

// Add messages to memory
$memory->add(new Message(
    role: Role::USER,
    content: 'Hello',
    type: 'text'
));

// Get messages by role
$userMessages = $memory->getByRole(Role::USER);

// Get messages by type
$textMessages = $memory->getByType('text');

// Clear memory
$memory->clear();

使用上下文

use Ronydebnath\MCP\Shared\Context;
use Ronydebnath\MCP\Types\Message;
use Ronydebnath\MCP\Types\Role;

$context = app(Context::class);

// Set context data
$context->set('user_id', 123);
$context->set('preferences', ['theme' => 'dark']);

// Add messages to context
$context->addMessage(new Message(
    role: Role::USER,
    content: 'Hello',
    type: 'text'
));

// Get context data
$userId = $context->get('user_id');
$messages = $context->getMessages();

// Clear context
$context->clear();

使用进度跟踪

use Ronydebnath\MCP\Shared\Progress;

$progress = app(Progress::class);

// Update progress
$progress->update(50, 'Processing...', ['step' => 'analysis']);

// Increment progress
$progress->increment(10, 'Moving to next step');

// Get progress information
$percentage = $progress->getPercentage();
$status = $progress->getStatus();
$metadata = $progress->getMetadata();

// Check if complete
if ($progress->isComplete()) {
    // Handle completion
}

// Reset progress
$progress->reset();

测试

composer test

安全

如果你发现任何安全相关问题，请发送邮件至 hello[at]ronydebnath.com，而不要使用问题跟踪器。

许可证

MIT 许可证（MIT）。更多信息请参阅许可证文件。