Laravel Telescope MCP

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

概览

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

要求

• PHP 8.3+
• Laravel 11、12 或 13
• Laravel Telescope 5.0+

重要

HTTP MCP 端点默认未经过身份验证。如果将其暴露到线上，请先启用身份验证（参见“在 IDE 中保护 Streamable HTTP”）。

状态：✅ 19 个 MCP 工具已全面运行并集成

v1.0 新功能

🎉 现由官方 Laravel/MCP 包提供支持！

• 基于 Laravel 官方 MCP 框架构建，维护性更好，长期支持更有保障
• 改进了架构，使用 Laravel\Mcp\Server\Tool 定义工具，使定义更简洁
• 使用 JsonSchema 构建器增强了架构验证
• 使用 Laravel\Mcp\Request 和 Laravel\Mcp\Response 改进了请求处理
• 保持完全向后兼容——全部 19 个工具的工作方式不变
• 为未来的 Laravel/MCP 功能做好准备（资源、提示词、OAuth 身份验证）

快速开始

1. 安装此包：

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

2. 自动配置 MCP 客户端：

   php artisan telescope-mcp:install
   

   💡 自动检测并配置：Cursor、Claude Code、Windsurf、Cline、Gemini App、Antigravity、Codex 和 OpenCode。

3. 重启 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"
      }
    }
  }
}

重要

**Antigravity 用户：**Antigravity 不支持 cwd 属性。你必须在 args 数组中使用 artisan 的绝对路径，并建议在 env 对象中添加 "MCP_MODE": "stdio"。

3. 验证安装

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

php artisan telescope-mcp:server

它应静默运行（日志写入 stderr），并等待 JSON-RPC 输入。

---

各助手的手动配置

如果你倾向于手动配置，请将以下内容添加到助手的配置文件中：

Cursor、Windsurf、Cline

文件： 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"
      }
    }
  }
}

Claude Code（CLI）

你可以通过 ~/.claude/mcp.json 文件（格式与 Cursor 相同）或使用命令进行配置：

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

Antigravity

文件： 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

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"
      }
    }
  }
}

Codex（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"

故障排除（Stdio）

找不到 PHP 或 Artisan

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

权限

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

MCP 日志

如果工具没有显示，请检查助手的错误日志（例如，Cursor Output > MCP）。在终端中手动执行时，命令 php artisan telescope-mcp:server 应能正常运行，不出现错误。

使用 MCP Inspector（浏览器 UI / HTTP）

如果你想通过 @modelcontextprotocol/inspector 在浏览器中测试服务，请使用 HTTP 传输，并提供 MCP 端点 URL。

1. 针对远程/公共端点启动 Inspector

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

2. 针对本地 HTTPS 端点启动 Inspector

如果你的本地证书是自签名证书（*.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. 如果默认 Inspector 端口已被占用

Inspector 默认使用端口 6274（UI）和 6277（代理）。如果出现“PORT IS IN USE”：

# 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 属于预期情况。
• MCP JSON-RPC 请求请使用 POST /telescope-mcp。

在 IDE 中使用安全的 Streamable HTTP

此软件包现在支持为 HTTP MCP 端点内置 Bearer 令牌身份验证。

1. 在 Laravel 中启用身份验证（.env）

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

你也可以使用 TELESCOPE_MCP_BEARER_TOKEN 代替 MCP_BEARER_TOKEN。 存在其中一个令牌环境变量时，将自动启用身份验证。 如果你希望显式控制，请设置：

TELESCOPE_MCP_AUTH_ENABLED=true

令牌生成示例：

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

2. IDE UI 字段映射（Streamable 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”，请手动设置标头：

• Key：Authorization
• Value：Bearer <your-token>

如果你的 IDE 支持“headers from env variables”，建议使用：

• 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 数据的结构化响应。

工具	状态	说明	关键参数
Requests	✅	记录传入的 HTTP 请求	id、limit、method、status、path
Exceptions	✅	跟踪带堆栈跟踪的应用程序错误	id、limit
Queries	✅	监控包含性能指标的数据库查询	id、limit、slow（布尔值）
Logs	✅	记录应用程序日志并支持筛选	id、limit、level、message
HTTP Client	✅	监控发出的 HTTP 请求	id、limit、method、status、url
Mail	✅	监控电子邮件操作	id、limit、to、subject
Notifications	✅	记录通知发送情况	id、limit、channel、status
Jobs	✅	跟踪队列中的作业执行情况	id、limit、status、queue
Events	✅	监控事件发送情况	id、limit、name
Models	✅	跟踪 Eloquent 模型操作	id、limit、action、model
Cache	✅	监控缓存操作	id、limit、operation、key
Redis	✅	跟踪 Redis 操作	id、limit、command
Schedule	✅	监控计划任务的执行情况	id、limit
Views	✅	记录视图渲染情况	id、limit
Dumps	✅	记录 var_dump 和 dd() 调用	id、limit、file、line
Commands	✅	跟踪 Artisan 命令执行情况	id、limit、command、status
Gates	✅	记录授权检查	id、limit、ability、result
Batches	✅	列出并分析批处理操作	id、limit、status、name
Prune	✅	移除较早的 Telescope 条目	hours

当前状态与功能

✅ MCP 集成状态

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

🚀 主要优势

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

📊 响应格式

每个 MCP 工具都会提供：

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

🔧 工具功能

• 列表操作：通过自定义限制获取概览
• 详细视图：按 ID 深入查看特定条目
• 筛选：应用状态、级别、时间范围等筛选条件
• 性能指标：跟踪慢查询、失败的作业和错误

配置

• 身份验证：使用内置 Bearer 身份验证，设置 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 客户端高效地格式化响应

贡献

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

许可证

采用 MIT 许可证。详情请参阅 LICENSE。