ree-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

REE MCP Server: A production-ready MCP (Model Context Protocol) server for accessing Red Eléctrica Española (REE) electricity data through the eSios API. Built with strict Domain-Driven Design (DDD) principles, Clean Architecture, and comprehensive testing.

Key Constraint: This codebase follows a NO MOCKING policy in the domain layer. Domain logic must remain pure and testable without mocks.

Development Commands

Environment Setup

# Using uv (recommended)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

# Using standard pip
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

Testing

# Run all tests
pytest

# Run only unit tests (domain layer)
pytest tests/unit/

# Run integration tests (infrastructure with mocked HTTP)
pytest tests/integration/

# Run e2e tests
pytest tests/e2e/

# Run with coverage report
pytest --cov=src/ree_mcp --cov-report=html

# Run specific test file
pytest tests/unit/domain/test_value_objects.py

# Run specific test function
pytest tests/unit/domain/test_value_objects.py::test_indicator_id_validation

Type Checking

# Type check entire codebase (mypy strict mode enabled)
mypy src/ree_mcp/

# Type check specific module
mypy src/ree_mcp/domain/

Linting and Formatting

# Check code style
ruff check .

# Auto-fix issues
ruff check --fix .

# Format code (line length: 100)
ruff format .

Running the Server

# STDIO mode (default for MCP)
python -m ree_mcp

# HTTP mode for testing/debugging
python -c "from ree_mcp.interface.mcp_server import mcp; mcp.run(transport='http', port=8000)"

Architecture Overview

This project implements Clean Architecture with Domain-Driven Design (DDD) in four distinct layers:

1. Domain Layer (src/ree_mcp/domain/)

Pure business logic with ZERO external dependencies. No I/O, no frameworks, no mocking in tests.