@mearl/mcp-server 2.0.0

package/README.md

@@ -0,0 +1,116 @@
+# Mearl MCP Server
+
+让 AI 能够与浏览器实时交互的 MCP 服务器。
+
+## 功能
+
+- 📊 **browser_get_requests**: 获取历史请求记录
+- 📊 **browser_get_events**: 获取 RUM/aplus 埋点事件
+- 📝 **browser_get_logs**: 获取控制台日志
+- 🎭 **browser_set_mock**: 动态设置 Mock 数据
+- 🌐 **browser_list**: 统一列出普通浏览器和托管浏览器，返回默认目标、类型及连接状态
+- 🚀 **browser_launch / browser_close**: 启动或关闭独立 Profile 的托管 Chrome
+- 🌐 **browser_page_snapshot**: 首次获取页面结构和可交互元素
+- ⚡ **browser_page_click/type/hover/scroll/press/upload**: 执行页面动作，默认内置观察，返回通知、可交互控件和焦点等高置信度信号
+
+## 浏览器交互工作流
+
+首次进入页面时调用 `browser_page_snapshot` 建立结构基线。后续点击、输入、悬停、滚动、按键和上传直接调用 `browser_page_click/type/hover/scroll/press/upload`，它们默认内置观察，动作与异步同步在一次调用内完成；同页结果读取 `effects.notifications`、`effects.interactives` 和 `effects.focus`，导航结果读取新 URL 和就绪状态。仅在导航后、`fullSnapshotRecommended: true` 或需要视觉判断时重新 snapshot 或截图。
+
+长列表重新感知时优先使用 `browser_page_snapshot(mode: "viewport")`；已知弹层或区域时使用 `rootSelector`；仅需要控件时使用 `mode: "interactive"`，避免整页 AX Tree 占用上下文。页面缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。
+
+页面动作传 `observe: false` 可关闭内置观察仅执行裸动作；不需要在每次动作后固定追加 wait、snapshot 或 screenshot。
+
+## 安装
+
+**方式一：使用 npx（推荐，保持最新）**
+
+```bash
+# 直接运行配置向导，会自动生成 npx 配置
+npx @mearl/mcp-server --configure
+```
+
+**方式二：全局安装（启动更快）**
+
+```bash
+# 全局安装
+npm install -g @mearl/mcp-server
+
+# 运行配置向导
+mearl-mcp-configure
+```
+
+配置向导会自动完成所有设置，支持 **VSCode Copilot**、**Claude Code**、**Cursor**。完成后重启 MCP 客户端即可使用。
+
+## 使用
+
+打开任意淘宝/飞猪页面，在 AI 客户端中发送：
+
+```
+获取最近 5 个请求
+帮我分析购物车相关的接口
+把购物车总价改成 150 元测试一下
+```
+
+## 本地开发
+
+```bash
+cd mcp-server
+npm install
+npm run build
+npm link
+```
+
+运行配置向导，选择使用自定义 Extension ID：
+
+```bash
+mearl-mcp-configure
+# 选择 "使用自定义 Chrome 插件 ID？" -> Yes
+# 输入你的开发版 Extension ID
+```
+
+> 💡 在 `chrome://extensions/` 查看你的 Extension ID
+
+发布新版本：
+
+```bash
+npm version patch
+npm run build
+npm publish --access public
+```
+
+## 卸载
+
+```bash
+# 全局安装的版本
+mearl-mcp-uninstall
+
+# 或使用 npx
+npx @mearl/mcp-server --uninstall
+```
+
+## 故障排查
+
+**配置失败**：检查目录权限和路径是否存在
+
+```bash
+# macOS
+mkdir -p ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts
+```
+
+**"Native host has exited"**：删除配置后重新运行
+
+```bash
+rm ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.alibaba.mearl.mcp.*
+```
+
+**Extension ID 不匹配**：使用 `mearl-mcp-configure` 重新配置
+
+**查看日志**：
+
+- MCP Server: AI 客户端的输出面板
+- Chrome Extension: `chrome://extensions/` → Mearl → background page
+
+## License
+
+ISC

package/dist/configure.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * mearl-mcp-configure - 配置 Native Messaging Host 和 MCP 客户端
+ *
+ * 使用方式：
+ *   mearl-mcp-configure                              # 交互式配置（会询问是否使用自定义 Extension ID）
+ *   mearl-mcp-configure --extension-id=YOUR_ID       # 直接指定自定义 Extension ID
+ *   mearl-mcp-configure --skip-mcp                   # 跳过 MCP 配置
+ *   mearl-mcp-configure --get                        # 查看当前配置
+ */
+export {};

package/dist/configure.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+/**
+ * mearl-mcp-configure - 配置 Native Messaging Host 和 MCP 客户端
+ *
+ * 使用方式：
+ *   mearl-mcp-configure                              # 交互式配置（会询问是否使用自定义 Extension ID）
+ *   mearl-mcp-configure --extension-id=YOUR_ID       # 直接指定自定义 Extension ID
+ *   mearl-mcp-configure --skip-mcp                   # 跳过 MCP 配置
+ *   mearl-mcp-configure --get                        # 查看当前配置
+ */
+import { installNativeHost, resolveHostDir } from '@mearl/native-host';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { HOST_NAME, DEFAULT_EXTENSION_ID } from './constants.js';
+import prompts from 'prompts';
+import { MCP_CLIENTS, getMCPServerConfig, isNpxMode, isClientInstalled, } from './mcp-clients.js';
+// 日志输出
+const log = (...args) => {
+    console.log('[Configure]', ...args);
+};
+// 解析命令行参数
+function parseArgs() {
+    const args = process.argv.slice(2);
+    let extensionId;
+    let skipMcp = false;
+    let get = false;
+    for (const arg of args) {
+        if (arg.startsWith('--extension-id=')) {
+            extensionId = arg.split('=')[1];
+        }
+        else if (arg.startsWith('--id=')) {
+            extensionId = arg.split('=')[1];
+        }
+        else if (arg === '--skip-mcp') {
+            skipMcp = true;
+        }
+        else if (arg === '--get') {
+            get = true;
+        }
+    }
+    return { extensionId, skipMcp, get };
+}
+// 替换或追加 TOML 中的 mcp_servers.xxx 节
+function replaceTOMLSection(content, serverName, newSectionLines) {
+    const header = `[mcp_servers.${serverName}]`;
+    const lines = content.split('\n');
+    let sectionStart = -1;
+    let sectionEnd = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed === header) {
+            sectionStart = i;
+        }
+        else if (sectionStart !== -1 && i > sectionStart && trimmed.startsWith('[')) {
+            sectionEnd = i;
+            break;
+        }
+    }
+    if (sectionStart === -1) {
+        const separator = content.length === 0 || content.endsWith('\n') ? '\n' : '\n\n';
+        return content + separator + newSectionLines.join('\n') + '\n';
+    }
+    const before = lines.slice(0, sectionStart);
+    const after = lines.slice(sectionEnd);
+    return [...before, ...newSectionLines, '', ...after].join('\n');
+}
+// 添加或更新 Codex TOML 配置
+function updateTomlMCPConfig(configPath, useNpx) {
+    try {
+        const dir = dirname(configPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        let content = '';
+        if (existsSync(configPath)) {
+            content = readFileSync(configPath, 'utf-8');
+        }
+        const sectionLines = ['[mcp_servers.mearl]', 'type = "stdio"'];
+        if (useNpx) {
+            sectionLines.push('command = "npx"');
+            sectionLines.push('args = ["-y", "@mearl/mcp-server"]');
+        }
+        else {
+            sectionLines.push('command = "mearl-mcp-server"');
+        }
+        content = replaceTOMLSection(content, 'mearl', sectionLines);
+        writeFileSync(configPath, content);
+        return true;
+    }
+    catch (error) {
+        console.error(`   ❌ 配置失败: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}
+// 添加或更新 MCP 配置
+function updateMCPConfig(configPath, clientConfig, useNpx) {
+    if (clientConfig.useTomlFormat) {
+        return updateTomlMCPConfig(configPath, useNpx);
+    }
+    try {
+        // 确保目录存在
+        const dir = dirname(configPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const useServersFormat = clientConfig.useServersFormat;
+        // 读取或创建配置文件
+        let config;
+        if (useServersFormat) {
+            // VS Code 格式
+            config = { inputs: [], servers: {} };
+            if (existsSync(configPath)) {
+                try {
+                    const content = readFileSync(configPath, 'utf-8');
+                    config = JSON.parse(content);
+                    if (!config.servers) {
+                        config.servers = {};
+                    }
+                    if (!config.inputs) {
+                        config.inputs = [];
+                    }
+                }
+                catch (error) {
+                    console.error(`   ⚠️  配置文件格式错误，将创建新配置: ${error instanceof Error ? error.message : String(error)}`);
+                    config = { inputs: [], servers: {} };
+                }
+            }
+            // 添加或更新 mearl 配置
+            config.servers['mearl'] = getMCPServerConfig(true, useNpx);
+        }
+        else {
+            // Claude Code/Cursor 格式
+            config = { mcpServers: {} };
+            if (existsSync(configPath)) {
+                try {
+                    const content = readFileSync(configPath, 'utf-8');
+                    config = JSON.parse(content);
+                    if (!config.mcpServers) {
+                        config.mcpServers = {};
+                    }
+                }
+                catch (error) {
+                    console.error(`   ⚠️  配置文件格式错误，将创建新配置: ${error instanceof Error ? error.message : String(error)}`);
+                    config = { mcpServers: {} };
+                }
+            }
+            // 添加或更新 mearl 配置
+            config.mcpServers['mearl'] = getMCPServerConfig(false, useNpx);
+        }
+        // 写回文件
+        writeFileSync(configPath, JSON.stringify(config, null, 2));
+        return true;
+    }
+    catch (error) {
+        console.error(`   ❌ 配置失败: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}
+// 查看当前配置
+function showCurrentConfig() {
+    console.log('📋 当前 Native Messaging 配置\n');
+    try {
+        const manifestPath = join(resolveHostDir(), `${HOST_NAME}.json`);
+        if (!existsSync(manifestPath)) {
+            console.log('❌ 未找到配置文件');
+            console.log(`   路径: ${manifestPath}`);
+            console.log('\n💡 运行 "mearl-mcp-configure" 进行配置\n');
+            return;
+        }
+        const content = readFileSync(manifestPath, 'utf-8');
+        const manifest = JSON.parse(content);
+        console.log('✅ 配置文件已存在');
+        console.log(`📍 路径: ${manifestPath}\n`);
+        console.log('📝 配置内容:');
+        console.log(`   Name: ${manifest.name}`);
+        console.log(`   Path: ${manifest.path}`);
+        console.log(`   Type: ${manifest.type}`);
+        if (manifest.allowed_origins && manifest.allowed_origins.length > 0) {
+            console.log('\n🔑 允许的扩展 ID:');
+            manifest.allowed_origins.forEach((origin) => {
+                const match = origin.match(/chrome-extension:\/\/([^/]+)\//);
+                if (match) {
+                    console.log(`   ${match[1]}`);
+                }
+            });
+        }
+        // 检查 wrapper 脚本是否存在
+        if (existsSync(manifest.path)) {
+            console.log('\n✅ Wrapper 脚本存在');
+        }
+        else {
+            console.log('\n⚠️  Wrapper 脚本不存在，需要重新配置');
+        }
+        console.log('');
+    }
+    catch (error) {
+        console.error('❌ 读取配置失败:', error instanceof Error ? error.message : String(error));
+        console.log('\n💡 运行 "mearl-mcp-configure" 重新配置\n');
+    }
+}
+async function main() {
+    const parseResult = parseArgs();
+    const { skipMcp, get } = parseResult;
+    const extensionId = parseResult.extensionId;
+    // 如果是查看配置，显示后退出
+    if (get) {
+        showCurrentConfig();
+        return;
+    }
+    console.log('🔧 Mearl MCP 配置\n');
+    // 检测 npx 模式
+    const useNpx = isNpxMode();
+    if (useNpx) {
+        log('检测到 npx 模式，将生成 npx 配置');
+    }
+    // 配置 Native Messaging Host
+    console.log('\n📦 配置 Chrome Native Messaging Host...');
+    // Install both host manifests so MCP and Skills integrations can be used at
+    // the same time (they share the same Unix socket and handlers).
+    await installNativeHost({
+        mode: 'both',
+        extensionId: extensionId || process.env.MEARL_EXTENSION_ID || DEFAULT_EXTENSION_ID,
+        silent: true,
+    });
+    console.log('✅ 配置完成\n');
+    // 配置 MCP 客户端
+    if (skipMcp) {
+        console.log('跳过 MCP 客户端配置\n');
+    }
+    else {
+        const response = await prompts({
+            type: 'confirm',
+            name: 'setupMcp',
+            message: '配置 MCP 客户端？',
+            initial: true,
+        });
+        if (response.setupMcp) {
+            // 列出全部支持的客户端，已检测到安装的默认预选
+            const allClients = Object.entries(MCP_CLIENTS).map(([key, client]) => ({
+                title: isClientInstalled(key) ? `${client.name} ✓` : client.name,
+                value: key,
+                selected: isClientInstalled(key),
+            }));
+            const detectedNames = allClients.filter(c => c.selected).map(c => c.title);
+            if (detectedNames.length > 0) {
+                console.log(`\n已检测到: ${detectedNames.join(', ')}\n`);
+            }
+            else {
+                console.log('\n未检测到已安装的客户端，可手动选择\n');
+            }
+            const clientResponse = await prompts({
+                type: 'multiselect',
+                name: 'clients',
+                message: '选择要配置的客户端:',
+                choices: allClients,
+                instructions: false,
+                hint: '空格选择，回车确认',
+            });
+            if (clientResponse.clients && clientResponse.clients.length > 0) {
+                console.log('');
+                for (const clientKey of clientResponse.clients) {
+                    const client = MCP_CLIENTS[clientKey];
+                    if (updateMCPConfig(client.configPath, client, useNpx)) {
+                        console.log(`✅ ${client.name}`);
+                    }
+                    else {
+                        console.log(`❌ ${client.name} 配置失败`);
+                    }
+                }
+                console.log('');
+            }
+            else {
+                console.log('已取消\n');
+            }
+        }
+        else {
+            console.log('跳过 MCP 客户端配置\n');
+        }
+    }
+    console.log('\n✅ 全部配置完成！');
+    console.log('\n💡 后续步骤:');
+    console.log('   1. 重启 MCP 客户端');
+    console.log('   2. 打开淘宝/飞猪页面');
+    console.log('   3. 在 AI 中测试: "获取最近 5 个请求"\n');
+}
+main().catch(error => {
+    console.error('Configuration failed:', error);
+    process.exit(1);
+});

package/dist/constants.d.ts

@@ -0,0 +1,10 @@
+/**
+ * MCP Server 共享常量
+ */
+export declare const DEFAULT_MAX_BODY_SIZE = 50000;
+export declare const RESPONSE_SIZE_SMALL: number;
+export declare const RESPONSE_SIZE_MEDIUM: number;
+export declare const RESPONSE_SIZE_LARGE: number;
+export declare const RESPONSE_SIZE_MAX: number;
+export declare const HOST_NAME = "com.alibaba.mearl.mcp";
+export declare const DEFAULT_EXTENSION_ID = "aoehhjnofngknnjefamjbplchbolghkm";

package/dist/constants.js

@@ -0,0 +1,13 @@
+/**
+ * MCP Server 共享常量
+ */
+// 响应体大小限制
+export const DEFAULT_MAX_BODY_SIZE = 50000; // 默认最大 50KB，避免传输过大数据
+// MCP 响应大小阈值
+export const RESPONSE_SIZE_SMALL = 50 * 1024; // 50KB - 小响应，格式化输出
+export const RESPONSE_SIZE_MEDIUM = 200 * 1024; // 200KB - 中等响应，格式化+提示
+export const RESPONSE_SIZE_LARGE = 500 * 1024; // 500KB - 大响应，压缩+提示
+export const RESPONSE_SIZE_MAX = 1024 * 1024; // 1MB - 超大响应，截断+建议
+// Native Messaging Host 配置
+export const HOST_NAME = 'com.alibaba.mearl.mcp';
+export const DEFAULT_EXTENSION_ID = 'aoehhjnofngknnjefamjbplchbolghkm';

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Mearl MCP Server
+ *
+ * 提供 MCP 工具让 AI 能够与浏览器交互:
+ * - browser_get_requests: 获取历史请求
+ * - browser_get_events: 获取 RUM/aplus 埋点事件
+ * - browser_get_logs: 获取控制台日志
+ * - browser_set_mock: 设置 Mock 数据
+ *
+ * 命令行参数:
+ * - configure / --configure: 运行配置向导
+ * - uninstall / --uninstall: 卸载并清理配置
+ * - --extension-id=ID: 指定 Chrome Extension ID
+ */
+export {};