Laravel Telescope MCP

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

概览

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

状态: ✅ 19个MCP工具完全运行并集成

安装

确保在继续之前已在应用中正确安装并配置了Laravel Telescope

1. 通过Composer添加包：

   composer require lucianotonet/laravel-telescope-mcp
   

2. 发布配置（可选）：

   php artisan vendor:publish --provider="LucianoTonet\TelescopeMcp\TelescopeMcpServiceProvider"
   

3. 更新你的.env（可选）：

   TELESCOPE_MCP_ENABLED=true
   TELESCOPE_MCP_PATH=telescope-mcp
   

   现在你可以通过访问浏览器中的http://localhost:8000/telescope-mcp/manifest.json来验证安装

连接AI客户端

对于Cursor（示例）：

1. 打开Cursor命令面板（Cmd/Ctrl+Shift+P）。

2. 运行视图：打开MCP设置。

3. 添加以下配置：

   {
     "mcpServers": {
       "Laravel Telescope MCP": {
         "command": "npx",
         "args": [
           "-y", 
           "mcp-remote", 
           "http://127.0.0.1:8000/telescope-mcp",
           "--allow-http"
         ],
         "env": { "NODE_TLS_REJECT_UNAUTHORIZED": "0" }
       }
     }
   }
   

   重要: 使用127.0.0.1而不是localhost以避免IPv6连接问题 确保URL与你的.env配置相匹配，结合APP_URL和TELESCOPE_MCP_PATH

4. 对于HTTPS，可以省略--allow-http和NODE_TLS_REJECT_UNAUTHORIZED，如下所示：

   {
     "mcpServers": {
       "Laravel Telescope MCP": {
         "command": "npx",
         "args": [
           "-y", 
           "mcp-remote", 
           "https://example.com/telescope-mcp"            
         ]
       }
     }
   }
   

故障排除

连接被拒绝错误

如果你在尝试连接时遇到ECONNREFUSED错误：

问题: MCP客户端试图通过IPv6（::1）连接，但你的Laravel服务器仅接受IPv4连接。

解决方案: 在你的MCP配置URL中使用127.0.0.1而不是localhost。

示例:

// ❌ 这可能会导致IPv6连接问题
"http://localhost:8000/telescope-mcp"

// ✅ 使用此方法强制IPv4连接
"http://127.0.0.1:8000/telescope-mcp"

替代方案: 如果你更喜欢使用localhost，可以启动支持IPv6的Laravel服务器：

php artisan serve --host=0.0.0.0 --port=8000

MCP工具问题

问题: 部分工具可能显示空结果或错误。

解决方案:

1. 确保Telescope正在记录数据: 检查你的应用程序是否生成了你查询的数据类型
2. 验证工具参数: 部分工具需要特定参数（例如，查询时的slow: true）
3. 检查数据新鲜度: 根据你的应用程序活动，某些工具可能没有最近的数据

工具特定说明:

• 修剪工具: 可能会显示错误，但不影响其他工具
• 空结果: 当Telescope中不存在该类型的数据时正常

快速开始

1. 安装和配置

composer require lucianotonet/laravel-telescope-mcp
php artisan vendor:publish --provider="LucianoTonet\TelescopeMcp\TelescopeMcpServiceProvider"

2. 连接MCP客户端

添加到你的Cursor MCP设置：

{
  "mcpServers": {
    "Laravel Telescope MCP": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8000/telescope-mcp", "--allow-http"],
      "env": { "NODE_TLS_REJECT_UNAUTHORIZED": "0" }
    }
  }
}

3. 开始使用MCP工具

# 查看最近的请求
@laravel-telescope-mcp requests --limit 5

# 查找错误
@laravel-telescope-mcp exceptions --limit 3

# 监控数据库性能
@laravel-telescope-mcp queries --slow true

使用示例

直接使用MCP工具（推荐）

一旦连接，你可以在你的AI助手直接使用MCP工具：

# 列出最近的HTTP请求
@laravel-telescope-mcp requests --limit 10

# 获取特定异常的详细信息
@laravel-telescope-mcp exceptions --id 123456

# 查找慢SQL查询
@laravel-telescope-mcp queries --slow true --limit 10

# 查看最近的日志
@laravel-telescope-mcp logs --level error --limit 5

自然语言查询

• "展示我应用程序最后5条错误日志"
• "识别耗时超过100毫秒的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	✅	跟踪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
修剪	⚠️	删除旧的Telescope条目	hours

图例: ✅ 完全运行 | ⚠️ 小问题

当前状态及功能

✅ MCP集成状态

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

🚀 关键优势

• 不再需要cURL: 直接在你的AI助手使用MCP工具
• 即时洞察: 通过自然语言获取应用程序指标
• 结构化数据: 提供可读摘要和编程访问
• 全面覆盖Telescope: 访问所有主要监控功能

📊 响应格式

每个MCP工具提供：

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

🔧 工具能力

• 列表操作: 获取带有自定义限制的概览
• 详细视图: 通过ID深入特定条目
• 过滤: 应用过滤器如状态、级别、时间范围
• 性能指标: 跟踪慢查询、失败任务、错误

配置

• 认证: 使用中间件保护MCP端点（例如，auth:sanctum，auth.basic）。
• 端点路径: 自定义TELESCOPE_MCP_PATH或修改config/telescope-mcp.php。
• 日志: 启用或禁用内部MCP日志。
• 超时和限制: 根据需要调整请求超时和负载限制。

高级

查看config/telescope-mcp.php：

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

性能与监控

实时洞察

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

数据保留

• 可配置限制: 根据需求为每个工具设置适当的限制
• 高效查询: 工具使用优化的Telescope查询以实现快速响应
• 内存管理: 响应被有效地格式化以供MCP客户端使用

贡献

欢迎贡献。请按照我们的CONTRIBUTING.md指南提交问题或拉取请求。

许可证

根据MIT许可。详情见LICENSE。