README

A super simple MCP (Model Context Protocol) server package for Laravel, based on the Laravel Telescope MCP architecture.

Features

🚀 Laravel Telescope MCP server
📊 Monitor and analyze your Laravel application through MCP
📦 Easy to extend with custom tools
🔧 Follows JSON-RPC 2.0 specification
📝 Built-in logging support
⚙️ Configurable via config file

Installation

1. Install via Composer

If you're developing this package locally, add it to your Laravel project's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "../laravel-packages/telescope-mcp"
        }
    ]
}

Then require it:

composer require skylence/telescope-mcp

2. Publish Configuration (Optional)

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

This will create config/telescope-mcp.php where you can customize:

Server path (default: telescope-mcp)
Enable/disable the server
Middleware configuration
Logging settings

Configuration

Environment Variables

Add these to your .env file:

SIMPLE_MCP_PATH=telescope-mcp
SIMPLE_MCP_ENABLED=true
SIMPLE_MCP_LOGGING_ENABLED=true
SIMPLE_MCP_LOGGING_CHANNEL=stack

Usage

Available Endpoints

Once installed, the MCP server is available at /telescope-mcp (or your configured path):

POST /telescope-mcp                - JSON-RPC 2.0 endpoint (supports all methods)
GET  /telescope-mcp/manifest.json  - Get server manifest (MCP protocol format)
POST /telescope-mcp/manifest.json  - JSON-RPC 2.0 endpoint (same as POST /)
POST /telescope-mcp/tools/call     - Call a tool via JSON-RPC
POST /telescope-mcp/tools/{tool}   - Direct tool execution

Testing the Server

Get the Manifest

curl http://localhost:8000/telescope-mcp/manifest.json

This will return the server manifest with all available tools, resources, and prompts in MCP protocol format.

Creating Custom Tools

1. Create a New Tool Class

Create a new file in src/MCP/Tools/YourTool.php:

<?php

declare(strict_types=1);

namespace Skylence\TelescopeMcp\MCP\Tools;

final class YourTool extends AbstractTool
{
    public function getShortName(): string
    {
        return 'your-tool';
    }

    public function getSchema(): array
    {
        return [
            'name' => $this->getName(),
            'description' => 'Your tool description',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'param1' => [
                        'type' => 'string',
                        'description' => 'Parameter description',
                    ],
                ],
                'required' => ['param1'],
            ],
        ];
    }

    public function execute(array $params): array
    {
        // Validate parameters
        if (!isset($params['param1'])) {
            return $this->formatError('param1 is required');
        }

        // Your logic here
        $result = "Processing: {$params['param1']}";

        return $this->formatResponse($result, [
            'processed' => true,
            'timestamp' => now()->toIso8601String(),
        ]);
    }
}

2. Register Your Tool

In src/MCP/TelescopeMcpServer.php, add your tool to the registerTools() method:

private function registerTools(): void
{
    $this->registerTool(new YourTool()); // Add this line

    // Or register conditionally if it depends on Telescope
    if (class_exists(\Laravel\Telescope\TelescopeServiceProvider::class)) {
        $this->registerTool(new YourTool());
    }
}

3. Test Your Tool

curl -X POST http://localhost:8000/telescope-mcp/tools/your-tool \
  -H "Content-Type: application/json" \
  -d '{"param1": "test value"}'

Architecture

telescope-mcp/
├── config/
│   └── telescope-mcp.php              # Configuration file
├── routes/
│   └── api.php                      # Route definitions
├── src/
│   ├── Http/
│   │   └── Controllers/
│   │       └── McpController.php    # HTTP handler
│   ├── MCP/
│   │   ├── TelescopeMcpServer.php      # Core server
│   │   └── Tools/
│   │       ├── AbstractTool.php     # Base tool class
│   │       └── [Various Telescope tools]
│   ├── Support/
│   │   ├── JsonRpcResponse.php      # JSON-RPC helpers
│   │   └── Logger.php               # Logging helper
│   └── TelescopeMcpServiceProvider.php # Service provider
└── composer.json

JSON-RPC 2.0 Compliance

This package follows the JSON-RPC 2.0 specification:

Request Format:

{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {...},
    "id": 1
}

Success Response:

{
    "jsonrpc": "2.0",
    "result": {...},
    "id": 1
}

Error Response:

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32600,
        "message": "Invalid Request"
    },
    "id": 1
}

Error Codes

-32700: Parse error
-32600: Invalid request
-32601: Method not found
-32602: Invalid params
-32603: Internal error

Logging

All MCP requests and responses are logged if logging is enabled. Check your Laravel logs:

tail -f storage/logs/laravel.log

Requirements

PHP 8.1 or higher
Laravel 10, 11, or 12

License

MIT

Credits

Based on the Laravel Telescope MCP architecture by Luciano Tonet.

Contributing

Feel free to extend this package with more tools and features!

skylence / laravel-telescope-mcp

Maintainers

Details