284 Development C045a48c

# Azure Pricing MCP - Development Guide

## Getting Started

### Prerequisites

- Python 3.10 or higher
- pip (Python package manager)
- Git

### Clone and Setup

```bash
# Clone the repository
git clone https://github.com/msftnadavbh/AzurePricingMCP.git
cd AzurePricingMCP

# Quick setup
python scripts/install.py

# Or manual setup
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .[dev]
```

## Project Structure

```
AzurePricingMCP/
├── src/azure_pricing_mcp/   # Source code
│   ├── server.py            # Main server implementation
│   ├── handlers.py          # Tool call handlers
│   ├── __init__.py          # Package initialization
│   └── __main__.py          # Entry point
├── tests/                   # Test files
├── scripts/                 # Utility scripts
├── docs/                    # Documentation
└── pyproject.toml          # Package configuration
```

See [docs/PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) for detailed information.

## Development Workflow

### 1. Make Changes

Edit files in `src/azure_pricing_mcp/`:

- `server.py` - Add new API methods or modify server logic
- `handlers.py` - Add new tool handlers or modify existing ones

### 2. Code Quality

#### Format Code

```bash
# Format with black (line length: 120)
black src/ tests/

# Check formatting
black --check src/ tests/
```

#### Lint Code

```bash
# Run ruff linter
ruff check src/ tests/

# Auto-fix issues
ruff check --fix src/ tests/
```

#### Type Checking

```bash
# Run mypy
mypy src/
```

### 3. Testing

```bash
# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_mcp_server.py

# Run with coverage
pytest --cov=azure_pricing_mcp tests/

# Run with verbose output
pytest -v tests/
```

### 4. Run the Server

```bash
# Method 1: Module execution
python -m azure_pricing_mcp

# Method 2: Console script (after pip install)
azure-pricing-mcp

# Method 3: Run script
python scripts/run_server.py
```

### 5. Test with MCP Client

Configure VS Code or Claude Desktop to use your development server:

```json
{
  "servers": {
    "azure-pricing-dev": {
      "type": "stdio",
      "command": "/absolute/path/to/AzurePricingMCP/.venv/bin/python",
      "args": ["-m", "azure_pricing_mcp"]
    }
  }
}
```

## Adding New Features

### Adding a New Tool

1. **Add the tool method to `server.py`**:

```python
class AzurePricingServer:
    async def my_new_feature(self, param1: str, param2: Optional[int] = None) -> Dict[str, Any]:
        """
        Description of what this does.
        
        Args:
            param1: Description
            param2: Description
            
        Returns:
            Dictionary with results
        """
        # Implementation
        return {"result": "data"}
```

2. **Register the tool in `server.py` `create_server()`**:

```python
@server.list_tools()
async def handle_list_tools() -> List[Tool]:
    return [
        # ... existing tools ...
        Tool(
            name="my_new_feature",
            description="Description for AI assistant",
            inputSchema={
                "type": "object",
                "properties": {
                    "param1": {
                        "type": "string",
                        "description": "Parameter description"
                    },
                    "param2": {
                        "type": "integer",
                        "description": "Optional parameter"
                    }
                },
                "required": ["param1"]
            }
        )
    ]
```

3. **Add handler in `handlers.py`**:

```python
async def _handle_my_new_feature(pricing_server, arguments: dict) -> List[TextContent]:
    """Handle my_new_feature tool calls."""
    result = await pricing_server.my_new_feature(**arguments)
    return [TextContent(type="text", text=json.dumps(result, indent=2))]

# Register in handle_call_tool
async def handle_call_tool(name: str, arguments: dict) -> list:
    if name == "my_new_feature":
        return await _handle_my_new_feature(pricing_server, arguments)
```

4. **Write tests in `tests/`**:

```python
import pytest
from azure_pricing_mcp import AzurePricingServer

@pytest.mark.asyncio
async def test_my_new_feature():
    async with AzurePricingServer() as server:
        result = await server.my_new_feature("test_value")
        assert "result" in result
```

5. **Update documentation** in README.md

## Code Style Guidelines

### Python Style

- Follow PEP 8
- Use type hints for all function parameters and return values
- Maximum line length: 120 characters
- Use descriptive variable names
- Add docstrings to all public functions/classes

### Example

```python
from typing import Dict, Optional, List

async def search_pricing(
    service_name: str,
    region: Optional[str] = None,
    limit: int = 50
) -> Dict[str, Any]:
    """
    Search Azure pricing with filters.
    
    Args:
        service_name: The Azure service to search for
        region: Optional region filter
        limit: Maximum number of results to return
        
    Returns:
        Dictionary containing search results and metadata
        
    Raises:
        ValueError: If service_name is empty
        RuntimeError: If API request fails
    """
    if not service_name:
        raise ValueError("service_name cannot be empty")
        
    # Implementation
    return {"items": [], "count": 0}
```

## Debugging

### Enable Debug Logging

```python
import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)
```

### Debug with VS Code

Create `.vscode/launch.json`:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug MCP Server",
      "type": "python",
      "request": "launch",
      "module": "azure_pricing_mcp",
      "console": "integratedTerminal"
    }
  ]
}
```

### Test API Calls Directly

Use the debug scripts in `scripts/`:

```bash
python scripts/debug_handler_return.py
python scripts/find_app_service.py
```

## Building and Distribution

### Build Package

```bash
# Build source distribution and wheel
python -m build

# Outputs to dist/
# - azure-pricing-mcp-2.1.0.tar.gz
# - azure_pricing_mcp-2.1.0-py3-none-any.whl
```

### Install from Built Package

```bash
pip install dist/azure_pricing_mcp-2.1.0-py3-none-any.whl
```

### Publish to PyPI (Maintainers Only)

```bash
# Install twine
pip install twine

# Upload to PyPI
python -m twine upload dist/*
```

## Common Tasks

### Update Dependencies

```bash
# Add new dependency to requirements.txt
echo "new-package>=1.0.0" >> requirements.txt

# Reinstall
pip install -e .[dev]

# Update pyproject.toml dependencies section
```

### Version Bump

Update version in:
1. `pyproject.toml` - `[project]` section
2. `setup.py` - `version` parameter
3. `src/azure_pricing_mcp/__init__.py` - `__version__`

### Run Pre-commit Checks

```bash
# Format, lint, type check, and test
black src/ tests/
ruff check --fix src/ tests/
mypy src/
pytest tests/
```

## Resources

- [MCP Documentation](https://modelcontextprotocol.io/)
- [Azure Retail Prices API](https://learn.microsoft.com/en-us/rest/api/cost-management/retail-prices/azure-retail-prices)
- [Python Packaging Guide](https://packaging.python.org/)
- [Project Structure Guide](docs/PROJECT_STRUCTURE.md)

## Getting Help

- Check existing documentation in `docs/`
- Review code comments and docstrings
- Open an issue on GitHub
- Review closed issues for similar problems

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes following the guidelines above
4. Run tests and quality checks
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to your branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

### PR Checklist

- [ ] Code follows style guidelines
- [ ] All tests pass
- [ ] New tests added for new features
- [ ] Documentation updated
- [ ] Type hints added
- [ ] Docstrings added/updated
- [ ] CHANGELOG.md updated (if applicable)