Opyconymcpy

🚀 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_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 中可视化。

快速开始

1. 启用指标收集：

export OPCON_METRICS_ENABLED=true

2. 启动指标 HTTP 服务器：

# 开发模式
npm run dev:metrics

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

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

可用指标

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

设置 Grafana 仪表盘

1. 设置 Prometheus 以抓取指标端点
2. 从 grafana/dashboard.json 导入仪表盘
3. 在 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 服务器架构包括：

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

流程

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

🤝 贡献代码

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

🔒 安全注意事项

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

📄 许可证

本项目采用 MIT 许可证。

🛠️ 支持

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