# Mortgage MCP Server

A Model Context Protocol (MCP) server that provides mortgage calculation tools for real estate agents and AI assistants.

## Features

- **Monthly Payment Calculation**: Calculate fixed monthly payments for mortgages
- **Amortization Schedules**: Generate complete payment schedules with principal/interest breakdown
- **Lump Sum Payments**: Model the impact of lump sum payments on loan payoff
- **Extra Monthly Payments**: Calculate accelerated payoff with extra payments
- **Structured Logging**: Full observability with `structlog`
- **Type Safety**: 100% typed with Python 3.13+
- **Clean Architecture**: Domain → Services → MCP Server layers

## Quick Start

### Installation

```bash
# Create environment
python3.13 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"
```

### Running the Server

```bash
python -m mortgage_mcp_server.server
```

### Running with Docker

The server can run in a Docker container for easier deployment and isolation.

**Build the image:**
```bash
# Using the build script (recommended)
chmod +x build.sh
./build.sh

# Or using docker directly
docker build -t mortgage-mcp-server:latest .
```

**Run the container:**
```bash
docker run -i mortgage-mcp-server:latest
```

The `-i` (interactive) flag is **required** — it keeps stdin open for MCP stdio communication with VSCode/Claude.

**Using Docker Compose:**
```bash
docker-compose up --build
```

For full Docker setup and VSCode integration details, see [DOCKER.md](DOCKER.md).

### Example: Calculate Monthly Payment

Using the MCP protocol, call the `calculate_monthly_payment` tool:

```json
{
  "principal": 350000,
  "annual_interest_rate": 6.5,
  "loan_term_years": 30
}
```

Returns:
```json
{
  "principal": "350000",
  "annual_interest_rate": "6.5",
  "loan_term_years": 30,
  "monthly_payment": "2208.84"
}
```

## Architecture

```
src/mortgage_mcp_server/
├── domain/           # Pure mortgage calculation logic
│   └── mortgage.py   # Core math (monthly payment, amortization, etc.)
├── schemas/          # Pydantic models for validation
│   └── loan.py       # Input/output schemas
├── services/         # Application orchestration
│   └── calculator.py # Service layer coordinating domain + I/O
├── server.py         # MCP server exposing tools
└── logging.py        # Centralized structlog configuration
```

### Design Principles

- **Domain Layer**: Pure functions with no I/O, fully typed, comprehensive docstrings
- **Services Layer**: Orchestrates domain logic, validates at boundaries, uses Pydantic
- **MCP Server**: Exposes tools via Model Context Protocol
- **Logging**: Structured events via `structlog` for observability

## Available Tools

### `calculate_monthly_payment`
Calculate the fixed monthly payment for a mortgage.

**Parameters:**
- `principal` (number): Loan amount in dollars
- `annual_interest_rate` (number): Annual rate as percentage (e.g., 6.5)
- `loan_term_years` (integer): Loan term in years

**Returns:** Monthly payment amount

### `get_amortization_schedule`
Get the complete amortization schedule.

**Parameters:**
- `principal` (number): Loan amount
- `annual_interest_rate` (number): Annual rate as percentage
- `loan_term_years` (integer): Loan term in years

**Returns:** Full schedule with payment-by-payment breakdown

### `calculate_with_lump_sum`
Model the impact of a lump sum payment at a specific month.

**Parameters:**
- `principal` (number): Loan amount
- `annual_interest_rate` (number): Annual rate
- `loan_term_years` (integer): Loan term
- `monthly_payment` (number): Regular monthly payment
- `lump_sum_amount` (number): Lump sum amount
- `month_to_apply` (integer): Which month to apply the lump sum

**Returns:** Updated amortization schedule

### `calculate_with_extra_payments`
Model accelerated payoff with extra monthly payments.

**Parameters:**
- `principal` (number): Loan amount
- `annual_interest_rate` (number): Annual rate
- `loan_term_years` (integer): Loan term
- `monthly_payment` (number): Base monthly payment
- `extra_monthly_payment` (number): Extra amount per month
- `num_months_with_extra` (integer): How many months to apply extra

**Returns:** Updated amortization schedule

## Testing

```bash
# Run tests
pytest tests/

# Run with coverage
pytest --cov=src/mortgage_mcp_server tests/

# View coverage report
pytest --cov=src/mortgage_mcp_server --cov-report=html tests/
```

## VSCode Integration

To use this MCP server with Claude in VSCode, add to your `settings.json`:

```json
{
  "claude.mcp.servers": {
    "mortgage-calculator": {
      "command": ".venv/bin/python",
      "args": ["-m", "mortgage_mcp_server.server"],
      "cwd": "/Users/jibbs/Documents/git-projects/mortgage-mcp-server",
      "env": {
        "PYTHONPATH": "src"
      }
    }
  }
}
```

Or with Docker:

```json
{
  "claude.mcp.servers": {
    "mortgage-calculator": {
      "command": "docker",
      "args": ["run", "-i", "mortgage-mcp-server:latest"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

After updating settings, restart VSCode. Claude will now have access to all 4 mortgage calculation tools.

## Quality Assurance

```bash
# Lint
ruff check src/ tests/

# Format
ruff format src/ tests/

# Check formatting
ruff format --check src/ tests/

# Type check (when Ty is installed)
ty check
```

## Development

This project follows clean architecture principles and the conventions in [.github/copilot-instructions.md](.github/copilot-instructions.md).

### Key Conventions

- **Python 3.13+** with strict type checking
- **Ruff** for linting and formatting
- **Pytest** for testing
- **Pydantic** for input validation
- **Structlog** for structured logging
- **Decimal** for precise financial calculations

### Making Changes

1. Implement in appropriate layer (domain/services/server)
2. Add/update types (no `Any` unless justified)
3. Add docstrings to public APIs
4. Write tests for new functionality
5. Run quality checks:
   ```bash
   ruff check .
   ruff format .
   pytest tests/
   ```
6. Verify all checks pass before committing

## License

MIT