Laravel MCP 服务器

Laravel MCP Server

An MCP (Model Context Protocol) server implementation for the Laravel framework, providing standardized tool invocation, resource management, and prompt word functionality.

Features

• 🛠️ Tool Management: Support registration and calling custom tools
• 📁 Resource ManagementProvide resource list, reading, and template functions
• 💬 Prompt managementSupport prompt word list and retrieval
• 🔧 Flexible configurationFlexible adjustment through environment variables and configuration files
• 🌐 HTTP interfaceProvide RESTful API and SSE support
• 📝 Standard ProtocolFully compatible with MCP protocol specifications (2024-11-05)

System Requirements

• PHP >= 7.1.3
• Laravel Framework >= 5.6
• Symfony YAML Component >= 5.3

Installation Instructions

1. Install using Composer

composer require jose-chan/laravel-mcp-server

2. Publish configuration files

After installation, publish the configuration file to your application:

php artisan vendor:publish --provider="JoseChan\McpServer\Providers\McpServerServiceProvider" --tag="mcp-server"

This will be config/ Create under directory mcp-server.php Configuration file.

3. Configure environment variables

In your .env Add the following configuration to the file (optional, all configuration items have default values):

# 服务器基本信息
MCP_SERVER_NAME=laravel-mcp-server
MCP_SERVER_VERSION=1.0.0

# 资源和提示词存储目录
MCP_RESOURCE_DIRECTORY=storage/mcp_resources
MCP_PROMPTS_DIRECTORY=storage/mcp_prompts

# 功能开关
MCP_CAPABILITY_RESOURCES=true
MCP_CAPABILITY_RESOURCES_SUBSCRIBE=true
MCP_CAPABILITY_RESOURCES_LIST_CHANGED=true
MCP_CAPABILITY_TOOLS=true
MCP_CAPABILITY_TOOLS_LIST_CHANGED=true
MCP_CAPABILITY_TOOLS_CALL=true
MCP_CAPABILITY_PROMPTS=true
MCP_CAPABILITY_PROMPTS_LIST_CHANGED=true
MCP_CAPABILITY_LOGGING=false
MCP_CAPABILITY_EXPERIMENTAL=false

# SSE 配置
MCP_SSE_TIMEOUT=30
MCP_SSE_RETRY=3000

Configuration Release Instructions

Configuration file description

The configuration file is located at config/mcp-server.phpIt includes the following main parts:

1. Server information

'server' => [
    'name' => env('MCP_SERVER_NAME', 'laravel-mcp-server'),
    'version' => env('MCP_SERVER_VERSION', '1.0.0'),
],

2. Protocol version

'protocol_version' => '2024-11-05',

3. Storage directory

'resource_directory' => env('MCP_RESOURCE_DIRECTORY', storage_path('mcp_resources')),
'prompts_directory' => env('MCP_PROMPTS_DIRECTORY', storage_path('mcp_prompts')),

4. Functional Capability Configuration

'capabilities' => [
    'resources' => [
        'enabled' => env('MCP_CAPABILITY_RESOURCES', true),
        'subscribe' => env('MCP_CAPABILITY_RESOURCES_SUBSCRIBE', true),
        'list_changed' => env('MCP_CAPABILITY_RESOURCES_LIST_CHANGED', true),
    ],
    'tools' => [
        'enabled' => env('MCP_CAPABILITY_TOOLS', true),
        'list_changed' => env('MCP_CAPABILITY_TOOLS_LIST_CHANGED', true),
        'call' => env('MCP_CAPABILITY_TOOLS_CALL', true),
    ],
    // ... 更多配置
],

5. Routing configuration

'route' => [
    'prefix' => 'mcp',
    'middleware' => ['api'],
],

6. Tool registration

'tools' => [
    // 在这里添加更多工具类
    // App\\Tools\\MyTool::class,
],

Configuration Item Description

Instructions for Use

1. Command line mode

You can start the MCP server through STDIO mode:

php artisan mcp:server

This command will start the MCP server in standard input/output mode, suitable for integration with MCP clients that support standard input/output.

2. HTTP API mode

The server also provides HTTP API interfaces, which can be accessed through the following endpoints:

• POST /mcp -MCP initialization and request processing
• GET /mcp/sse -Server Send Events real-time communication

3. Add custom tools

1. Create tool class:

The framework will read all static methods under registered utility classes as tools and return them to MCP Client for calling. The comments of the method will be parsed in the standard PHPDoc format, and the description and parameter information of the extraction tool will be passed to MCP Client

<?php

namespace App\Tools;

class MyTool
{
    /**
     * 工具描述
     * @param array $params 工具参数描述
     */
    public static function exampleFunction($params){
    
    }
}

2. Register the tool in the configuration file:

'tools' => [
    App\Tools\MyTool::class,
],

4. Resource management

Create resource files to configure resource_directory catalogue

# 创建资源目录
mkdir -p storage/mcp_resources

# 添加资源文件
echo "我的资源内容" > storage/mcp_resources/example.txt

5. Prompt word management

Create prompt word file to configure prompts_directory catalogue

# 创建提示词目录
mkdir -p storage/mcp_prompts

# 添加提示词文件（Markdown 格式）
cat > storage/mcp_prompts/example.md << EOF
---
name: example_prompt
description: 示例提示词
arguments:
  - name: topic
    description: 主题
    required: true
---

请提供一个关于 {{topic}} 的详细说明。
EOF

example

JSON RPC Request Example

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {
            "tools": {}
        },
        "clientInfo": {
            "name": "test-client",
            "version": "1.0.0"
        }
    }
}

Example of tool invocation

{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
        "name": "my_tool",
        "arguments": {
            "param1": "test value"
        }
    }
}

troubleshooting

Frequently Asked Questions

1. Tool registration failed

   • Check if the tool class correctly implements static methods
   • Confirm that the class path is correctly set in the configuration file

2. Resources cannot be accessed

   • Confirm that the resource directory exists and has read and write permissions
   • check MCP_RESOURCE_DIRECTORY Environment variable settings

3. Prompt words cannot be loaded

   • Confirm that the prompt word directory exists and has read and write permissions
   • Check if the Markdown file format meets the requirements

debug log

Enable logging to obtain more information:

MCP_CAPABILITY_LOGGING=true

The logs will be recorded in Laravel's default logging system.

contribution

Welcome to submit Pull Requests and Issues!

license

This project adopts the MIT license. For details, please refer to LICENSE Document.