sibunting/evcharging-tools-mcp

EVCharging.tools MCP Server

MCP (Model Context Protocol) server providing tool-calling capabilities for the EVCharging.tools dataset.

Overview

This server acts as an HTTP shim for MCP tools, proxying requests to the existing evct-web API endpoints. It provides a standardized interface for LLMs to query EV charging infrastructure data.

Architecture

LLM → Chat API → MCP Server → evct-web API → Database

• Input: Structured tool calls with validation
• Processing: Data transformation and filtering
• Output: Standardized responses for LLM consumption

API Endpoints

Health Check

• GET /api/health - Service health and version info

MCP Tools

• POST /api/tools/search-models - Search for charger models
• POST /api/tools/get-model-by-id - Get model by UUID
• POST /api/tools/search-manufacturers - Search manufacturers
• POST /api/tools/get-manufacturer-by-id - Get manufacturer by UUID

Example requests

Search models (Netherlands, 7kW exact):

curl -sS -X POST "$MCP_BASE_URL/api/tools/search-models" \
  -H "Content-Type: application/json" \
  -d '{
    "manufacturerCountry": "NL",
    "powerKwMin": 7,
    "powerKwMax": 7,
    "limit": 5,
    "offset": 0
  }'

Search manufacturers (country=NL):

curl -sS -X POST "$MCP_BASE_URL/api/tools/search-manufacturers" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NL",
    "limit": 5,
    "offset": 0
  }'

Features

Data Transformation

• Country normalization: "Netherlands" → "NL" (ISO-3166-1 alpha-2)
• Power tolerance: 7kW searches expand to 6.5-7.5kW range if no exact match
• Filter mapping: Tool parameters → API query parameters

Validation

• Zod schema validation for all inputs
• UUID format validation
• Parameter range limits (1-100 for limits)

Error Handling

• Structured error responses
• Request/response logging
• Graceful API failure handling

Development

Local Setup

npm install
npm run dev  # Runs on port 4001

Environment Variables

EVCT_WEB_API_URL=https://evct-web.vercel.app/api/v1  # Production API
PORT=4001  # Local development port

Testing

# Health check
curl http://localhost:4001/api/health

# Search models (Netherlands, 7kW)
curl -X POST http://localhost:4001/api/tools/search-models \
  -H "Content-Type: application/json" \
  -d '{"manufacturerCountry": "NL", "powerKwMin": 7, "powerKwMax": 7}'

Deployment

Vercel (Recommended)

vercel --prod

Environment Variables (Production)

• EVCT_WEB_API_URL: https://evct-web.vercel.app/api/v1
• NODE_ENV: production

Tool Schemas

Search Models Input

{
  q?: string;                    // General search query
  powerKwMin?: number;           // Minimum power in kW
  powerKwMax?: number;           // Maximum power in kW
  acOrDc?: 'AC' | 'DC';         // Charger type
  manufacturerCountry?: string;  // ISO-3166-1 alpha-2 country code
  manufacturerName?: string;     // Manufacturer name search
  ocppVersion?: string;          // OCPP protocol version
  limit?: number;                // Results limit (1-100, default 25)
  offset?: number;               // Results offset (default 0)
}

Response Format

{
  items: Model[];     // Array of matching models
  total: number;      // Total count (before pagination)
  offset: number;     // Applied offset
  limit: number;      // Applied limit
}

Integration

This MCP server is designed to integrate with:

• OpenAI Functions: Direct tool-calling support
• Vercel AI SDK: Streaming chat responses
• evct-web: Existing stable API endpoints

Future Enhancements

• Native MCP transport (beyond HTTP shim)
• Enhanced caching layer
• Additional tool endpoints (protocols, regulations, grants)
• User authentication and preferences
• Real-time data synchronization