# CLAUDE.md

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

## Documentation

Read `DEVELOPER_GUIDE.md` for comprehensive development guidance including module responsibilities, entry points, environment variable loading, and common development tasks.

Keep both `README.md` and `DEVELOPER_GUIDE.md` updated with any user-facing or architectural changes.

## Architecture

Modular MCP server organized by separation of concerns (~2120 total LOC across 13 files):

```
powerbi_mcp/
├── __init__.py        # Main entry point (contains main())
├── __main__.py        # Module execution support
├── server.py          # FastMCP initialization
├── auth.py            # OAuth2 authentication, token management
├── client.py          # PowerBI REST API client
├── constants.py       # Configuration values (URLs, timeouts, limits)
├── exceptions.py      # Centralized error handling
├── validation.py      # Reusable input validation
├── formatters.py      # Response formatting (markdown/JSON)
├── models.py          # Pydantic data models
└── tools/             # MCP tool definitions
    ├── workspaces.py  # Workspace operations
    ├── datasets.py    # Dataset operations
    └── queries.py     # DAX query execution
```

**Key principle**: Configuration in `constants.py`, validation in `validation.py`, error handling in `exceptions.py`. One change updates all tools automatically.

## Development Commands

```bash
# Package manager: uv (with .venv virtual environment)
uv sync                # Install dependencies
uv run run-server      # Run server (calls powerbi_mcp:main)

# Development testing with MCP Inspector
npx @modelcontextprotocol/inspector uv --directory . run run-server
```

## Development Guidelines

1. **File Size**: Keep LOC per file ≤ 400 lines (current files comply).

2. **Module Responsibilities**: See DEVELOPER_GUIDE.md for what belongs where. Follow existing patterns.

3. **File Creation**: Do not create files/directories unnecessarily. Only create when explicitly required.

4. **Branch Management**: If on main branch, ask user before making significant changes. Offer to create feature/fix branch.

5. **Package Management**: Use `uv` commands only (not `python` or `pip` directly). Virtual environment is at `.venv/`.

6. **Code Quality**: Use the `code-simplifier` agent for refactoring and cleanup.

7. **Testing**: Use the `powerbi-mcp-server-tester` skill to verify changes before committing.

8. **PowerBI Expertise**: Use the `powerbi-expert` skill for DAX, M language, and data modeling questions.

9. **Version Bumping**: Check if version in `pyproject.toml` needs updating (currently 0.1.1).

10. **Commit Message**: Do not add "Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com" to commit message.

## Environment Variables

Required in `.env` (loaded from `os.getcwd()`) or MCP client config:
- `POWERBI_TENANT_ID`
- `POWERBI_CLIENT_ID`
- `POWERBI_CLIENT_SECRET`

See DEVELOPER_GUIDE.md for Azure AD setup and `.env` loading behavior (project-specific credentials from working directory).

## Import Patterns & Anti-Patterns

✅ DO:
- Put configuration in `constants.py`
- Reuse validation functions from `validation.py`
- Use centralized error handling from `exceptions.py`
- Follow existing formatter patterns in `formatters.py`

❌ DON'T:
- Hardcode magic numbers in business logic
- Duplicate validation or error handling
- Create circular dependencies
- Mix concerns (e.g., formatting in `client.py`)
