实战MCP协议：从零搭建AI浏览器Agent，手把手落地可直接用的分析MVP

大家平时做前端开发、AI工具对接的时候，有没有遇到过这些痛点：

想让AI帮忙分析网页性能,流程繁琐；AI想直接操控浏览器获取页面信息，没有统一的对接规范，各种适配改到头疼；想做一个轻量化的浏览器智能助手，既要对接大模型，又要做插件、写服务，不知道从何下手。

最近MCP协议彻底火了，被誉为AI世界的「USB-C统一接口」，完美解决AI与外部工具对接混乱的问题。本着实战落地的原则，我基于MCP协议+AI Agent架构，从零开发了mcp-browser-analyzer——一款可直接运行的浏览器智能分析工具MVP，全程踩坑+实战思路全分享，文末附开源地址，新手也能跟着跑起来！

一、先搞懂：MCP协议到底是什么？

很多人看到「协议」就头大，其实完全不用怕，用一句话就能讲透：

MCP（模型上下文协议），就是AI连接外部工具的万能翻译官。

以前AI想调用浏览器、数据库、本地文件，每个工具都要写一套专属对接代码，就像以前的手机，每个品牌一个充电器，互不通用；而MCP协议就是统一的USB-C接口，只要遵循这套规范，AI就能无缝对接各类工具，不用重复写适配逻辑，开发AI工具的效率直接拉满。

放到这个项目里，MCP协议就是核心桥梁：一边连接AI Agent，一边对接Chrome浏览器插件，让AI能直接操控浏览器、获取页面数据，实现智能分析、指令交互，全程不用手动介入。

基于MCP协议的过程

二、为什么要做这个浏览器AI Agent？

市面上的浏览器性能工具、AI插件大多是单一功能：要么只能做性能分析，要么只能简单对话，而且AI对接逻辑混乱，很难二次开发。

我做mcp-browser-analyzer的初衷，就是打造一个轻量化、可扩展、易落地的AI浏览器助手MVP：

• 基于MCP标准协议，后续可无缝对接各类大模型，不用改底层逻辑
• 不止是前端性能分析（Lighthouse、页面日志），还自带AI Agent基础对话、指令解析能力
• 采用monorepo架构，插件、服务模块分离，新手也能二次开发
• 全程本地运行，开箱即用，适合学习MCP协议、AI Agent开发、Chrome插件实战

三、实战开发：从零搭建MCP浏览器Agent全流程

整个项目我采用循序渐进的开发思路，先搭底层架构，再补核心功能，新手完全可以复刻这个开发流程，一步步落地自己的AI工具MVP。

1. 前期准备：环境与架构选型

考虑到轻量化与开发效率，技术栈全部选用主流易上手的方案，降低学习成本：

• 包管理：pnpm+monorepo，多模块统一管理，拆分插件、服务逻辑
• Chrome插件：Vue3+Vite+MV3，适配最新Chrome扩展规范
• MCP服务：Node.js，原生实现MCP协议通信，不依赖复杂框架
• AI Agent：独立agent-server服务，实现对话交互、指令解析
• 通信：WebSocket，保证插件与服务实时互通

环境要求也很简单：Node.js≥20、pnpm≥9，常规前端开发环境即可。

2. 核心架构搭建

清晰的三层结构

项目分为三大核心模块，各司其职，这也是MCP工具的经典架构：

• chrome-extension：Chrome浏览器插件，负责页面截图、性能采集、日志获取、DOM信息读取
• server：MCP协议服务端，实现标准化协议通信，打通AI与插件的数据通道
• agent-server：AI Agent核心，实现基础对话、指令解析、数据归纳，让工具拥有智能交互能力

**开发初期我踩过一个坑：**最开始把MCP逻辑和Agent逻辑写在一起，后期扩展极不方便，后来重构拆分了agent-server，模块化之后，后续加功能、对接大模型都变得特别简单。

3. 核心功能落地

作为MVP版本，核心落地的关键的是「工具封装（tools）+ 指令处理（handler）」——这是AI Agent能调用浏览器功能、MCP协议能正常通信的核心，也是新手最容易困惑的部分。下面结合项目实际代码逻辑，手把手讲清楚怎么构造tools和handler，复制就能复用。

（1）构造Tools：浏览器功能的“工具封装库”

Tools的核心作用：把Chrome浏览器的原生能力（截图、日志、性能分析）封装成标准化接口，供handler调用，同时适配MCP协议的参数格式，避免AI调用时出现适配问题。

结合项目的chrome-extension和server模块，我们分2类封装tools（简化核心代码，贴合MVP落地）：

// 1. 浏览器端（chrome-extension/src/tools/browserTools.js）
// 封装浏览器原生功能，供插件与服务通信时调用
const browserTools = {

  // 性能工具：调用Lighthouse获取性能数据（简化版）
  async getPerformanceData() {
    const lighthouse = await import('lighthouse');
    const result = await lighthouse(chrome.tabs.getCurrent().url, { output: 'json' });
    return { code: 200, data: result.lhr.score };
  }
};

// 暴露工具接口，供插件通信模块调用
export default browserTools;

// 2. 服务端（server/src/tools/mcpTools.js）
// 封装MCP协议相关工具，打通Agent与浏览器插件的通信
const mcpTools = {
  // 协议适配工具：将AI指令转换成浏览器能识别的格式
  adaptMcpCommand(command) {
    // MCP协议标准化格式：{ action: "工具名", params: "参数" }
    const commandMap = {
      "截图": "captureScreenshot",
      "获取日志": "getConsoleLogs",
      "分析性能": "getPerformanceData"
    };
    return {
      action: commandMap[command] || command,
      params: {}
    };
  },
  // 数据格式化工具：将浏览器返回结果转换成MCP协议格式，供AI Agent读取
  formatMcpResponse(data) {
    return {
      version: "1.0", // MCP协议版本
      status: "success",
      data: data
    };
  }
};

export default mcpTools;

核心要点：MVP阶段的tools不用复杂，重点是「单一功能封装+统一返回格式」，确保后续handler调用时不用重复处理适配逻辑，也为后续扩展新工具（比如DOM信息采集）预留接口。

（2）构造Handler：指令与工具的“桥梁处理器”

Handler的核心作用：接收AI Agent的指令（通过MCP协议）、调用对应tools、处理异常、返回结果——相当于“AI指令的翻译官+工具调度员”，是MVP落地的核心枢纽。

我们在agent-server模块中构造handler，核心分为「指令解析handler」和「工具调用handler」，简化代码如下：

// agent-server/src/handlers/commandHandler.js
import browserTools from '../../chrome-extension/src/tools/browserTools.js';
import mcpTools from '../../server/src/tools/mcpTools.js';

// 1. 指令解析Handler：解析AI发送的自然语言指令
export const commandParseHandler = async (agentCommand) => {
  try {
    // 简化版解析：实际可对接大模型，这里先实现基础指令匹配
    const mcpCommand = mcpTools.adaptMcpCommand(agentCommand);
    // 调用工具调用Handler，执行对应操作
    const toolResult = await toolCallHandler(mcpCommand.action);
    // 格式化结果，返回给AI Agent（符合MCP协议）
    return mcpTools.formatMcpResponse(toolResult);
  } catch (error) {
    return { status: "error", message: "指令解析失败：" + error.message };
  }
};

// 2. 工具调用Handler：根据解析后的指令，调用对应tools
export const toolCallHandler = async (action) => {
  // 匹配tools中的方法，执行对应浏览器操作
  switch (action) {
    case "captureScreenshot":
      return await browserTools.captureScreenshot();
    case "getConsoleLogs":
      return await browserTools.getConsoleLogs();
    case "getPerformanceData":
      return await browserTools.getPerformanceData();
    default:
      throw new Error(`未找到对应工具：${action}`);
  }
};

（3）Agent核心落地：串联指令、Handler与Tools

很多人误以为Agent是“高大上的黑盒”，其实MVP阶段的Agent核心很简单——接收指令、调度Handler、返回结果，我们用一个简单的类封装Agent，实现基础智能交互能力，贴合项目的agent-server模块实际开发：

// agent-server/src/agent/BaseAgent.js
import { commandParseHandler } from '../handlers/commandHandler.js';

// 基础Agent类：MVP阶段核心实现，后续可扩展对接大模型
class BaseAgent {
  constructor() {
    // 初始化MCP通信连接（对接server模块的MCP服务）
    this.mcpClient = this.initMcpClient();
    // 存储历史交互记录，实现基础对话上下文
    this.history = [];
  }

  // 初始化MCP客户端，与MCP服务建立WebSocket连接
  initMcpClient() {
    const WebSocket = require('ws');
    const client = new WebSocket('ws://localhost:3000/mcp'); // 对应server服务地址
    client.on('open', () => {
      console.log('MCP客户端连接成功，Agent可接收指令');
    });
    return client;
  }

  // 核心方法：接收用户/AI指令，执行并返回结果
  async run(command) {
    try {
      // 记录历史指令，用于基础上下文交互
      this.history.push({ command, time: new Date().toLocaleString() });
      // 调用handler解析并执行指令
      const result = await commandParseHandler(command);
      // 通过MCP客户端，将结果返回给调用方（AI或前端）
      this.mcpClient.send(JSON.stringify(result));
      return result;
    } catch (error) {
      console.error('Agent执行失败：', error);
      return { status: "error", message: error.message };
    }
  }

  // 扩展方法：获取历史交互记录（后续可对接大模型，实现上下文对话）
  getHistory() {
    return this.history;
  }
}

// 实例化Agent，供外部调用
const agent = new BaseAgent();
// 示例：执行指令（实际可通过前端、AI调用）
agent.run("分析当前页面性能");

export default agent;

Agent落地要点：

• MVP阶段不追求复杂大模型对接，先实现「指令调度闭环」，后续可直接在BaseAgent类中新增大模型调用方法（如对接ChatGPT、通义千问），无需改动核心架构
• 与MCP服务通过WebSocket通信，确保指令和结果实时传输，这也是项目中server模块与agent-server模块的核心通信方式
• 封装成类的形式，便于后续扩展（如新增Agent记忆能力、多指令并行处理），贴合项目“可扩展”的设计初衷

作为MVP版本，我优先实现了刚需核心功能，兼顾性能分析与AI交互：

• ✅ MCP协议标准化通信：AI与浏览器插件无缝对接，无需手动适配
• × 前端性能分析：集成Lighthouse，自动生成性能报告
• ✅ AI Agent基础能力：简单对话、指令解析、数据归纳，不止是工具，更是智能助手

这里重点说下Agent能力：很多人觉得AI Agent很高深，其实MVP阶段不用追求复杂，先实现「指令接收+逻辑处理+结果返回」即可。这个项目里，Agent可以听懂简单的浏览器操作指令，也能做基础问答，后续再接入大模型，就能直接升级成更智能的浏览器助手。

我们在agent-server模块中构造handler，核心分为「指令解析handler」和「工具调用handler」，简化代码如下：

结合代码，以下是AI Agent的核心工作流程图（指令从接收至执行的完整闭环）：

// agent-server/src/handlers/commandHandler.js
import browserTools from '../../chrome-extension/src/tools/browserTools.js';
import mcpTools from '../../server/src/tools/mcpTools.js';

// 1. 指令解析Handler：解析AI发送的自然语言指令
export const commandParseHandler = async (agentCommand) => {
  try {
    // 简化版解析：实际可对接大模型，这里先实现基础指令匹配
    const mcpCommand = mcpTools.adaptMcpCommand(agentCommand);
    // 调用工具调用Handler，执行对应操作
    const toolResult = await toolCallHandler(mcpCommand.action);
    // 格式化结果，返回给AI Agent（符合MCP协议）
    return mcpTools.formatMcpResponse(toolResult);
  } catch (error) {
    return { status: "error", message: "指令解析失败：" + error.message };
  }
};

// 2. 工具调用Handler：根据解析后的指令，调用对应tools
export const toolCallHandler = async (action) => {
  // 匹配tools中的方法，执行对应浏览器操作
  switch (action) {
    case "captureScreenshot":
      return await browserTools.captureScreenshot();
    case "getConsoleLogs":
      return await browserTools.getConsoleLogs();
    case "getPerformanceData":
      return await browserTools.getPerformanceData();
    default:
      throw new Error(`未找到对应工具：${action}`);
  }
};

核心要点：MVP阶段的handler不用做复杂的指令识别（后续可对接大模型优化），重点是「打通“指令-工具-结果”的闭环」，确保AI发送的简单指令（比如“截图当前页面”）能被正确解析、执行，并返回标准化结果。

四、工程化落地：让MVP可维护、可扩展

很多新手做MVP只关注“能跑起来”，却忽略了工程化，导致后续迭代、多人协作时一团乱麻。这个项目从初始化就融入工程化实践，结合pnpm monorepo、代码规范、CI/CD等，既保证了MVP的开发效率，也为后续扩展埋下伏笔，全程贴合项目实际配置。

1. 核心工程化：pnpm monorepo架构落地

项目采用pnpm workspace实现monorepo架构，这也是现代前端工程化的主流方案，核心解决“多模块统一管理”的问题——项目中的chrome-extension（插件）、server（MCP服务）、agent-server（Agent服务）是独立子项目，却能共享依赖、统一配置，具体落地如下：

// 项目根目录 pnpm-workspace.yaml（项目实际配置）
packages:
  - 'chrome-extension' # Chrome插件子项目
  - 'server' # MCP服务子项目
  - 'agent-server' # AI Agent子项目
  - 'docs' # 文档子项目

// 根目录package.json 统一脚本配置
{
  "scripts": {
    "server": "pnpm --filter server start", // 启动MCP服务
    "extension": "pnpm --filter chrome-extension dev", // 启动插件开发
    "agent": "pnpm --filter agent-server start", // 启动Agent服务
    "build": "pnpm --filter '*' build", // 构建所有子项目
    "lint": "eslint .", // 统一代码检查
    "format": "prettier --write ." // 统一代码格式化
  }
}

工程化优势（项目实战踩坑总结）：

• 避免重复安装依赖：三个子项目共享pnpm依赖池，减少磁盘占用，同时统一依赖版本，避免“版本不一致导致的报错”
• 统一脚本命令：不用分别进入每个子项目执行命令，根目录一键启动、构建所有服务，提升开发效率
• 模块解耦：插件、服务、Agent分离，后续修改某一个模块（如优化Agent逻辑），不会影响其他模块，符合“可扩展”设计

2. 代码规范：确保多人协作一致性

项目引入ESLint + Prettier + husky + lint-staged，从代码格式、语法规范、提交规范三个层面，保证代码质量，贴合项目实际配置：

• ESLint + Prettier：统一代码风格（如缩进、引号、分号），避免“每个人写的代码都不一样”，项目根目录的.eslintrc.js和.prettierrc.json已配置好基础规则，克隆项目即可使用
• husky + lint-staged：Git提交钩子，提交代码前自动检查代码规范，不符合规范的代码无法提交，避免“脏代码”进入仓库（项目中已配置.husky目录，对应pre-commit钩子）
• 提交规范：遵循“feat/fix/docs/chore”等提交前缀（如项目提交记录中的“feat(agent-server): 添加新的agent-server服务”），便于后续代码追溯、版本管理

3. CI/CD：自动化构建与部署（项目实战配置）

项目在.github/workflows目录下配置了CI/CD流程（对应项目中的ci.yml文件），核心实现“代码提交后自动检查、构建”，避免手动操作出错，具体流程：

1. 开发者推送代码到develop/main分支
2. GitHub Actions自动触发CI流程，安装Node.js 24（项目指定版本）、pnpm依赖
3. 自动执行pnpm lint（代码检查）、pnpm build（构建所有子项目）
4. 构建成功后，可后续扩展自动部署（如部署MCP服务、打包Chrome插件）

工程化总结：MVP阶段的工程化不用复杂，核心是“统一配置、模块解耦、自动化”，这个项目的工程化实践，既适配了当前MVP的开发需求，也为后续多人协作、功能迭代（如开发计划中的Lighthouse性能分析完善）提供了支撑，新手可以直接复用项目的工程化配置，快速搭建自己的AI工具项目。

五、项目结构可视化

mcp-browser-analyzer/
├── .github/
│ └── workflows/
│ └── ci.yml # CI/CD 配置
├── .husky/ # Git Hooks
├── .trae/
│ └── rules/
│ └── project_rules.md # 项目规则
├── chrome-extension/ # Chrome 插件（子项目）
├── server/ # MCP 服务（子项目）
├── agent-server/ # AI Agent服务（子项目）
├── .eslintrc.js # 代码规范配置
├── .prettierrc.json # 格式化配置
├── package.json # 根目录依赖配置
├── pnpm-workspace.yaml # monorepo配置
└── README.md # 项目说明文档

这是目前还在开发的部分,以后可以基于这里进行拓展

六、极速上手：5分钟跑起整个项目

实战型工具，上手一定要简单，我整理了极简启动步骤，克隆代码直接运行：

# 1. 克隆项目（文末附开源地址）
# 2. 安装依赖
pnpm install

# 3. 启动MCP服务
pnpm server

# 4. 启动Chrome插件开发模式
pnpm extension

# 5. Chrome开启开发者模式，加载dist目录插件即可

全程不用复杂配置，本地一键运行，既能用来学习MCP协议，也能直接当做前端性能分析、浏览器智能助手使用。

七、写在最后：开源共建+后续规划

这款mcp-browser-analyzer目前是MVP开发版本，核心架构已经全部落地，既能作为MCP协议、AI Agent的学习项目，也能在此基础上二次开发，打造属于自己的浏览器AI工具。

后续我会继续完善功能：优化Agent对话能力、完善MCP协议适配、新增更多浏览器分析能力，也欢迎大家一起共建。

开源地址（欢迎Star、Fork）

gitee.com/Singularity…

适合人群：

• 想学习MCP协议实战落地的开发者
• 想从零搭建AI Agent的前端/后端新手
• 需要轻量化浏览器性能分析工具的工程师
• 想学习Chrome插件+Monorepo架构开发的同学

如果觉得这个实战项目对你有帮助，麻烦点个Star支持一下，后续会持续更新开发教程、功能迭代，带你彻底吃透MCP协议+AI Agent落地！