内容
# log_pilot_mcp
[](https://pub.dev/packages/log_pilot_mcp)
[](LICENSE)
用于 [log_pilot](https://pub.dev/packages/log_pilot) 的 MCP（模型上下文协议）服务器。 为 **Cursor, Claude Code, Windsurf** 等支持 MCP 的工具以及其他工具提供直接访问运行中的 Flutter 应用日志状态的功能。
---
## 工作原理
```
+----------------+ +------------------+
| Flutter 应用 | -- VM 服务 ---> | log_pilot_mcp |
| （调试模式） | <-- ext.LogPilot.* | （MCP 服务器） |
+-------+--------+ +---------+--------+
| |
| 写入 URI | MCP 协议
| 在启动时 |
v v
.dart_tool/ +------------------+
log_pilot_vm_service_uri | Cursor / Claude |
| | Windsurf / ... |
+--- 被 MCP 服务器监视 --->+------------------+
```
`log_pilot_mcp` 连接到您的应用的 Dart VM 服务，并使用 LogPilot 的服务扩展（`ext.LogPilot.*`）来查询日志、获取诊断快照、更改日志级别等 - 无需编辑代码或重启。
服务器在热重启、隔离回收和完整应用重启时自动重新连接（使用文件监视器自动发现）。
### Dart MCP 与 LogPilot MCP
这两个是相互补充的独立 MCP 服务器：
| 需要 | 使用 |
|------|-----|
| 小部件树、热重载、运行时错误 | Dart MCP (`user-dart`) |
| 结构化日志、快照、日志级别控制 | LogPilot MCP (`log_pilot_mcp`) |
| 静态分析、代码检查 | Dart MCP (`analyze_files`) |
两者可以同时运行。
---
## 快速入门
### 1. 安装
**全局激活（推荐 - 避免工作目录问题）：**
```bash
dart pub global activate log_pilot_mcp
```
或作为开发依赖添加到您的 Flutter 应用中：
```bash
dart pub add --dev log_pilot_mcp
```
> **为什么更倾向于全局激活？** 当作为开发依赖安装时，`dart run log_pilot_mcp` 仅在包含 `pubspec.yaml` 的目录中有效，而该 `pubspec.yaml` 列表中包含了它。 IDE 通常从不同的工作目录（工作区根目录，可能不是您的 Flutter 应用根目录）启动 MCP 服务器进程。全局激活为您提供了一个独立的可执行文件，可以从任何地方工作。
### 2. 配置您的 Flutter 应用
您的应用必须调用 `LogPilot.init()` 或 `LogPilot.configure()` - 两个函数都注册了 MCP 服务器需要的服务扩展。如果您的应用已经使用其中一个，则可以正常使用。
```dart
// 选项 A - 简单应用：
void main() {
LogPilot.init(child: const MyApp());
}
// 选项 B - Firebase / 异步启动：
void main() {
runZonedGuarded<Future<void>>(() async {
WidgetsFlutterBinding.ensureInitialized();
LogPilot.configure(config: LogPilotConfig.debug());
await Firebase.initializeApp();
runApp(const MyApp());
}, (error, stack) { /* ... */ });
}
```
### 3. 运行您的 Flutter 应用
```bash
flutter run
```
LogPilot 会在桌面平台上自动将 VM 服务 URI 写入 `.dart_tool/log_pilot_vm_service_uri`。在 **Android/iOS** 上，设备无法写入主机文件系统 - 使用 `--project-root` 或 `write-uri`（参见 [CLI 参考](#cli-参考)）。
### 4. 配置您的 IDE
选择下面的 IDE 以获取确切的设置说明。
<details>
<summary><b>Cursor</b></summary>
在您的 **工作区根目录** 中创建或编辑 `.cursor/mcp.json`：
**如果全局激活（推荐）：**
```json
{
"mcpServers": {
"LogPilot": {
"command": "log_pilot_mcp",
"args": ["--project-root=/path/to/your-flutter-app"]
}
}
}
```
在 **Windows** 上，使用可执行文件的完整路径：
```json
{
"mcpServers": {
"LogPilot": {
"command": "C:\\Users\\you\\AppData\\Local\\Pub\\Cache\\bin\\log_pilot_mcp.bat",
"args": ["--project-root=C:/Users/you/your-flutter-app"]
}
}
}
```
**如果作为开发依赖安装（macOS/Linux）：**
```json
{
"mcpServers": {
"LogPilot": {
"command": "dart",
"args": ["run", "log_pilot_mcp"]
}
}
}
```
在 **Windows** 上使用开发依赖时，还需要添加 `--project-root` 和 `cwd`：
`"cwd": "C:/Users/you/your-flutter-app"` 和 `"--project-root=C:/Users/you/your-flutter-app"` 在参数中。全局激活完全避免了这种复杂性。
**启用服务器（3 个步骤 - 全部需要）：**
1. 按 `Ctrl+Shift+P`（或 `Cmd+Shift+P`）→ **"开发者：重新加载窗口"**
2. 打开 **Cursor 设置 → MCP** 并 **切换 LogPilot 为 ON** （默认为 OFF）
3. 验证 LogPilot 旁边出现绿色圆点
</details>
<details>
<summary><b>VS Code (GitHub Copilot)</b></summary>
在您的 **工作区根目录** 中创建或编辑 `.vscode/mcp.json`：
```json
{
"mcpServers": {
"LogPilot": {
"command": "dart",
"args": ["run", "log_pilot_mcp"]
}
}
}
```
在 **Windows** 上，添加 `--project-root=C:/Users/you/your-flutter-app`。
**启用：** 重新加载窗口（`Ctrl+Shift+P` → "开发者：重新加载窗口"），并验证 LogPilot 出现在 MCP 面板中。
</details>
<details>
<summary><b>Windsurf</b></summary>
编辑 `~/.codeium/windsurf/mcp_config.json` 处的 **全局** 配置：
```json
{
"mcpServers": {
"LogPilot": {
"command": "dart",
"args": ["run", "log_pilot_mcp"]
}
}
}
```
如果文件已经有其他服务器，请合并到现有的 `mcpServers` 中。在 **Windows** 上，添加 `--project-root=C:/Users/you/your-flutter-app`。
</details>
<details>
<summary><b>Claude Code (CLI)</b></summary>
直接传递 URI：
```bash
dart run log_pilot_mcp --vm-service-uri=ws://127.0.0.1:PORT/TOKEN=/ws
```
或通过环境变量：
```bash
export LOG_PILOT_VM_SERVICE_URI=ws://127.0.0.1:PORT/TOKEN=/ws
dart run log_pilot_mcp
```
对于持久化配置，请添加到 `~/.claude/mcp.json`：
```json
{
"mcpServers": {
"LogPilot": {
"command": "dart",
"args": [
"run", "log_pilot_mcp",
"--project-root=/path/to/your-flutter-app"
]
}
}
}
```
</details>
<details>
<summary><b>Antigravity</b></summary>
1. 打开 **IDE 设置 → MCP** 面板
2. 添加一个新的 MCP 服务器，参数为：
- **命令：** `dart`
- **参数：** `run log_pilot_mcp`
3. 在 **Windows** 上，添加 `--project-root=C:/Users/you/your-flutter-app`
4. 切换服务器为 ON 并验证连接
</details>
<details>
<summary><b>Gemini CLI</b></summary>
编辑 `~/.gemini/settings.json`：
```json
{
"mcpServers": {
"LogPilot": {
"command": "dart",
"args": [
"run", "log_pilot_mcp",
"--project-root=/path/to/your-flutter-app"
]
}
}
}
```
</details>
<details>
<summary><b>其他 MCP 客户端</b></summary>
任何基于 stdio 的 MCP 客户端都可以使用：
```json
{
"mcpServers": {
"LogPilot": {
"command": "dart",
"args": ["run", "log_pilot_mcp"]
}
}
}
```
在 Windows 上，添加 `--project-root=<ABSOLUTE_PATH>` 到参数中。查阅客户端文档获取配置文件位置。
</details>
> **重要：工作目录。** `dart run log_pilot_mcp` 必须在 `log_pilot_mcp` 作为依赖项（在 `pubspec.yaml` 中列出）的目录中执行。如果您的 IDE 工作区根目录与 Flutter 应用目录不同（单体仓库、子目录应用等），请在服务器配置中添加 `"cwd"`：
>
> ```json
> {
> "mcpServers": {
> "LogPilot": {
> "command": "dart",
> "args": ["run", "log_pilot_mcp"],
> "cwd": "/absolute/path/to/your-flutter-app"
> }
> }
> }
> ```
>
> `cwd` 必须指向包含 `pubspec.yaml` 的目录，该 `pubspec.yaml` 将 `log_pilot_mcp` 列为开发依赖项。
### 5. 验证
要求代理调用 `get_snapshot` 或 `get_log_level` - 如果返回数据，则表示已连接。
---
## 当应用重启时
**热重启（相同调试会话）：** 自动重新连接 - 无需操作。
**完整重启（新调试会话）：**
- **自动发现模式**（无 `--vm-service-uri` 标志）：URI 文件自动更新，服务器自行重新连接。
- **Android/iOS**：设备无法更新 URI 文件。运行 `log_pilot_mcp write-uri <new_ws_uri>` 从主机 - 服务器的文件监视器检测到更改并重新连接。
- **手动 URI 模式**（`mcp.json` 中的 `--vm-service-uri`）：更新 URI 值并重新加载 Cursor 窗口。
---
## MCP 工具
| 工具 | 描述 |
|------|-------------|
| `get_snapshot` | 结构化诊断摘要：错误、计时器、配置、最近的日志。支持 `group_by_tag`。 |
| `query_logs` | 按级别、标签、消息、跟踪 ID、错误存在、元数据键过滤历史记录。 |
| `export_logs` | 完整日志历史记录为文本或 NDJSON。 |
| `export_for_llm` | 为 LLM 上下文窗口优化的压缩摘要。 |
| `set_log_level` | 在运行时更改详细程度。 |
| `get_log_level` | 读取当前最低日志级别。 |
| `clear_logs` | 清除内存中的日志历史记录。 |
| `watch_logs` | 通过 MCP 通知流式传输新条目。 |
| `stop_watch` | 停止活动监视器并获取交付摘要。 |
### 推荐的调试工作流程
1. `get_snapshot` - 查看错误、配置、活动计时器
2. `set_log_level(level: "verbose")` - 增加详细程度
3. 重现问题
4. `query_logs(level: "error", deduplicate: true)` - 查找根本原因
5. `export_for_llm(token_budget: 2000)` - 为分析压缩上下文
6. `set_log_level(level: "warning")` - 恢复安静模式
### `get_snapshot` 参数
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `max_recent_errors` | int | 5 | 最大错误/致命记录数 |
| `max_recent_logs` | int | 10 | 任意级别的最大最近记录数 |
| `group_by_tag` | bool | false | 包括 `recentByTag` 部分 |
| `per_tag_limit` | int | 5 | 分组时的每标签记录数 |
### `query_logs` 参数
所有筛选器都与 AND 逻辑结合使用。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `level` | string | - | 最低日志级别筛选器 |
| `tag` | string | - | 精确标签匹配 |
| `message_contains` | string | - | 不区分大小写的子字符串搜索 |
| `trace_id` | string | - | 按确切跟踪 ID 筛选 |
| `has_error` | bool | - | `true` = 仅错误，`false` = 仅非错误 |
| `metadata_key` | string | - | 仅包含此键的元数据记录 |
| `limit` | int | 20 | 最大记录数（1-100） |
| `deduplicate` | bool | false | 合并连续的相同条目（相同级别 + 消息 + 调用者）。仅服务扩展模式；评估回退返回时不进行重复数据删除。 |
### `export_for_llm` 参数
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `token_budget` | int | 4000 | 最大输出大小（近似令牌）(~4 chars/token) |
### `watch_logs` 参数
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `tag` | string | - | 仅传递具有此标签的条目 |
| `level` | string | - | 最低日志级别筛选器 |
| `interval_ms` | int | 2000 | 毫秒轮询间隔（500-30,000） |
---
## MCP 资源
| 资源 | 描述 |
|----------|-------------|
| `LogPilot://config` | 当前 LogPilot 配置快照 |
| `LogPilot://session` | 会话 ID 和跟踪 ID |
| `LogPilot://tail` | 活动监视器的最新批次（可订阅） |
---
## Flutter 网页
在 Flutter 网页（`dart:io`不可用）上不可用 **自动发现**。直接传递 `--vm-service-uri`：
```json
{
"mcpServers": {
"LogPilot": {
"command": "dart",
"args": [
"run", "log_pilot_mcp",
"--vm-service-uri=ws://127.0.0.1:PORT/TOKEN=/ws"
]
}
}
}
```
URI 在每次应用重启时都会更改。最简单的方法是从调试控制台复制 `ws://...` URI。对于自动化，您可以使用 `--vm-service-uri-file` 和辅助脚本，但请注意这些脚本会解析 Flutter 的控制台输出，**可能会在 SDK 版本之间中断**：
**macOS / Linux：**
```bash
flutter run -d chrome --machine 2>&1 \
| grep -o 'ws://[^ "]*' | head -1 \
> .dart_tool/log_pilot_vm_service_uri
```
**Windows (PowerShell):**
```powershell
flutter run -d chrome --machine 2>&1 |
Select-String -Pattern 'ws://[^ "]+' |
ForEach-Object { $_.Matches[0].Value } |
Select-Object -First 1 |
Set-Content .dart_tool\log_pilot_vm_service_uri
```
然后指向 MCP 服务器到该文件：
```json
{
"mcpServers": {
"LogPilot": {
"command": "dart",
"args": [
"run", "log_pilot_mcp",
"--vm-service-uri-file=.dart_tool/log_pilot_vm_service_uri"
]
}
}
}
```
服务器监视文件，因此当您重启应用并重新运行捕获脚本时，它会自动重新连接。
---
## 故障排除
**诊断检查清单 - 按顺序执行：**
1. **在您的 IDE 中服务器是否可见？** 否 → 在创建/编辑 MCP 配置后重新加载 IDE 窗口。 新服务器默认为关闭状态。
2. **是否显示绿色/已连接状态？** 否 → 应用可能未运行，或自动发现失败。 继续以下步骤。
3. **应用是否在调试模式下运行？** 必须是 `flutter run`（不是 `--release`）。 VM 服务仅在调试/配置文件中可用。
4. **.dart_tool/log_pilot_vm_service_uri 是否存在于您的项目中？** 否 → 应用必须调用 `LogPilot.init()` 或 `LogPilot.configure()`。 在 Windows 上，为 MCP 服务器参数添加 `--project-root`。
5. **调用 `get_snapshot`。** 如果它返回数据，则表示您已连接。
**常见错误：**
| 错误 | 原因 | 修复 |
|-------|-------|-----|
| 服务器显示“禁用” | IDE 新服务器的默认设置 | 在 MCP 设置中切换 **ON** |
| 服务器不在 MCP 列表中 | 配置未加载 | `Ctrl+Shift+P` → "开发者：重新加载窗口" |
| `Could not find package "log_pilot_mcp"` | 包未安装 | `dart pub add --dev log_pilot_mcp` |
| `Failed to connect to VM service` | 应用未运行或 URI 过时 | 启动应用；检查 URI 文件是否包含有效的 `ws://` URI |
| `VM service not responding` / `getVM: (-32601)` | URI 过时或应用已重启 | 重启应用以重新生成 URI 文件。在 Android/iOS 上，运行 `log_pilot_mcp write-uri <new_ws_uri>`。如果使用 `--vm-service-uri`，复制新的 URI 从调试控制台。 |
| `No isolates found` | 应用的主隔离尚未启动 | 稍等重试；自动重试最多 3 次 |
| 自动发现失败于 Android/iOS | 设备无法写入主机的 `.dart_tool` | 在 MCP 配置中使用 `--project-root`，或在主机上运行 `log_pilot_mcp write-uri <ws://...>`。 |
| `LogPilot library not found and no service extensions registered` | 应用依赖于 `log_pilot` 但未调用 `init()`/`configure()` | 在 `pubspec.yaml` 中添加 `log_pilot` 并调用 `LogPilot.init()` 或 `LogPilot.configure()` |
| `Service extensions available: false` | `init()`/`configure()` 尚未运行 | 确保 `init()` 或 `configure()` 在应用启动时运行。 服务器在扩展注册时检测到它们。 |
| “等待 VM 服务 URI ...” 永远 | Flutter 网页（无 `dart:io`）或缺少 `.dart_tool` | 直接传递 `--vm-service-uri`，或在 Windows 上添加 `--project-root` |
| 热重启后工具失败 | 正常重新连接 | 自动恢复；重试工具调用 |
---
## 需求
- Flutter 应用必须依赖 [`log_pilot`](https://pub.dev/packages/log_pilot) 并调用 **`LogPilot.init()` 或 `LogPilot.configure()`** - 两者都注册了 MCP 服务器需要的服务扩展。
- 应用必须在 **调试或配置文件模式** 下运行（发布构建中不可用 VM 服务）。
- Dart SDK >= 3.9.2。
---
## CLI 参考
```
log_pilot_mcp [options]
log_pilot_mcp write-uri <ws://...> [--project-root=PATH]
选项:
--vm-service-uri=URI 直接连接到此 VM 服务 URI。
--vm-service-uri-file=PATH 从文件中读取 URI（监视更改）。
--project-root=PATH Flutter 应用项目根目录的绝对路径。
-h, --help 显示使用信息。
命令:
write-uri <URI> 将 VM 服务 URI 写入
.dart_tool/log_pilot_vm_service_uri。
适用于 Android/iOS，其中应用
无法写入主机文件系统。
环境变量：
LOG_PILOT_VM_SERVICE_URI 当未提供标志时的备用 URI。
```
---
## 贡献
在 [CONTRIBUTING.md](CONTRIBUTING.md) 中查看开发设置、代码风格和提交指南。
## License
[MIT](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器