prandogabriel/ieee2030.5-mcp

IEEE 2030.5 MCP Server

A Model Context Protocol (MCP) server for interacting with IEEE 2030.5 (SEP 2.0) Smart Energy Profile servers.

Quick Start: npx -y @prandogabriel/ieee2030.5-mcp

Table of Contents

• Features
• Prerequisites
  • System Requirements
  • Install Node.js
  • Install pnpm
  • IEEE 2030.5 Server Requirements
• Quick Start
  • Option 1: Using Published Package (Fastest)
  • Option 2: Local Development Setup
• Environment Configuration
• Available MCP Tools
  • Connection & Status Tools
  • IEEE 2030.5 Resource Tools
  • Available MCP Prompts
• IEEE 2030.5 Navigation
• Development
  • Development Dependencies
  • Development Commands
  • Development Workflow
• Usage Examples
  • Using Published Package (Recommended)
  • Using with Claude Desktop (Local Development)
  • Using MCP Inspector
  • Programmatic Usage
• Contributing
  • Getting Started
  • Development Guidelines
  • Areas for Contribution
  • Contribution Workflow
  • Architecture Overview
  • Community Guidelines
  • Getting Help
• Security Notes
• Troubleshooting

Features

• 🔐 Certificate-based authentication (single .pem or separate cert/key files)
• 📡 Full IEEE 2030.5 endpoint support
• 🛠️ MCP tools for all major IEEE 2030.5 resources
• 🎯 HATEOAS-based navigation with comprehensive guide
• ⚙️ Environment-based configuration
• 🧪 Built-in test client and MCP Inspector support

Prerequisites

System Requirements

• Node.js: Version 20.0.0 or higher
• Package Manager: pnpm (recommended) or npm
• Operating System: macOS, Linux, or Windows

Install Node.js

If you don't have Node.js installed:

Using Node Version Manager (recommended):

# Install nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node.js 20
nvm install 20
nvm use 20

Direct download:

• Download from nodejs.org (LTS version recommended)

Install pnpm

npm install -g pnpm

Or using corepack (Node.js 16.10+):

corepack enable
corepack prepare pnpm@latest --activate

IEEE 2030.5 Server Requirements

To use this MCP server, you need access to an IEEE 2030.5 compliant server with:

• HTTPS endpoint (typically port 8443)
• Client certificate authentication (.pem format recommended)
• IEEE 2030.5/SEP 2.0 compliance with standard endpoints

Common IEEE 2030.5 implementations:

• OpenADR VEN/VTN servers
• Smart inverter management systems
• Utility demand response platforms
• Distributed Energy Resource (DER) management systems

Quick Start

Option 1: Using Published Package (Fastest)

For most users, the simplest way is to use the published npm package:

1. Ensure Node.js 20+ is installed:

   node --version  # Should be 20.0.0 or higher
   

2. Test the server:

   npx -y @prandogabriel/ieee2030.5-mcp
   

3. Configure with Claude Desktop - see Published Package Configuration

Option 2: Local Development Setup

For development or customization:

1. Verify Requirements

Check your Node.js and pnpm versions:

node --version  # Should be 20.0.0 or higher
pnpm --version  # Should be 8.0.0 or higher

2. Clone and Install

git clone <repository-url>
cd ieee2030.5-mcp
pnpm install

3. Configure Environment

Copy the example environment file and configure your IEEE 2030.5 server:

cp .env.example .env

Edit .env with your configuration. The server will automatically load environment variables from the .env file:

# REQUIRED: Your IEEE 2030.5 server URL
IEEE2030_BASE_URL=https://your-ieee2030-server:port

# REQUIRED: Certificate for authentication (choose one option)
# Option 1: Single PEM file (like curl -E $CTRL_CERT)
IEEE2030_CERT_PATH=/path/to/your/client.pem

# Option 2: Separate files
# IEEE2030_CERT_PATH=/path/to/client.crt
# IEEE2030_KEY_PATH=/path/to/client.key

# Optional: Security settings
IEEE2030_INSECURE=true  # Set to true for development with self-signed certs

Note: The .env file is automatically ignored by git for security.

4. Build the Project

pnpm build

5. Test the Server

Use the MCP Inspector for interactive testing and debugging:

# Build and start the inspector
pnpm debug

This will:

1. Build your server
2. Open the MCP Inspector in your browser at http://localhost:5173
3. Connect to your IEEE 2030.5 MCP server

The inspector provides a web UI where you can:

• View all available tools
• Test tools interactively with parameters
• See real-time responses and errors
• Debug your server behavior

Environment Configuration

Available MCP Tools

Connection & Status Tools

• ieee2030_status - Check client configuration status
• ieee2030_test_connection - Test connectivity to IEEE 2030.5 server

IEEE 2030.5 Resource Tools

• ieee2030_get_device_capabilities - Get device capabilities (/dcap) - Start here for resource discovery
• ieee2030_get_end_devices - Get end devices (/edev) - Physical devices and their DERs
• ieee2030_get_der_programs - Get DER programs (/derp) - Control programs for DERs
• ieee2030_get_demand_response_programs - Get demand response programs (/drp)
• ieee2030_get_usage_points - Get usage points (/upt) - Metering locations
• ieee2030_get_time - Get server time (/tm) - Server time synchronization
• ieee2030_get_custom_endpoint - Access any custom endpoint with dynamic navigation

Available MCP Prompts

• ieee2030_navigation_guide - Comprehensive guide for navigating IEEE 2030.5 resources using HATEOAS principles

IEEE 2030.5 Navigation

This MCP server includes a comprehensive navigation guide that teaches you how to explore IEEE 2030.5 resources dynamically. The IEEE 2030.5 standard uses HATEOAS (Hypermedia as the Engine of Application State) principles, where each response contains links to related resources.

Key Navigation Tips:

1. Always start with /dcap (Device Capabilities) to discover available resources
2. Follow links dynamically - use the href attributes in responses to navigate
3. Use the custom endpoint tool to access any discovered path
4. Check the navigation guide prompt for detailed examples and patterns

Development

Development Dependencies

This project uses modern development tools:

• TypeScript: Type-safe JavaScript development
• esbuild: Fast bundling and compilation
• Biome: Fast linting and formatting (replaces ESLint + Prettier)
• nodemon: Auto-restart during development
• MCP Inspector: Interactive testing and debugging

Development Commands

# Start development server with auto-reload
pnpm dev

# Run linting and formatting
pnpm lint          # Check for issues
pnpm lint:fix      # Fix issues automatically
pnpm format        # Check formatting
pnpm format:fix    # Fix formatting
pnpm check         # Run both lint and format checks
pnpm check:fix     # Fix both lint and format issues

# Build for production
pnpm build

# Start production server
pnpm start

# Development with auto-restart
pnpm watch

Development Workflow

1. Make changes to source code in /src
2. Run development server: pnpm dev
3. Test with MCP Inspector: pnpm debug
4. Format and lint: pnpm check:fix
5. Build for production: pnpm build

Usage Examples

Using Published Package (Recommended)

The easiest way to use this MCP server is through the published npm package. No need to clone or build locally!

With npx (Quick Start)

You can run the server directly using npx:

npx -y @prandogabriel/ieee2030.5-mcp

Claude Desktop Configuration (Published Package)

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ieee2030-5-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@prandogabriel/ieee2030.5-mcp@0.1.0"
      ],
      "env": {
        "IEEE2030_BASE_URL": "https://your-ieee2030-server:port",
        "IEEE2030_CERT_PATH": "/path/to/your/cert.pem",
        "IEEE2030_INSECURE": "true"
      }
    }
  }
}

Benefits of using the published package:

• ✅ No local setup required - just install and run
• ✅ Always up-to-date - specify version or use latest
• ✅ Automatic dependency management - npx handles everything
• ✅ Cross-platform compatibility - works on any system with Node.js

Configuration Steps:

1. Ensure Node.js 20+ is installed (see Prerequisites)
2. Add configuration to Claude Desktop using the JSON above
3. Update environment variables with your IEEE 2030.5 server details:
   • Replace https://your-ieee2030-server:port with your server URL
   • Replace /path/to/your/cert.pem with your certificate path
   • Set IEEE2030_INSECURE to "false" for production
4. Restart Claude Desktop
5. Test the connection:
   • Ask Claude: "Check the IEEE 2030.5 server status"
   • Ask Claude: "Show me the navigation guide for IEEE 2030.5 resources"

Using with Claude Desktop (Local Development)

To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ieee2030-5-mcp": {
      "command": "node",
      "args": [
        "/path/to/your/ieee2030.5-mcp/dist/index.js"
      ],
      "env": {
        "IEEE2030_BASE_URL": "https://your-ieee2030-server:port",
        "IEEE2030_CERT_PATH": "/path/to/your/cert.pem",
        "IEEE2030_INSECURE": "true"
      }
    }
  }
}

Configuration Steps:

1. Build your server first:

   cd /path/to/your/ieee2030.5-mcp
   pnpm build
   

2. Update the config with your actual paths:

   • Replace /path/to/your/ieee2030.5-mcp/dist/index.js with the full path to your built server
   • Replace https://your-ieee2030-server:port with your actual IEEE 2030.5 server URL
   • Replace /path/to/your/cert.pem with the path to your client certificate

3. Restart Claude Desktop for the changes to take effect

4. Test the connection:

   • Ask Claude: "Check the IEEE 2030.5 server status"
   • Ask Claude: "Get device capabilities from the IEEE 2030.5 server"
   • Ask Claude: "Show me the navigation guide for IEEE 2030.5 resources"

Using MCP Inspector

1. Start the inspector:

   pnpm debug
   

2. Test ieee2030_get_device_capabilities:

   • Open the inspector at http://localhost:5173
   • Click on "Tools" tab
   • Find ieee2030_get_device_capabilities in the list
   • Click "Execute" to test the tool
   • View the IEEE 2030.5 XML response in JSON format

3. Test custom endpoints:

   • Select ieee2030_get_custom_endpoint
   • Enter endpoint path like /dcap, /tm, /drp
   • Execute and see results

4. Access navigation guide:

   • Click on "Prompts" tab
   • Find ieee2030_navigation_guide
   • Click to view the comprehensive guide for navigating IEEE 2030.5 resources

Programmatic Usage

You can also connect to your MCP server programmatically using the MCP SDK:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { spawn } from 'node:child_process';

// Start your server process
const serverProcess = spawn('node', ['dist/index.js']);
const transport = new StdioClientTransport({
  reader: serverProcess.stdout,
  writer: serverProcess.stdin,
});

// Connect and use tools
const client = new Client({ name: 'my-client', version: '1.0.0' }, { capabilities: {} });
await client.connect(transport);

// Call IEEE 2030.5 tools
const response = await client.request({
  method: 'tools/call',
  params: { name: 'ieee2030_get_device_capabilities' }
}, { method: 'tools/call' });

Contributing

We welcome contributions to the IEEE 2030.5 MCP Server! Whether you're fixing bugs, adding features, improving documentation, or enhancing the navigation guide, your help is appreciated.

🚀 Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/your-username/ieee2030.5-mcp.git
   cd ieee2030.5-mcp
   

3. Install dependencies:

   pnpm install
   

4. Create a feature branch:

   git checkout -b feature/your-feature-name
   

🛠️ Development Guidelines

Code Style

• Follow existing TypeScript conventions
• Use Biome for linting and formatting: pnpm check:fix
• Write descriptive commit messages following conventional commits
• Add JSDoc comments for public APIs

Testing Your Changes

1. Build the project: pnpm build
2. Test with MCP Inspector: pnpm debug
3. Test with Claude Desktop using your local build
4. Verify all tools work with a real IEEE 2030.5 server (if available)

Code Quality Checklist

• Code builds without errors: pnpm build
• Linting passes: pnpm lint
• Formatting is correct: pnpm format
• All tools can be loaded in MCP Inspector
• Navigation guide reflects any new endpoints

🎯 Areas for Contribution

🐛 Bug Fixes

• Fix SSL/TLS connection issues
• Improve error handling and messages
• Resolve XML parsing edge cases

✨ Features

• New IEEE 2030.5 endpoints (e.g., pricing, messaging, historical data)
• Enhanced XML/JSON conversion with schema validation

📚 Documentation

• Expand navigation guide with more examples
• Add more IEEE 2030.5 resource patterns
• Create video tutorials or walkthroughs
• Improve error documentation

🧪 Testing

• Unit tests for client functions
• Integration tests with mock IEEE 2030.5 servers
• End-to-end tests with MCP protocol

📝 Contribution Workflow

1. Create an issue first (for larger changes)
2. Implement your changes:

   # Make your changes
   pnpm check:fix    # Format and lint
   pnpm build        # Test build
   pnpm debug        # Test functionality
   

3. Commit with conventional format:

   git add .
   git commit -m "feat: add support for new IEEE 2030.5 endpoint"
   # or
   git commit -m "fix: resolve SSL certificate validation issue"
   # or  
   git commit -m "docs: expand navigation guide with pricing examples"
   

4. Push and create PR:

   git push origin feature/your-feature-name
   

5. Open a Pull Request with:
   • Clear description of changes
   • Screenshots/examples if applicable
   • Reference to related issues

🏗️ Architecture Overview

Understanding the codebase structure:

src/
├── handlers/           # MCP request handlers
│   ├── tools-handler.ts    # Tool execution logic
│   └── prompts-handler.ts  # Prompt serving logic
├── prompts/           # MCP prompts
│   └── ieee2030-navigation-guide.ts
├── services/          # Core business logic
│   ├── config.ts          # Environment configuration
│   ├── ieee2030-5-client.ts  # IEEE 2030.5 HTTP client
│   └── ieee2030-5-types.ts   # TypeScript definitions
├── tools/             # MCP tools implementation
│   ├── ieee2030-connection-tools.ts
│   ├── ieee2030-data-tools.ts
│   └── tool-registry.ts
├── server.ts          # MCP server setup
└── index.ts           # Entry point

🤝 Community Guidelines

• Be respectful and inclusive in all interactions
• Ask questions if you're unsure about anything
• Help others by reviewing PRs and answering issues
• Follow the code of conduct (be kind and professional)

📧 Getting Help

• Open an issue for bugs or feature requests
• Start a discussion for questions or ideas
• Check existing issues before creating new ones

Thank you for contributing to the IEEE 2030.5 MCP Server! 🎉

Security Notes

• Always use HTTPS in production
• Store certificates securely
• Set IEEE2030_INSECURE=false in production
• Validate all server certificates in production environments
• Never commit .env files or certificates to version control

Troubleshooting

Common Issues

1. "IEEE2030_BASE_URL environment variable is required"

   • Set the IEEE2030_BASE_URL environment variable

2. "Certificate path or value is required"

   • Set either IEEE2030_CERT_PATH or IEEE2030_CERT_VALUE

3. SSL Certificate errors

   • For development: Set IEEE2030_INSECURE=true
   • For production: Ensure proper certificate chain

4. Connection timeouts

   • Increase IEEE2030_TIMEOUT value
   • Check network connectivity
   • Verify server URL and port