Laravel Telescope MCP Server Mvp

Laravel望远镜MCP服务器（PHP）

一个内置于PHP中的模型上下文协议（MCP）服务器，为AI代理提供对Laravel Telescope数据的直接访问，从而能够高效地调试和分析Laravel应用程序。

项目概述

关键目标

• 概念验证：创建最基本的MCP服务器来演示Laravel Telescope集成
• PHP原生：完全内置于PHP中，使用PHP-mcp/server库
• 光标集成：针对Cursor IDE进行了优化，支持深度链接，实现了无缝的开发工作流程
• 最低可行性产品：专注于核心功能，使其快速工作

功能（计划中）

核心MCP工具

• telescope_requests -列出最近来自Telescope的HTTP请求
• telescope_search -使用基本过滤器（状态、方法、URI模式）搜索请求
• telescope_request_details -获取特定请求的详细信息
• telescope_queries -查看特定请求的数据库查询

光标集成

• Deeplink支持快速启动和调试服务器
• 开发友好型配置
• Laravel项目的简单设置

建筑

Laravel App → Telescope → MySQL Database
                              ↓
                    PHP MCP Server (php-mcp/server)
                              ↓
                         Cursor IDE
                              ↓
                      AI Assistant Integration

快速启动（计划中）

先决条件

• PHP 8.1+
• 作曲家
• 安装了Telescope的Laravel应用程序
• 光标IDE

安装

git clone 
cd laravel-telescope-mcp-server
composer install

配置

# Copy environment file
cp .env.example .env

# Configure database connection to your Laravel app
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_laravel_db
DB_USERNAME=your_username
DB_PASSWORD=your_password

运行服务器

选项1：直接执行PHP

php server.php

选项2：使用Composer脚本

composer run serve

选项3：使用PHPX（推荐）

如果你有 PHPX 安装：

phpx laravel-telescope-mcp-server

游标深度链接集成

要与Cursor集成，您需要创建一个深度链接配置。以下是Cursor的MCP服务器配置：

用于光标IDE设置

将此添加到您的Cursor MCP配置中：

{
  "telescope": {
    "command": "php",
    "args": [
      "/path/to/laravel-telescope-mcp-server/server.php"
    ],
    "env": {
      "DB_HOST": "127.0.0.1",
      "DB_PORT": "3306",
      "DB_DATABASE": "your_laravel_db",
      "DB_USERNAME": "your_username",
      "DB_PASSWORD": "your_password"
    }
  }
}

替代方案：使用PHPX

{
  "telescope": {
    "command": "phpx",
    "args": [
      "laravel-telescope-mcp-server"
    ],
    "env": {
      "DB_HOST": "127.0.0.1",
      "DB_PORT": "3306",
      "DB_DATABASE": "your_laravel_db",
      "DB_USERNAME": "your_username",
      "DB_PASSWORD": "your_password"
    }
  }
}

生成光标深度链接

1. 获取服务器配置JSON
2. 使用 JSON.stringify() 转换它并对其进行base64编码
3. 创建深度链接： cursor://mcp/install?name=telescope&config=BASE64_ENCODED_CONFIG

生成深度链接的示例辅助脚本：

 [
        "command" => "php",
        "args" => [getcwd() . "/server.php"],
        "env" => [
            "DB_HOST" => "127.0.0.1",
            "DB_PORT" => "3306",
            "DB_DATABASE" => "your_laravel_db",
            "DB_USERNAME" => "your_username",
            "DB_PASSWORD" => "your_password"
        ]
    ]
];

$encoded = base64_encode(json_encode($config));
echo "cursor://mcp/install?name=telescope&config=" . $encoded . "\n";
?>

## Development Roadmap

### Phase 1: Basic MCP Server
- [x] Project setup and README
- [ ] Basic MCP server using php-mcp/server
- [ ] Database connection to Laravel Telescope tables
- [ ] Simple request listing tool

### Phase 2: Core Tools
- [ ] Request search and filtering
- [ ] Request detail retrieval
- [ ] Query analysis tool
- [ ] Basic error handling

### Phase 3: Cursor Integration
- [ ] Deeplink configuration
- [ ] Development workflow optimization
- [ ] Documentation for Cursor setup

### Phase 4: Enhancement
- [ ] Performance optimization
- [ ] Additional Telescope data types (jobs, cache, etc.)
- [ ] Better error messages and debugging

## Technical Stack

- **Language**: PHP 8.1+
- **MCP Library**: [php-mcp/server](https://github.com/php-mcp/server)
- **Database**: MySQL/MariaDB (Laravel Telescope tables)
- **IDE Integration**: Cursor with deeplink support

## Inspiration

This project draws inspiration from:
- [bradleybernard/TelescopeMCP](https://github.com/bradleybernard/TelescopeMCP) - Python implementation
- [php-mcp/server](https://github.com/php-mcp/server) - PHP MCP server library

## Why PHP?

- Native integration with Laravel ecosystem
- Leverages existing PHP knowledge for Laravel developers
- Direct access to Laravel's database structure and conventions
- Easier deployment alongside existing PHP/Laravel infrastructure

## Contributing

This is a proof-of-concept project focused on getting a minimal viable product working. Contributions welcome once the basic functionality is established.

## License

MIT License - see LICENSE file for details.

---

**Status**: 🚧 Early Development - Proof of Concept Phase

**Next Steps**: Set up basic MCP server structure using php-mcp/server library. ```