# LangChain MCP Demo

一个基于 Node.js 的 MCP 示例项目，演示如何：

- 使用 `@modelcontextprotocol/sdk` 创建本地 MCP Server
- 在 Cursor 等 MCP Client 中挂载本地工具
- 通过 `@langchain/mcp-adapters` 让 LangChain 同时连接多个 MCP Server
- 使用 OpenAI 兼容接口完成“模型思考 -> 工具调用 -> 返回结果”的 Agent 流程
- 组合高德地图 AMap MCP、filesystem MCP、Chrome DevTools MCP 获取位置、路线、文件和浏览器相关信息

## 功能概览

项目包含两个示例：

| 示例 | 入口 | 说明 |
| --- | --- | --- |
| 本地用户查询 MCP | `src/my-mcp/my-mcp-server.mjs` | 注册 `query-user` 工具和 `docs://guide` 资源，演示本地 MCP Server 的创建与调用 |
| AMap 多 MCP Agent | `src/amap-mcp/amap-mcp-test.mjs` | 同时连接高德地图、filesystem、Chrome DevTools MCP，用自然语言完成地点查询、路线规划、文档保存和浏览器操作 |

本地用户查询示例注册了以下 MCP 能力：

| 类型 | 名称 | 说明 |
| --- | --- | --- |
| Tool | `query-user` | 根据用户 ID 查询用户姓名、邮箱和角色 |
| Resource | `docs://guide` | 提供 MCP Server 使用说明 |

AMap 示例连接了以下外部 MCP Server：

| MCP Server | 配置方式 | 说明 |
| --- | --- | --- |
| `amap-maps-streamableHTTP` | `https://mcp.amap.com/mcp?key=${AMAP_MAPS_API_KEY}` | 调用高德地图能力查询地点、周边信息和路线 |
| `filesystem` | `npx -y @modelcontextprotocol/server-filesystem` | 在 `ALLOWED_PATHS` 允许的目录内读写文件 |
| `chrome-devtools` | `npx -y chrome-devtools-mcp@latest` | 通过 Chrome DevTools MCP 获取或操作浏览器相关信息 |

## 项目结构

```text
.
├── assets/
│   └── cursor-mcp-setting.png
├── src/
│   ├── amap-mcp/
│   │   └── amap-mcp-test.mjs       # 高德地图、filesystem、Chrome DevTools 多 MCP 示例
│   └── my-mcp/
│       ├── my-mcp-server.mjs       # 本地 MCP Server，注册工具和资源
│       └── langchain-mcp-test.mjs  # LangChain MCP Client 调用示例
├── package.json
├── pnpm-lock.yaml
└── README.md
```

## 环境要求

- Node.js 18+
- pnpm
- Cursor 或其他支持 MCP 的客户端
- OpenAI 兼容的模型服务
- AMap 示例需要可用的高德地图 MCP API Key

## 安装依赖

```bash
pnpm install
```

## 配置环境变量

在项目根目录创建 `.env` 文件：

```env
MODEL_NAME=your-model-name
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1

AMAP_MAPS_API_KEY=your-amap-maps-api-key
ALLOWED_PATHS=D:/code/agent-node/mcp-server/src/amap-mcp/output
```

如果使用官方 OpenAI API，`OPENAI_BASE_URL` 可以按你的 SDK 配置习惯填写或省略。

`ALLOWED_PATHS` 用英文逗号分隔多个允许 filesystem MCP 访问的目录。

## 在 Cursor 中使用本地 MCP Server

打开 Cursor 的 MCP 配置，添加本地 server：

```json
{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": [
        "D:/code/agent-node/mcp-server/src/my-mcp/my-mcp-server.mjs"
      ]
    }
  }
}
```

如果项目路径不同，请把 `args` 中的路径替换为你本机的 `src/my-mcp/my-mcp-server.mjs` 绝对路径。

配置示例：

![Cursor MCP setting](assets/cursor-mcp-setting.png)

配置完成后，Cursor 可以在对话中识别并调用 `query-user` 工具。

## 运行本地用户查询示例

```bash
pnpm run start:my-mcp
```

`src/my-mcp/langchain-mcp-test.mjs` 的主要流程：

1. 从 `.env` 读取模型名称、API Key 和接口地址。
2. 使用 `MultiServerMCPClient` 启动并连接本地 MCP Server。
3. 调用 `mcpClient.getTools()` 获取 MCP 工具列表。
4. 调用 `mcpClient.listResources()` 和 `mcpClient.readResource()` 读取 MCP 资源内容。
5. 使用 `model.bindTools(tools)` 将工具绑定到模型。
6. 进入 Agent 循环：模型产生工具调用时执行工具，并把结果追加回消息历史。

默认示例问题是：

```text
MCP Server 的使用指南是什么
```

如果切换到用户查询问题，模型会读取本地示例数据并返回用户信息。

## 运行 AMap 多 MCP 示例

```bash
pnpm run start:amap
```

`src/amap-mcp/amap-mcp-test.mjs` 会同时连接高德地图、filesystem 和 Chrome DevTools MCP。默认示例问题会查询上海南站附近的火锅店，选择最近的 1 个地点，规划路线，并把结果保存为 Markdown 文档。

如果需要调整输出目录，请同步修改 `.env` 中的 `ALLOWED_PATHS`，并确保自然语言任务里要求写入的路径位于允许目录内。

## 示例数据

本地 MCP Server 当前内置了 3 条用户数据：

| 用户 ID | 姓名 | 邮箱 | 角色 |
| --- | --- | --- | --- |
| `001` | 张三 | `zhangsan@example.com` | `admin` |
| `002` | 李四 | `lisi@example.com` | `user` |
| `003` | 王五 | `wangwu@example.com` | `user` |

你可以在 `src/my-mcp/my-mcp-server.mjs` 中替换 `database`，把它改造成真实数据库、HTTP API 或业务系统查询工具。

## 常见问题

### Cursor 找不到 MCP Server

请检查：

- `command` 是否能在终端中直接执行
- `args` 是否使用了正确的绝对路径
- 依赖是否已经通过 `pnpm install` 安装
- Node.js 版本是否满足要求

### LangChain 示例无法调用模型

请检查：

- `.env` 中的 `MODEL_NAME` 是否可用
- `OPENAI_API_KEY` 是否正确
- `OPENAI_BASE_URL` 是否与所使用的模型服务匹配

### AMap 示例无法获取地图信息

请检查：

- `.env` 中的 `AMAP_MAPS_API_KEY` 是否有效
- 当前网络是否可以访问 `https://mcp.amap.com`
- 模型是否正确选择了高德地图 MCP 暴露的工具

### filesystem MCP 无法写入文件

请检查：

- `ALLOWED_PATHS` 是否配置了目标目录
- 目标路径是否位于 `ALLOWED_PATHS` 允许的目录内
- 目录是否存在并且当前用户有写入权限

### 修改项目路径后示例失效

`README.md`、`src/my-mcp/langchain-mcp-test.mjs` 和 `src/amap-mcp/amap-mcp-test.mjs` 中都包含本地路径示例。移动项目后，需要同步更新 MCP Server 入口路径和 filesystem 允许路径。

## 后续可扩展方向

- 将示例数据替换为数据库查询
- 增加更多 MCP tools，例如新增用户、搜索订单、查询知识库
- 将 server 路径和输出路径改为环境变量，避免硬编码本机路径
- 为 MCP Server 添加单元测试和集成测试