MCP Energy Server

# Project Structure ``` mcp-energy/ │ ├── .github/ │ └── workflows/ │ └── ci.yml # GitHub Actions CI/CD pipeline │ ├── tests/ │ ├── __init__.py # Tests package marker │ └── test_server.py # Server tests │ ├── .env.example # Template for environment variables ├── .gitignore # Git ignore rules ├── __init__.py # Package initialization ├── LICENSE # MIT License ├── README.md # Main documentation ├── QUICKSTART.md # Quick start guide ├── DEPLOYMENT.md # Deployment instructions ├── STRUCTURE.md # This file ├── pyproject.toml # Project configuration & dependencies ├── requirements.txt # Direct dependencies list ├── setup.py # Setup script (backward compatibility) └── server.py # Main MCP server implementation ``` ## File Descriptions ### Core Files - **server.py**: The main MCP server implementation - Defines all EIA API tools - Handles API requests and responses - Implements MCP protocol communication - Contains 8 different energy data tools - **pyproject.toml**: Modern Python project configuration - Package metadata - Dependencies - Build system configuration - Development tools configuration - **requirements.txt**: Simple dependency list - For quick `pip install -r requirements.txt` ### Configuration Files - **.env.example**: Template for environment variables - Shows how to configure API key - Copy to `.env` for local use - **.gitignore**: Prevents committing unwanted files - Python cache files - Virtual environments - IDE settings - Environment variables ### Documentation - **README.md**: Comprehensive documentation - Features overview - Installation instructions - API reference for all tools - Usage examples - **QUICKSTART.md**: Get started in 5 minutes - Minimal steps to run the server - Basic configuration - Simple examples - **DEPLOYMENT.md**: GitHub deployment guide - Step-by-step GitHub setup - PyPI publishing instructions - Security considerations - **STRUCTURE.md**: This file - Project organization - File purposes ### Testing & CI/CD - **tests/**: Test suite directory - Unit tests - Integration tests - Test utilities - **.github/workflows/ci.yml**: Automated testing - Runs on push and pull requests - Tests multiple Python versions - Code quality checks ### Legal - **LICENSE**: MIT License - Open source license - Allows commercial use - Requires attribution ## Key Components in server.py ### 1. Imports & Configuration ```python - MCP server libraries - HTTP client (httpx) - API configuration (key, base URL) ``` ### 2. API Client ```python fetch_eia_data() - Handles all EIA API requests - Error handling - Response formatting ``` ### 3. Tool Definitions ```python @app.list_tools() - Registers 8 energy data tools - Defines input schemas - Provides descriptions ``` ### 4. Tool Handler ```python @app.call_tool() - Routes tool calls - Builds API parameters - Formats responses ``` ### 5. Server Runner ```python main() - Initializes MCP server - Handles stdio communication ``` ## Data Flow ``` Claude Desktop ↓ MCP Protocol (stdio) ↓ server.py (MCP Server) ↓ fetch_eia_data() ↓ EIA API (HTTPS) ↓ Energy Data ↓ Formatted Response ↓ Claude Desktop ``` ## Dependencies ### Runtime Dependencies - **mcp**: Model Context Protocol framework - **httpx**: Modern async HTTP client ### Development Dependencies - **pytest**: Testing framework - **pytest-asyncio**: Async test support - **black**: Code formatter - **ruff**: Fast Python linter ## Architecture Decisions ### Why MCP? - Standard protocol for AI model integrations - Clean separation of concerns - Works with Claude and other AI systems ### Why httpx? - Modern async/await support - Better than requests for async operations - Excellent error handling ### Why stdio? - Simple, reliable communication - No network configuration needed - Standard MCP transport method ### Why separate tools? - Clear organization by energy type - Easy to find specific data - Better user experience in Claude ## Extension Points To add new features: 1. **New EIA Endpoint**: Add new tool in `list_tools()` 2. **New API**: Create new fetch function 3. **Data Processing**: Add helper functions 4. **Caching**: Add caching layer in fetch function 5. **Rate Limiting**: Add rate limit handling ## Development Workflow ```bash # 1. Create feature branch git checkout -b feature/new-tool # 2. Make changes # Edit server.py # 3. Format code black . ruff check . # 4. Run tests pytest # 5. Commit git commit -m "Add new tool" # 6. Push and create PR git push origin feature/new-tool ``` ## Security Considerations ### API Key Management - Default key included for convenience - Environment variable support for security - .env file gitignored ### Rate Limiting - EIA has rate limits (check their docs) - Consider implementing caching - Add retry logic for production ### Error Handling - All API calls wrapped in try-catch - User-friendly error messages - No sensitive data in error logs ## Performance Optimization Potential improvements: - Add response caching - Implement connection pooling - Batch multiple requests - Add request deduplication ## Monitoring & Logging To add logging: ```python import logging logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) ``` ## Contribution Guidelines When contributing: 1. Follow existing code style 2. Add tests for new features 3. Update documentation 4. Run linters before committing 5. Keep commits focused and clear ## Version History - **v0.1.0**: Initial release - 8 EIA data tools - Basic MCP implementation - GitHub Actions CI