PVPC MCP Server

Instructions

Implementation Reference

• src/mcp.ts:110-166 (handler)

  MCP tool handler for 'fetch_prices'. Delegates to PvpcApiClient.fetchPrices, formats output as structured content with JSON text, and handles PvpcErrors.
  async ({ locale, startDate, endDate, timeAggregation, timeTruncation, geographicalAggregation, geographicalIds, geographicalTruncation, }) => { try { const prices = await this.apiClient.fetchPrices({ locale, startDate, endDate, timeAggregation, timeTruncation, geographicalAggregation, geographicalIds, geographicalTruncation, }); return { content: [ { type: "text", text: JSON.stringify({ prices }, null, 2), }, ], structuredContent: { prices, }, }; } catch (error) { if (error instanceof PvpcError) { return { content: [ { type: "text", text: `Failed to fetch prices: ${error.name} - ${error.message}\nStatus: ${error.status}`, }, ], isError: true, }; } return { content: [ { type: "text", text: "Failed to fetch prices: Unknown error", }, ], isError: true, }; } },
• src/pvpc.ts:79-118 (helper)

  Core implementation in PvpcApiClient that constructs query params, fetches from REE ESIOS API, and transforms response into PvpcPrice array.
  async fetchPrices(params: FetchPricesParams): Promise<PvpcPrice[]> { const queryParams = { locale: params.locale, start_date: params.startDate, end_date: params.endDate, time_agg: params.timeAggregation, time_trunc: params.timeTruncation, geo_agg: params.geographicalAggregation, geo_ids: params.geographicalIds, geo_trunc: params.geographicalTruncation, }; const stringQueryParams = QueryString.stringify(queryParams, { arrayFormat: "brackets", encode: false, skipNulls: true, }); const response = await this.get<FetchPricesResponse>( `?${stringQueryParams}`, ); const currencyCode = "EUR"; const currencySymbol = "€"; const magnitude = "€/MWh"; return response.indicator.values.map((v) => ({ price: { amount: v.value, currencyCode, currencySymbol, }, magnitude, datetime: v.datetime, datetimeUtc: v.datetime_utc, geographicalId: v.geo_id, geographicalName: v.geo_name, updatedAt: response.indicator.values_updated_at, })); }
• src/mcp.ts:38-109 (schema)

  Zod-based inputSchema and outputSchema for the 'fetch_prices' tool, defining parameters like dates, locale, geo_ids with defaults and descriptions.
  { title: "Fetch PVPC Prices", description: "Fetches the Voluntary Price for the Small Consumer (PVPC) prices for a given date range and geographical area.", inputSchema: { locale: z .enum(["es", "en"]) .default("es") .describe( "Get translations for sources. Accepted values: `es`, `en`. Defaults to `es`.", ), startDate: z .string() .default(startOfToday().toISOString()) .describe( "Beginning of the date range to filter indicator values in iso8601 format. E.g. 2025-06-29T00:00:00.000+02:00. Defaults to the start of today.", ), endDate: z .string() .default(endOfToday().toISOString()) .describe( "End of the date range to filter indicator values in iso8601 format. E.g. 2025-06-29T23:59:59.999+02:00. Defaults to the end of today.", ), timeAggregation: z .enum(["sum", "average"]) .default("sum") .describe( "How to aggregate indicator values when grouping them by time. Accepted values: `sum`, `average`. Defaults to `sum`.", ), timeTruncation: z .enum(["hour", "day", "month", "year"]) .optional() .describe( "Tells how to truncate data time series. Accepted values: `hour`, `day`, `month`, `year`.", ), geographicalAggregation: z .enum(["sum", "average"]) .default("sum") .describe( "How to aggregate indicator values when grouping them by geographical ID. Accepted values: `sum`, `average`. Defaults to `sum`.", ), geographicalIds: z .array(z.number()) .default([8741, 8742, 8743, 8744, 8745]) .describe( "Tells the geographical IDs to filter indicator values. Accepted values: `3` (España), `8741` (Península), `8742` (Canarias), `8743` (Baleares), `8744` (Ceuta), `8745` (Melilla). Defaults to `8741`, `8742`, `8743`, `8744`, `8745`.", ), geographicalTruncation: z .enum(["country", "electric_system"]) .optional() .describe( "Tells how to group data at geographical level when the geographical aggregation is informed. Accepted values: `country`, `electric_system`.", ), }, outputSchema: { prices: z.array( z.object({ price: z.object({ amount: z.number(), currencyCode: z.string(), currencySymbol: z.string(), }), magnitude: z.string(), datetime: z.string(), datetimeUtc: z.string(), geographicalId: z.number(), geographicalName: z.string(), updatedAt: z.string(), }), ), }, },
• src/mcp.ts:36-167 (registration)

  Registers the 'fetch_prices' tool with the MCP server using registerTool, providing name, schema, and handler.
  this.server.registerTool( "fetch_prices", { title: "Fetch PVPC Prices", description: "Fetches the Voluntary Price for the Small Consumer (PVPC) prices for a given date range and geographical area.", inputSchema: { locale: z .enum(["es", "en"]) .default("es") .describe( "Get translations for sources. Accepted values: `es`, `en`. Defaults to `es`.", ), startDate: z .string() .default(startOfToday().toISOString()) .describe( "Beginning of the date range to filter indicator values in iso8601 format. E.g. 2025-06-29T00:00:00.000+02:00. Defaults to the start of today.", ), endDate: z .string() .default(endOfToday().toISOString()) .describe( "End of the date range to filter indicator values in iso8601 format. E.g. 2025-06-29T23:59:59.999+02:00. Defaults to the end of today.", ), timeAggregation: z .enum(["sum", "average"]) .default("sum") .describe( "How to aggregate indicator values when grouping them by time. Accepted values: `sum`, `average`. Defaults to `sum`.", ), timeTruncation: z .enum(["hour", "day", "month", "year"]) .optional() .describe( "Tells how to truncate data time series. Accepted values: `hour`, `day`, `month`, `year`.", ), geographicalAggregation: z .enum(["sum", "average"]) .default("sum") .describe( "How to aggregate indicator values when grouping them by geographical ID. Accepted values: `sum`, `average`. Defaults to `sum`.", ), geographicalIds: z .array(z.number()) .default([8741, 8742, 8743, 8744, 8745]) .describe( "Tells the geographical IDs to filter indicator values. Accepted values: `3` (España), `8741` (Península), `8742` (Canarias), `8743` (Baleares), `8744` (Ceuta), `8745` (Melilla). Defaults to `8741`, `8742`, `8743`, `8744`, `8745`.", ), geographicalTruncation: z .enum(["country", "electric_system"]) .optional() .describe( "Tells how to group data at geographical level when the geographical aggregation is informed. Accepted values: `country`, `electric_system`.", ), }, outputSchema: { prices: z.array( z.object({ price: z.object({ amount: z.number(), currencyCode: z.string(), currencySymbol: z.string(), }), magnitude: z.string(), datetime: z.string(), datetimeUtc: z.string(), geographicalId: z.number(), geographicalName: z.string(), updatedAt: z.string(), }), ), }, }, async ({ locale, startDate, endDate, timeAggregation, timeTruncation, geographicalAggregation, geographicalIds, geographicalTruncation, }) => { try { const prices = await this.apiClient.fetchPrices({ locale, startDate, endDate, timeAggregation, timeTruncation, geographicalAggregation, geographicalIds, geographicalTruncation, }); return { content: [ { type: "text", text: JSON.stringify({ prices }, null, 2), }, ], structuredContent: { prices, }, }; } catch (error) { if (error instanceof PvpcError) { return { content: [ { type: "text", text: `Failed to fetch prices: ${error.name} - ${error.message}\nStatus: ${error.status}`, }, ], isError: true, }; } return { content: [ { type: "text", text: "Failed to fetch prices: Unknown error", }, ], isError: true, }; } }, );
• src/interfaces.ts:1-37 (schema)

  TypeScript interfaces for FetchPricesParams, FetchPricesResponse, and PvpcPrice used by the API client and tool output.
  export interface PvpcPrice { price: { amount: number; currencyCode: string; currencySymbol: string; }; magnitude: string; datetime: string; datetimeUtc: string; geographicalId: number; geographicalName: string; updatedAt: string; } export interface FetchPricesResponse { indicator: { values: { value: number; datetime: string; datetime_utc: string; geo_id: number; geo_name: string; }[]; values_updated_at: string; }; } export interface FetchPricesParams { locale: string; startDate: string; endDate: string; timeAggregation: string; timeTruncation?: string; geographicalAggregation: string; geographicalIds: number[]; geographicalTruncation?: string; }