laravel-mcp-server-demo by TapanDerasari - MCP Server

Laravel MCP Server Demo (WIP)

A demonstration of a Laravel-based Model Context Protocol (MCP) server implementation. This project showcases how to create and expose a custom tool for user management through the MCP interface.

Features

User Management API: RESTful endpoints for user operations
MCP Tool Integration: Implements the get_users MCP tool
Advanced Filtering: Filter users by role, active status, and more
Pagination & Sorting: Built-in support for pagination and field-based sorting
Authentication: User authentication system with role-based access control

Prerequisites

PHP 8.4 or higher
Composer
MySQL/PostgreSQL/SQLite
Laravel 12.x

Installation

Clone the repository:

git clone https://github.com/TapanDerasari/laravel-mcp-server-demo.git
cd laravel-mcp-server-demo

Install dependencies:
```
composer install
```
Copy the environment file and configure your database:
```
cp .env.example .env
php artisan key:generate
```
Run migrations and seed the database:
```
php artisan migrate --seed
```

Configuration

Edit the .env file to configure your database connection and other settings:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_mcp
DB_USERNAME=root
DB_PASSWORD=

Usage

MCP Tool: Get Users

The main MCP tool get_users provides paginated user data with filtering and sorting capabilities.

Endpoint

GET /mcp/test

Query Parameters

Parameter	Type	Description
search	string	Search term for name or email (optional)
role	string	Filter by user role (admin, moderator, user)
is_active	boolean	Filter by active status (true/false)
sort	string	Sort field with optional - prefix for descending
per_page	integer	Number of items per page (default: 20, max: 100)
page	integer	Page number (default: 1)

Example Request

GET /mcp/test?search=john&role=admin&is_active=true&sort=-created_at&per_page=10&page=1

Example Response

{
    "data": [
        {
            "id": 1,
            "name": "John Doe",
            "email": "john@example.com",
            "role": "admin",
            "is_active": true,
            "created_at": "2023-01-01T00:00:00.000000Z",
            "updated_at": "2023-01-01T00:00:00.000000Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "http://localhost:8000/mcp/test",
        "per_page": 10,
        "to": 1,
        "total": 1
    }
}

MCP Client Configuration

To connect to this MCP server from a client application, add the following configuration to your MCP client's configuration file:

"laravel-mcp-server-demo": {
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "http://localhost:8000/mcp"
  ],
  "disabledTools": [
    "example",
    "hello-world",
    "check-version"
  ]
}

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request