使用说明

Laravel MCP 服务器

一个实现了模型上下文协议（MCP）服务器规范的Laravel包，使AI模型能够通过标准化协议与您的Laravel应用程序进行交互。

特点/功能

✅ 完整实现了MCP 2024-11-05协议
✅ 提供JSON-RPC 2.0的工具和资源支持
✅ 精细的权限系统，具备字段级别的访问控制
✅ 带有参数提取的模板资源
✅ 多种认证方法（API密钥、基本认证、Bearer令牌）
✅ 灵活的自定义认证系统，支持数据库集成
✅ 全面的安全中间件堆栈
✅ 带有客户端控制和突发流量保护的速率限制
✅ 性能监控和详细日志记录
✅ 可扩展的架构，用于自定义工具/资源
✅ 支持 Laravel 10+、11+ 和 12+
✅ 全面的测试套件
✅ 自动发现工具和资源
✅ 新带有自定义解析器的高级权限解析系统
✅ 表示“正确”或“已确认”。新增强字段级安全性，实现数据过滤
✅ 新API密钥审计日志记录和使用追踪
✅ 新带突发流量保护的每键速率限制
✅ 新安全增强（密钥轮换、基于范围的权限）
✅ 新性能监控和指标追踪

安装

通过 Composer 安装包：

composer require chaoticingenuity/laravel-mcp-server

快速入门

1. 发布配置

php artisan vendor:publish --tag=mcp-config

2. 发布控制器（可选）

php artisan vendor:publish --tag=mcp-controllers

注你只需要在想要自定义MCPController时才需要发布。中间件类可以直接从包命名空间中使用。

3. Laravel 版本特定设置

Laravel 11+（包括Laravel 12）安装设置（推荐方法）

对于 Laravel 11 及更高版本，请使用静态辅助方法来注册中间件 bootstrap/app.php:

<?php

use ChaoticIngenuity\LaravelMCP\Providers\MCPServiceProvider;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        // Register MCP middleware aliases using static helper
        $middleware->alias(MCPServiceProvider::middlewareAliases());
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();

将MCP路由添加到您的（系统/网络/配置中） routes/api.php：

<?php

use App\Http\Controllers\MCPController;
use Illuminate\Support\Facades\Route;

Route::post('/mcp', [MCPController::class, 'handle'])
    ->middleware([
        'mcp.security',
        'mcp.auth', 
        'mcp.throttle',
        'mcp.logging'
    ])
    ->name('mcp.handle');

Laravel 10 安装设置

对于Laravel 10，中间件会由服务提供者自动注册。只需确保你的 routes/api.php 包括MCP路线（与上文相同）。

4. 设置环境变量

添加到您的 .env 文件：

# Server Information
MCP_SERVER_NAME="Your MCP Server"
MCP_SERVER_VERSION="1.0.0"

# Authentication - Static Keys (Optional)
MCP_API_KEY_1=mcp_live_sk_1234567890abcdef1234567890abcdef
MCP_CLIENT_1=gpt_client

# User Model Configuration (for database authentication)
MCP_USER_MODEL=App\Models\User
MCP_USER_FOREIGN_KEY=user_id
MCP_USER_OWNER_KEY=id

# Security
MCP_REQUIRE_HTTPS=true
MCP_ALLOWED_IPS=192.168.1.0/24

# Rate Limiting
MCP_RATE_LIMIT=100
MCP_BURST_LIMIT=20

# Logging & Monitoring
MCP_LOG_REQUESTS=true
MCP_LOG_PERFORMANCE=true
MCP_LOG_API_USAGE=false
MCP_TRACK_PERMISSIONS=false

# Performance
MCP_AUTH_CACHE_DURATION=300
MCP_CACHE_PERMISSION_RESULTS=true
MCP_PERMISSION_CACHE_TTL=300

5. 配置身份验证

选择您的认证策略：

选项A：静态配置（简单）

编辑 config/mcp.php：

'clients' => [
    'gpt_client' => [
        'permissions' => [
            'tools.echo',
            'resources.status',
        ],
        'field_access' => [],
        'metadata' => ['tier' => 'standard']
    ],
],

选项B：数据库认证（推荐）

在您的用户模型中添加MCP支持：

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use ChaoticIngenuity\LaravelMCP\Traits\HasMCPAuthentication;
use ChaoticIngenuity\LaravelMCP\Contracts\MCPUserInterface;

class User extends Authenticatable implements MCPUserInterface
{
    use HasMCPAuthentication;

    protected $fillable = [
        'name', 'email', 'password', 'mcp_enabled', 'mcp_permissions', 'mcp_field_access'
    ];

    protected $casts = [
        'email_verified_at' => 'datetime',
        'password' => 'hashed',
        'mcp_enabled' => 'boolean',
        'mcp_permissions' => 'array',
        'mcp_field_access' => 'array',
        'mcp_tokens' => 'array',
        'mcp_scopes' => 'array', // NEW: Scope-based permissions
    ];

    // Optional: Customize permissions based on user roles
    public function getMCPPermissions(): array
    {
        if ($this->hasRole('admin')) {
            return ['admin'];
        }

        if ($this->hasRole('api_user')) {
            return [
                'tools.*',
                'resources.catalog',
                'products.read'
            ];
        }

        return parent::getMCPPermissions();
    }
}

运行迁移：

# Option A: For API key-based authentication (includes both api_keys table and users table fields)
php artisan vendor:publish --tag=mcp-migrations-api-keys
php artisan migrate

# Option B: For Bouncer integration (enables MCP for existing Bouncer users)
php artisan vendor:publish --tag=mcp-migrations-bouncer
php artisan migrate

# Option C: Custom implementation (no migrations needed - implement custom storage in your User model)
# See examples in documentation for user table columns, JSON storage, etc.

// In the migration file
public function up(): void
{
    Schema::table('users', function (Blueprint $table) {
        $table->boolean('mcp_enabled')->default(false);
        $table->json('mcp_permissions')->nullable();
        $table->json('mcp_field_access')->nullable();
        $table->json('mcp_tokens')->nullable();
        $table->json('mcp_scopes')->nullable(); // NEW: Scope-based permissions
        
        $table->index('mcp_enabled');
    });
}

启用自定义数据库认证器：

// config/mcp.php
'auth' => [
    'custom_authenticators' => [
        \App\Services\Custom\MCP\Auth\DatabaseAuthenticator::class,
    ],
],

6. 测试安装

# Generate an API key for a user (if using database auth)
php artisan tinker
>>> $user = User::find(1);
>>> $apiKey = $user->generateMCPApiKey('test_client', ['tools.*']);
>>> echo $apiKey->key;

# Test the endpoint
curl -X POST http://your-app.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-MCP-API-Key: mcp_live_sk_1234567890abcdef1234567890abcdef" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

7. 验证

检查一切是否正常运行：

# Verify routes are registered
php artisan route:list --name=mcp

# Check middleware is loaded
php artisan route:show mcp.handle

# Clear cache if needed
php artisan optimize:clear

高级功能（v1.1.0+）

权限解析系统

该包现在包含一个灵活的权限解析系统，允许自定义权限逻辑：

// Create custom permission resolvers
class OrganizationPermissionResolver implements PermissionResolverInterface
{
    public function resolveUserPermissions($user): array
    {
        // Custom logic based on organization membership
        $orgPermissions = $user->organization->mcp_permissions ?? [];
        $userPermissions = $user->mcp_permissions ?? [];
        
        return array_merge($orgPermissions, $userPermissions);
    }
    
    public function resolveUserFieldAccess($user): array
    {
        // Dynamic field access based on user tier
        return match($user->subscription_tier) {
            'premium' => ['*'],
            'standard' => ['name', 'price', 'description'],
            'basic' => ['name', 'price'],
            default => []
        };
    }
    
    public function canResolve($user): bool
    {
        return $user->organization !== null;
    }
    
    public function getPriority(): int
    {
        return 50; // Medium priority
    }
}

// Register in config/mcp.php
'auth' => [
    'custom_permission_resolvers' => [
        \App\Services\MCP\OrganizationPermissionResolver::class,
    ],
],

增强的API密钥管理

高级API密钥功能，配备审计日志和每密钥速率限制：

// Generate API key with specific rate limits and scopes
$apiKey = $user->generateMCPApiKey('mobile_app', ['tools.search'], 'Mobile App Key');

// Set per-key rate limits
$apiKey->update([
    'rate_limit_per_minute' => 500,
    'rate_limit_burst' => 50
]);

// Track usage automatically
$keyWithTracking = $user->getMCPApiKeyWithTracking($keyValue);

// Rotate keys securely
$newKey = $user->rotateMCPApiKey($oldKeyValue);

// Get detailed usage analytics
$analytics = $user->getMCPApiKeysSummary();
// Returns: total_keys, active_keys, expired_keys, usage_stats

基于作用域的权限

实现基于作用域的细粒度访问控制：

// Add scopes to users
$user->addMCPScope('read:products');
$user->addMCPScope('write:orders');

// Check scopes in tools/resources
public function isAccessibleTo(ContextInterface $context): bool
{
    return $context->hasScope('read:products') || 
           $context->hasPermission('admin');
}

// Configure scope-based client permissions
'clients' => [
    'mobile_app' => [
        'permissions' => ['tools.*'],
        'scopes' => ['read:products', 'read:categories'],
        'metadata' => ['app_version' => '2.1.0']
    ]
]

数据过滤与字段安全性

根据字段访问权限自动过滤响应数据：

public function execute(array $arguments, ContextInterface $context): ResultInterface
{
    $products = Product::all()->toArray();
    
    // Automatically filter fields based on user permissions
    $filteredProducts = array_map(function($product) use ($context) {
        return $context->filterFields('product', $product);
    }, $products);
    
    return Result::success([
        'products' => $filteredProducts,
        'accessible_fields' => $context->getAccessibleFields('product')
    ]);
}

性能监控与分析

内置性能追踪和使用分析功能：

// Enable in .env
MCP_TRACK_PERMISSIONS=true
MCP_LOG_API_USAGE=true

// Access metrics via Cache
$permissionStats = Cache::get('mcp.perms.tools.search_products.granted', 0);
$deniedAttempts = Cache::get('mcp.perms.tools.search_products.denied', 0);

// View API usage logs
tail -f storage/logs/mcp.log | grep "API Key Usage"

认证方法

该包支持多种可同时使用的认证策略：

静态配置

配置静态API密钥、基本身份验证和承载令牌：

// config/mcp.php
'auth' => [
    'api_keys' => [
        env('MCP_API_KEY_1'),
        env('MCP_API_KEY_2'),
    ],
    'basic_auth' => [
        env('MCP_BASIC_USER_1') => env('MCP_BASIC_PASS_1'),
    ],
    'bearer_tokens' => [
        env('MCP_BEARER_TOKEN_1'),
    ],
],

数据库认证

在数据库中存储API密钥，并与用户关联：

// Generate API keys for users
$user = User::find(1);
$apiKey = $user->generateMCPApiKey('mobile_app', ['tools.search', 'resources.catalog']);

// Check if a key is valid
$isValid = $user->isMCPApiKeyValid($apiKey->key);

// Revoke a key
$user->revokeMCPApiKey($apiKey->key);

// Get key information (without exposing the actual key)
$keyInfo = $user->getMCPApiKeyInfo($apiKey->key);

自定义身份验证

创建您自己的认证逻辑：

// app/Services/Custom/MCP/Auth/CustomAuthenticator.php
class CustomAuthenticator implements AuthenticatorInterface
{
    public function handles(string $type): bool
    {
        return $type === 'custom_token';
    }

    public function authenticate(string $type, array $credentials): AuthenticationResult
    {
        // Your custom authentication logic
        $token = $credentials['token'] ?? '';
        
        if ($this->isValidCustomToken($token)) {
            return AuthenticationResult::success('custom_client_id');
        }
        
        return AuthenticationResult::failure('Invalid custom token');
    }
}

// Register in config/mcp.php
'auth' => [
    'custom_authenticators' => [
        \App\Services\Custom\MCP\Auth\CustomAuthenticator::class,
    ],
],

灵活的密钥存储模式

该包支持多种API密钥存储策略：

独立表格（默认）

使用 ApiKey 具有外键关系的模型：

// Uses the HasMCPAuthentication trait defaults
class User extends Authenticatable implements MCPUserInterface
{
    use HasMCPAuthentication;
    
    // No overrides needed - uses ApiKey model
}

用户表列

直接在用户表列中存储哈希密钥：

class User extends Authenticatable implements MCPUserInterface
{
    use HasMCPAuthentication;

    protected $fillable = [
        'mcp_api_key_1', 'mcp_api_key_2', 
        'mcp_api_key_1_meta', 'mcp_api_key_2_meta'
    ];

    protected $casts = [
        'mcp_api_key_1_meta' => 'array',
        'mcp_api_key_2_meta' => 'array',
    ];

    protected $hidden = [
        'mcp_api_key_1', 'mcp_api_key_2'
    ];

    public function generateMCPApiKey(string $clientIdentifier, array $scopes = [], ?string $name = null): ApiKey
    {
        $key = 'mcp_' . bin2hex(random_bytes(32));
        $hashedKey = Hash::make($key);
        
        if (empty($this->mcp_api_key_1)) {
            $this->update([
                'mcp_api_key_1' => $hashedKey,
                'mcp_api_key_1_meta' => [
                    'client_identifier' => $clientIdentifier,
                    'scopes' => $scopes,
                    'created_at' => now(),
                ],
            ]);
        }
        // Return mock ApiKey for compatibility
    }

    public function isMCPApiKeyValid(string $key): bool
    {
        return ($this->mcp_api_key_1 && Hash::check($key, $this->mcp_api_key_1)) ||
               ($this->mcp_api_key_2 && Hash::check($key, $this->mcp_api_key_2));
    }
}

JSON列存储

将所有密钥存储在一个JSON列中：

class User extends Authenticatable implements MCPUserInterface
{
    use HasMCPAuthentication;

    protected $casts = [
        'mcp_api_keys' => 'array',
    ];

    public function isMCPApiKeyValid(string $key): bool
    {
        $keys = $this->mcp_api_keys ?? [];
        foreach ($keys as $keyData) {
            if (Hash::check($key, $keyData['hash']) && 
                ($keyData['is_active'] ?? false) &&
                (!isset($keyData['expires_at']) || now()->isBefore($keyData['expires_at']))) {
                return true;
            }
        }
        return false;
    }
}

客户端权限

为每个客户端配置细粒度的权限：

'clients' => [
    'admin_client' => [
        'permissions' => ['admin'], // Full access
        'field_access' => ['*'],
        'metadata' => ['tier' => 'admin']
    ],
    
    'api_client' => [
        'permissions' => [
            'tools.*',           // All tools
            'resources.*',       // All resources
            'products.read',     // Entity-level permission
        ],
        'field_access' => [
            'user' => ['name', 'email'],           // Limited fields
            'product' => ['*'],                    // All product fields
        ],
        'rate_limit' => [
            'requests_per_minute' => 1000,        // Client-specific limits
            'burst_limit' => 50,
        ],
        'metadata' => ['tier' => 'premium']
    ],
    
    'public_client' => [
        'permissions' => [
            'tools.echo',
            'resources.status',
        ],
        'field_access' => [
            'product' => ['name', 'price'],       // Public fields only
        ],
        'metadata' => ['tier' => 'public']
    ]
]

创建自定义工具

1. 生成工具存根

php artisan vendor:publish --tag=mcp-stubs

2. 创建你的工具

<?php

namespace App\Services\Custom\MCP\Tools;

use ChaoticIngenuity\LaravelMCP\Contracts\{ToolInterface, ContextInterface, ResultInterface};
use ChaoticIngenuity\LaravelMCP\Core\Result;

class SearchProductsTool implements ToolInterface
{
    public function getName(): string
    {
        return 'search_products';
    }

    public function getDescription(): string
    {
        return 'Search products in the database with advanced filtering';
    }

    public function getInputSchema(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'filters' => [
                    'type' => 'array',
                    'description' => 'Search filters to apply',
                    'items' => [
                        'type' => 'object',
                        'properties' => [
                            'field' => [
                                'type' => 'string',
                                'description' => 'Field name to filter on'
                            ],
                            'operator' => [
                                'type' => 'string', 
                                'enum' => ['=', '!=', '>', '<', '>=', '<=', 'like', 'in'],
                                'description' => 'Comparison operator'
                            ],
                            'value' => [
                                'oneOf' => [
                                    {'type' => 'string'},
                                    {'type' => 'number'},
                                    {'type' => 'array'}
                                ],
                                'description' => 'Value to compare against'
                            ]
                        ],
                        'required' => ['field', 'operator', 'value']
                    ]
                ],
                'limit' => [
                    'type' => 'integer',
                    'default' => 10,
                    'maximum' => 100,
                    'description' => 'Maximum number of results'
                ],
                'sort' => [
                    'type' => 'object',
                    'properties' => [
                        'field' => ['type' => 'string'],
                        'direction' => ['type' => 'string', 'enum' => ['asc', 'desc']]
                    ]
                ]
            ],
            'required' => ['filters'],
            'examples' => [
                {
                    'description' => 'Find electronics under $500',
                    'filters' => [
                        {'field' => 'category', 'operator' => '=', 'value' => 'electronics'},
                        {'field' => 'price', 'operator' => '<', 'value' => 500}
                    ],
                    'limit' => 20,
                    'sort' => {'field' => 'name', 'direction' => 'asc'}
                }
            ]
        ];
    }

    public function isAccessibleTo(ContextInterface $context): bool
    {
        return $context->hasPermission('tools.search_products') || 
               $context->hasPermission('admin');
    }

    public function execute(array $arguments, ContextInterface $context): ResultInterface
    {
        $filters = $arguments['filters'] ?? [];
        $limit = min($arguments['limit'] ?? 10, 100);
        $sort = $arguments['sort'] ?? ['field' => 'created_at', 'direction' => 'desc'];
        
        // Apply field-level access control
        $accessibleFields = $context->getAccessibleFields('product');
        
        $query = Product::query();
        
        // Apply filters with field access checking
        foreach ($filters as $filter) {
            $field = $filter['field'];
            $operator = $filter['operator'];
            $value = $filter['value'];
            
            // Skip inaccessible fields
            if (!$context->hasFieldAccess('product', $field)) {
                continue;
            }
            
            match($operator) {
                '=' => $query->where($field, $value),
                '!=' => $query->where($field, '!=', $value),
                '>', '<', '>=', '<=' => $query->where($field, $operator, $value),
                'like' => $query->where($field, 'like', "%{$value}%"),
                'in' => $query->whereIn($field, (array) $value),
                default => null
            };
        }
        
        // Apply sorting if field is accessible
        if ($context->hasFieldAccess('product', $sort['field'])) {
            $query->orderBy($sort['field'], $sort['direction']);
        }
        
        $products = $query->limit($limit)->get();
        
        // Filter response fields based on permissions
        $filteredProducts = $products->map(function ($product) use ($accessibleFields) {
            if (in_array('*', $accessibleFields)) {
                return $product->toArray();
            }
            return $product->only($accessibleFields);
        });

        return Result::success([
            'products' => $filteredProducts,
            'total' => $filteredProducts->count(),
            'applied_filters' => $filters,
            'accessible_fields' => $accessibleFields
        ], [
            'execution_time_ms' => microtime(true) * 1000,
            'client_id' => $context->getClientId()
        ]);
    }
}

3. 注册您的工具

添加到 config/mcp.php:

'custom' => [
    'tools' => [
        \App\Services\Custom\MCP\Tools\SearchProductsTool::class,
    ],
]

创建自定义资源

1. 静态资源

<?php

namespace App\Services\Custom\MCP\Resources;

use ChaoticIngenuity\LaravelMCP\Contracts\{ResourceInterface, ContextInterface, ResultInterface};
use ChaoticIngenuity\LaravelMCP\Core\Result;

class ProductCatalogResource implements ResourceInterface
{
    public function getUri(): string
    {
        return 'catalog://products';
    }

    public function getName(): string
    {
        return 'Product Catalog';
    }

    public function getDescription(): string
    {
        return 'Complete product catalog with categories and metadata';
    }

    public function getMimeType(): string
    {
        return 'application/json';
    }

    public function isTemplate(): bool
    {
        return false;
    }

    public function isAccessibleTo(ContextInterface $context): bool
    {
        return $context->hasPermission('resources.catalog') ||
               $context->hasPermission('products.read');
    }

    public function getAccessibleFields(ContextInterface $context): array
    {
        return $context->getAccessibleFields('product');
    }

    public function getContent(string $uri, ContextInterface $context): ResultInterface
    {
        $accessibleFields = $this->getAccessibleFields($context);
        
        // Cache based on client permissions
        $cacheKey = 'mcp.catalog.products.' . md5(json_encode($accessibleFields));
        
        $data = Cache::remember($cacheKey, 300, function () use ($accessibleFields) {
            $query = Product::with('categories');
            
            if (!in_array('*', $accessibleFields)) {
                $query->select($accessibleFields);
            }
            
            return [
                'products' => $query->get()->toArray(),
                'categories' => Category::all(['id', 'name', 'description'])->toArray(),
            ];
        });

        return Result::success([
            ...$data,
            'metadata' => [
                'total_products' => count($data['products']),
                'total_categories' => count($data['categories']),
                'accessible_fields' => $accessibleFields,
                'last_updated' => now()->toISOString(),
            ]
        ], [
            'cached' => true,
            'cache_key' => $cacheKey
        ]);
    }
}

2. 模板资源

在URI中接受参数的资源：

class ProductResource implements ResourceInterface
{
    public function getUri(): string
    {
        return 'product://{product_id}';
    }

    public function isTemplate(): bool
    {
        return true;
    }

    public function getContent(string $uri, ContextInterface $context): ResultInterface
    {
        // Extract product_id from URI: product://123
        $productId = str_replace('product://', '', $uri);
        
        if (!$context->hasFieldAccess('product', 'id')) {
            return Result::error('Access denied to product data');
        }
        
        $accessibleFields = $context->getAccessibleFields('product');
        $product = Product::find($productId);
        
        if (!$product) {
            return Result::error('Product not found');
        }
        
        $filteredProduct = in_array('*', $accessibleFields) 
            ? $product->toArray() 
            : $product->only($accessibleFields);
        
        return Result::success($filteredProduct, [
            'product_id' => $productId,
            'accessible_fields' => $accessibleFields
        ]);
    }
}

3. 注册您的资源

// config/mcp.php
'custom' => [
    'resources' => [
        \App\Services\Custom\MCP\Resources\ProductCatalogResource::class,
        \App\Services\Custom\MCP\Resources\ProductResource::class,
    ],
]

安全

字段级访问控制

在细粒度级别上控制客户端可以访问的字段：

'clients' => [
    'public_api' => [
        'field_access' => [
            'user' => ['name', 'avatar'],           // Public fields only
            'product' => ['name', 'price', 'description'], // No internal data
            'order' => [],                          // No access to orders
        ]
    ],
    'partner_api' => [
        'field_access' => [
            'user' => ['name', 'email', 'phone'],   // More fields for partners
            'product' => ['*'],                     // All product data
            'order' => ['id', 'status', 'total'],  // Limited order access
        ]
    ],
    'internal_admin' => [
        'permissions' => ['admin'],              // Full access
        'field_access' => ['*']                  // All fields, all entities
    ]
]

中间件堆栈

该软件包包含全面的安全中间件：

MCPSecurityMiddleware（可译为）：MCPS安全中间件HTTPS强制执行、IP白名单、安全头部设置
MCP身份验证中间件使用自定义认证器进行多方法认证
MCP限流中间件基于客户端和突发流量的速率限制
MCP日志记录中间件带有性能指标的请求/响应日志记录

基于环境的安全

# Production Security Settings
MCP_REQUIRE_HTTPS=true
MCP_ALLOWED_IPS=203.0.113.0/24,192.168.1.0/24
MCP_BLOCK_SUSPICIOUS_UA=true

# Never enable these in production
MCP_DEBUG_EXPOSE_SYSTEM_INFO=false
MCP_DEBUG_DETAILED_ERRORS=false
MCP_DEBUG_LOG_REQUESTS=false

IP白名单

支持单个IP地址和CIDR表示法：

# Individual IPs
MCP_ALLOWED_IPS=203.0.113.1,203.0.113.2

# CIDR ranges
MCP_ALLOWED_IPS=192.168.1.0/24,10.0.0.0/8

# Mixed
MCP_ALLOWED_IPS=203.0.113.1,192.168.1.0/24,10.0.0.0/8

速率限制

全局和按客户端配置速率限制：

# Global Defaults
MCP_RATE_LIMIT=60        # Requests per minute
MCP_BURST_LIMIT=10       # Short-term burst allowance

# Per-client limits in config/mcp.php
'clients' => [
    'high_volume_client' => [
        'rate_limit' => [
            'requests_per_minute' => 1000,
            'burst_limit' => 100,
        ],
    ],
]

v1.0.0 新特性 🎉

增强的权限管理

🔗 可选的Bouncer集成与Laravel Bouncer无缝集成，实现高级基于角色的权限管理
🔄 权限管理器架构可插拔的权限系统，具备自动回退功能
⚡ 性能优化注册表模板匹配与编译模式缓存
🛡️ 增强的安全性改进了认证流程并防止了循环依赖

新功能

🚀 MCP 设置命令： php artisan mcp:setup --bouncer 便于配置
📊 综合测试套件74项测试涵盖所有主要功能
🎛️ 灵活认证API密钥的多种存储模式（数据库、用户列、JSON）
📝 更好的文档增强的示例、故障排除指南和迁移说明

开发者体验

✨ 符合PSR-12标准使用.editorconfig实现全面的代码格式化标准
🔧 自动检测自动检测和配置Bouncer包
📚 丰富的实例基本用法和Bouncer用法的综合示例
🐛 改进了错误处理更好的验证和错误提示

使用Bouncer快速设置（可选）

如果您想在 Laravel 中使用 Bouncer 实现增强的权限管理：

# Install Bouncer (optional)
composer require silber/bouncer

# Setup MCP with Bouncer integration
php artisan mcp:setup --bouncer

# Enable Bouncer in your .env
MCP_BOUNCER_ENABLED=true

测试

综合测试套件（v1.0.0）

该套装包括 74项综合测试 覆盖：

✅ 核心MCP协议初始化，工具/列表，工具/调用，资源/*
✅ 认证API密钥、基本身份验证、承载令牌、自定义身份验证器
✅ 权限管理默认和Bouncer权限管理器
✅ 翻译成中文是：✓（正确/对） 门卫系统集成包检测、回退行为、配置
✅ 注册表性能模板匹配、缓存、内存优化
✅ 安全访问控制、速率限制、验证
✅（对号，表示正确、确认或完成） HTTP 集成中间件、路由、错误处理

运行测试

# Run all tests
composer test

# Run specific test suites
vendor/bin/phpunit tests/Feature/
vendor/bin/phpunit tests/Unit/

# Run with coverage
composer test-coverage

# Individual test files
vendor/bin/phpunit tests/Feature/MCPServerTest.php
vendor/bin/phpunit tests/Feature/AuthenticationTest.php
vendor/bin/phpunit tests/Unit/PermissionManagerTest.php
vendor/bin/phpunit tests/Feature/BouncerIntegrationTest.php
vendor/bin/phpunit tests/Unit/RegistryTest.php

性能基准

v1.0.0测试套件包括性能验证：

模板URI匹配1000场匹配在<100毫秒内完成
内存使用量1000个工具/资源注册使用<5MB
认证缓存权限查找以实现最佳性能
注册表为重复模板匹配编译模式缓存

运行软件包测试

composer test

测试你的实现

# List available tools
curl -X POST http://localhost/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-MCP-API-Key: your_key" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# Execute a tool with structured query
curl -X POST http://localhost/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-MCP-API-Key: your_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_products",
      "arguments": {
        "filters": [
          {"field": "category", "operator": "=", "value": "electronics"},
          {"field": "price", "operator": "<", "value": 500}
        ],
        "limit": 5,
        "sort": {"field": "name", "direction": "asc"}
      }
    },
    "id": 2
  }'

# Read a static resource
curl -X POST http://localhost/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-MCP-API-Key: your_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "resources/read",
    "params": {"uri": "catalog://products"},
    "id": 3
  }'

# Read a template resource
curl -X POST http://localhost/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-MCP-API-Key: your_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "resources/read",
    "params": {"uri": "product://123"},
    "id": 4
  }'

# Test with database authentication
curl -X POST http://localhost/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-User-Token: user_token_xyz" \
  -H "X-User-ID: 123" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 5}'

MCP协议方法

该软件包实现了所有标准的MCP方法：

方法	描述	响应
`initialize`	初始化MCP会话	服务器功能和信息
`tools/list`	列出可用工具	工具定义的数组
`tools/call`	执行工具	工具执行结果
`resources/list`	列出可用的静态资源	资源定义的数组
`resources/read`	读取资源内容	资源内容
`resources/templates/list`	列出模板资源	模板定义的数组

错误处理

该包提供了标准化的 JSON-RPC 2.0 错误响应：

代码	含义	使用时机
`-32001`	需要身份验证	凭据无效/缺失
`-32002`	访问被拒绝	权限不足
`-32003`	请求速率限制已超出	请求过多
`-32602`	无效参数	缺失/无效的参数
`-32603`	内部错误	服务器端错误

异常类型

该包使用特定的异常类型以实现更好的错误处理：

**MCPAuthenticationException**因认证失败、无效客户端ID或授权问题而抛出
客户端ID验证客户端ID必须为字母数字组合，仅允许包含点、连字符或下划线（最多255个字符）

输入验证

客户端ID会自动进行验证，并且必须满足以下要求：

非空
最多255个字符
仅允许使用字母数字字符、点号（.）、连字符（-）和下划线（_）
无效字符将引发异常 MCPAuthenticationException

示例错误响应：

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32002,
    "message": "Access denied",
    "data": {
      "required_permission": "tools.search_products",
      "client_permissions": ["tools.echo", "resources.status"]
    }
  },
  "id": 1
}

性能考量

缓存策略

在您的自定义工具和资源中实现智能缓存：

public function getContent(string $uri, ContextInterface $context): ResultInterface
{
    // Cache based on URI and client permissions
    $cacheKey = "mcp.resource.{$uri}." . md5(json_encode([
        $context->getClientId(),
        $context->getAccessibleFields('product')
    ]));
    
    $data = Cache::remember($cacheKey, 300, function() use ($uri, $context) {
        return $this->fetchExpensiveData($uri, $context);
    });
    
    return Result::success($data, ['cached' => true]);
}

数据库优化

为您的搜索字段使用适当的索引
根据访问权限实现字段选择
对于高频率的MCP（可能指某种数据库或应用系统）使用，考虑使用读取副本
使用 select() 限制返回的列

// Optimize queries based on field access
$accessibleFields = $context->getAccessibleFields('product');
$query = Product::query();

if (!in_array('*', $accessibleFields)) {
    $query->select($accessibleFields);
}

认证性能

数据库认证器采用智能缓存技术
缓存持续时间可根据环境进行配置
失败的认证尝试受到速率限制
异步更新（last_used_at）不会阻塞请求

// config/mcp.php
'auth' => [
    'cache_duration' => 300, // 5 minutes
    'rate_limit_failed_attempts' => 10, // Per IP per hour
],

监测

使用内置日志来监控性能：

# View MCP request logs
tail -f storage/logs/mcp.log

# Monitor slow requests (>500ms)
grep "duration_ms.*[5-9][0-9][0-9]" storage/logs/mcp.log

# Check authentication patterns
grep "auth_type" storage/logs/mcp.log | sort | uniq -c

# Monitor rate limiting
grep "rate.*limit" storage/logs/mcp.log

用户管理

为用户创建API密钥

// Generate API keys programmatically
$user = User::find(1);

// Basic API key
$apiKey = $user->generateMCPApiKey('mobile_app_v1');

// API key with specific scopes
$apiKey = $user->generateMCPApiKey('analytics_dashboard', [
    'tools.search_products',
    'resources.catalog',
    'products.read'
], 'Analytics Dashboard Key');

// Check key validity
$isValid = $user->isMCPApiKeyValid($apiKey->key);

// Get key information (safe - no actual key exposed)
$keyInfo = $user->getMCPApiKeyInfo($apiKey->key);

// Get summary of all user's keys
$summary = $user->getMCPApiKeysSummary();

用户权限管理

// Enable MCP access for a user
$user->update(['mcp_enabled' => true]);

// Set user permissions
$user->update([
    'mcp_permissions' => [
        'tools.search_products',
        'tools.get_inventory',
        'resources.catalog'
    ]
]);

// Set field access
$user->update([
    'mcp_field_access' => [
        'product' => ['name', 'price', 'category'],
        'user' => ['name', 'email']
    ]
]);

// Check permissions
$hasAccess = $user->hasMCPPermission('tools.search_products');
$hasFieldAccess = $user->hasMCPFieldAccess('product', 'price');

批量操作

// Revoke all keys for a user
$revokedCount = $user->revokeAllMCPApiKeys();

// Clean up expired keys
$cleanedCount = $user->cleanupExpiredMCPApiKeys();

// Enable MCP for multiple users
User::whereIn('id', [1, 2, 3])->update(['mcp_enabled' => true]);

// Find users with specific permissions
$apiUsers = User::withMCPAccess()
    ->whereJsonContains('mcp_permissions', 'tools.search_products')
    ->get();

部署

生产检查清单

[ ] 设置 MCP_DEBUG_* 变量到 false
使用强API密钥（32个字符以上）
[ ] 配置适合您基础设施的速率限制
[ ] 启用HTTPS（MCP_REQUIRE_HTTPS=true)
[ ] 如适用，设置IP白名单
[ ] 配置适当的日志记录级别
[ ] 为MCP日志设置日志轮转
[ ] 测试所有中间件是否已正确注册
[ ] 验证错误响应不泄露敏感信息
[ ] 为MCP端点设置监控
为API密钥查找配置数据库索引
[ ] 测试负载下的认证性能

环境变量

# Production Settings
APP_ENV=production
MCP_REQUIRE_HTTPS=true
MCP_DEBUG_EXPOSE_SYSTEM_INFO=false
MCP_DEBUG_DETAILED_ERRORS=false

# Security
MCP_ALLOWED_IPS=your.trusted.networks
MCP_BLOCK_SUSPICIOUS_UA=true

# Performance
MCP_RATE_LIMIT=1000
MCP_BURST_LIMIT=50
MCP_LOG_PERFORMANCE=true
MCP_AUTH_CACHE_DURATION=300

# Monitoring
MCP_LOG_REQUESTS=true
MCP_LOG_LEVEL=warning
MCP_LOG_RETENTION_DAYS=30

# Database Authentication
MCP_USER_MODEL=App\Models\User
MCP_USER_FOREIGN_KEY=user_id
MCP_USER_OWNER_KEY=id

Docker

# Add to your Dockerfile
COPY config/mcp.php /var/www/config/
RUN php artisan config:cache

# Ensure logs directory is writable
RUN mkdir -p /var/www/storage/logs && \
    chown -R www-data:www-data /var/www/storage

# Add database indexes for performance
COPY database/migrations/add_mcp_indexes.php /var/www/database/migrations/

数据库索引

创建适当的索引以优化性能：

// database/migrations/add_mcp_indexes.php
public function up(): void
{
    Schema::table('api_keys', function (Blueprint $table) {
        $table->index(['key', 'is_active']);
        $table->index(['user_id', 'is_active']);
        $table->index(['client_identifier']);
        $table->index(['expires_at']);
    });

    Schema::table('users', function (Blueprint $table) {
        $table->index('mcp_enabled');
    });
}

负载均衡

MCP服务器是无状态的，因此可以正常进行负载均衡。请考虑：

无需会话亲和性
速率限制可能需要共享存储（如Redis）
资源缓存得益于共享缓存
跨实例的监控日志聚合
用于认证的数据库连接池

监控设置

# Set up log monitoring
tail -f storage/logs/mcp.log | grep ERROR

# Monitor authentication failures
grep "Authentication.*failed" storage/logs/mcp.log

# Track performance metrics
grep "duration_ms" storage/logs/mcp.log | awk '{print $6}' | sort -n

# Monitor rate limiting
grep "rate.*limit.*exceeded" storage/logs/mcp.log

故障排除

常见问题

中间件未找到错误

# Laravel 11 - Check bootstrap/app.php has middleware aliases
grep -A 10 "withMiddleware" bootstrap/app.php

# Laravel 10 - Ensure service provider is registered
php artisan config:show app.providers

# Verify route middleware
php artisan route:show mcp.handle

工具/资源未找到

# Check registration in config/mcp.php
php artisan config:show mcp.custom

# Verify class exists and implements correct interface
php artisan tinker
>>> class_exists(\App\Services\Custom\MCP\Tools\YourTool::class)
>>> class_implements(\App\Services\Custom\MCP\Tools\YourTool::class)

# Clear application cache
php artisan optimize:clear

数据库认证问题

# Check user model configuration
php artisan config:show mcp.auth.user_model

# Test user has MCP access
php artisan tinker
>>> $user = User::find(1)
>>> $user->hasMCPAccess()
>>> $user->getMCPPermissions()

# Check API key generation
>>> $key = $user->generateMCPApiKey('test')
>>> $user->isMCPApiKeyValid($key->key)

客户端ID验证错误

# MCPAuthenticationException: Invalid client ID format
# Client IDs must be alphanumeric with dots, hyphens, or underscores only

# Valid client IDs:
# ✅ "mobile_app"
# ✅ "api-client"  
# ✅ "client.v1"
# ❌ "client@domain"
# ❌ "client/path"
# ❌ "client with spaces"

# Test client ID validation
php artisan tinker
>>> app(\ChaoticIngenuity\LaravelMCP\Core\ContextFactory::class)->createFromClient('test-client')

字段访问问题

# Field access permissions are now working correctly (v1.0.0 bug fix)
# Test field access in tinker
php artisan tinker
>>> $user = User::find(1)
>>> $user->hasMCPFieldAccess('product', 'price')
>>> $user->getMCPFieldAccess()

访问被拒绝错误

# Check client permissions in config/mcp.php
php artisan config:show mcp.auth.clients

# Verify field-level access configuration
php artisan tinker
>>> $context = app(\ChaoticIngenuity\LaravelMCP\Core\ContextFactory::class)->createFromClient('your_client')
>>> $context->hasPermission('tools.your_tool')
>>> $context->hasFieldAccess('product', 'price')

# Check authentication headers are correct
curl -v -H "X-MCP-API-Key: your_key" http://localhost/api/mcp

速率限制问题

# Check current rate limit settings
php artisan config:show mcp.rate_limit

# Verify client identification is working
grep "mcp_client" storage/logs/mcp.log

# Clear rate limit cache if needed
php artisan cache:forget "mcp_throttle:your_client"

# Check for burst limit hits
grep "burst.*limit" storage/logs/mcp.log

调试模式

为开发启用调试模式：

MCP_DEBUG_DETAILED_ERRORS=true
MCP_DEBUG_LOG_REQUESTS=true
MCP_LOG_LEVEL=debug
MCP_DEBUG_EXPOSE_SYSTEM_INFO=true

检查日志以获取详细信息：

# View all MCP logs
tail -f storage/logs/mcp.log

# Filter by specific client
grep "client_1" storage/logs/mcp.log

# Find slow requests (>1 second)
grep "duration_ms.*[1-9][0-9][0-9][0-9]" storage/logs/mcp.log

# Check authentication flow
grep -E "(Authentication|auth_type)" storage/logs/mcp.log

# Monitor memory usage
grep "memory_mb" storage/logs/mcp.log | sort -k6 -n

性能调试

监控并优化性能：

# Average request duration
grep "duration_ms" storage/logs/mcp.log | \
  awk '{print $6}' | awk '{sum+=$1; count++} END {print sum/count}'

# Memory usage patterns
grep "memory_mb" storage/logs/mcp.log | \
  awk '{print $8}' | sort -n | tail -10

# Most used tools/resources
grep -E "(tool|resource)" storage/logs/mcp.log | \
  awk '{print $4}' | sort | uniq -c | sort -nr

# Authentication method distribution
grep "auth_type" storage/logs/mcp.log | \
  awk '{print $7}' | sort | uniq -c

测试认证

// Test database authentication in tinker
php artisan tinker

// Create a test user and API key
>>> $user = User::first()
>>> $user->update(['mcp_enabled' => true])
>>> $key = $user->generateMCPApiKey('test_client', ['tools.*'])
>>> echo $key->key

// Test key validation
>>> $user->isMCPApiKeyValid($key->key)
>>> $user->getMCPApiKeyInfo($key->key)

// Test custom authenticator
>>> $auth = app(\App\Services\Custom\MCP\Auth\DatabaseAuthenticator::class)
>>> $result = $auth->authenticate('api_key', ['api_key' => $key->key])
>>> $result->isSuccess()
>>> $result->getClientId()

Laravel 版本兼容性

Laravel 11

✅ 完全支持
⚠️ 需要手动注册中间件 bootstrap/app.php
✅ 使用了新的应用程序结构
✅ 遵循Laravel 11的规范

Laravel 10

✅ 完全支持
✅ 自动中间件注册
✅ 传统 app/Http/Kernel.php 结构

从 Laravel 10 迁移到 11

如果要升级您的Laravel应用程序：

更新中间件注册信息 bootstrap/app.php
移除任何手动中间件注册 app/Http/Kernel.php
测试所有MCP终端点是否仍然正常工作
按照Laravel 11的模式更新任何自定义中间件

高级配置

自定义上下文工厂

创建自定义客户端上下文逻辑：

// app/Services/Custom/MCP/CustomContextFactory.php
class CustomContextFactory extends ContextFactory
{
    public function createFromClient(string $clientId): ContextInterface
    {
        // Custom logic for determining client permissions
        if (str_starts_with($clientId, 'user_')) {
            $userId = str_replace('user_', '', $clientId);
            $user = User::find($userId);
            
            return new Context(
                clientId: $clientId,
                permissions: $user->getMCPPermissions(),
                fieldAccess: $user->getMCPFieldAccess(),
                metadata: ['user_id' => $userId, 'tier' => $user->subscription_tier]
            );
        }
        
        return parent::createFromClient($clientId);
    }
}

// Register in service provider
$this->app->singleton(ContextFactory::class, CustomContextFactory::class);

多租户支持

为多租户应用程序配置MCP：

class TenantAwareMCPMiddleware
{
    public function handle(Request $request, Closure $next)
    {
        $tenant = $this->resolveTenant($request);
        
        if (!$tenant) {
            return response()->json([
                'jsonrpc' => '2.0',
                'error' => ['code' => -32001, 'message' => 'Invalid tenant']
            ], 401);
        }
        
        // Set tenant context
        $request->merge(['mcp_tenant' => $tenant->id]);
        
        return $next($request);
    }
}

自定义模式验证

为工具输入添加JSON Schema验证：

use JsonSchema\Validator;

public function execute(array $arguments, ContextInterface $context): ResultInterface
{
    // Validate against schema
    $validator = new Validator();
    $validator->validate($arguments, $this->getInputSchema());
    
    if (!$validator->isValid()) {
        $errors = array_map(fn($error) => $error['message'], $validator->getErrors());
        return Result::error('Validation failed: ' . implode(', ', $errors));
    }
    
    // Continue with execution...
}

做出贡献

为仓库创建分支（或：克隆仓库）
创建一个特性分支（git checkout -b feature/amazing-feature)
为新功能添加测试
确保所有测试通过（composer test）
遵循PSR-12编码标准（composer format)
根据需要更新文档
提交拉取请求

开发环境设置

# Clone the repository
git clone https://github.com/chaoticingenuity/laravel-mcp-server.git
cd laravel-mcp-server

# Install dependencies
composer install

# Run tests
composer test

# Run code formatting
composer format

# Run static analysis
composer analyse

包装结构

src/
├── Contracts/           # Interfaces and contracts
├── Core/               # Core functionality (Registry, Context, etc.)
├── Auth/               # Authentication system
├── Http/               # Controllers and middleware
├── Tools/              # Built-in tools
├── Resources/          # Built-in resources
├── Traits/             # Reusable traits
└── Providers/          # Service providers

config/                 # Configuration files
routes/                 # Route definitions
tests/                  # Test suite
examples/               # Usage examples
stubs/                  # Code generation stubs

许可证

MIT 许可证 - 详见许可证详情见文件。

更新日志

见 CHANGELOG.md（版本更新日志文件）用于版本历史。

支持

文档： GitHub Wiki（维基）
问题: GitHub Issues（GitHub问题）
讨论： GitHub 讨论区
安全问题邮件发送至：security@chaoticingenuity.com

功劳/学分/积分（根据上下文，"Credits" 可能有多种含义，这里提供了几种可能的翻译）

模型上下文协议规范
Laravel 框架
JSON-RPC 2.0 规范
所有帮助改进此软件包的贡献者