@ampeco/public-api-mcp 0.2.2 → 0.4.0

package/dist/server/index.js

@@ -3,1397 +3,14 @@
  *
  * This server exposes pre-processed OpenAPI endpoints as MCP resources and provides
  * a tool for making authenticated HTTP requests to any endpoint.
+ *
+ * This is the legacy standalone server. Consider using http.ts or stdio.ts instead.
  */
 import express from 'express';
 import cors from 'cors';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { z } from 'zod';
-import { readFileSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import fetch from 'node-fetch';
-// Get the directory name for ES modules
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-/**
- * Load pre-processed endpoints from build artifacts
- */
-function loadEndpoints() {
-    const endpointsPath = join(__dirname, '../generated/endpoints.json');
-    const content = readFileSync(endpointsPath, 'utf-8');
-    return JSON.parse(content);
-}
-/**
- * Create and configure the MCP server
- */
-function createServer(endpoints, bearerToken, hostname) {
-    const server = new McpServer({
-        name: 'public-api-mcp',
-        version: '0.1.0',
-    }, {
-        capabilities: {
-            resources: {},
-            tools: {},
-            prompts: {},
-            logging: {},
-        },
-        instructions: `This server provides access to the ${endpoints.info.title} API (v${endpoints.info.version}).
-
-It exposes ${endpoints.endpoints.filter(e => !e.deprecated).length} active API endpoints through a hierarchical resource structure (deprecated endpoints are automatically filtered out) and provides a tool for making authenticated HTTP requests.
-
-Target API: ${hostname}
-
-Resource Structure (3-tier hierarchy):
-- Tier 1 (Discovery): List resources returns API tags (e.g., tag://Users, tag://ChargingSessions)
-- Tier 2 (Navigation): Read a tag resource to see all endpoints within that tag
-- Tier 3 (Details): Read an individual endpoint resource for full specification
-
-Usage:
-1. List available resources to discover API tags (returns ~10-30 tags instead of 443 endpoints)
-2. Read a tag resource (e.g., tag://Users) to see all endpoints within that tag
-3. Read an endpoint resource (e.g., api://GET/users/{id}) to get detailed endpoint information
-4. Use the 'api_request' tool to make HTTP calls to any endpoint
-
-URI Formats:
-- Tags: tag://{TagName} (e.g., tag://Users)
-- Endpoints: api://{METHOD}{path} (e.g., api://GET/users/{id})
-
-The server automatically proxies your Bearer token to all API requests to ${hostname}.
-
-Note: Deprecated endpoints are not exposed as resources and cannot be accessed. This hierarchical structure reduces initial context consumption by ~95-97%.
-
-## Available Prompts
-
-This server provides helpful prompts for common workflows. Use these prompts to learn best practices:
-
-- **charging_session_workflow**: Learn how to implement the complete charging session lifecycle: finding charge points, starting/stopping sessions, and retrieving session details
-- **authentication_workflow**: Understand how authentication works with the AMPECO API and how to implement custom authentication in your backend
-- **reservation_workflow**: Learn how to reserve charge points for immediate or future use
-- **smart_charging_setup**: Guide for configuring smart charging modes including scheduled, solar, and dynamic pricing strategies
-
-To use a prompt, simply reference it by name when you need guidance on these workflows.
-
-## AMPECO API Resource Relationships
-
-The AMPECO API has a hierarchical structure: **Locations** → **Charging Zones** → **Charge Points** → **EVSEs** → **Connectors**
-
-Each resource can be listed independently. EVSEs contain the currentType field ("ac"/"dc") for determining charging type.
-
-## Best Practices for Data Fetching
-
-**Always prefer top-level listing endpoints over nested fetching:**
-- ✅ Use \`GET /evses\` to get all EVSEs across all charge points (1 API call)
-- ❌ Avoid fetching \`GET /charge-points/{id}/evses\` for each charge point (N API calls)
-
-The top-level listing endpoints are more efficient and reduce API load. Use nested endpoints only when you specifically need resources for a single parent entity.
-
-## Session State & Webhooks
-
-The AMPECO API is event-driven and uses webhooks for real-time updates. When performing actions like starting/stopping charging sessions:
-- Initial API responses return immediately with session IDs
-- Actual state changes arrive via webhooks (SessionUpdateNotification, SessionMeterValuesNotification)
-- Clients should implement webhook handlers to track session status changes from "pending" → "active" → "finished"
-- Session details and final metrics are retrieved via GET requests after receiving webhook notifications
-
-## Cursor Pagination Guide
-
-Many list endpoints support cursor-based pagination, which is faster and more reliable than offset-based pagination. Here's how to use it:
-
-**Initial Request** - Start with an empty cursor:
-\`\`\`
-api_request(endpoint: "/users", method: "GET", query_params: { limit: 100, cursor: "" })
-\`\`\`
-
-**Subsequent Requests** - Use the cursor from the previous response:
-\`\`\`
-api_request(endpoint: "/users", method: "GET", query_params: { limit: 100, cursor: "eyJpZCI6MTAwfQ==" })
-\`\`\`
-
-**Pagination Loop:**
-1. Start with \`cursor=""\` (empty string)
-2. Make request with current cursor
-3. Collect items from response
-4. If response contains a non-empty cursor, use it for next request
-5. Stop when cursor is null/empty or data array is empty
-
-**Key Points:**
-- ✅ Always use \`cursor=""\` for first request
-- ✅ Use exact cursor value from responses
-- ✅ Check for null/empty cursor or empty data array to detect end
-- ✅ Adjust limit based on data size (100-1000 typical)
-- ❌ Don't use offset pagination when cursor is available`,
-    });
-    // Use the underlying Server API for dynamic resource handling with many endpoints
-    // This gives us more control than the higher-level .resource() method
-    // Register resources/list handler - returns tags (Tier 1)
-    server.server.setRequestHandler(ListResourcesRequestSchema, async () => {
-        const startTime = Date.now();
-        console.log(`[Resources List] Building tag-based resource list...`);
-        // Filter out deprecated endpoints first
-        const activeEndpoints = endpoints.endpoints.filter(endpoint => !endpoint.deprecated);
-        // Extract unique tags from all active endpoints
-        const tagsSet = new Set();
-        let untaggedCount = 0;
-        for (const endpoint of activeEndpoints) {
-            if (endpoint.tags && endpoint.tags.length > 0) {
-                endpoint.tags.forEach(tag => tagsSet.add(tag));
-            }
-            else {
-                untaggedCount++;
-            }
-        }
-        // Convert to sorted array
-        const tags = Array.from(tagsSet).sort();
-        // Add "Untagged" category if there are untagged endpoints
-        if (untaggedCount > 0) {
-            tags.push('Untagged');
-        }
-        // Build resources list with tag URIs
-        const resources = tags.map(tag => {
-            const tagEndpoints = activeEndpoints.filter(e => tag === 'Untagged'
-                ? !e.tags || e.tags.length === 0
-                : e.tags?.includes(tag));
-            return {
-                uri: `tag://${tag}`,
-                name: tag,
-                description: `${tagEndpoints.length} endpoint${tagEndpoints.length !== 1 ? 's' : ''} tagged with '${tag}'`,
-                mimeType: 'application/json',
-            };
-        });
-        const duration = Date.now() - startTime;
-        console.log(`[Resources List] Built ${resources.length} tag resources (filtered ${endpoints.endpoints.length - activeEndpoints.length} deprecated endpoints) in ${duration}ms`);
-        return { resources };
-    });
-    // Register resources/read handler - supports tag:// (Tier 2) and api:// (Tier 3) URIs
-    server.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-        const uri = request.params.uri;
-        // Manual URI parsing to handle spaces and special characters in tag names
-        // Format: tag://{TagName} or api://{METHOD}{path}
-        const protocolMatch = uri.match(/^([^:]+):\/\/(.*)$/);
-        if (!protocolMatch) {
-            throw new Error(`Invalid URI format: ${uri}`);
-        }
-        const protocol = protocolMatch[1];
-        const remainder = protocolMatch[2];
-        // Tier 2: Handle tag:// URIs - return list of endpoints within the tag
-        if (protocol === 'tag') {
-            const tag = remainder;
-            // Filter active endpoints by tag
-            const activeEndpoints = endpoints.endpoints.filter(endpoint => !endpoint.deprecated);
-            const taggedEndpoints = activeEndpoints.filter(e => tag === 'Untagged'
-                ? !e.tags || e.tags.length === 0
-                : e.tags?.includes(tag));
-            if (taggedEndpoints.length === 0) {
-                throw new Error(`No endpoints found for tag: ${tag}`);
-            }
-            // Build response with endpoint summaries
-            const tagResource = {
-                tag,
-                count: taggedEndpoints.length,
-                endpoints: taggedEndpoints.map(e => ({
-                    uri: `api://${e.method.toUpperCase()}${e.path}`,
-                    method: e.method.toUpperCase(),
-                    path: e.path,
-                    summary: e.summary || e.operationId || `${e.method} ${e.path}`,
-                    operationId: e.operationId,
-                })),
-            };
-            return {
-                contents: [
-                    {
-                        uri,
-                        mimeType: 'application/json',
-                        text: JSON.stringify(tagResource, null, 2),
-                    },
-                ],
-            };
-        }
-        // Tier 3: Handle api:// URIs - return individual endpoint details
-        if (protocol === 'api') {
-            // Parse URI format: api://METHOD/path
-            // Example: api://POST/users or api://GET/users/{id}
-            const match = remainder.match(/^([A-Z]+)(\/.*)/);
-            if (!match) {
-                throw new Error(`Invalid API URI format: ${uri}`);
-            }
-            const method = match[1];
-            const path = match[2];
-            // Find the matching endpoint
-            const endpoint = endpoints.endpoints.find((e) => e.path === path && e.method.toUpperCase() === method.toUpperCase());
-            if (!endpoint) {
-                throw new Error(`Endpoint not found: ${method} ${path}`);
-            }
-            // Reject deprecated endpoints
-            if (endpoint.deprecated) {
-                throw new Error(`Endpoint is deprecated: ${method} ${path}`);
-            }
-            // Return comprehensive endpoint information
-            return {
-                contents: [
-                    {
-                        uri,
-                        mimeType: 'application/json',
-                        text: JSON.stringify(endpoint, null, 2),
-                    },
-                ],
-            };
-        }
-        // Unsupported protocol
-        throw new Error(`Unsupported URI protocol: ${protocol}. Expected 'tag' or 'api'`);
-    });
-    // Register the API request tool
-    server.tool('api_request', `Make an authenticated HTTP request to any active API endpoint from the OpenAPI specification. Deprecated endpoints cannot be called and will return an error. Authentication is handled automatically using the Bearer token from the MCP request. The target API hostname is: ${hostname}
-
-CRITICAL - NEVER GUESS: You MUST read the endpoint resource first (using api://{METHOD}{path} URI) before calling this tool. DO NOT guess parameter names, request body structure, or query parameters. The endpoint resource contains the complete specification including all required/optional parameters, request body schema, and response format. Guessing will result in API errors.
-
-IMPORTANT - Pagination: Always prefer cursor-based pagination when available. For list endpoints that support both offset and cursor pagination, you MUST use cursor pagination by including an empty "cursor" query parameter (cursor="") in your initial request to engage cursor-based pagination. Subsequent requests should use the cursor value returned in the response.`, {
-        endpoint: z.string().describe('The API endpoint path (e.g., "/users/{id}")'),
-        method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']).describe('HTTP method'),
-        path_params: z.preprocess((val) => (val === null || val === undefined || val === '' ? {} : val), z.record(z.any()).default({})).optional().describe('Path parameter values as key-value pairs (optional)'),
-        query_params: z.preprocess((val) => (val === null || val === undefined || val === '' ? {} : val), z.record(z.any()).default({})).optional().describe('Query string parameters as key-value pairs (optional)'),
-        body: z.preprocess((val) => (val === null || val === undefined || val === '' ? undefined : val), z.any()).optional().describe('Request body for POST/PUT/PATCH requests (optional)'),
-        headers: z.preprocess((val) => (val === null || val === undefined || val === '' ? {} : val), z.record(z.string()).default({})).optional().describe('Additional HTTP headers (optional)'),
-    }, async (args) => {
-        const { endpoint, method, path_params = {}, query_params = {}, body, headers = {}, } = args;
-        // Check if endpoint is deprecated
-        const endpointDef = endpoints.endpoints.find((e) => e.path === endpoint && e.method.toUpperCase() === method.toUpperCase());
-        if (endpointDef?.deprecated) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            error: true,
-                            message: `Endpoint is deprecated and cannot be called: ${method} ${endpoint}`,
-                        }, null, 2),
-                    },
-                ],
-                isError: true,
-            };
-        }
-        // Construct the full URL
-        let url = hostname.replace(/\/$/, '') + endpoint;
-        // Replace path parameters
-        for (const [key, value] of Object.entries(path_params)) {
-            url = url.replace(`{${key}}`, encodeURIComponent(String(value)));
-        }
-        // Add query parameters
-        const queryString = Object.entries(query_params)
-            .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
-            .join('&');
-        if (queryString) {
-            url += `?${queryString}`;
-        }
-        // Prepare headers with proxied Bearer token
-        const requestHeaders = {
-            'Content-Type': 'application/json',
-            ...headers,
-        };
-        // Add Authorization header if bearer token is available
-        if (bearerToken) {
-            requestHeaders['Authorization'] = `Bearer ${bearerToken}`;
-        }
-        // Log the request
-        console.log(`[API Request] ${method} ${url}`);
-        try {
-            // Prepare fetch options
-            const fetchOptions = {
-                method,
-                headers: requestHeaders,
-            };
-            // Only include body for methods that support it (not GET/HEAD)
-            if (body && !['GET', 'HEAD'].includes(method.toUpperCase())) {
-                fetchOptions.body = JSON.stringify(body);
-            }
-            // Make the HTTP request
-            const response = await fetch(url, fetchOptions);
-            // Parse response
-            const rawResponseText = await response.text();
-            let responseBody;
-            try {
-                responseBody = rawResponseText ? JSON.parse(rawResponseText) : null;
-            }
-            catch {
-                responseBody = rawResponseText;
-            }
-            // Log the response
-            console.log(`[API Response] ${response.status} ${response.statusText}`);
-            // Prepare structured response with truncation
-            const responseObject = {
-                status: response.status,
-                statusText: response.statusText,
-                headers: Object.fromEntries(response.headers.entries()),
-                body: responseBody,
-            };
-            let responseText = JSON.stringify(responseObject, null, 2);
-            // Truncate if response exceeds 20000 characters (leaving room for metadata)
-            const MAX_RESPONSE_LENGTH = 20000;
-            let wasTruncated = false;
-            if (responseText.length > MAX_RESPONSE_LENGTH) {
-                wasTruncated = true;
-                const originalLength = responseText.length;
-                responseText = responseText.substring(0, MAX_RESPONSE_LENGTH);
-                // Try to truncate at a reasonable boundary (end of a line)
-                const lastNewlineIndex = responseText.lastIndexOf('\n');
-                if (lastNewlineIndex > MAX_RESPONSE_LENGTH * 0.9) {
-                    responseText = responseText.substring(0, lastNewlineIndex);
-                }
-                // Add truncation notice
-                responseText += `\n\n... [Response truncated - original size: ${originalLength} characters, showing first ${responseText.length} characters]\n\nNote: The response was too large to display in full. This is typically because the API returned detailed error information or a large dataset. Check the status code and the visible portion of the response for key information.`;
-            }
-            const toolResponse = {
-                content: [
-                    {
-                        type: 'text',
-                        text: responseText,
-                    },
-                ],
-            };
-            console.log(`[Tool Response] Returning response with ${responseText.length} characters${wasTruncated ? ' (truncated)' : ''}`);
-            // Return structured response
-            return toolResponse;
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            console.error(`[API Error] ${errorMessage}`);
-            const errorObject = {
-                error: true,
-                message: errorMessage,
-                details: error instanceof Error ? error.stack : undefined,
-            };
-            let errorText = JSON.stringify(errorObject, null, 2);
-            // Truncate error responses too
-            const MAX_ERROR_LENGTH = 5000;
-            if (errorText.length > MAX_ERROR_LENGTH) {
-                errorText = errorText.substring(0, MAX_ERROR_LENGTH) + '\n\n... [Error message truncated]';
-            }
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: errorText,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-    // Register prompts for common workflows
-    server.server.setRequestHandler(ListPromptsRequestSchema, async () => {
-        return {
-            prompts: [
-                {
-                    name: 'charging_session_workflow',
-                    description: 'Learn how to implement the complete charging session lifecycle: finding charge points, starting/stopping sessions, and retrieving session details',
-                    arguments: [
-                        {
-                            name: 'evseId',
-                            description: 'The EVSE network ID to start charging on (optional - if not provided, guidance will be generic)',
-                            required: false,
-                        },
-                        {
-                            name: 'sessionId',
-                            description: 'The session ID to monitor or stop (optional - if not provided, guidance will be generic)',
-                            required: false,
-                        },
-                    ],
-                },
-                {
-                    name: 'authentication_workflow',
-                    description: 'Understand how authentication works with the AMPECO API and how to implement custom authentication in your backend',
-                    arguments: [],
-                },
-                {
-                    name: 'reservation_workflow',
-                    description: 'Learn how to reserve charge points for immediate or future use',
-                    arguments: [
-                        {
-                            name: 'chargePointId',
-                            description: 'The charge point ID to reserve (optional)',
-                            required: false,
-                        },
-                        {
-                            name: 'evseNetworkId',
-                            description: 'The EVSE network ID to reserve (optional)',
-                            required: false,
-                        },
-                        {
-                            name: 'userId',
-                            description: 'The user ID making the reservation (optional)',
-                            required: false,
-                        },
-                        {
-                            name: 'reservationType',
-                            description: 'Type of reservation: "immediate" or "future" (optional, defaults to immediate)',
-                            required: false,
-                        },
-                    ],
-                },
-                {
-                    name: 'smart_charging_setup',
-                    description: 'Guide for configuring smart charging modes including scheduled, solar, and dynamic pricing strategies',
-                    arguments: [
-                        {
-                            name: 'chargePointId',
-                            description: 'The charge point ID to configure (optional)',
-                            required: false,
-                        },
-                        {
-                            name: 'mode',
-                            description: 'Smart charging mode to configure: "scheduled", "solar", "octopus_agile", "octopus_go", "nordpool", or "energi_elspot" (optional)',
-                            required: false,
-                        },
-                    ],
-                },
-            ],
-        };
-    });
-    server.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-        const promptName = request.params.name;
-        const args = request.params.arguments || {};
-        switch (promptName) {
-            case 'charging_session_workflow': {
-                const evseId = args.evseId;
-                const sessionId = args.sessionId;
-                let specificGuidance = '';
-                if (evseId) {
-                    specificGuidance += `\n## Specific Task: Work with EVSE ${evseId}\n\nYou have been provided with EVSE ID: ${evseId}\nUse this ID when starting a charging session in Step 2.\n`;
-                }
-                if (sessionId) {
-                    specificGuidance += `\n## Specific Task: Monitor/Stop Session ${sessionId}\n\nYou have been provided with session ID: ${sessionId}\nUse this ID to retrieve session details or stop the charging session.\n`;
-                }
-                return {
-                    messages: [
-                        {
-                            role: 'user',
-                            content: {
-                                type: 'text',
-                                text: `# Charging Session Workflow${specificGuidance}
-
-This guide explains how to implement a complete EV charging session using the AMPECO API.
-
-## Overview
-
-The charging session lifecycle follows this sequence:
-1. **Discovery**: Find available charge points
-2. **Start Session**: Initiate charging
-3. **Monitor**: Track session progress via webhooks
-4. **Stop Session**: End charging
-5. **Retrieve Details**: Get final session metrics and billing
-
-## Step 1: Find Available Charge Points
-
-Use the top-level listing endpoints to discover charging infrastructure:
-
-**Get Locations:**
-\`\`\`
-GET /resources/locations/v1.0
-\`\`\`
-Returns all locations with geographic coordinates and availability status.
-
-**Get Charge Points:**
-\`\`\`
-GET /resources/charge-points/v1.0?status=active&accessType=public&networkStatus=available
-\`\`\`
-Filter for active, public, and available charge points.
-
-**Get EVSEs (Recommended for charging type):**
-\`\`\`
-GET /resources/evses
-\`\`\`
-EVSEs contain the \`currentType\` field ("ac" or "dc") which tells you the charging type. Each EVSE belongs to a charge point and contains connectors.
-
-## Step 2: Start a Charging Session
-
-**Endpoint:**
-\`\`\`
-POST /actions/evse/v1.0/{evseId}/start
-\`\`\`
-
-**Required Parameters:**
-- \`evseId\`: The EVSE network ID (from Step 1)
-
-**Response:**
-\`\`\`json
-{
-  "success": true,
-  "sessionId": 12345,
-  "message": "Session starting..."
-}
-\`\`\`
-
-**Important:** The response returns immediately with a session ID, but the session is not yet active.
-
-## Step 3: Monitor Session Status
-
-**Webhook Notifications:**
-
-The AMPECO API is event-driven. After starting a session, you will receive:
-
-1. **First Notification - SessionUpdateNotification:**
-   - Status: \`"pending"\`
-   - Indicates session is being prepared
-
-2. **Second Notification - SessionUpdateNotification:**
-   - Status: \`"active"\`
-   - Charging has started
-
-3. **Ongoing - SessionMeterValuesNotification:**
-   - Contains real-time energy consumption (in Wh)
-   - Provides meter readings during charging
-
-**To get current session details:**
-\`\`\`
-GET /resources/sessions/v1.0/{sessionId}
-\`\`\`
-
-## Step 4: Stop Charging Session
-
-**Endpoint:**
-\`\`\`
-POST /actions/charge-point/v1.0/{chargePointId}/stop/{sessionId}
-\`\`\`
-
-**Required Parameters:**
-- \`chargePointId\`: The charge point ID
-- \`sessionId\`: The session ID from Step 2
-
-**Response:**
-Returns confirmation that stop request was sent.
-
-**Webhook Notification:**
-You will receive a \`SessionUpdateNotification\` with status \`"finished"\` when the session has fully terminated.
-
-## Step 5: Retrieve Final Session Details
-
-**Endpoint:**
-\`\`\`
-GET /resources/sessions/v1.0/{sessionId}
-\`\`\`
-
-**Wait for:** The \`SessionUpdateNotification\` webhook with status \`"finished"\` before retrieving final details.
-
-**Response includes:**
-- Total energy consumed (kWh)
-- State of charge percentage
-- Total amount charged (billing)
-- Payment status
-- Charging periods breakdown
-- Price breakdown by tariff components
-- Complete tariff snapshot
-
-## Best Practices
-
-1. **Use webhooks for state changes** - Don't poll for status updates
-2. **Wait for "finished" status** - Final metrics are only accurate after session completes
-3. **Use top-level EVSE listing** - More efficient than nested queries
-4. **Check currentType** - Verify AC vs DC compatibility before starting session
-5. **Handle webhook delays** - Status changes may take 10-30 seconds
-
-## Error Handling
-
-- If start request fails, check EVSE availability and network status
-- If session doesn't transition to "active" within 60 seconds, check charge point hardware status
-- If stop request fails, the session may already be finished or the charge point may be offline`,
-                            },
-                        },
-                    ],
-                };
-            }
-            case 'authentication_workflow': {
-                // No arguments needed for this workflow - it's purely educational
-                return {
-                    messages: [
-                        {
-                            role: 'user',
-                            content: {
-                                type: 'text',
-                                text: `# Authentication Workflow
-
-This guide explains how authentication works with the AMPECO Public API and how to implement it in your application.
-
-## Important: No Client-Level Authentication
-
-**The AMPECO Public API does NOT provide client-level authentication or authorization for mobile apps or end users.**
-
-This means:
-- There is no \`/login\` endpoint for end users
-- There is no user session management in the API
-- You cannot directly authenticate mobile app users against the API
-- You MUST implement your own authentication layer
-
-## Authentication Architecture
-
-\`\`\`
-Mobile App → Custom Backend → AMPECO Public API
-              (Your Auth)      (Bearer Token)
-\`\`\`
-
-### What You Build (Custom Backend)
-1. User registration and login endpoints
-2. Password hashing and validation
-3. Session/JWT token management for your users
-4. User credential storage in your database
-5. Authorization logic (who can access what)
-
-### What AMPECO Provides
-- **Admin-level Bearer Token** for your backend to call the API
-- User resource management via \`POST /resources/users\` (create users in AMPECO system)
-- User-scoped data filtering on API endpoints
-
-## Implementation Guide
-
-### Step 1: User Registration
-
-**Your Backend:**
-1. Accept user registration (email, password, name) from mobile app
-2. Hash password and store in your database
-3. Call AMPECO API to create user resource:
-
-\`\`\`
-POST /resources/users
-Authorization: Bearer YOUR_ADMIN_TOKEN
-Content-Type: application/json
-
-{
-  "email": "user@example.com",
-  "first_name": "John",
-  "last_name": "Doe"
-}
-\`\`\`
-
-4. Store AMPECO user ID alongside your user record
-5. Return success to mobile app
-
-### Step 2: User Login
-
-**Your Backend:**
-1. Accept login credentials (email, password) from mobile app
-2. Validate credentials against your database
-3. Generate your own session token/JWT
-4. Return token to mobile app
-
-**Mobile App:**
-- Store your session token
-- Include it in all requests to your backend
-- Your backend validates this token on each request
-
-### Step 3: Making API Calls on Behalf of Users
-
-**Your Backend:**
-1. Validate user's session token
-2. Retrieve user's AMPECO user ID from your database
-3. Call AMPECO API with admin Bearer token
-4. Use user filters to scope requests:
-
-\`\`\`
-GET /resources/sessions/v1.0?userId={ampecoUserId}
-Authorization: Bearer YOUR_ADMIN_TOKEN
-\`\`\`
-
-This returns only sessions for that specific user.
-
-### Step 4: Securing the Bearer Token
-
-**Critical Security Practices:**
-
-1. **NEVER expose admin Bearer token to mobile apps**
-   - Token stays on your backend only
-   - Mobile apps never see or use it
-
-2. **Store token securely:**
-   - Environment variables (recommended)
-   - Secrets management service (AWS Secrets Manager, etc.)
-   - Never commit to git
-
-3. **Use HTTPS:**
-   - All communication between mobile app and your backend
-   - All communication between your backend and AMPECO API
-
-## User-Scoped API Requests
-
-Many AMPECO endpoints support filtering by user:
-
-**Sessions:**
-\`\`\`
-GET /resources/sessions/v1.0?userId={id}
-\`\`\`
-
-**Charge Points (user's favorites/home chargers):**
-\`\`\`
-GET /resources/charge-points/v1.0?userId={id}
-\`\`\`
-
-**Reservations:**
-\`\`\`
-GET /resources/reservations?userId={id}
-\`\`\`
-
-Always use these filters to ensure users only see their own data.
-
-## Example Flow: Start Charging Session
-
-\`\`\`
-1. Mobile app → Your backend: "Start charging at EVSE 123"
-   Headers: Authorization: Bearer YOUR_USER_SESSION_TOKEN
-
-2. Your backend validates user session token
-
-3. Your backend → AMPECO API:
-   POST /actions/evse/v1.0/123/start
-   Headers: Authorization: Bearer YOUR_ADMIN_TOKEN
-
-4. AMPECO API → Your backend: {"sessionId": 456}
-
-5. Your backend → Mobile app: {"sessionId": 456}
-\`\`\`
-
-## Best Practices
-
-1. **Implement rate limiting** - Protect your backend from abuse
-2. **Log API calls** - Track which user triggered which AMPECO API call
-3. **Handle token expiration** - Refresh admin token if needed
-4. **Validate user ownership** - Ensure users can only stop their own sessions, etc.
-5. **Use webhook authentication** - Verify webhooks are actually from AMPECO
-
-## Summary
-
-- **You build:** User authentication, session management, password security
-- **AMPECO provides:** Admin-level API access, user resource storage, user-scoped filtering
-- **Your backend** acts as a trusted intermediary between untrusted mobile apps and the AMPECO API`,
-                            },
-                        },
-                    ],
-                };
-            }
-            case 'reservation_workflow': {
-                const chargePointId = args.chargePointId;
-                const evseNetworkId = args.evseNetworkId;
-                const userId = args.userId;
-                const reservationType = args.reservationType || 'immediate';
-                let specificGuidance = '';
-                if (chargePointId || evseNetworkId || userId) {
-                    specificGuidance += `\n## Specific Task: Create ${reservationType === 'future' ? 'Future' : 'Immediate'} Reservation\n\n`;
-                    if (userId)
-                        specificGuidance += `User ID: ${userId}\n`;
-                    if (chargePointId)
-                        specificGuidance += `Charge Point ID: ${chargePointId}\n`;
-                    if (evseNetworkId)
-                        specificGuidance += `EVSE Network ID: ${evseNetworkId}\n`;
-                    specificGuidance += `\nUse these IDs when creating the reservation in the examples below.\n`;
-                }
-                return {
-                    messages: [
-                        {
-                            role: 'user',
-                            content: {
-                                type: 'text',
-                                text: `# Reservation Workflow${specificGuidance}
-
-This guide explains how to reserve charge points using the AMPECO API for both immediate and future use.
-
-## Overview
-
-Reservations allow users to guarantee access to a specific charge point or EVSE. AMPECO supports two types:
-1. **Immediate Reservation** ("Reserve Now") - Reserve for use right now
-2. **Future Reservation** - Reserve for a specific date/time in the future
-
-## Reservation Endpoint
-
-\`\`\`
-POST /actions/charge-point/v1.0/{chargePointId}/reserve/{evseNetworkId}
-\`\`\`
-
-**Path Parameters:**
-- \`chargePointId\`: The charge point ID (number)
-- \`evseNetworkId\`: The EVSE network ID (string) - specific connector to reserve
-
-**Request Body:**
-\`\`\`json
-{
-  "userId": 123,
-  "reason": "User requested reservation"
-}
-\`\`\`
-
-## Immediate Reservation ("Reserve Now")
-
-**Use Case:** User wants to reserve a charge point to use immediately.
-
-**Steps:**
-
-1. **Find available charge point:**
-\`\`\`
-GET /resources/charge-points/v1.0?networkStatus=available&hardwareStatus=available
-\`\`\`
-
-2. **Get EVSE details:**
-\`\`\`
-GET /resources/evses?chargePointId={chargePointId}
-\`\`\`
-Note the \`networkId\` field from the EVSE you want to reserve.
-
-3. **Create immediate reservation:**
-\`\`\`
-POST /actions/charge-point/v1.0/{chargePointId}/reserve/{evseNetworkId}
-Content-Type: application/json
-Authorization: Bearer YOUR_TOKEN
-
-{
-  "userId": 123,
-  "reason": "Immediate charging needed"
-}
-\`\`\`
-
-**Response:**
-\`\`\`json
-{
-  "success": true,
-  "reservationId": 456,
-  "status": "accepted",
-  "message": "Reservation created successfully"
-}
-\`\`\`
-
-4. **Start charging session** (user should plug in soon):
-\`\`\`
-POST /actions/evse/v1.0/{evseNetworkId}/start
-\`\`\`
-
-**Important:** Immediate reservations typically expire after 10-15 minutes if not used.
-
-## Future Reservation
-
-**Use Case:** User wants to reserve a charge point for a specific time (e.g., tomorrow at 8 AM).
-
-**Steps:**
-
-1. **Identify charge point and EVSE** (same as immediate reservation)
-
-2. **Create future reservation:**
-\`\`\`
-POST /actions/charge-point/v1.0/{chargePointId}/reserve/{evseNetworkId}
-Content-Type: application/json
-Authorization: Bearer YOUR_TOKEN
-
-{
-  "userId": 123,
-  "reason": "Reserved for tomorrow morning",
-  "expiryDate": "2025-10-11T08:00:00Z",
-  "reservationStart": "2025-10-11T08:00:00Z"
-}
-\`\`\`
-
-**Note:** Check the OpenAPI spec for exact field names - the API may use \`startDateTime\` or similar fields for scheduling.
-
-**Response:**
-\`\`\`json
-{
-  "success": true,
-  "reservationId": 789,
-  "status": "scheduled",
-  "startTime": "2025-10-11T08:00:00Z",
-  "expiryTime": "2025-10-11T09:00:00Z"
-}
-\`\`\`
-
-## Managing Reservations
-
-### List User's Reservations
-\`\`\`
-GET /resources/reservations?userId={userId}
-\`\`\`
-
-Returns all active and past reservations for the user.
-
-### Get Reservation Details
-\`\`\`
-GET /resources/reservations/{reservationId}
-\`\`\`
-
-### Cancel Reservation
-Check the OpenAPI spec for the cancel endpoint (typically):
-\`\`\`
-DELETE /resources/reservations/{reservationId}
-\`\`\`
-or
-\`\`\`
-POST /actions/charge-point/v1.0/{chargePointId}/cancel-reservation/{reservationId}
-\`\`\`
-
-## Reservation States
-
-Reservations go through these states:
-- **accepted** - Reservation created successfully
-- **scheduled** - Future reservation waiting for start time
-- **active** - Reservation time window is now active
-- **expired** - Reservation time passed without use
-- **used** - User started charging session with this reservation
-- **cancelled** - Reservation was cancelled
-
-## Error Handling
-
-### Reservation Fails
-Common reasons:
-- EVSE already reserved by another user
-- Charge point offline or unavailable
-- Invalid user ID
-- Invalid time range (past date, too far in future)
-
-**Check response:**
-\`\`\`json
-{
-  "success": false,
-  "status": "rejected",
-  "message": "EVSE already reserved for that time"
-}
-\`\`\`
-
-**Recovery steps:**
-1. Try different EVSE at same location
-2. Adjust reservation time window
-3. Find alternative charge point
-
-### Reservation Expires
-If user doesn't show up:
-- Immediate reservations expire after 10-15 minutes
-- Future reservations expire after the scheduled time window ends
-- EVSE becomes available for other users
-- User's reservation record shows "expired" status
-
-## Best Practices
-
-1. **Check availability before reserving** - Use \`networkStatus\` and \`hardwareStatus\` filters
-2. **Provide clear reason** - Helps with debugging and user support
-3. **Set appropriate expiry** - Don't hold EVSEs longer than needed
-4. **Notify users** - Send reminders before reservation time
-5. **Handle expiry gracefully** - Let users know if their reservation expired
-6. **Allow cancellation** - Users should be able to cancel if plans change
-
-## Example: Reserve for Scheduled Charging
-
-**Scenario:** User wants to charge during cheap electricity hours (2 AM - 6 AM).
-
-1. **Create overnight reservation:**
-\`\`\`
-POST /actions/charge-point/v1.0/42/reserve/EVSE-001
-{
-  "userId": 123,
-  "reason": "Scheduled charging during off-peak hours",
-  "reservationStart": "2025-10-11T02:00:00Z",
-  "expiryDate": "2025-10-11T06:00:00Z"
-}
-\`\`\`
-
-2. **User plugs in before 2 AM** (or at any time if they're at home)
-
-3. **Set smart charging profile** (see smart_charging_setup prompt)
-
-4. **Charging starts automatically at 2 AM** using the reservation
-
-## Integration with Smart Charging
-
-Reservations work well with smart charging modes:
-- Reserve the EVSE
-- Set a scheduled charging profile
-- Charging starts automatically during the reservation window
-- Optimizes for electricity price or solar availability`,
-                            },
-                        },
-                    ],
-                };
-            }
-            case 'smart_charging_setup': {
-                const chargePointId = args.chargePointId;
-                const mode = args.mode;
-                let specificGuidance = '';
-                if (chargePointId || mode) {
-                    specificGuidance += `\n## Specific Task: Configure Smart Charging\n\n`;
-                    if (chargePointId)
-                        specificGuidance += `Charge Point ID: ${chargePointId}\n`;
-                    if (mode) {
-                        specificGuidance += `Target Mode: ${mode}\n\n`;
-                        specificGuidance += `Focus on implementing the "${mode}" smart charging mode in the examples below.\n`;
-                    }
-                    else if (chargePointId) {
-                        specificGuidance += `\nConfigure smart charging for this charge point using the appropriate mode from the options below.\n`;
-                    }
-                }
-                return {
-                    messages: [
-                        {
-                            role: 'user',
-                            content: {
-                                type: 'text',
-                                text: `# Smart Charging Setup${specificGuidance}
-
-This guide explains how to configure smart charging modes for home chargers using the AMPECO API.
-
-## Overview
-
-Smart charging optimizes when and how EVs charge based on various factors:
-- **Scheduled** - Charge during specific time windows
-- **Solar** - Charge using excess solar power
-- **Dynamic Pricing** - Charge when electricity is cheapest
-- **Grid Optimization** - Respond to grid demand
-
-AMPECO supports multiple smart charging modes that can be configured per charge point.
-
-## Available Smart Charging Modes
-
-### 1. Scheduled (user_controlled_schedule)
-Time-based charging within defined windows.
-
-### 2. Solar (solar)
-Charges using excess solar power from home panels.
-
-### 3. Octopus Agile (octopus_agile)
-Dynamic pricing based on Octopus Energy's Agile tariff (UK).
-
-### 4. Octopus Go (octopus_go)
-Fixed off-peak window for Octopus Energy's Go tariff (UK).
-
-### 5. Energi Elspot (energi_elspot)
-Nordic spot market electricity pricing.
-
-### 6. Nordpool (nordpool)
-Nordic power exchange pricing.
-
-## Step 1: Get Available Smart Charging Modes
-
-**Endpoint:**
-\`\`\`
-GET /resources/charge-points/v2.0/{chargePointId}/available-personal-smart-charging-modes
-Authorization: Bearer YOUR_TOKEN
-\`\`\`
-
-**Response:**
-\`\`\`json
-{
-  "modes": [
-    {
-      "name": "Scheduled",
-      "integrationId": "user_controlled_schedule",
-      "type": "user_controlled_schedule",
-      "defaults": {
-        "start_time": "00:00:00",
-        "end_time": "06:00:00",
-        "target_charge": null
-      }
-    },
-    {
-      "name": "Solar",
-      "integrationId": "solar",
-      "type": "solar",
-      "defaults": {
-        "min_charge_kWh": 10,
-        "max_charge_kWh": 50
-      }
-    },
-    {
-      "name": "Agile-Octopus",
-      "integrationId": "octopus_agile",
-      "type": "octopus_agile",
-      "defaults": {
-        "max_price_threshold": 15.0
-      }
-    }
-  ]
-}
-\`\`\`
-
-**Note:** Available modes depend on tenant configuration.
-
-## Step 2: Configure Smart Charging Preferences
-
-**Endpoint:**
-\`\`\`
-POST /resources/charge-points/v2.0/{chargePointId}/personal-smart-charging-preferences
-Authorization: Bearer YOUR_TOKEN
-Content-Type: application/json
-\`\`\`
-
-### Configuration A: Scheduled Charging
-
-**Use Case:** Charge only during off-peak hours (2 AM - 6 AM).
-
-**Request Body:**
-\`\`\`json
-{
-  "type": "user_controlled_schedule",
-  "enabled": true,
-  "preferences": {
-    "start_time": "02:00:00",
-    "end_time": "06:00:00",
-    "target_charge": null
-  }
-}
-\`\`\`
-
-**Parameters:**
-- \`start_time\`: When charging window begins (24h format)
-- \`end_time\`: When charging window ends (24h format)
-- \`target_charge\`: Target kWh (null = charge fully during window)
-
-**Response:**
-\`\`\`json
-{
-  "success": true,
-  "preferenceId": 123,
-  "message": "Smart charging preference saved"
-}
-\`\`\`
-
-### Configuration B: Solar Charging
-
-**Use Case:** Charge using excess solar power, with minimum guaranteed charge.
-
-**Request Body:**
-\`\`\`json
-{
-  "type": "solar",
-  "enabled": true,
-  "preferences": {
-    "min_charge_kWh": 15,
-    "max_charge_kWh": 60,
-    "allow_grid_charging": true,
-    "grid_charging_threshold": 20
-  }
-}
-\`\`\`
-
-**Parameters:**
-- \`min_charge_kWh\`: Minimum energy to charge (guaranteed even from grid)
-- \`max_charge_kWh\`: Maximum energy to charge
-- \`allow_grid_charging\`: Allow grid if solar insufficient for minimum
-- \`grid_charging_threshold\`: Battery % below which to use grid
-
-**How it works:**
-1. Charges primarily from solar excess
-2. If solar insufficient and battery < threshold, uses grid to reach minimum
-3. Stops at maximum kWh
-
-### Configuration C: Dynamic Pricing (Octopus Agile)
-
-**Use Case:** Charge when electricity price is below threshold.
-
-**Request Body:**
-\`\`\`json
-{
-  "type": "octopus_agile",
-  "enabled": true,
-  "preferences": {
-    "max_price_threshold": 12.0,
-    "location": "H",
-    "target_charge_kWh": 40
-  }
-}
-\`\`\`
-
-**Parameters:**
-- \`max_price_threshold\`: Maximum p/kWh to charge at (pence)
-- \`location\`: Octopus pricing region code
-- \`target_charge_kWh\`: How much energy to add
-
-**How it works:**
-1. Monitors Octopus Agile half-hourly prices
-2. Charges when price drops below threshold
-3. Stops when target kWh reached
-
-### Configuration D: Octopus Go (Fixed Off-Peak)
-
-**Use Case:** Charge during Octopus Go's fixed off-peak window (12:30 AM - 4:30 AM).
-
-**Request Body:**
-\`\`\`json
-{
-  "type": "octopus_go",
-  "enabled": true,
-  "preferences": {
-    "start_time": "00:30:00",
-    "end_time": "04:30:00"
-  }
-}
-\`\`\`
-
-### Configuration E: Nordpool / Energi Elspot
-
-**Use Case:** Charge during cheapest Nordic spot market hours.
-
-**Request Body:**
-\`\`\`json
-{
-  "type": "nordpool",
-  "enabled": true,
-  "preferences": {
-    "max_price_threshold": 0.50,
-    "price_area": "SE3",
-    "target_charge_kWh": 50
-  }
-}
-\`\`\`
-
-**Parameters:**
-- \`max_price_threshold\`: Maximum price in local currency
-- \`price_area\`: Nordic price area code (SE1-4, NO1-5, DK1-2, FI)
-- \`target_charge_kWh\`: Energy target
-
-## Step 3: Get Current Smart Charging Preferences
-
-**Endpoint:**
-\`\`\`
-GET /resources/charge-points/v2.0/{chargePointId}/personal-smart-charging-preferences
-Authorization: Bearer YOUR_TOKEN
-\`\`\`
-
-**Response:**
-\`\`\`json
-{
-  "active": true,
-  "type": "user_controlled_schedule",
-  "preferences": {
-    "start_time": "02:00:00",
-    "end_time": "06:00:00",
-    "target_charge": null
-  },
-  "enabled": true
-}
-\`\`\`
-
-## Step 4: Update or Disable Smart Charging
-
-### Update Preferences
-Use the same POST endpoint with new values:
-\`\`\`
-POST /resources/charge-points/v2.0/{chargePointId}/personal-smart-charging-preferences
-{
-  "type": "user_controlled_schedule",
-  "enabled": true,
-  "preferences": {
-    "start_time": "01:00:00",
-    "end_time": "05:00:00"
-  }
-}
-\`\`\`
-
-### Disable Smart Charging
-Set \`enabled: false\`:
-\`\`\`json
-{
-  "type": "user_controlled_schedule",
-  "enabled": false,
-  "preferences": {}
-}
-\`\`\`
-
-Charging will revert to immediate/manual mode.
-
-## Best Practices
-
-1. **Check available modes first** - Not all modes enabled for all tenants
-2. **Validate time windows** - Ensure start < end for scheduled modes
-3. **Set reasonable thresholds** - Price thresholds should match local market
-4. **Combine with reservations** - Reserve EVSE + smart charging = guaranteed optimized charging
-5. **Monitor effectiveness** - Track sessions to see if smart charging is working
-6. **Fallback strategy** - Set minimum charge to ensure users aren't stranded
-
-## Common Workflows
-
-### Workflow 1: Home Charging Optimization
-
-\`\`\`
-1. User has home charger and solar panels
-2. User wants to charge from solar, but guarantee 20 kWh minimum
-
-Setup:
-POST /resources/charge-points/v2.0/{id}/personal-smart-charging-preferences
-{
-  "type": "solar",
-  "enabled": true,
-  "preferences": {
-    "min_charge_kWh": 20,
-    "max_charge_kWh": 60,
-    "allow_grid_charging": true,
-    "grid_charging_threshold": 30
-  }
-}
-\`\`\`
-
-### Workflow 2: Cheap Night Charging
-
-\`\`\`
-1. User has variable electricity pricing
-2. Wants to charge only when price < $0.10/kWh
-
-Setup:
-POST /resources/charge-points/v2.0/{id}/personal-smart-charging-preferences
-{
-  "type": "nordpool",
-  "enabled": true,
-  "preferences": {
-    "max_price_threshold": 0.10,
-    "price_area": "SE3",
-    "target_charge_kWh": 40
-  }
-}
-\`\`\`
-
-### Workflow 3: Fixed Schedule for Apartment
-
-\`\`\`
-1. User has fixed off-peak hours (midnight - 6 AM)
-2. Wants to fully charge during this window
-
-Setup:
-POST /resources/charge-points/v2.0/{id}/personal-smart-charging-preferences
-{
-  "type": "user_controlled_schedule",
-  "enabled": true,
-  "preferences": {
-    "start_time": "00:00:00",
-    "end_time": "06:00:00",
-    "target_charge": null
-  }
-}
-\`\`\`
-
-## Integration with Charging Sessions
-
-Smart charging preferences apply automatically to charging sessions:
-
-1. User plugs in EV
-2. Session starts (or waits for reservation)
-3. Smart charging controller manages charging based on active preferences
-4. Charging occurs only during optimal times/conditions
-5. Session completes when target reached or window closes
-
-**No additional API calls needed** - preferences persist until changed.
-
-## Troubleshooting
-
-**Smart charging not working:**
-- Verify \`enabled: true\`
-- Check charge point supports smart charging (v2.0 endpoints)
-- Ensure preferences are valid (time format, thresholds)
-- Verify external integrations are configured (Octopus, Nordpool)
-
-**Charging outside schedule:**
-- Check for overriding factors (low battery emergency charge)
-- Verify no other smart mode is active
-- Check charge point firmware version`,
-                            },
-                        },
-                    ],
-                };
-            }
-            default:
-                throw new Error(`Unknown prompt: ${promptName}`);
-        }
-    });
-    return server;
-}
+import { createServer } from './factory.js';
+import { loadEndpoints, loadResponseSchemas } from './loader.js';
 /**
  * Main server startup
  */
@@ -1403,6 +20,9 @@ async function main() {
     const endpoints = loadEndpoints();
     console.log(`Loaded ${endpoints.endpoints.length} endpoints from ${endpoints.info.title} v${endpoints.info.version}`);
     console.log(`Optimization: ${endpoints.stats.reductionPercent.toFixed(2)}% size reduction`);
+    console.log('Loading response schemas...');
+    const responseSchemas = loadResponseSchemas();
+    console.log(`Loaded ${Object.keys(responseSchemas).length} response schemas (${endpoints.stats.responseSchemas?.withSchemas || 0} with schemas)`);
     // Create Express app
     const app = express();
     app.use(express.json());
@@ -1451,7 +71,11 @@ async function main() {
         const hostname = `${protocol}://${hostnameWithoutSuffix}`;
         console.log(`[MCP Request] Target API: ${hostname}, Method: ${req.body?.method || 'unknown'}`);
         // Create server instance with the bearer token and hostname
-        const server = createServer(endpoints, bearerToken, hostname);
+        const server = createServer(endpoints, responseSchemas, {
+            hostname,
+            bearerToken,
+            emulateResourcesViaTools: false, // Legacy server uses native resources
+        });
         try {
             // Create stateless transport (no session management)
             const transport = new StreamableHTTPServerTransport({