Andon SOP MCP Server

这是一个面向 WorkBuddy 的本地 MCP Server，用于连接 MES 系统，提供 SOP 上传辅助工具和异常报表查询工具。

当前项目通过 MCP stdio 协议与 WorkBuddy 通信，通过 HTTP REST 接口访问 MES 后端。

架构

WorkBuddy
   |
   | MCP Protocol (stdio)
   v
本地 MCP Server（本项目）
   |
   | HTTP REST / 登录鉴权
   v
MES 系统

环境要求

• Node.js >= 18
• npm
• WorkBuddy
• 可访问的 MES 后端服务
• MES 登录账号和密码，或可用的 MES 鉴权配置

快速开始

1. 安装依赖

进入项目根目录：

cd D:\svn-workspace\andon_sop-mcp

安装依赖：

npm install

2. 配置 MES 连接

配置文件位于：

config\mes-config.json

示例：

{
  "mes": {
    "baseUrl": "http://localhost:9998",
    "auth": {
      "type": "login",
      "username": "superadmin",
      "password": "1234554321",
      "loginUrl": "/main/login",
      "contentType": "application/x-www-form-urlencoded"
    },
    "timeout": 300000,
    "queryTimeoutMs": 25000,
    "retry": 3,
    "writeIntervalMs": 2400
  },
  "tools": {
    "likeSelectMaterielList": true,
    "selectCategoryTreeList": true,
    "uploadSop": true,
    "queryAbnormalReportPage": true
  }
}

字段说明：

字段	说明
mes.baseUrl	MES 后端地址。如果 MES 不在本机，不要使用 localhost，要改成真实地址。
mes.auth.type	当前使用 login，表示通过用户名密码登录 MES。
mes.auth.username	MES 用户名。
mes.auth.password	MES 密码。
mes.auth.loginUrl	MES 登录接口路径。
mes.timeout	普通请求超时时间，单位毫秒。
mes.queryTimeoutMs	查询类请求超时时间，单位毫秒。
mes.retry	网络失败后的重试次数。
mes.writeIntervalMs	写入类接口调用间隔，用于避开 MES 防重复提交限制。
tools.*	控制 MCP 工具是否启用，true 启用，false 禁用。

3. 编译

npm run build

编译后入口文件是：

dist\src\index.js

4. 本地手动启动测试

$env:MES_CONFIG_PATH="D:\svn-workspace\andon_sop-mcp\config\mes-config.json"
node D:\svn-workspace\andon_sop-mcp\dist\src\index.js

如果看到类似日志，说明 MCP Server 已启动：

MES TaskReport MCP Server starting...
Config loaded from: D:\svn-workspace\andon_sop-mcp\config\mes-config.json
Registered 4 tools: likeSelectMaterielList, selectCategoryTreeList, uploadSop, queryAbnormalReportPage
MES TaskReport MCP Server is ready. Waiting for requests...

这是 stdio MCP，启动后会等待客户端连接，终端没有继续输出是正常的。测试结束后按 Ctrl + C 退出。

WorkBuddy 配置

在 WorkBuddy 的自定义 MCP 配置中填写：

{
  "mcpServers": {
    "andon-sop-mcp": {
      "type": "stdio",
      "command": "node",
      "args": [
        "D:\\svn-workspace\\andon_sop-mcp\\dist\\src\\index.js"
      ],
      "cwd": "D:\\svn-workspace\\andon_sop-mcp",
      "env": {
        "MES_CONFIG_PATH": "D:\\svn-workspace\\andon_sop-mcp\\config\\mes-config.json"
      }
    }
  }
}

说明：

字段	说明
type	固定使用 stdio。
command	启动命令，这里是 node。
args	MCP 编译后的入口文件。
cwd	项目根目录，即 package.json 所在目录。建议保留。
env.MES_CONFIG_PATH	指定 mes-config.json 的绝对路径。建议保留，避免配置文件找不到。

Windows 路径写到 JSON 中时，\ 要写成 \\。

可用工具

Tool	用途
likeSelectMaterielList	按物料名称模糊分页查询物料，返回物料 ID、名称、编码。
selectCategoryTreeList	查询 SOP 分类列表，返回分类 ID 和分类名称。
uploadSop	上传 SOP 文件到 MES。
queryAbnormalReportPage	分页查询异常报表，支持开单人、发生时间范围、关闭状态、异常类型、关闭人等条件。

典型使用流程

上传 SOP

1. 准备或生成 SOP 文件，并拿到本地文件路径 file_path。
2. 如果只有物料名称，调用 likeSelectMaterielList 查询物料，让用户选择正确物料，使用表格中的物料 ID 作为 materielId。
3. 如果没有 SOP 分类 ID，调用 selectCategoryTreeList 查询分类，让用户选择正确分类，使用表格中的分类 ID 作为 esopCategoryId。
4. 确认 version、procedureId。
5. 参数齐全后调用 uploadSop。

uploadSop 必需参数：

参数	说明
file_path	本地 SOP 文件路径，MCP Server 所在机器必须能读取。
version	SOP 版本号。
materielId	物料 ID。
procedureId	工序 ID。
esopCategoryId	SOP 分类 ID。

不要猜测 materielId、procedureId、esopCategoryId。如果用户没有明确提供，应先查询或追问。

查询异常报表

调用 queryAbnormalReportPage。

常用参数：

参数	说明
page	页码，默认 1。
limit	每页数量，默认 5，最大 100。
billUserName	开单人姓名，模糊查询。
beginOccurDateStart	发生开始时间，格式 yyyy-MM-dd HH:mm:ss。
beginOccurDateEnd	发生结束时间，格式 yyyy-MM-dd HH:mm:ss。
closeStatus	关闭状态，模糊查询。
abnormalType	异常类型，模糊查询。
closeUserName	关闭人姓名，模糊查询。

返回结果中包含：

• 当前页表格
• hasPrevPage
• prevPage
• hasNextPage
• nextPage

如果 hasNextPage=true，可以继续查询下一页。

Skills

项目内置了 WorkBuddy 使用流程说明：

skills\mes-sop-abnormal-workflows\SKILL.md

该技能重点说明：

• 上传 SOP 应按什么流程调用 MCP 工具
• 查询异常报表应使用哪个工具和哪些参数
• 哪些 ID 不能猜，必须查询或询问用户

自包含打包

项目提供 scripts\bundle.mjs，用于把 MCP Server 打包成单个 JS 文件：

npm run bundle

输出文件：

andon_sop-mcp.js

这种方式适合分发给其他电脑使用。对方仍需要：

• Node.js >= 18
• config\mes-config.json
• WorkBuddy MCP 配置指向打包后的 JS 文件

如果执行 npm run bundle 报找不到 esbuild，先执行：

npm install

项目结构

andon_sop-mcp/
├─ config/
│  ├─ mes-config.json              # MES 实际连接配置
│  ├─ mes-config.example.json      # MES 配置示例
│  └─ 说明.txt                     # WorkBuddy 配置简要说明
├─ docs/
│  └─ workbuddy配置教程.md          # WorkBuddy 详细配置教程
├─ scripts/
│  └─ bundle.mjs                   # esbuild 打包脚本
├─ skills/
│  └─ mes-sop-abnormal-workflows/
│     └─ SKILL.md                  # WorkBuddy 业务流程技能说明
├─ src/
│  ├─ index.ts                     # MCP Server 入口
│  ├─ tools/
│  │  ├─ index.ts                  # 工具注册
│  │  ├─ like_select_materiel_list.ts
│  │  ├─ select_category_tree_list.ts
│  │  ├─ upload_sop.ts
│  │  └─ query_abnormal_report_page.ts
│  ├─ services/
│  │  ├─ mesClient.ts              # MES HTTP 客户端
│  │  ├─ authService.ts            # 登录和 token 管理
│  │  └─ entityResolverService.ts
│  ├─ types/
│  │  ├─ api.ts
│  │  └─ toolContent.ts
│  └─ utils/
│     └─ logger.ts                 # 日志输出到 stderr，避免干扰 MCP stdio
├─ test/
├─ package.json
└─ tsconfig.json

常见问题

MCP error -32000: Connection closed

通常表示 WorkBuddy 启动了本地 MCP 进程，但 MCP 进程马上退出。

优先检查：

1. 是否执行过 npm run build。
2. dist\src\index.js 是否存在。
3. WorkBuddy 配置里的 cwd 是否是项目根目录。
4. MES_CONFIG_PATH 是否指向真实存在的 config\mes-config.json。
5. mes-config.json 是否是合法 JSON。
6. node 命令是否可用。

MES 接口连不上

检查 config\mes-config.json：

"baseUrl": "http://localhost:9998"

如果 MES 后端不在本机，必须改成真实 MES 地址。

工具没有出现

检查 config\mes-config.json 的 tools 配置。设置为 false 的工具不会注册。

开发命令

# 编译 TypeScript
npm run build

# 运行测试
npm test

# 启动 MCP Server
npm start

# 打包成单个 JS 文件
npm run bundle

扩展工具

新增 MCP 工具时：

1. 在 src\tools 下新增工具文件。
2. 导出 name、description、inputSchema、handler。
3. 在 src\tools\index.ts 中注册。
4. 在 config\mes-config.json 的 tools 中增加开关。
5. 添加对应测试。