Skip to main content
Glama

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 系统

Related MCP server: CMMS MCP Server

环境要求

  • 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. 添加对应测试。

Available Tools

11 tools
deleteProjProjectA

批量删除项目,调用 /projProject/delEntityById。调用本工具前必须先调用 queryProjProjectList 查询项目并让用户选择要删除的项目。只有 projectStatus 为 0(未开始)的项目允许删除;其他状态不能删除。本工具会在删除前校验每个项目的状态。

Inputs: projects (required).

deleteProjTaskA

批量删除项目任务,调用 /projTask/delEntityById。调用本工具前必须先调用 queryProjectTask 查询任务树,并让用户选择要删除的任务。任务 id 必须来自 queryProjectTask 返回的任务记录 id。本工具会把多个任务 id 用英文逗号拼接为 ids 后提交给后端。

Inputs: tasks (required).

queryDutyListA

查询项目任务责任人列表。用于调用 saveProjTask 前选择责任人。会读取 AndonSysUser 表单配置,查询 /user/queryPageMap,并固定带上 accountType=0。调用 saveProjTask 时,dutyUserId 使用返回 records 中的 id,dutyUserName 使用同一条 records 的 display 中的用户姓名字段。

Inputs: page, limit, contain, exclude, +1 more.

queryProjCustomerA

按 MES 表单配置动态分页查询项目客户列表。会先读取 ProjCustomer 表单字段配置,构建查询参数,查询 /projCustomer/queryPageMap,并使用数据字典翻译展示值。返回的 Work Buddy 查询上下文会包含每条记录的 id,方便后续按客户记录继续操作。

Inputs: page, limit, contain, exclude, +1 more.

queryProjectTaskA

查询指定项目的任务树。调用本工具前必须先调用 queryProjProjectList 查询项目列表,并让用户选择正确的项目 id。工具会调用 /projTask/getTasksByProject 获取任务,组装为树形结构,并用 notify_type、proj_status 数据字典翻译通知类型和任务状态。

Inputs: projectId (required).

queryProjProjectListA

按 MES 表单配置动态分页查询项目管理列表。会先读取 ProjProject 表单字段配置,构建查询参数,查询 /projProject/queryPageMap,并使用数据字典翻译展示值。

Inputs: page, limit, contain, exclude, +1 more.

queryProjUserA

按 MES 表单配置动态分页查询用户列表。会先读取 User 表单字段配置,构建查询参数,查询 /user/queryPageMap,并使用数据字典翻译展示值。返回的 Work Buddy 查询上下文会包含每条记录的 id,方便后续按用户记录继续操作。

Inputs: page, limit, contain, exclude, +1 more.

saveProjProjectA

新增项目,直接调用 /projProject/saveEntityMap。调用本工具前必须先调用 queryProjCustomer 查询并让用户选择客户;customerName、customerCode、customerId 必须来自 queryProjCustomer 返回的同一条客户记录。若要填写项目经理,还必须先调用 queryProjUser 查询并让用户选择用户;userId 必须来自 queryProjUser 返回记录的 id,pmName 应使用同一条用户记录的名称。projectStatus 固定为 0,id 固定为空字符串。

Inputs: customerId (required), customerCode (required), customerName (required), pmName, +6 more.

saveProjTaskA

新增项目任务或子任务,直接调用 /projTask/saveEntityMap。调用本工具前必须先调用 queryProjProjectList 查询并让用户选择项目,projectId 必须来自项目记录 id;必须先调用 queryDutyList 查询并让用户选择责任人,dutyUserId 和 dutyUserName 必须来自同一条责任人记录。新增子任务时还需要传 parentId,parentId 应来自 queryProjectTask 返回的任务 id。progress 固定为 0,delayDays 固定为 0。

Inputs: taskName (required), projectId (required), dutyUserId (required), notifyType (required), +6 more.

updateProjProjectA

修改项目信息,调用 /projProject/saveEntityMap。调用本工具前必须先调用 queryProjProjectList 查询项目并让用户选择要修改的项目,id 必须来自项目记录 id。除了 id 以外,只传需要修改的字段。若修改客户,customerName、customerCode、customerId 必须来自 queryProjCustomer 返回的同一条客户记录并一起传入;若修改项目经理,pmName、userId 必须来自 queryProjUser 返回的同一条用户记录并一起传入。

Inputs: id (required), pmName, userId, planHours, +8 more.

updateProjTaskA

修改项目任务信息,调用 /projTask/saveEntityMap。调用本工具前必须先调用 queryProjectTask 查询任务树并让用户选择要修改的任务,id 必须来自任务记录 id。除了 id 以外,只传需要修改的字段。若修改责任人,dutyUserId、dutyUserName 必须来自 queryDutyList 返回的同一条责任人记录并一起传入。

Inputs: id (required), parentId, progress, taskName, +9 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct operation: project CRUD, task CRUD, and supporting queries (customers, users, duty list). No two tools have overlapping purposes; descriptions clearly differentiate them.

    Naming Consistency4/5

    Tools follow a verb+noun pattern with camelCase (e.g., queryProjProjectList, saveProjTask). Minor inconsistency: 'queryDutyList' lacks the 'Proj' prefix present in others, but overall pattern is predictable.

    Tool Count4/5

    11 tools cover the core operations of a project and task management system: 4 for projects (create, read list, update, delete), 4 for tasks (create, read tree, update, delete), and 3 supporting queries. This is well-scoped, though slightly on the higher side.

    Completeness4/5

    CRUD operations are covered for both projects and tasks, along with necessary supporting queries (customers, users, duty list). However, there is no explicit tool to update project status or get a single entity by ID, leaving minor gaps.

    Related MCP Connectors

    Related MCP Servers