JinDaGe - opyconymcpy MCP Details

article

README

🚀 OpCon MCP 服务器

OpCon MCP 服务器是一个基于模型上下文协议（MCP）的服务器，用于与 SMA OpCon REST API 进行交互。该服务器使 AI 代理和应用程序能够通过标准化协议与 OpCon 自动化平台进行交互。

🚀 快速开始

确保满足以下前提条件：
- Node.js 18 或更高版本
- 能够访问 OpCon API 服务器
- 拥有 OpCon API 凭证（令牌或用户名/密码）
安装依赖：

npm install

配置环境变量，具体变量说明见下方「配置」部分。
启动服务器：

# 开发模式
npm run dev

# 生产模式（构建后）
npm run build
node dist/index.js

✨ 主要特性

✅ 完整的 API 覆盖：根据 OpenAPI 规范自动生成 MCP 工具。
✅ 认证支持：支持基于令牌和用户名/密码的认证方式。
✅ 类型安全：使用 TypeScript 编写，具有完整的类型定义。
✅ 全面测试：使用 Jest 进行单元测试。
✅ CI/CD：通过 GitHub Actions 工作流进行测试、代码检查和安全扫描。
✅ 开发工具：支持 DevContainer 和 VSCode 集成。
✅ 最佳实践：使用 ESLint、Prettier 进行代码规范检查和格式化，同时进行安全扫描。
✅ Grafana 支持：提供 Prometheus 指标，用于监控和可观测性。

📦 安装指南

安装依赖

npm install

📚 详细文档

查看完整文档 - 完整指南包括：

快速入门指南 - 几分钟内即可开始使用
工具参考 - 所有 257 个可用工具及其详细参数
配置指南 - 环境设置
集成指南 - MCP 客户端集成
示例 - 使用示例

💻 使用示例

运行服务器

# 开发模式
npm run dev

# 生产模式（构建后）
npm run build
node dist/index.js

与 MCP 客户端配合使用

配置你的 MCP 客户端（例如 Claude Desktop、MCP Inspector）以使用此服务器：

{
  "mcpServers": {
    "opcon": {
      "command": "node",
      "args": ["/path/to/OpyConyMcpy/dist/index.js"],
      "env": {
        "OPCON_BASE_URL": "https://your-opcon-server:9010",
        "OPCON_TOKEN": "your-token-here"
      }
    }
  }
}

可用工具

服务器根据 OpCon OpenAPI 规范自动生成 MCP 工具。每个 API 端点都成为一个可调用的工具。

涵盖 65 个类别，共 257 个工具，例如：

DailyJobs（40 个工具） - 监控和管理日常作业执行
DailySchedules（11 个工具） - 日常调度操作
Machines（10 个工具） - 机器配置和监控
Calendars（8 个工具） - 日历管理
AccessCodes（5 个工具） - 访问代码管理
Resources（5 个工具） - 资源管理
还有 59 个其他类别...

完整列表请参阅工具参考。

🔧 技术细节

配置

服务器通过环境变量进行配置： | 变量 | 是否必需 | 描述 | |------|----------|------| | OPCON_BASE_URL | 是 | OpCon API 基础 URL（例如，https://opcon-server:9010） | | OPCON_TOKEN | 否* | 用于认证的应用程序令牌 | | OPCON_USERNAME | 否* | 用于认证的用户名 | | OPCON_PASSWORD | 否* | 用于认证的密码 | | OPCON_VERIFY_TLS | 否 | 设置为 false 可禁用 TLS 验证（默认：true） | | OPCON_METRICS_ENABLED | 否 | 设置为 true 可启用 Prometheus 指标（默认：false） | | OPCON_METRICS_PORT | 否 | 指标 HTTP 服务器的端口（默认：9090） |

*OPCON_TOKEN 或 OPCON_USERNAME 和 OPCON_PASSWORD 两者都需要提供。

开发

环境搭建

# 安装依赖
npm install

# 以开发模式运行
npm run dev

测试

# 运行所有测试
npm test

# 以监视模式运行测试
npm run test:watch

# 运行带覆盖率的测试
npm run test:coverage

代码检查和格式化

# 运行 ESLint
npm run lint

# 修复 ESLint 问题
npm run lint:fix

# 检查代码格式
npm run format:check

# 修复代码格式
npm run format

构建

npm run build

监控

OpCon MCP 服务器支持 Prometheus 指标，可在 Grafana 中可视化。

快速开始

启用指标收集：

export OPCON_METRICS_ENABLED=true

启动指标 HTTP 服务器：

# 开发模式
npm run dev:metrics

# 生产模式（构建后）
node dist/metrics-server.js

在 http://localhost:9090/metrics 访问指标。

可用指标

请求计数：按工具和方法统计的 MCP 工具总请求数
错误率：按工具、方法和错误类型统计的错误数
请求持续时间：带有 p95、p99 百分位数的延迟直方图
可用工具：已注册的 MCP 工具数量

设置 Grafana 仪表盘

设置 Prometheus 以抓取指标端点
从 grafana/dashboard.json 导入仪表盘
在 Grafana 中配置 Prometheus 数据源

详细说明请参阅 grafana/README.md。

项目结构

OpyConyMcpy/
├── .devcontainer/          # DevContainer 配置
├── .github/
│   └── workflows/          # GitHub Actions 工作流
├── .vscode/                # VS Code 设置
├── src/
│   ├── index.ts           # 主服务器入口点
│   ├── client.ts          # OpCon API 客户端
│   ├── parser.ts          # OpenAPI 规范解析器
│   └── types.ts           # 类型定义
├── tests/                  # 单元测试
├── swagger.json           # OpCon OpenAPI 规范
├── package.json           # 项目依赖
├── tsconfig.json          # TypeScript 配置
├── jest.config.js         # Jest 配置
├── .eslintrc.json         # ESLint 配置
└── .prettierrc            # Prettier 配置

架构

MCP 服务器架构包括：

解析器：读取 OpenAPI 规范并生成 MCP 工具定义
客户端：处理与 OpCon API 的 HTTP 通信，包括认证
服务器：实现 MCP 协议并将工具调用路由到相应的 API 端点

流程

MCP 客户端 → MCP 服务器 → OpCon 客户端 → OpCon REST API

🤝 贡献代码

分叉仓库
创建功能分支
进行更改
运行测试和代码检查
提交拉取请求

🔒 安全注意事项

生产环境中始终使用 HTTPS
安全存储凭证（使用环境变量，切勿提交到代码库）
除非绝对必要，否则启用 TLS 验证
定期更新依赖项
查看 GitHub Actions 中的安全扫描结果

📄 许可证

本项目采用 MIT 许可证。

🛠️ 支持

如有问题和疑问，请使用 GitHub 问题跟踪器。

opyconymcpy