使用说明

Laravel Telescope的一个扩展，通过模型上下文协议（MCP）向AI助手（例如Cursor、Claude、Copilot Chat）公开遥测数据。非常适合使用Telescope检查应用程序指标并需要快速、精确见解的开发人员。

概述

Telescope MCP通过模型上下文协议（MCP）公开所有Laravel Telescope遥测数据，使AI助手能够直接访问和分析应用程序指标。这为开发人员提供了通过自然语言查询对日志、慢速查询、HTTP请求、异常、作业等的即时洞察。

需求

PHP 8.3+
Laravel 11、12或13
Laravel望远镜5.0+

[！重要] HTTP MCP端点为 默认情况下未通过身份验证。如果您在线公开它，请先启用身份验证（请参阅“IDE中的安全流式HTTP”）。

状态: ✅ 19个MCP工具完全可操作和集成

v1.0的新增功能

🎉 现在由官方提供动力 Laravel/MCP 包裹！

基于Laravel的官方MCP框架，提供更好的可维护性和长期支持
使用更清晰的工具定义改进了架构 Laravel\Mcp\Server\Tool
通过以下方式增强架构验证 JsonSchema 建造者
更好地处理请求 Laravel\Mcp\Request 和 Laravel\Mcp\Response
保持完全向后兼容性-所有19个工具工作方式相同
为未来的Laravel/MCP功能做好准备（参考资料、提示、OAuth身份验证）

快速开始

安装软件包：

composer require lucianotonet/laravel-telescope-mcp --dev

自动配置MCP客户端：
```
php artisan telescope-mcp:install
```
💡 自动检测和配置：光标, 克劳德代码, 帆板运动, 克莱恩, Gemini应用程序, 反重力, 法典，以及 开源代码.
重新启动IDE/编辑器 开始使用工具！

详细安装

1.要求包装

composer require lucianotonet/laravel-telescope-mcp --dev

2.配置MCP客户端

您可以使用自动安装程序或手动配置。

选项A：自动安装（推荐）

php artisan telescope-mcp:install

此命令将：

检测已安装的MCP客户端
生成正确的配置文件(mcp.json, settings.json等等）
在中设置服务器 stdio 模式

选项B：手动配置 将以下内容添加到MCP客户端的配置文件中：

{
  "mcpServers": {
    "laravel-telescope": {
      "command": "php",
      "args": ["artisan", "telescope-mcp:server"],
      "cwd": "/path/to/your/project",
      "env": {
        "APP_ENV": "local"
      }
    }
  }
}

[！重要] 反重力用户： 反重力不支持 cwd 财产。您必须使用绝对路径 artisan 在 args 数组，建议添加 "MCP_MODE": "stdio" 到 env 对象。

3.验证安装

手动运行服务器以确保其正常工作：

php artisan telescope-mcp:server

它应该静默运行（记录到stderr）并等待JSON-RPC输入。

每个助手手动配置

如果您更喜欢手动配置，请将以下内容添加到助手的配置文件中：

光标，风帆，克莱恩

文件： mcp.json 或 cline_mcp_settings.json

{
  "mcpServers": {
    "laravel-telescope": {
      "command": "php",
      "args": ["artisan", "telescope-mcp:server"],
      "cwd": "/absolute/path/to/your/project",
      "env": {
        "APP_ENV": "local"
      }
    }
  }
}

克劳德代码（CLI）

您可以通过配置 ~/.claude/mcp.json 文件（与游标格式相同）或通过命令：

claude mcp add -s local -t stdio laravel-telescope php artisan telescope-mcp:server

反重力

文件： mcp_config.json （仅限全局配置）

{
  "mcpServers": {
    "laravel-telescope": {
      "command": "php",
      "args": ["/absolute/path/to/your/project/artisan", "telescope-mcp:server"],
      "env": {
        "APP_ENV": "local",
        "MCP_MODE": "stdio"
      }
    }
  }
}

开源代码

OpenCode使用不同的键，需要绝对路径 artisan.

文件： opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "laravel-telescope": {
      "type": "local",
      "enabled": true,
      "command": ["php", "/absolute/path/to/your/project/artisan", "telescope-mcp:server"],
      "environment": {
        "APP_ENV": "local"
      }
    }
  }
}

食品法典委员会（TOML）

文件： config.toml

[mcpServers.laravel-telescope]
command = "php"
args = ["artisan", "telescope-mcp:server"]
cwd = "/absolute/path/to/your/project"

[mcpServers.laravel-telescope.env]
APP_ENV = "local"

故障排除（标准）

未找到PHP或Artisan

确保 php 位于全局PATH中，或使用PHP可执行文件的绝对路径。在Windows上，使用双反斜杠 \\ 在JSON/TOML路径中。

权限

确保AI助手有权在Laravel项目中读/写 storage Telescope存储数据的目录。

MCP日志

如果工具未出现，请检查助手的错误日志（例如，光标输出>MCP）。命令 php artisan telescope-mcp:server 如果在终端中手动执行，则应无错误运行。

使用MCP检查器（浏览器UI/HTTP）

如果您想使用以下命令从浏览器测试服务器 @modelcontextprotocol/inspector，将HTTP传输与MCP端点URL一起使用。

1.对远程/公共端点启动检查器

npx -y @modelcontextprotocol/inspector --transport http --server-url "https://your-domain.com/telescope-mcp"

2.针对本地HTTPS端点启动检查器

如果您的本地证书是自签名的（与 *.test 域），在当前shell中禁用Node的TLS验证：

# PowerShell
$env:NODE_TLS_REJECT_UNAUTHORIZED='0'
npx -y @modelcontextprotocol/inspector --transport http --server-url "https://your-local-domain.test/telescope-mcp"

3.如果默认检查器端口繁忙

检查员使用端口 6274 （UI）和 6277 （代理）默认情况下。如果您收到“端口正在使用中”：

# PowerShell
$env:CLIENT_PORT='6284'
$env:SERVER_PORT='6287'
npx -y @modelcontextprotocol/inspector --transport http --server-url "https://your-domain.com/telescope-mcp"

4.可选的身份验证标头

如果您的MCP路由受中间件保护，请传递标头：

npx -y @modelcontextprotocol/inspector --transport http --server-url "https://your-domain.com/telescope-mcp" --header "Authorization: Bearer YOUR_TOKEN"

5.快速健康检查

GET /telescope-mcp 返回 405 这是意料之中的。
使用 POST /telescope-mcp 用于MCP JSON-RPC请求。

IDE中的安全流式HTTP

此包现在支持HTTP MCP端点的内置承载令牌身份验证。

1.在Laravel中启用auth(`.env`)

MCP_BEARER_TOKEN=replace-with-a-long-random-token

您还可以使用 TELESCOPE_MCP_BEARER_TOKEN 而不是 MCP_BEARER_TOKEN. 当这些令牌env变量之一存在时，会自动启用Auth。如果您更喜欢显式控制，请设置：

TELESCOPE_MCP_AUTH_ENABLED=true

生成一个令牌示例：

php -r "echo bin2hex(random_bytes(32)), PHP_EOL;"

2.IDE UI映射（流式HTTP）

对于需要以下字段的IDE：

Name
Streamable HTTP
URL
Bearer token env var
Headers / Headers from environment variables

用途：

Name: laravel-telescope-online （或任何名称）
Transport: Streamable HTTP
URL: https://your-domain.com/telescope-mcp
Bearer token env var: MCP_BEARER_TOKEN

如果您的IDE不支持“Bearer token env var”，请手动设置headers：

Key: Authorization
Value: Bearer <your-token>

如果您的IDE支持“来自env变量的headers”，请首选：

Key: Authorization
Value: Bearer ${MCP_BEARER_TOKEN}

3.本地和在线示例

本地URL: https://your-local-domain.test/telescope-mcp
在线URL: https://your-public-domain.com/telescope-mcp

参考：OpenAI Codex MCP文档(https://developers.openai.com/codex/mcp/).

如何使用

连接后，您可以直接在AI助手中使用MCP工具：

# List recent HTTP requests
@laravel-telescope-mcp requests --limit 5

# Details of a specific exception
@laravel-telescope-mcp exceptions --id 123456

# Find slow queries
@laravel-telescope-mcp queries --slow true --limit 10

用法示例

MCP工具的直接使用（推荐）

连接后，您可以直接在AI助手中使用MCP工具：

# List recent HTTP requests
@laravel-telescope-mcp requests --limit 5

# Get details of a specific exception
@laravel-telescope-mcp exceptions --id 123456

# Find slow database queries
@laravel-telescope-mcp queries --slow true --limit 10

# Check recent logs
@laravel-telescope-mcp logs --level error --limit 5

自然语言查询

“显示应用程序的最后5个错误日志”
“识别耗时超过100ms的SQL查询”
“显示上个小时以来所有失败的作业”
“用5xx状态代码总结HTTP请求”

AI将自动使用适当的MCP工具来获取和分析数据。

可用工具

所有19个MCP工具都可以完全运行，并提供具有人类可读文本和JSON数据的结构化响应。

工具	状态	描述	关键参数
请求：	✅	记录传入的HTTP请求	`id`, `limit`, `method`, `status`, `path`
异常	✅	使用堆栈跟踪跟踪应用程序错误	`id`, `limit`
查询	✅	使用性能指标监控数据库查询	`id`, `limit`, `slow` （布尔值）
日志	✅	通过过滤记录应用程序日志	`id`, `limit`, `level`, `message`
HTTP客户端	✅	监视传出的HTTP请求	`id`, `limit`, `method`, `status`, `url`
邮件	✅	监控电子邮件操作	`id`, `limit`, `to`, `subject`
通知	✅	记录通知发送	`id`, `limit`, `channel`, `status`
工作	✅	跟踪排队的作业执行情况	`id`, `limit`, `status`, `queue`
事件	✅	监控事件调度	`id`, `limit`, `name`
模型	✅	跟踪Eloquent模型操作	`id`, `limit`, `action`, `model`
缓存	✅	监控缓存操作	`id`, `limit`, `operation`, `key`
瑞迪斯	✅	跟踪Redis操作	`id`, `limit`, `command`
日程	✅	监控计划任务执行	`id`, `limit`
视图	✅	记录视图渲染	`id`, `limit`
垃圾	✅	记录var_dump和dd（）调用	`id`, `limit`, `file`, `line`
命令	✅	跟踪Artisan命令执行情况	`id`, `limit`, `command`, `status`
大门	✅	记录授权检查	`id`, `limit`, `ability`, `result`
批次	✅	列出并分析批处理操作	`id`, `limit`, `status`, `name`
修剪	✅	删除旧的望远镜条目	`hours`

当前状态和功能

✅ MCP集成状态

19个MCP工具正在运行：现在可以通过MCP访问望远镜的所有主要功能
原生游标集成：工具直接在Cursor中工作，无需外部命令
结构化响应：每个工具都返回人类可读的文本和JSON数据
实时数据访问：无需HTTP请求即可直接访问Telescope遥测

🚀 主要优势

不再需要cURL：直接在AI助手中使用MCP工具
即时洞察：通过自然语言获取应用程序指标
结构化数据：可读摘要和程序化访问
全望远镜覆盖：访问所有主要监控功能

📊 响应格式

每个MCP工具提供：

人类可读输出：格式化表格和摘要
JSON数据：用于程序化处理的结构化数据
MCP合规性：标准MCP响应格式

🔧 工具功能

清单的操作：获取具有可自定义限制的概述
详细视图：按ID深入查看特定条目
过滤：应用状态、级别、时间范围等过滤器
性能指标：跟踪慢速查询、失败作业、错误

配置

认证：使用内置的承载身份验证 TELESCOPE_MCP_AUTH_ENABLED=true 和 MCP_BEARER_TOKEN （或 TELESCOPE_MCP_BEARER_TOKEN)，或使用Laravel中间件进行保护(auth:sanctum, auth.basic).
端点路径：自定义 TELESCOPE_MCP_PATH 或修改 config/telescope-mcp.php.
中间件：设置 TELESCOPE_MCP_MIDDLEWARE 作为逗号分隔的列表（例如。， api,auth:sanctum).
日志记录：启用或禁用内部MCP日志记录。
超时和限制：根据需要调整请求超时和有效载荷限制。

高级

看 config/telescope-mcp.php 用于：

自定义中间件堆栈
操作特定设置
路由和命名空间覆盖

性能与监控

实时洞察

HTTP请求：监控传入流量、响应时间和状态代码
数据库查询：跟踪慢速查询并优化性能
应用程序错误：获取详细的堆栈跟踪和错误上下文
作业处理：监视队列性能和故障
缓存操作：跟踪缓存命中/未命中率和性能

数据保留

可配置的限制：根据您的需求为每个工具设置适当的限制
高效查询：工具使用优化的Telescope查询进行快速响应
内存管理：MCP客户端的响应格式高效

贡献

欢迎捐款。请按照我们的要求提交问题或拉取请求贡献.md 指导方针。

许可证

在麻省理工学院获得许可。看许可证了解详情。