Skip to main content
Glama
guansuian

Andon SOP MCP Server

by guansuian
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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: Industrial MCP Agent Platform

环境要求

  • 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

1 tool
queryAbnormalReportPageA

调用工具前，应先读取 MCP resource: mcp://abnormal-report-mcp/instructions/serverInstructions。该 resource 描述了安灯系统 MCP 的能力、查询流程和输出要求；如果 resources/list 为空，也可以直接用 resources/read 读取该 URI。查询 MES 异常报表/安灯异常记录时使用本工具；当用户明确想查看异常报表、异常记录、异常统计、异常处理历史时，应调用本工具。用户提出制造现场、生产现场、工位、设备、质量、物料、节拍等问题或异常，并希望查找原因、处理结果、历史解决方案、处置经验时，也应先调用本工具查询 AndonAbnormalReport 历史异常记录，再从查询结果中的异常详情、处理结果、处理人、持续时长等字段中总结可参考的解决方案。工具会先读取 AndonAbnormalReport 表单字段配置，构建动态查询参数，查询分页数据，并使用数据字典翻译展示值。

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo页码，从 1 开始。默认 1。
limitNo每页数量，默认 5，最大 100。
containNo初始化表单字段时只包含指定字段，默认空。
excludeNo初始化表单字段时排除指定字段，默认空。
filtersNo动态查询条件。key 必须是表单字段 field；文本字段模糊查，时间字段传 {start,end} 范围查。

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It discloses key behaviors: reads form field configurations, builds dynamic query parameters, queries paginated data, and uses data dictionary translations. However, it does not explicitly state that the tool is read-only, nor does it mention authentication, rate limits, or side effects. The info is adequate but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph that front-loads the critical prerequisite (reading an MCP resource) before stating the main purpose. It contains several sentences but all contribute useful information. It could be slightly more concise, but the structure is logical and prioritized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is complex (5 parameters, nested objects) and has no output schema. The description mentions that results include fields like 异常详情, 处理结果, and that translation is applied, but it does not describe the response format, pagination metadata, or error handling. For a tool of this complexity, more detail about the output would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that filters support fuzzy search for text fields and range search for time fields, and that 'contain' and 'exclude' manage form field initialization. These details enrich the agent's understanding beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: querying MES abnormal reports / Andon abnormal records. It uses specific verbs (查询) and resource (AndonAbnormalReport), and explicitly lists scenarios where the tool should be used, making it easy for an agent to select correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use the tool, including specific user intents (e.g., viewing abnormal reports, records, statistics) and even suggests it as a first step for exploring historical solutions. It also instructs to read a prerequisite MCP resource. However, no sibling tools are listed, so no direct comparison or when-not-to-use is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 1 tool updatev1.0.0
    • First observedqueryAbnormalReportPage
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of confusion between tools. The single tool's purpose is clearly defined, so disambiguation is perfect.

Naming Consistency5/5

The tool name 'queryAbnormalReportPage' follows a clear verb_noun pattern. With only one tool, consistency is inherent and the naming is descriptive and predictable.

Tool Count3/5

A single tool feels thin for the domain of abnormal report management. While the tool is detailed, a server typically requires multiple tools for different operations, so the count is borderline.

Completeness2/5

The server only provides a query tool, missing create, update, and delete operations. This is a significant gap for an abnormal report management server, limiting agent capabilities.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers