前端如何开发一个MCP Server - 安全审计实战项目介绍

hhx-mcp-audit（MCP）

gitHub:github.com/1571044963h... npm:www.npmjs.com/package/@hh...

MCP（Model Context Protocol）是什么

MCP（Model Context Protocol）：AI 智能体与外部工具之间的标准化通信协议。

它的核心作用是统一双方的 "对话格式"，让不懂专业工具的 AI 能精准调用工具能力，让工具能看懂 AI 的需求指令。

一个实际场景的严谨表述

假设我开发了一台 MCP Server（专业工具服务器） ，它的核心能力是做「项目依赖安全审计」；而 Cursor 编辑器本质是一个集成了大模型的 MCP Client（AI 智能体）------大模型本身没有"扫描项目依赖漏洞"的专业能力，只能做文本理解和推理。

当我们在 Cursor 里输入指令「帮我审计这个项目的依赖安全风险」时，流程是这样的：

Cursor 的大模型先判断：这个需求我自己做不了，但可以找外部工具帮忙；
它通过 MCP 协议的标准化格式，向已接入的 MCP Server 发送调用请求（包含项目路径、审计规则等关键参数）；
MCP Server 接收到符合协议格式的请求后，执行专业的依赖扫描和漏洞分析，再按 MCP 协议要求，把审计报告（比如漏洞列表、风险等级）结构化返回给 Cursor；
Cursor 的大模型拿到结果后，翻译成自然语言呈现给用户，最终我们才能得到清晰的安全审计结论。

简单说：MCP 就是 AI 和专业工具之间的 "翻译官"。没有这个统一协议，AI 喊不动工具，工具也听不懂 AI 在说什么。

关键概念的严谨区分（避免混淆）

概念	核心定位	举例
MCP Protocol	通信标准 / 规则（无实体）	规定请求必须包含任务类型 + 参数；返回必须包含状态码 + 结构化数据
MCP Server	提供专业能力的工具端	你开发的 `hhx-mcp-audit` 审计服务器
MCP Client	发起调用的 AI 智能体端	集成 LLM 的 Cursor 编辑器

MCP项目实战 - 安全依赖审计工具

演示流程和结果展示

如何进行安全审计

复制代码

npm audit

为什么不直接使用npm audit

npm audit的问题：

阅读不友好
- 依赖关系不清晰
功能不完整
- 无法对远程仓库进行审计
- 无法对工程本身进行审计（只能审计依赖）
难以集成
- AI应用集成：取决于应用是否支持运行命令
- CI/CD集成：无法定义部署决策逻辑

需求

自定义安全审计功能，该功能可支持：

对本地工程或远程仓库均能进行安全审计
安全审计时能够对工程本身进行审计
审计结果中包含清晰的依赖路径
审计的结果是一个统一标准的markdown格式文档
支持MCP Server协议

安全审计功能的实现流程

创建工作目录：创建一个临时的工作目录，用于保存执行期间要用到的临时文件
解析工程 ：解析本地工程目录或者远程仓库链接，得到对应的package.json文件内容
生成lock文件 ：将package.json写入到临时工作目录，同时根据它生成package-lock.json
安全审计 ：进入到临时工作目录，使用npm audit命令进行安全审计，并讲审计结果规格化
渲染：将上一步得到的规格化审计结果进行渲染，渲染成标准化的markdown内容，并保存到结果文件
删除工作目录：将之前创建的临时工作目录删除

实现细节

创建工作目录: 创建一个临时的工作目录，用于保存执行期间要用到的临时文件
- 如何保证目录名的唯一性：随机字符串+时间戳、uuid
解析工程 ：解析本地工程目录或者远程仓库链接，得到对应的package.json文件内容
- 分辨是本地工程还是远程仓库
- 具体是何种远程仓库（MVP版本仅考虑github仓库）
- 如何从出远程仓库的链接中分析得到关键信息：owner、repo、tag、default_brach
- 如何获取远程仓库中的package.json
- 其他情况处理（MVP版本不涉及）：非前端工程、monorepo工程
生成lock文件 ：将package.json写入到临时工作目录，同时根据它生成package-lock.json
- 如何根据package.json生成lock文件：npm install --package-lock-only
安全审计 ：进入到临时工作目录，使用npm audit命令进行安全审计，并讲审计结果规格化
- 如何得到审计结果：npm audit --json
- 审计结果中包含哪些信息：
  
  severity: docs.npmjs.com/about-audit...
  
  source: npm对漏洞的编号，仅存在于npm包中的漏洞
  
  CVE：漏洞的通用编号，该编号跨越语言，可以从www.cve.org/查询详情
  
  CWE：漏洞类型编号，通过此编号可以找到漏洞是如何产生的，会造成什么影响，可以通过cwe.mitre.org/ 进行查询
  
  CVSS：漏洞严重性评分，对应到severity字段
- 规格化的目标
- 如何实现规格化图的DFS算法
- 如何获取当前工程的审计结果：npm的远程API
- 把当前工程的审计结果汇总到结果中
渲染：将上一步得到的规格化审计结果进行渲染，渲染成标准化的 markdown 内容，并保存到结果文件
- 如何将审计结果渲染为 markdown：使用模板引擎，此项目使用的是ejs
删除工作目录：将之前创建的临时工作目录删除

一个用于前端工程依赖安全审计 的 MCP Server：在 Cursor 里调用 auditPackage 工具，即可对指定项目（本地路径或 GitHub 仓库）做依赖漏洞审计，并输出一份可直接阅读/分享的 Markdown 报告。

功能

本地项目审计：传入项目根目录（绝对路径），分析其直接与间接依赖的漏洞风险。
远程仓库审计 ：传入 GitHub 仓库 URL，拉取仓库根目录的 package.json 后进行审计。
报告输出 ：将审计结果渲染为 Markdown 并写入你指定的 savePath。
Cursor 集成：按 MCP 方式配置后，可直接在对话中触发审计。

安装

本项目发布为 npm 包：@hhxhhxhhx/hhx-mcp-audit。

方式 A（推荐） ：使用 npx 运行（无需全局安装）
方式 B ：全局安装后直接使用 hhx-mcp-audit

在 Cursor 中配置 MCP

你可以在项目级 或用户级配置 MCP Server（两者选其一即可）。

项目级配置（推荐）

在你的项目根目录创建文件：.cursor/mcp.json cursor - 首选项 - Cursor Setting - Tools & MCP 进行配置

json 复制代码

{
  "mcpServers": {
    "hhx-mcp-audit": {
      "command": "npx",
      "args": ["-y", "@hhxhhxhhx/hhx-mcp-audit"]
    }
  }
}

用户级配置（可选）

在你的用户目录创建：~/.cursor/mcp.json（macOS/Linux）

内容与上面一致。

配置完成后，重启 Cursor（或刷新 MCP Servers）使其生效。

如何使用（在 Cursor 对话中）

该 MCP Server 暴露一个工具：

tool 名称 ：auditPackage
入参：
- projectRoot：本地工程根路径（绝对路径）或 GitHub 仓库 URL
- savePath：报告保存路径（必须是绝对路径 ），例如：/abs/path/to/audit.md

审计本地项目

在 Cursor 里对我说类似：

对 /abs/path/to/your-project 做安全审计，输出到 /abs/path/to/your-project/audit.md

审计 GitHub 仓库

示例（仓库根目录存在 package.json）：

对 https://github.com/owner/repo 做安全审计，输出到 /abs/path/to/audit.md

也支持 tree URL（会转换为 tags/<name> 形式去拉取 package.json）：

https://github.com/owner/repo/tree/v1.2.3

输出报告长什么样

报告为 Markdown，包含：

漏洞总数与严重性分布（critical/high/moderate/low）
每个漏洞包的：
- 漏洞标题、npm advisory 编号、链接、受影响版本范围
- 依赖链（从当前工程到漏洞包的路径）
- 漏洞包在 lock/node_modules 解析中的位置（nodes）

工作原理（实现概览）

整体流程（对应 auditPackage(projectRoot, savePath)）：

创建临时工作目录 ：在项目内部的 work/ 下创建一次性目录
解析目标项目 ：
- 本地：读取 projectRoot/package.json
- 远程：仅支持 github.com，从 GitHub 拉取仓库根目录的 package.json
生成 lock 文件 ：在工作目录写入 package.json，执行：
- npm install --package-lock-only --force
执行审计 ：
- npm audit --json
- 并额外对"当前工程包本身"（name@version）调用 npm 安全审计接口补充结果
结果规范化 & 依赖链计算 ：把 npm audit 的结构整理为按严重性分组的统一格式，并计算依赖链
渲染 Markdown：通过 EJS 模板渲染为最终报告
清理临时目录：删除工作目录，避免污染
写入文件 ：把 Markdown 写到 savePath

注意与限制

远程审计限制 ：
- 仅支持 github.com
- 仅拉取仓库根目录 的 package.json（不支持 monorepo 子目录 package）
网络访问 ：
- 生成 lock 与审计过程需要访问 npm registry
- 远程审计需要访问 GitHub API 与 raw 内容地址
不会执行你的项目脚本 ：
- 工具不会运行你的 start/build 等脚本；它只在临时目录内运行 npm install --package-lock-only 与 npm audit

本地开发

bash 复制代码

npm install
npm run start

然后按 MCP 的方式用 stdio 连接（Cursor 配置时也会通过 stdio 启动）。

License

ISC