AI导哈

Laravel MCP集成包

一个全面的Laravel包，提供与模型上下文协议（MCP）的无缝集成，使Laravel开发者能够轻松创建MCP服务器，向AI应用程序如Claude Desktop、Claude Code和ChatGPT Desktop公开工具、资源和提示。

  • by jerthedev
  • PHP
  • 本地部署
  • 更新于
在 GitHub 查看 jerthedev/laravel-mcp

使用说明

Laravel MCP

一个全面的Laravel包，提供与 模型上下文协议（MCP），使Laravel开发人员能够轻松创建MCP服务器，这些服务器可以向Claude Desktop、Claude Code和ChatGPT Desktop等AI应用程序公开工具、资源和提示。

什么是MCP？

模型上下文协议（MCP）是一个开放标准，它实现了人工智能应用程序和外部系统之间安全、受控的交互。它允许您：

  • 显示工具：AI可以执行的函数（例如，数据库查询、API调用）
  • 提供资源：AI可以读取的数据源（例如文件、文档、配置）
  • 分享提示：用于一致人工智能交互的模板系统

特性

核心功能

  • 🚀 Laravel原生：基于Laravel约定和模式构建
  • 🔌 双重运输：支持HTTP和Stdio传输
  • 🎯 自动发现：自动注册您的MCP组件
  • 🛠️ Artisan命令：快速生成工具、资源和提示
  • 🔒 安全第一：内置身份验证和授权
  • 📚 有据可查：综合指南和示例
  • ✅ 经过全面测试：Laravel测试工具的高测试覆盖率
  • 🪶 轻量级：自定义MCP 1.0实现，不依赖外部SDK

增强的生产功能

  • ⚡ 异步处理：基于队列的MCP请求处理和作业监控
  • 📊 事件驱动架构：10多个事件，内置和自定义监听器
  • 🚨 高级监控：绩效监控和指标收集
  • 🛡️ 7层中间件栈：生产安全和验证管道
  • 📨 通知系统：多渠道交付（电子邮件、Slack、数据库）
  • 🏗️ 服务提供商：100%符合增强功能的规格

需求

  • PHP程序：8.2或更高
  • 拉瑞维尔：11.0或更高
  • 扩展: ext-json, ext-mbstring

安装

通过Composer安装软件包：

composer require jerthedev/laravel-mcp

该包将通过Laravel的包自动发现自动注册。

配置

发布配置文件：

php artisan vendor:publish --tag="laravel-mcp"

这将创建两个配置文件：

  • config/laravel-mcp.php -主包配置
  • config/mcp-transports.php -特定于运输的设置

基本配置

// config/laravel-mcp.php
return [
    'auto_discovery' => [
        'enabled' => true,
        'paths' => [
            'tools' => app_path('Mcp/Tools'),
            'resources' => app_path('Mcp/Resources'),
            'prompts' => app_path('Mcp/Prompts'),
        ],
    ],
    
    'transports' => [
        'http' => [
            'enabled' => true,
            'prefix' => 'mcp',
        ],
        'stdio' => [
            'enabled' => true,
        ],
    ],
];

快速开始

1.创建您的第一个MCP工具

php artisan make:mcp-tool DatabaseQueryTool

这会产生 app/Mcp/Tools/DatabaseQueryTool.php:

<?php

namespace App\Mcp\Tools;

use JTD\LaravelMCP\Abstracts\McpTool;

class DatabaseQueryTool extends McpTool
{
    public function getName(): string
    {
        return 'database_query';
    }
    
    public function getDescription(): string
    {
        return 'Execute database queries safely';
    }
    
    public function getInputSchema(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'query' => [
                    'type' => 'string',
                    'description' => 'SQL query to execute'
                ]
            ],
            'required' => ['query']
        ];
    }
    
    public function execute(array $params): array
    {
        // Your tool logic here
        return ['result' => 'Query executed successfully'];
    }
}

2.创建MCP资源

php artisan make:mcp-resource UserResource

3.创建MCP提示

php artisan make:mcp-prompt EmailTemplate

4.配置克劳德桌面

生成Claude桌面配置：

php artisan mcp:register --client=claude-desktop

这将为Claude Desktop创建一个配置文件，以连接到您的MCP服务器。

使用示例

HTTP传输（Web集成）

您的MCP服务器通过HTTP路由自动可用：

# List available tools
GET /mcp/tools

# Execute a tool
POST /mcp/tools/database_query
Content-Type: application/json

{
    "params": {
        "query": "SELECT * FROM users LIMIT 5"
    }
}

Stdio传输（桌面AI客户端）

Stdio传输由桌面AI客户端使用，如Claude desktop：

# Start MCP server
php artisan mcp:serve

高级用法

自定义身份验证

// In your AppServiceProvider
use JTD\LaravelMCP\Facades\Mcp;

public function boot(): void
{
    Mcp::authenticateUsing(function ($request) {
        return $request->bearerToken() === config('app.mcp_token');
    });
}

动态资源内容

public function getContent(): string
{
    return Cache::remember('user-stats', 300, function () {
        return json_encode([
            'total_users' => User::count(),
            'active_sessions' => Session::where('last_activity', '>', now()->subMinutes(15))->count(),
        ]);
    });
}

验证和错误处理

public function execute(array $params): array
{
    $validator = Validator::make($params, [
        'email' => 'required|email',
        'message' => 'required|string|max:1000',
    ]);
    
    if ($validator->fails()) {
        throw new McpValidationException($validator->errors());
    }
    
    // Execute your logic...
}

可用命令

# Generate MCP components
php artisan make:mcp-tool CalculatorTool
php artisan make:mcp-resource UserResource  
php artisan make:mcp-prompt EmailTemplate

# Server management
php artisan mcp:serve                    # Start stdio server
php artisan mcp:list                     # List registered components

# Client configuration
php artisan mcp:register                 # Generate config for AI clients

传输配置

HTTP传输

HTTP传输使您的MCP服务器可以通过Laravel路由访问：

// config/mcp-transports.php
'http' => [
    'enabled' => true,
    'prefix' => 'mcp',
    'middleware' => ['auth:sanctum', 'throttle:60,1'],
    'cors' => [
        'enabled' => true,
        'origins' => ['https://claude.ai'],
    ],
],

标准运输

Stdio传输用于桌面AI客户端：

'stdio' => [
    'enabled' => true,
    'timeout' => 30,
    'buffer_size' => 4096,
],

开发状态

🎉 生产准备就绪！ 该软件包现已完成全面实施：

✅ 已完成的功能

  • [x] 包装架构：配备增强型服务提供商
  • [x] MCP协议实现：完全符合JSON-RPC 2.0和MCP 1.0
  • [x] 传输层：具有生产功能的HTTP和Stdio传输
  • [x] 组件系统：具有自动发现功能的工具、资源和提示抽象
  • [x] Artisan命令：具有基于特征的架构的完整指挥系统（100%符合规范）
  • [x] Laravel集成：事件系统、作业、通知、中间件
  • [x] 服务提供商：100%符合增强功能的规格
  • [x] 测试基础设施：727次快速测试，1355次单元测试，CI/CD管道
  • [x] 文档：全面的规格和使用示例

🏗️ 架构状态

  • ✅ 核心服务：登记、运输、协议处理
  • ✅ 增强的服务：性能监控、模式验证、调试
  • ✅ 事件系统：10多个事件，内置和自定义监听器
  • ✅ 异步处理：基于队列的处理和作业监控
  • ✅ 通知系统：多渠道交付（电子邮件、Slack、数据库）
  • ✅ 安全：7层中间件堆栈，具有全面的验证功能

测试

综合测试基础设施

该包实现了 分层测试策略 为了优化开发工作流程：

# Fast tests for CI/CD (727 tests, ~9.4s)
composer test:fast

# Unit tests (1,355 tests, ~15s)  
composer test:unit

# Feature tests
composer test:feature

# Full comprehensive suite (1,624+ tests, ~20s)
composer test:comprehensive

# Run with coverage
composer test:coverage

测试状态

  • ✅ 727快速测试：核心功能验证（CI友好）
  • ✅ 1355单元测试：全面的单元测试覆盖率
  • ✅ GitHub操作CI：推送/PR的自动测试
  • ✅ 生产就绪：所有关键路径都经过测试和验证

检查代码样式：

composer pint

运行静态分析：

composer analyse

文档

提供全面的文档：

贡献

请看 贡献 了解如何为这个项目做出贡献的详细信息。

安全

如果您发现任何与安全相关的问题，请发送电子邮件至jeremy@jerthedev.com而不是使用问题跟踪器。

鸣谢

相关项目

许可证

MIT许可证（MIT）。请看 许可证 了解更多信息。

相关 MCP