Release v1.4.0

Features

• Add geographic filtering for electricity price tools

  • New get_spain_hourly_prices tool for simplified Spanish market lookups
  • Add geo_filter parameter to get_price_analysis for multi-country data
  • Filter SPOT price data by geographic scope (Península)
  • Handle multi-country data from indicator 600 (Spain, Portugal, France, Belgium, Netherlands, Germany)

• Add demand analysis tools and PVPC rate tool

  • New tools for analyzing electricity demand patterns
  • PVPC regulated rate retrieval functionality

Improvements

• Add uv lockfile for dependency management
• Apply ruff formatting to entire codebase for consistent code style

Documentation

• Update CLAUDE.md with new tool usage examples
• Add multi-country data handling notes
• Clarify geographic filtering options

v1.3.0 - Streamlined README & Enhanced UX

🎉 What's New in v1.3.0

📖 Streamlined README

• 40% smaller - Reduced from 445 to 270 lines for faster onboarding
• 7 new question categories with 40+ practical examples
• Removed technical details (moved to CLAUDE.md for developers)
• Enhanced user-focused content for quick start

💬 Expanded "What to Ask" Section

New categories with clear examples:

• 📊 Real-time operations
• 🔍 Event investigation & analysis
• 🌱 Renewable energy & emissions
• 💰 Price & market analysis
• ⚙️ Grid stability & storage
• 🔎 Data discovery
• 📈 Comparisons & trends

🎓 Maintained Content

• All promotions (La Escuela de IA, YouTube, Javi Santos)
• Powerful April 28th blackout story
• Quick 3-minute installation guide
• Community links and resources

🎯 Improved User Experience

Users can now immediately see what questions to ask and how to get started - perfect for new users discovering the MCP server!

---

Full Changelog: v1.2.2...v1.3.0

v1.2.2 - Code style fixes

🧹 Code Style Fixes

This patch release fixes linting errors that caused CI failures with ruff checks.

🐛 Fixed

Linting compliance issues:

• F401: Removed unused imports (json in mcp_server.py, pytest in test_tool_helpers.py)
• UP035: Import AsyncIterator from collections.abc instead of typing (modern Python 3.9+ pattern)
• I001: Formatted import blocks for consistency
• B011: Replace assert False with raise AssertionError() (safer for production)

✅ Verified

• ✅ All ruff checks pass
• ✅ mypy strict mode passes (36 source files)
• ✅ All 96 tests passing
• ✅ No functional changes

📦 What's Changed

All changes are cosmetic code style improvements with zero functional impact. This is a purely technical fix to ensure CI passes completely.

Files modified:

• src/ree_mcp/interface/mcp_server.py
• src/ree_mcp/interface/tool_helpers.py
• tests/unit/interface/test_indicator_config.py
• tests/unit/interface/test_tool_helpers.py

---

Full Changelog: v1.2.1...v1.2.2

v1.2.1 - Fix mypy strict mode compatibility

🔧 Bug Fix Release

This patch release fixes a type checking error that caused CI failures with mypy strict mode.

🐛 Fixed

• mypy strict mode compatibility - Fixed type error where MCP resource was attempting to call a FunctionTool object directly (not callable)
  • Updated list_all_indicators() resource to use ToolExecutor pattern directly
  • Maintains same functionality with proper type safety

✅ Verified

• ✅ All 96 tests passing
• ✅ mypy strict mode check passes (36 source files)
• ✅ No breaking changes - same API and behavior

📦 What's Changed

File: src/ree_mcp/interface/mcp_server.py

• Fixed line 877: Changed from calling wrapped tool to using ToolExecutor directly
• Added proper error handling with ResponseFormatter

This is a purely technical fix with no user-facing changes.

---

Full Changelog: v1.2.0...v1.2.1

v1.2.0 - Architecture Refactoring

🏗️ Major Architecture Refactoring

This release includes a comprehensive refactoring of the interface layer following industry best practices: DRY (Don't Repeat Yourself), KISS (Keep It Simple, Stupid), and SOLID principles.

🎯 What Changed

New Modular Architecture:

• indicator_config.py - Centralized repository of 40+ indicator IDs and metadata
• tool_helpers.py - Reusable utility classes (DateTimeHelper, ResponseFormatter, ToolExecutor)
• tool_services.py - Service layer for complex multi-indicator operations

Refactored mcp_server.py:

• Reduced from 1314 to 923 lines (30% code reduction)
• Eliminated 15+ instances of duplicate code
• Improved separation of concerns with focused, single-responsibility classes

✨ Benefits

• 🚀 Better Maintainability - Changes isolated to specific services
• 📈 More Scalable - Easy to add new tools without code duplication
• 🧪 Better Tested - 96 tests with 90% coverage (up from 59 tests)
• 🎓 Better Documented - Updated README.md and CLAUDE.md with new architecture
• 🔒 Type Safe - 100% type-annotated with mypy strict mode

🔄 Breaking Changes

None! All 15 MCP tools maintain the same API. This is a purely internal refactoring.

📊 Testing

• ✅ 96 tests passing (44 new tests added)
• ✅ 90% code coverage across all layers
• ✅ Unit tests for all new helper classes and services
• ✅ E2E tests for all 15 MCP tools

📝 What's Next

The refactored architecture makes it much easier to:

• Add new analysis tools
• Extend existing functionality
• Maintain and debug the codebase
• Contribute to the project

🙏 Acknowledgments

Built with Claude Code following Clean Architecture and Domain-Driven Design principles.

---

Full Changelog: v1.1.0...v1.2.0

v1.1.0 - Advanced Grid Analysis Tools

🎉 Major Feature Release

This release expands the REE MCP Server from 5 to 14 tools, adding comprehensive high-level analysis capabilities for renewable energy, grid stability, market analysis, and sustainability tracking.

✨ New Features

🌱 Renewable Energy & Sustainability (2 tools)

• get_renewable_summary: Comprehensive renewable generation analysis with variable/synchronous breakdown and percentage of total demand
• get_carbon_intensity: CO₂ emissions per kWh with quality ratings (excellent/good/moderate/poor) and time-series analysis

⚙️ Grid Operations & Stability (3 tools)

• get_grid_stability: Synchronous vs variable renewable balance analysis with inertia assessment and stability risk levels
• get_storage_operations: Pumped storage efficiency analysis with arbitrage opportunity identification
• get_international_exchanges: Cross-border electricity flows by country (Andorra, Morocco, Portugal, France) with net balance calculations

💰 Market Analysis & Forecasting (3 tools)

• get_price_analysis: SPOT market price analysis with multi-country comparison and statistical aggregations
• compare_forecast_actual: Demand forecast accuracy metrics (MAE, RMSE, MAPE) with bias detection
• get_peak_analysis: Daily peak demand patterns, load factors, and efficiency metrics

⚡ Enhanced Generation Analysis (1 tool)

• get_generation_mix_timeline: Full-day generation breakdown (extends existing single-hour tool)

🔧 Technical Improvements

• All tools follow DDD/Clean Architecture patterns
• Type-safe with mypy strict mode
• Comprehensive E2E test coverage (16 new tests)
• DRY principles with reusable patterns
• Proper error handling and validation

📚 Documentation

• Updated CLAUDE.md with complete tool reference
• Added usage examples for all new tools
• Categorized tools by use case
• Added tools section to README (Spanish)

📊 Statistics

• Total Tools: 14 (up from 5)
• New Tools: 9
• Lines Added: 1,450+
• Test Coverage: 16 new E2E tests
• Code Quality: 100% type-safe, passes mypy strict + ruff linting

🎯 Use Cases

Perfect for:

• 📈 Energy traders analyzing market opportunities
• ⚡ Grid operators monitoring stability
• 🌍 Climate analysts tracking decarbonization
• 🔬 Researchers studying renewable integration
• 🏛️ Policy makers assessing energy transition

🔗 Resources

• Repository: https://github.com/ESJavadex/ree-mcp
• MCP Documentation: https://docs.claude.com/mcp
• REE API: https://api.esios.ree.es

🤖 Built with Claude Code

This release was developed with assistance from Claude Code 🚀

---

Full Changelog: v1.0.0...v1.1.0

🎉 v1.0.0 - First Production Release

🎉 REE MCP Server v1.0.0

First production-ready release! Access Spanish electricity data through Claude using natural language.

---

✨ What's Included

🛠️ MCP Tools (5)

Query Spain's electricity grid data with simple natural language:

1. get_indicator_data - Fetch time-series data for any of 1,967+ indicators
2. list_indicators - Browse all available REE indicators with metadata
3. search_indicators - Find indicators by keyword (e.g., "solar", "precio", "demanda")
4. get_demand_summary - Quick demand overview for any date
5. get_generation_mix - Generation breakdown by source at specific times

📚 MCP Resources (2)

• ree://indicators - Complete indicator catalog
• ree://indicators/{id} - Individual indicator metadata

---

🏗️ Architecture Highlights

Built with industry best practices:

• ✅ Domain-Driven Design (DDD) - 4 clean layers (Domain, Application, Infrastructure, Interface)
• ✅ Clean Architecture - Dependencies point inward, domain has zero external deps
• ✅ SOLID Principles - All 5 implemented throughout the codebase
• ✅ Type Safety - 100% type-annotated, passes mypy strict mode
• ✅ NO Mocking - Domain tests use pure functions (no mocks/stubs)
• ✅ Comprehensive Testing - 59 tests covering all layers (unit, integration, e2e)

---

⚡ Production-Ready Features

• 🔄 Automatic retry with exponential backoff for transient failures
• 🛡️ Comprehensive error handling with domain-specific exceptions
• ✅ Type-safe configuration using Pydantic Settings
• ⚡ Async/await for optimal performance
• 🔒 Context managers for proper resource cleanup
• 📊 Structured logging with detailed error messages

---

📊 Data Access

Access 1,967+ electricity indicators including:

⚡ Real-Time Data (5-minute updates)

• Electricity demand (real-time and forecasts)
• Generation by source (nuclear, wind, solar, hydro, coal, gas)
• Market prices (SPOT, PVPC rates)
• CO₂ emissions tracking
• International exchanges (imports/exports)

📈 Common Indicators

• 1293 - Real Demand (Peninsular)
• 2038 - Wind Generation (National)
• 1295 - Solar PV (Peninsular)
• 549 - Nuclear Generation
• 600 - SPOT Market Price
• 10355 - CO₂ Emissions

---

🚀 Installation & Setup

Quick Start (3 minutes)

# Clone and install
git clone https://github.com/ESJavadex/ree-mcp.git
cd ree-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# Configure
cp .env.example .env
# Edit .env with your REE_API_TOKEN

# Add to Claude Code
./INSTALL_COMMAND.sh

Verify Installation

claude mcp list
# Should show: ree-mcp: ✓ Connected

---

💬 Example Usage

Open Claude Code and try:

• "Show me the current electricity demand in Spain"
• "What's the generation mix right now?"
• "Compare solar vs wind generation today"
• "Investigate what happened on April 28, 2025"
• "Search for price indicators"

Claude will automatically use the REE MCP tools to fetch and analyze the data!

---

📚 Documentation

• README.md - User guide with Quick Start and examples
• CLAUDE.md - Developer guidance for contributing
• API Reference - Common indicator IDs and usage patterns
• Installation Script - Automated Claude Code setup

---

🎓 Learn More

Created by Javi Santos - AI & Robotics Specialist with published research in computer vision and LLM interpretability.

📚 Join La Escuela de IA

Learn AI without the fluff! Spanish AI learning community with real-world projects.
👉 skool.com/la-escuela-de-ia-9955

📺 YouTube Channel

AI tutorials, MCP servers, and LLM applications.
👉 @JavadexAI

🤝 Connect

• LinkedIn: Javi Santos
• YouTube: @JavadexAI

---

🔧 Technical Details

Requirements:

• Python 3.11+
• REE API token (demo token included)

Dependencies:

• fastmcp 0.2.0+
• httpx 0.27.0+
• pydantic 2.10.0+
• pydantic-settings 2.6.0+

Development:

• pytest, pytest-asyncio, pytest-cov
• mypy (strict mode)
• ruff (linting & formatting)

---

📄 License

This project is for educational and research purposes. The REE API is provided by Red Eléctrica de España.

---

🙏 Acknowledgments

• REE (Red Eléctrica de España) for providing the eSios API
• FastMCP for the excellent MCP framework
• Anthropic for Claude and the Model Context Protocol

---

🐛 Issues & Support

• Issues: GitHub Issues
• REE API: consultasios@ree.es
• FastMCP: https://github.com/jlowin/fastmcp

---

Built with ❤️ using Domain-Driven Design and modern Python best practices

⭐ Star this repo if you find it useful!