Opyconymcpy

🚀 OpCon MCP Server

An MCP server that interacts with the SMA OpCon REST API, enabling AI agents and applications to communicate with the OpCon automation platform via a standardized protocol.

🚀 Quick Start

1. Ensure you have Node.js 18 or higher installed, access to an OpCon API server, and OpCon API credentials (token or username/password).
2. Install the project dependencies:

npm install

3. Configure the server through environment variables.
4. Run the server in development or production mode.

✨ Features

• ✅ Complete API Coverage: Automatically generates MCP tools from OpenAPI specification.
• ✅ Authentication Support: Token-based and username/password authentication.
• ✅ Type Safety: Written in TypeScript with full type definitions.
• ✅ Comprehensive Testing: Unit tests with Jest.
• ✅ CI/CD: GitHub Actions workflows for testing, linting, and security.
• ✅ Development Tools: DevContainer and VSCode integration.
• ✅ Best Practices: ESLint, Prettier, and security scanning.
• ✅ Grafana Support: Prometheus metrics for monitoring and observability.

📦 Installation

npm install

📚 Documentation

View Full Documentation - Complete guide including:

• Quick Start Guide - Get started in minutes.
• Tool Reference - All 257 available tools with detailed parameters.
• Configuration Guide - Environment setup.
• Integration Guide - MCP client integration.
• Examples - Usage examples.

🔧 Technical Details

Prerequisites

• Node.js 18 or higher.
• Access to an OpCon API server.
• OpCon API credentials (token or username/password).

Configuration

The server is configured via environment variables:

*Either OPCON_TOKEN or both OPCON_USERNAME and OPCON_PASSWORD are required.

Usage

Running the Server

# Development mode
npm run dev

# Production mode (after building)
npm run build
node dist/index.js

Using with MCP Clients

Configure your MCP client (e.g., Claude Desktop, MCP Inspector) to use this server:

{
  "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"
      }
    }
  }
}

Available Tools

The server automatically generates MCP tools from the OpCon OpenAPI specification. Each API endpoint becomes a callable tool.

257 tools across 65 categories including:

• DailyJobs (40 tools) - Monitor and manage daily job execution.
• DailySchedules (11 tools) - Daily schedule operations.
• Machines (10 tools) - Machine configuration and monitoring.
• Calendars (8 tools) - Calendar management.
• AccessCodes (5 tools) - Access code management.
• Resources (5 tools) - Resource management.
• And 59 more categories...

For a complete list, see the Tool Reference.

Development

Setup

# Install dependencies
npm install

# Run in development mode
npm run dev

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Linting and Formatting

# Run ESLint
npm run lint

# Fix ESLint issues
npm run lint:fix

# Check formatting
npm run format:check

# Fix formatting
npm run format

Building

npm run build

Monitoring with Grafana

Quick Start

1. Enable metrics collection:

export OPCON_METRICS_ENABLED=true

2. Start the metrics HTTP server:

# Development mode
npm run dev:metrics

# Production mode (after building)
node dist/metrics-server.js

3. Access metrics at http://localhost:9090/metrics

Available Metrics

• Request counts: Total MCP tool requests by tool and method.
• Error rates: Errors by tool, method, and error type.
• Request duration: Latency histograms with p95, p99 percentiles.
• Tools available: Number of registered MCP tools.

Setup Grafana Dashboard

1. Set up Prometheus to scrape the metrics endpoint.
2. Import the dashboard from grafana/dashboard.json.
3. Configure your Prometheus data source in Grafana.

For detailed instructions, see grafana/README.md.

DevContainer Support

This project includes a DevContainer configuration for VS Code. To use it:

1. Install Docker and VS Code.
2. Install the Remote - Containers extension.
3. Open the project in VS Code.
4. Click "Reopen in Container" when prompted.

VS Code Integration

The project includes VS Code settings and recommended extensions:

• ESLint: Code linting.
• Prettier: Code formatting.
• Jest Runner: Run tests from the editor.
• TypeScript: Enhanced TypeScript support.

CI/CD

GitHub Actions workflows are configured for:

• CI: Linting, testing, and building on multiple Node.js versions.
• Security: CodeQL analysis, dependency review, and npm audit.

Project Structure

OpyConyMcpy/
├── .devcontainer/          # DevContainer configuration
├── .github/
│   └── workflows/          # GitHub Actions workflows
├── .vscode/                # VS Code settings
├── src/
│   ├── index.ts           # Main server entry point
│   ├── client.ts          # OpCon API client
│   ├── parser.ts          # OpenAPI spec parser
│   └── types.ts           # Type definitions
├── tests/                  # Unit tests
├── swagger.json           # OpCon OpenAPI specification
├── package.json           # Project dependencies
├── tsconfig.json          # TypeScript configuration
├── jest.config.js         # Jest configuration
├── .eslintrc.json         # ESLint configuration
└── .prettierrc            # Prettier configuration

Architecture

The MCP server architecture consists of:

1. Parser: Reads the OpenAPI specification and generates MCP tool definitions.
2. Client: Handles HTTP communication with the OpCon API, including authentication.
3. Server: Implements the MCP protocol and routes tool calls to the appropriate API endpoints.

Flow

MCP Client → MCP Server → OpCon Client → OpCon REST API

Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Run tests and linting.
5. Submit a pull request.

Security

• Always use HTTPS in production.
• Store credentials securely (use environment variables, never commit them).
• Enable TLS verification unless absolutely necessary.
• Regularly update dependencies.
• Review security scan results in GitHub Actions.

📄 License

MIT

Support

For issues and questions, please use the GitHub issue tracker.