MCP实战学习笔记（基于高德地图MCP代码案例）

UIUV
4 阅读26分钟

MCP实战学习笔记（基于高德地图MCP代码案例）

一、前言：认识MCP及其学习意义

在人工智能与大模型应用快速发展的当下，模型与外部工具的联动能力成为提升应用价值的核心竞争力。Model Context Protocol（简称MCP），即模型上下文协议，作为连接大语言模型与各类外部工具、服务的桥梁，解决了大模型“能思考但不会操作”的痛点，让模型能够通过标准化协议调用外部资源，实现更复杂的任务落地。

本次学习以高德地图MCP实战代码为核心，结合LangChain框架、OpenAI大模型、文件系统、浏览器工具等技术，完整拆解MCP从环境搭建、客户端初始化、工具调用到任务执行的全流程。通过对代码的逐行解析、功能拆解、实战演练及问题排查，深入理解MCP的核心原理与应用逻辑，掌握基于MCP协议开发多工具联动AI应用的方法，为后续构建更复杂的AI Agent奠定基础。

本笔记适用于具备一定JavaScript/Node.js基础、了解大语言模型基本概念，且希望学习MCP协议应用、LangChain框架使用的开发者。笔记总字数将超过4000字，涵盖核心概念、代码解析、实战细节、常见问题及拓展延伸，力求做到理论与实战结合，让学习者能够跟着笔记一步步理解代码逻辑、复现实战效果，并掌握背后的技术原理。

二、核心概念铺垫：MCP、LangChain与相关工具解析

2.1 MCP（Model Context Protocol）核心定义

MCP全称Model Context Protocol，译为模型上下文协议，是一套用于规范大语言模型与外部工具、服务之间通信的标准化协议。其核心目标是解决不同工具与模型之间的兼容性问题，通过统一的接口规范，让模型能够快速调用各类外部工具，同时让工具能够准确接收模型的指令、返回符合模型需求的结果。

简单来说，MCP就像是“翻译官”，一边对接大模型的自然语言指令，一边将指令转化为外部工具能够识别的格式，同时将工具的执行结果转化为模型能够理解的上下文信息，实现模型与工具的双向联动。

MCP的核心优势体现在三个方面：一是标准化，统一的接口规范让不同工具无需单独适配模型，降低开发成本；二是可扩展性，支持灵活添加各类工具（如地图服务、文件系统、浏览器、API接口等），轻松扩展AI应用的功能边界；三是易用性，结合LangChain等框架，开发者可以快速搭建MCP客户端，实现工具调用的自动化。

2.2 LangChain框架核心作用

LangChain是一个用于构建大语言模型应用的开发框架，其核心价值在于简化大模型与外部工具的联动开发流程，提供了一系列开箱即用的组件（如模型适配器、工具调用模块、对话管理等），让开发者无需从零构建工具调用逻辑。

在本次实战代码中，LangChain主要发挥了两个核心作用：一是通过@langchain/mcp-adapters提供的MultiServerMCPClient类，快速搭建MCP客户端，实现对多个外部工具的统一管理；二是通过@langchain/openai提供的ChatOpenAI类，实现与OpenAI大模型的对接，同时借助bindTools方法将MCP工具绑定到模型上，让模型能够自动判断是否需要调用工具、调用哪个工具。

此外，LangChain的core/messages模块提供了HumanMessage、SystemMessage、ToolMessage等消息类型，用于规范模型与用户、工具之间的消息传递格式，确保对话上下文的连贯性和准确性。

2.3 本次实战涉及的核心工具

结合参考资料中的代码，本次实战共涉及4类核心工具/技术，分别是：

  1. OpenAI大模型：作为核心的“思考主体”，负责接收用户查询、分析需求、判断是否需要调用工具，并根据工具返回结果生成最终回复。
  2. 高德地图MCP服务：提供地图相关功能（如酒店查询、路线规划等），通过HTTP接口与MCP客户端通信，接收模型指令并返回相关数据。
  3. 文件系统工具：基于MCP官网提供的filesystem工具，用于实现文件的读写、保存等操作，本次实战中用于将路线规划结果保存为MD文件。
  4. Chrome DevTools工具：通过MCP协议调用浏览器，实现浏览器的启动、标签页打开、页面标题修改等操作，本次实战中用于展示酒店图片。

此外，代码中还使用了dotenv用于环境变量管理、chalk用于控制台日志着色，提升开发体验和日志可读性。

三、环境搭建：实战前的准备工作

3.1 开发环境要求

本次实战基于Node.js环境开发，因此需要提前安装相关依赖和工具，具体要求如下：

  1. Node.js：版本建议16.x及以上（确保支持ES6+语法和模块导入方式），可通过官网下载安装，安装完成后通过node -v命令验证版本。
  2. npm/yarn：包管理工具，Node.js安装完成后会自动附带npm，也可自行安装yarn（推荐使用npm，与代码中的npx命令兼容）。
  3. 代码编辑器：推荐使用VS Code，支持JavaScript语法高亮、代码提示等功能，提升开发效率。
  4. 相关API密钥：需要提前获取OpenAI API密钥、高德地图API密钥，用于对接对应的服务。

3.2 依赖安装步骤

参考资料中的代码依赖多个第三方包，需通过npm安装，具体步骤如下：

  1. 创建项目目录：新建一个文件夹（如mcp_in_action），作为项目根目录，打开终端并进入该目录。

  2. 初始化项目：执行npm init -y命令，生成package.json文件，用于管理项目依赖。

  3. 安装核心依赖：依次执行以下命令，安装所需的第三方包：

    1. npm install dotenv：用于加载环境变量，避免将API密钥等敏感信息硬编码到代码中。
    2. npm install @langchain/mcp-adapters：LangChain提供的MCP适配器，用于搭建MCP客户端。
    3. npm install @langchain/openai：LangChain提供的OpenAI适配器，用于对接OpenAI大模型。
    4. npm install chalk：用于控制台日志着色，让日志更易读。
    5. npm install @langchain/core：LangChain核心模块，提供消息类型、工具接口等基础功能。

  4. 安装工具依赖：代码中使用了filesystem和chrome-devtools两个MCP工具，需通过npx临时安装（无需全局安装），具体命令会在工具调用时自动执行，无需手动提前安装。

3.3 环境变量配置

为了避免敏感信息（如API密钥）硬编码到代码中，本次实战使用dotenv管理环境变量，具体配置步骤如下：

  1. 在项目根目录下创建.env文件，用于存储环境变量。
  2. 在.env文件中添加以下内容，替换为自己的API密钥和相关配置： # OpenAI相关配置 `` MODEL_NAME=gpt-3.5-turbo # 模型名称，可根据需求替换为gpt-4等 `` OPENAI_API_KEY=your_openai_api_key # 你的OpenAI API密钥 `` OPENAI_BASE_URL=https://api.openai.com/v1 # OpenAI API基础地址，国内用户可替换为代理地址 ```` # 高德地图相关配置 ``AMAP_MAPS_API_KEY=your_amap_api_key # 你的高德地图API密钥
  3. 注意事项：.env文件需添加到.gitignore中，避免提交到代码仓库，防止敏感信息泄露；确保API密钥有效，若密钥过期或无效，会导致接口调用失败。

四、代码逐行解析：从初始化到任务执行

参考资料中的代码完整实现了“调用MCP工具完成北京南站附近酒店查询、浏览器展示酒店图片”的功能，整体流程分为：环境变量加载、模型初始化、MCP客户端初始化、工具绑定、Agent任务执行、客户端关闭6个步骤。下面逐行解析代码，深入理解每个环节的作用和逻辑。

4.1 环境变量加载与模块导入

import 'dotenv/config';
import { MultiServerMCPClient } from '@langchain/mcp-adapters';
import { ChatOpenAI } from '@langchain/openai';
import chalk from 'chalk';
import {
    HumanMessage,
    SystemMessage,
    ToolMessage,
} from '@langchain/core/messages';

这部分代码的核心作用是加载环境变量和导入所需的模块，具体解析如下：

  1. import 'dotenv/config'：加载.env文件中的环境变量，让代码中可以通过process.env访问到配置的API密钥、模型名称等信息。如果不加载该模块，process.env将无法获取到.env文件中的变量，会导致API调用失败。

  2. import { MultiServerMCPClient } from '@langchain/mcp-adapters'：导入LangChain的MCP多服务器客户端类，用于创建MCP客户端，管理多个外部工具（如高德地图、文件系统、浏览器）。

  3. import { ChatOpenAI } from '@langchain/openai'：导入LangChain的OpenAI聊天模型类，用于对接OpenAI大模型，发送用户查询并获取模型响应。

  4. import chalk from 'chalk'：导入chalk模块，用于给控制台日志添加颜色，提升日志可读性（如绿色背景的“正在等待AI思考”、蓝色背景的“工具调用信息”）。

  5. import { HumanMessage, SystemMessage, ToolMessage } from '@langchain/core/messages'：导入LangChain核心消息类型，用于规范消息传递格式：

    1. HumanMessage：用户发送的查询消息，是Agent任务的输入。
    2. SystemMessage：系统提示消息，用于引导模型的行为（本次代码中未使用，但可用于定义模型的角色、规则等）。
    3. ToolMessage：工具执行结果消息，用于将工具的执行结果返回给模型，作为模型后续思考的上下文。

4.2 OpenAI大模型初始化

const model = new ChatOpenAI({
    modelName: process.env.MODEL_NAME,
    apiKey: process.env.OPENAI_API_KEY,
    configuration: {
        baseURL: process.env.OPENAI_BASE_URL,
    }
});

这部分代码用于初始化OpenAI大模型实例，配置模型的相关参数，具体解析如下：

  1. new ChatOpenAI()：创建ChatOpenAI实例，该实例是LangChain封装的OpenAI聊天模型接口，简化了与OpenAI API的对接流程。
  2. modelName: process.env.MODEL_NAME：指定使用的OpenAI模型名称，从.env文件中读取，默认使用gpt-3.5-turbo（性价比高，适合日常开发测试），也可替换为gpt-4（性能更强，但成本更高）。
  3. apiKey: process.env.OPENAI_API_KEY：传入OpenAI API密钥，从.env文件中读取，用于身份验证，确保API调用的合法性。
  4. configuration: { baseURL: process.env.OPENAI_BASE_URL }：配置OpenAI API的基础地址，默认使用官方地址api.openai.com/v1，国内用户若无法直…

注意事项：初始化模型时，需确保API密钥有效、baseURL可访问，否则会抛出身份验证失败或网络错误。如果使用的是其他大模型（如百度文心一言、阿里通义千问），可替换为LangChain对应的模型适配器（如ChatErnie、ChatTongyi），配置方式类似。

4.3 MCP客户端初始化与工具配置

const mcpClient = new MultiServerMCPClient({
    mcpServers: {
        "amap-maps-streamableHTTP": {
            url: `https://mcp.amap.com/mcp?key=${process.env.AMAP_MAPS_API_KEY}`
        },
        // 来自mcp 官网的 filesystem 工具
        "filesystem":{
            "command": "npx",
            "args": [
                "-y",
                "@modelcontextprotocol/server-filesystem",
                "D:/workspace/lesson_zp/ai/agent/mcp_in_action/wendang"
            ]
        },
        "chrome-devtools": {
            "command": "npx",
            "args": [
                "-y",
                "chrome-devtools-mcp@latest",
            ]
        }
    }
})

这部分代码是本次实战的核心，用于创建MCP多服务器客户端，并配置需要调用的外部工具，具体解析如下：

  1. new MultiServerMCPClient()：创建MCP多服务器客户端实例，该实例用于管理多个MCP工具，提供工具的加载、调用、关闭等功能。

  2. mcpServers参数：一个对象，用于配置需要接入的MCP工具，每个属性对应一个工具，属性名是工具的唯一标识（可自定义），属性值是工具的配置信息。本次代码中配置了3个工具：amap-maps-streamableHTTP（高德地图）、filesystem（文件系统）、chrome-devtools（浏览器）。

  3. 高德地图工具（amap-maps-streamableHTTP）配置：

    1. url：高德地图MCP服务的接口地址，格式为mcp.amap.com/mcp?key=API…
    2. 该工具的作用：通过HTTP接口为模型提供地图相关服务，如酒店查询、路线规划、POI搜索等，模型可通过调用该工具获取北京南站附近的酒店信息。

  4. 文件系统工具（filesystem）配置：

    1. command: "npx"：指定启动该工具的命令，npx是npm的临时执行工具，用于无需全局安装即可执行包。

    2. args：命令参数，依次为：

      • -y：自动确认安装，避免执行npx时出现交互提示。
      • @modelcontextprotocol/server-filesystem：MCP官网提供的文件系统工具包名称，npx会自动下载并执行该包。
      • D:/workspace/lesson_zp/ai/agent/mcp_in_action/wendang：文件操作的根目录，工具将在该目录下进行文件的读写、保存等操作（需确保该目录存在，否则会出现文件操作失败）。

    3. 该工具的作用：为模型提供文件操作能力，如创建MD文件、写入路线规划结果等。

  5. Chrome DevTools工具（chrome-devtools）配置：

    1. command: "npx"：同样使用npx临时执行工具包。

    2. args：命令参数，依次为：

      • -y：自动确认安装。
      • chrome-devtools-mcp@latest：最新版本的Chrome DevTools MCP工具包，用于通过MCP协议调用浏览器。

    3. 该工具的作用：为模型提供浏览器操作能力，如打开新标签页、访问酒店图片URL、修改页面标题等。

注意事项：工具配置时，需确保工具包名称正确、参数格式无误；文件系统工具的根目录需提前创建，否则会导致文件保存失败；Chrome DevTools工具需要确保本地安装了Chrome浏览器，否则无法启动浏览器。

4.4 工具加载与模型绑定

const tools = await mcpClient.getTools();
const modelWithTools = model.bindTools(tools);

这部分代码用于加载MCP工具，并将工具绑定到OpenAI模型上，让模型能够自动调用工具，具体解析如下：

  1. const tools = await mcpClient.getTools()：调用MCP客户端的getTools()方法，加载配置的所有MCP工具，返回一个工具数组。该方法是异步的，因此需要使用await关键字等待加载完成。加载完成后，tools数组中包含了3个工具实例，分别对应配置的高德地图、文件系统、Chrome DevTools工具。
  2. const modelWithTools = model.bindTools(tools)：调用模型的bindTools()方法，将加载的工具绑定到模型上。绑定后，模型会自动分析用户查询，判断是否需要调用工具：如果用户查询可以直接通过模型回答（如简单的常识问题），则不调用工具；如果需要外部数据或操作（如查询酒店、打开浏览器），则自动选择对应的工具进行调用。

关键说明：bindTools()方法是LangChain提供的核心功能，其内部实现了工具的匹配逻辑——模型会根据用户查询的语义，从绑定的工具中选择最适合的工具，生成工具调用指令（包含工具名称、参数等信息），后续代码会根据该指令执行工具调用。

4.5 Agent任务执行函数（核心逻辑）

async function runAgentWithTools(query, maxIterations = 30) {
    const messages = [
        new HumanMessage(query)
    ];
    for (let i = 0; i < maxIterations; i++) {
        console.log(chalk.bgGreen('⏳正在等待AI思考...'));
        const response = await modelWithTools.invoke(messages);
        messages.push(response);
        if (!response.tool_calls || response.tool_calls.length === 0) {
            console.log(`\n AI 最终回复：\n ${response.content}\n`);
            return response.content;
        }
        console.log(chalk.bgBlue(`🔍 检测到 ${response.tool_calls.length} 个工具调用`));
        console.log(chalk.bgBlue(`🔍 工具调用: ${response.tool_calls.map(t => t.name).join(', ')}`));
        for (const toolCall of response.tool_calls) {
            const foundTool = tools.find(t => t.name === toolCall.name);
            if (foundTool) {
                const toolResult = await foundTool.invoke(toolCall.args);
                let contentStr;
                if (typeof toolResult === 'string') {
                    contentStr = toolResult;
                } else if(toolResult && toolResult.text) {
                    contentStr = toolResult.text;
                }
                messages.push(new ToolMessage({
                    content: contentStr,
                    tool_call_id: toolCall.id
                }));
            }
        }
    }
    return messages[messages.length - 1].content;
}

这部分代码是整个实战的核心逻辑，定义了一个异步函数runAgentWithTools，用于执行AI Agent的任务流程——接收用户查询、让模型思考、调用工具、处理工具结果，直到生成最终回复。函数的参数的解析和流程拆解如下：

4.5.1 函数参数

  1. query：用户的查询内容，即需要Agent完成的任务（如“北京南站附近的3个酒店，拿到酒店图片，展开浏览器，展示每个酒店的图片，每个tab一个url展示，并且把那个页面标题改为酒店名称”）。
  2. maxIterations：最大迭代次数，默认值为30，用于防止模型陷入无限循环（如工具调用失败后反复调用）。如果迭代次数达到最大值仍未生成最终回复，则返回最后一条消息的内容。

4.5.2 函数核心流程（循环执行）

函数内部通过for循环实现Agent的迭代思考和工具调用，具体流程分为6个步骤：

  1. 初始化消息队列：const messages = [new HumanMessage(query)]; 创建一个消息数组，初始值为用户的查询消息（HumanMessage），用于存储整个对话过程中的所有消息（用户查询、模型响应、工具结果），确保模型能够获取完整的上下文。

  2. AI思考阶段：console.log(chalk.bgGreen('⏳正在等待AI思考...')); 打印日志，提示用户模型正在思考；const response = await modelWithTools.invoke(messages); 调用绑定了工具的模型，传入当前的消息队列，获取模型的响应。模型会分析消息队列中的上下文（用户查询、之前的工具结果等），判断是否需要调用工具。

  3. 添加模型响应到消息队列：messages.push(response); 将模型的响应（无论是工具调用指令还是最终回复）添加到消息队列中，作为后续思考的上下文。

  4. 判断是否需要调用工具：if (!response.tool_calls || response.tool_calls.length === 0) { ... } 。模型的响应中会包含tool_calls字段，如果该字段为空或长度为0，说明模型不需要调用工具，可以直接生成最终回复，此时打印最终回复并返回。如果tool_calls字段不为空，说明模型需要调用工具，进入工具调用阶段。

  5. 工具调用阶段：

    1. 打印工具调用信息：console.log(chalk.bgBlue(...)) 打印检测到的工具调用数量和工具名称，方便开发者调试。
    2. 循环调用每个工具：for (const toolCall of response.tool_calls) { ... } 遍历模型返回的所有工具调用指令，每个toolCall包含工具名称（name）、参数（args）、工具调用ID（id）。
    3. 匹配工具：const foundTool = tools.find(t => t.name === toolCall.name); 根据工具名称，从加载的工具数组中找到对应的工具实例。如果找不到工具（可能是工具配置错误或工具名称不匹配），则跳过该工具调用。
    4. 执行工具调用：const toolResult = await foundTool.invoke(toolCall.args); 调用工具的invoke方法，传入工具调用参数，获取工具的执行结果（异步操作，需用await等待）。
    5. 处理工具结果：将工具结果转化为字符串格式，因为模型只能识别字符串类型的上下文。如果工具结果本身是字符串，直接使用；如果工具结果是对象且包含text字段（如部分MCP工具返回的结果），则使用text字段的值；否则忽略（可根据需求补充错误处理）。
    6. 添加工具结果到消息队列：messages.push(new ToolMessage({ ... })); 创建ToolMessage实例，传入工具结果和工具调用ID（用于关联工具调用和结果），添加到消息队列中，让模型能够获取工具执行结果，进行下一步思考。

  6. 循环终止条件：如果迭代次数达到maxIterations，循环终止，返回消息队列中最后一条消息的内容（可能是工具调用结果或模型的中间响应）。

4.5.3 关键逻辑说明

  1. 消息队列的作用：消息队列是Agent能够持续思考的核心，它记录了整个对话过程中的所有信息，模型每次思考都会基于消息队列中的上下文进行分析，确保思考的连贯性和准确性。例如，模型第一次调用高德地图工具获取酒店信息后，工具结果会被添加到消息队列中，模型下次思考时会基于该结果，继续调用Chrome DevTools工具打开酒店图片。
  2. 工具调用的关联性：每个ToolMessage都包含tool_call_id，与对应的工具调用指令的id关联，确保模型能够正确识别哪个工具结果对应哪个工具调用，避免上下文混乱。
  3. 错误处理的缺失：当前代码中没有完善的错误处理（如工具调用失败、工具结果为空等情况），实际开发中需要补充错误处理逻辑，例如工具调用失败时打印错误日志、重试调用或返回错误提示，提升应用的稳定性。

4.6 任务执行与客户端关闭

// await runAgentWithTools('北京南站附件的酒店，以及去的路线');
// await runAgentWithTools(`北京南站附件的2个酒店，以及去的路线，路线规划生成文档保存到,
//     路线规划生成文档保存到 D:/workspace/lesson_zp/ai/agent/mcp_in_action/wendang 的一个md 文件`);
await runAgentWithTools(`
北京南站附近的3个酒店，拿到酒店图片，展开浏览器，展示每个酒店的图片，
每个tab一个url展示，并且把那个页面标题改为酒店名称
`);
await mcpClient.close();

这部分代码用于执行具体的Agent任务，并在任务完成后关闭MCP客户端，具体解析如下：

  1. 注释的任务：代码中注释了两个任务，分别是“查询北京南站附近酒店及路线”“查询2个酒店及路线并保存为MD文件”，可根据需求取消注释执行。
  2. 当前执行的任务：await runAgentWithTools(...) 调用任务执行函数，传入具体的用户查询，任务内容为：查询北京南站附近的3个酒店，获取酒店图片URL，打开浏览器，每个酒店图片用一个浏览器标签页展示，并将标签页标题改为酒店名称。该任务需要调用高德地图工具（查询酒店信息和图片URL）和Chrome DevTools工具（打开浏览器、操作标签页），是一个多工具联动的典型场景。
  3. 关闭MCP客户端：await mcpClient.close(); 任务执行完成后，调用MCP客户端的close()方法，关闭所有加载的工具和连接，释放资源，避免内存泄漏。该方法是异步的，需用await等待关闭完成。

五、实战演练：代码运行与效果验证

5.1 运行步骤

完成环境搭建和代码编写后，可按照以下步骤运行代码，验证实战效果：

  1. 确认.env文件配置正确，API密钥有效，文件系统工具的根目录存在。

  2. 打开终端，进入项目根目录，执行命令：node 文件名.js（如node mcp.js，需将文件名替换为自己的代码文件名）。

  3. 观察控制台日志，查看模型思考、工具调用的过程：

    1. 首先打印“⏳正在等待AI思考...”，说明模型正在分析用户查询。
    2. 随后打印“🔍 检测到X个工具调用”，显示模型需要调用的工具（如amap-maps-streamableHTTP、chrome-devtools）。
    3. 工具调用完成后，模型会再次思考，判断是否需要进一步调用工具，直到生成最终回复。

  4. 观察浏览器行为：代码运行过程中，会自动启动Chrome浏览器，打开3个标签页，每个标签页对应一个酒店的图片URL，且标签页标题会改为酒店名称。

  5. 查看最终结果：控制台会打印AI的最终回复，包含酒店名称、图片URL等信息，同时浏览器会展示对应的酒店图片。

5.2 预期效果

本次实战的预期效果分为两个部分：控制台输出和浏览器行为。

5.2.1 控制台输出

  1. 模型思考日志：多次打印“⏳正在等待AI思考...”，对应模型的多轮思考过程。
  2. 工具调用日志：打印“🔍 检测到2个工具调用”（高德地图和Chrome DevTools），以及工具名称。
  3. 最终回复：打印AI的最终回复，内容大致为：“已查询到北京南站附近的3个酒店，分别为XXX、XXX、XXX，已打开浏览器展示各酒店图片，每个标签页对应一个酒店，标题已修改为酒店名称。”

5.2.2 浏览器行为

  1. 自动启动Chrome浏览器（需确保本地安装了Chrome）。
  2. 打开3个新标签页，每个标签页访问一个酒店的图片URL（由高德地图工具返回）。
  3. 每个标签页的标题会被修改为对应的酒店名称（由Chrome DevTools工具实现）。

5.3 常见问题及解决方法

在运行代码的过程中，可能会遇到各种问题，以下是常见问题及对应的解决方法，帮助大家快速排查问题、完成实战。

5.3.1 环境变量相关问题

  1. 问题1：process.env.MODEL_NAME等变量为undefined，导致模型初始化失败。 解决方法：检查.env文件是否创建，文件路径是否正确（需在项目根目录）；检查.env文件中的变量名称是否与代码中的一致（如是否拼写错误，如MODEL_NAME是否误写为MODELNAME）；重新启动终端，确保dotenv模块正确加载环境变量。
  2. 问题2：API密钥无效，出现“Invalid API key”错误。 解决方法：检查OpenAI和高德地图的API密钥是否正确，是否过期；登录对应平台（OpenAI官网、高德地图开放平台），确认密钥是否有效，若过期则重新生成；确保密钥没有泄露，且已添加到.env文件中。

5.3.2 工具调用相关问题

  1. 问题1：MCP工具加载失败，出现“Tool not found”错误。 解决方法：检查mcpServers配置中的工具名称是否正确，是否与getTools()返回的工具名称一致；检查工具包名称是否正确（如chrome-devtools-mcp@latest是否误写）；确保npx能够正常访问网络，能够下载对应的工具包。
  2. 问题2：文件系统工具调用失败，出现“File not found”或“Permission denied”错误。 解决方法：检查文件系统工具配置的根目录（D:/workspace/lesson_zp/ai/agent/mcp_in_action/wendang）是否存在，若不存在则手动创建；检查该目录的权限，确保Node.js有权限进行读写操作；Windows系统需注意路径分隔符，使用“/”或“\”（转义后的反斜杠）。
  3. 问题3：Chrome DevTools工具调用失败，无法启动浏览器。 解决方法：检查本地是否安装了Chrome浏览器，若未安装则安装；检查Chrome的安装路径是否正确，确保npx能够找到Chrome可执行文件；关闭已打开的Chrome浏览器，避免端口冲突。

5.3.3 网络相关问题

  1. 问题1：OpenAI API调用失败，出现“Network Error”或“Timeout”错误。 解决方法：检查网络是否正常，能否访问OpenAI官网；若国内用户，需替换OpenAI的baseURL为合法的代理地址；检查API密钥是否有效，是否有足够的调用额度。
  2. 问题2：高德地图MCP接口调用失败，出现“403 Forbidden”错误。 解决方法：检查高德地图API密钥是否有效，是否开通了MCP相关服务；检查接口地址是否正确，确保key参数已正确拼接。

5.3.4 代码逻辑相关问题

  1. 问题1：模型陷入无限循环，反复调用工具，超过maxIterations。 解决方法：检查用户查询是否清晰，是否存在歧义，导致模型无法判断是否需要停止调用工具；调整maxIterations的值，适当减小迭代次数；补充错误处理逻辑，当工具调用失败或结果无效时，强制终止循环。
  2. 问题2：工具结果无法正确返回，模型无法获取上下文。 解决方法：检查工具调用的参数是否正确，是否与工具的要求一致；检查工具结果的处理逻辑，确保能够正确提取字符串格式的结果；打印toolResult，查看工具返回的具体格式，调整处理逻辑。

六、核心知识点总结与拓展

6.1 本次学习核心知识点总结

通过对参考资料代码的解析和实战演练，我们掌握了以下核心知识点，这些知识点是构建MCP相关AI应用的基础：

  1. MCP协议的核心原理：MCP是模型与外部工具的通信桥梁，通过标准化接口实现工具的统一管理和调用，解决了模型与工具的兼容性问题。
  2. LangChain框架的使用：掌握了LangChain中MCP客户端（MultiServerMCPClient）、OpenAI模型（ChatOpenAI）、消息类型（HumanMessage、ToolMessage）的使用方法，以及工具绑定（bindTools）、模型调用（invoke）等核心操作。
  3. 多工具联动逻辑：理解了AI Agent如何通过多轮思考，调用多个工具（高德地图、文件系统、浏览器）完成复杂任务，掌握了消息队列的作用和工具调用的关联性。
  4. 环境搭建与配置：掌握了Node.js环境下的依赖安装、环境变量管理（dotenv）、API密钥配置等基础操作，能够独立完成实战环境的搭建。
  5. 问题排查能力：熟悉了MCP应用开发中常见的问题（环境变量、工具调用、网络、代码逻辑），掌握了对应的解决方法，提升了代码调试能力。

6.2 拓展延伸：MCP的更多应用场景

MCP协议的应用场景非常广泛，除了本次实战中的地图查询、浏览器操作、文件处理，还可以应用于以下场景，帮助大家拓展思路：

  1. 办公自动化：通过MCP调用办公软件（如Word、Excel、PPT），实现文档生成、数据统计、报告导出等功能，提升办公效率。
  2. 数据分析与可视化：调用Excel、Python数据分析工具（如Pandas、Matplotlib），实现数据查询、分析、可视化，让模型能够生成专业的数据分析报告。
  3. API接口调用：通过MCP调用各类第三方API（如天气API、快递API、支付API），实现天气查询、快递跟踪、支付操作等功能，丰富AI应用的服务能力。
  4. 智能家居控制：通过MCP调用智能家居设备的接口，实现灯光控制、温度调节、门窗开关等操作，打造智能生活场景。
  5. 多模态应用：结合图像识别、语音合成等工具，实现图片分析、语音交互、视频生成等多模态任务，提升AI应用的交互体验。

6.3 进阶学习建议

如果希望进一步深入学习MCP和LangChain，提升AI Agent的开发能力，可参考以下进阶学习方向：

  1. 深入学习LangChain框架：研究LangChain的核心组件（如Agent、Chain、Memory），掌握更复杂的对话管理、工具调用逻辑，实现多轮对话和上下文记忆功能。
  2. 自定义MCP工具：学习如何开发自定义的MCP工具，适配自己的业务需求，如对接公司内部系统、自定义API接口等。
  3. 多模型适配：学习如何对接多个大模型（如OpenAI、百度文心一言、阿里通义千问），实现模型的切换和负载均衡，提升应用的稳定性和灵活性。
  4. 错误处理与异常捕获：完善代码的错误处理逻辑，实现工具调用失败重试、异常捕获、日志记录等功能，提升应用的健壮性。
  5. 实战项目开发：结合实际需求，开发一个完整的MCP应用（如智能办公助手、旅游规划助手），将所学知识应用到实际项目中，提升实战能力。

七、学习心得与体会

通过本次基于高德地图MCP代码的学习，我深刻体会到了MCP协议在大模型应用中的核心价值——它让大模型从“只能思考”走向“能够行动”，通过与外部工具的联动，极大地拓展了大模型的应用边界。在学习过程中，从环境搭建、代码解析到实战演练，每一个环节都让我对MCP、LangChain等技术有了更深入的理解。

刚开始接触代码时，我对MCP客户端的配置、工具绑定、消息队列等概念感到困惑，尤其是Agent的多轮思考和工具调用逻辑，难以理解模型如何判断何时调用工具、调用哪个工具。但通过逐行解析代码、梳理流程，以及实际运行代码、观察效果，我逐渐理清了整个逻辑——消息队列是核心，它记录了所有上下文信息，模型通过分析上下文判断是否需要调用工具，工具结果又作为上下文反馈给模型，形成一个闭环。

在实战过程中，我也遇到了很多问题，比如环境变量配置错误导致API调用失败、Chrome DevTools工具无法启动、模型陷入无限循环等。但通过排查错误日志、查阅相关文档、尝试不同的解决方法，我不仅解决了这些问题，还提升了自己的问题排查能力和代码调试能力。同时，我也意识到，一个稳定的AI应用不仅需要正确的代码逻辑，还需要完善的错误处理、日志记录等功能，这也是我后续学习和改进的方向。

本次学习让我明白，大模型应用的开发不仅仅是调用API，更重要的是理解模型与工具的联动逻辑，掌握标准化的协议和框架，才能构建出功能强大、稳定可靠的AI应用。未来，我将继续深入学习MCP和LangChain相关技术，尝试开发更多实际项目，将所学知识转化为实际价值，同时也希望能够通过这篇笔记，帮助更多开发者快速入门MCP实战，共同进步。

avatar
文章
阅读
粉丝