# Risk Assessment MCP Server

A mortgage risk underwriting server built on [FastMCP 3.x](https://gofastmcp.com) that exposes individual risk calculation tools and an aggregation tool for producing loan recommendations. Built from the [FastMCP server template](https://github.com/redhat-ai-americas/mcp-server-template).

## Tools

| Tool | Description |
|------|-------------|
| `calculate_dti` | Debt-to-Income ratio from monthly income and debts |
| `calculate_ltv` | Loan-to-Value ratio from loan amount and property value |
| `evaluate_credit_risk` | Credit risk rating from borrower credit score |
| `assess_income_stability` | Income stability from employment statuses of all borrowers |
| `assess_asset_sufficiency` | Asset reserve adequacy relative to loan amount |
| `generate_risk_recommendation` | Aggregator: combines all risk factors into Approve / Approve with Conditions / Suspend / Deny |

### calculate_dti

Computes the Debt-to-Income ratio as a percentage. Rates Low below 36%, Medium at 36--43%, High above 43%.

**Parameters:** `monthly_income` (float), `monthly_debts` (float)

**Returns:** JSON with `metric`, `value`, `rating`, `guidance`.

```json
{"monthly_income": 8000, "monthly_debts": 2400}
```

### calculate_ltv

Computes the Loan-to-Value ratio as a percentage. Rates Low below 60%, Medium at 60--80%, High above 80%. Includes `pmi_required` flag.

**Parameters:** `loan_amount` (float), `property_value` (float)

**Returns:** JSON with `metric`, `value`, `rating`, `guidance`, `pmi_required`.

```json
{"loan_amount": 320000, "property_value": 400000}
```

### evaluate_credit_risk

Evaluates credit risk from a FICO-range score (300--850). Rates Low above 680, Medium at 620--680, High below 620.

**Parameters:** `credit_score` (int), `source` (str, default `"self_reported"`)

**Returns:** JSON with `metric`, `value`, `rating`, `guidance`, `source`.

```json
{"credit_score": 720, "source": "experian"}
```

### assess_income_stability

Takes a list of employment statuses for all borrowers and returns the worst-case rating. Valid statuses: `w2_employee`, `self_employed`, `retired`, `unemployed`, `other`.

**Parameters:** `employment_statuses` (list of strings)

**Returns:** JSON with `metric`, `statuses`, `rating`, `guidance`, `individual_ratings`.

```json
{"employment_statuses": ["w2_employee", "self_employed"]}
```

### assess_asset_sufficiency

Checks asset reserves as a percentage of the loan amount. Rates Low above 20%, Medium at 10--20%, High below 10%.

**Parameters:** `total_assets` (float), `loan_amount` (float)

**Returns:** JSON with `metric`, `value`, `rating`, `guidance`.

```json
{"total_assets": 90000, "loan_amount": 350000}
```

### generate_risk_recommendation

Aggregates all five risk assessments plus document status and optional ML predictions into a final underwriting decision. The decision logic applies deny triggers (DTI > 55%, credit < 580, LTV > 97%, all borrowers unemployed), suspend triggers (missing documents), and conditional triggers (PMI, elevated DTI, self-employment documentation). Compensating factors such as strong credit offsetting high DTI are also considered.

**Parameters:** `dti_value`, `dti_rating`, `ltv_value`, `ltv_rating`, `credit_score`, `credit_rating`, `income_rating`, `asset_rating`, `employment_statuses`, `has_financial_docs`, `has_credit_report`, `document_count`, `ml_prediction` (optional), `ml_confidence` (optional)

**Returns:** JSON with `recommendation`, `rationale`, `conditions`, `compensating_factors`, `overall_risk`, `warnings`, `risk_summary`.

```json
{
  "dti_value": 38.5, "dti_rating": "Medium",
  "ltv_value": 75.0, "ltv_rating": "Medium",
  "credit_score": 720, "credit_rating": "Low",
  "income_rating": "Low", "asset_rating": "Low",
  "employment_statuses": ["w2_employee"],
  "has_financial_docs": true,
  "has_credit_report": true,
  "document_count": 5
}
```

## Quick Start

### Local Development

```bash
make install
make run-local

# In another terminal, test with cmcp
cmcp ".venv/bin/python -m src.main" tools/list
cmcp ".venv/bin/python -m src.main" tools/call calculate_dti '{"monthly_income": 8000, "monthly_debts": 2400}'
```

### Deploy to OpenShift

```bash
make deploy PROJECT=mcp-risk-server
```

The server is deployed at:
`https://mcp-server-mcp-risk-server.apps.cluster-z9hbt.z9hbt.sandbox1495.opentlc.com/mcp/`

## Testing

```bash
# Run all 53 tests
make test

# Run a single test file
.venv/bin/pytest tests/test_risk_calculations.py -v

# Test against local STDIO server with cmcp
make test-local
```

## Architecture

The server uses FastMCP 3.x with `FileSystemProvider` for automatic tool discovery. Tools use standalone `@tool` decorators (no shared server instance). The server runs in STDIO mode locally and uses streamable-http transport on port 8080 when deployed to OpenShift.

Tool source lives in two files under `src/tools/`: `risk_calculations.py` (five calculation tools) and `risk_recommendation.py` (the aggregation tool). The recommendation logic is factored into a pure `compute_recommendation()` function for direct use in tests.

## Environment Variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
| `MCP_HTTP_HOST` | `127.0.0.1` | HTTP bind address |
| `MCP_HTTP_PORT` | `8000` | HTTP port |
| `MCP_HTTP_PATH` | `/mcp/` | HTTP endpoint path |
| `MCP_LOG_LEVEL` | `INFO` | Logging level |
| `MCP_HOT_RELOAD` | `0` | Enable hot-reload for development |
| `MCP_SERVER_NAME` | `fastmcp-unified` | Server name in MCP responses |
| `MCP_AUTH_JWT_ALG` | *(none)* | JWT algorithm (e.g., RS256). Auth disabled if unset |
| `MCP_AUTH_JWT_SECRET` | *(none)* | Shared secret for HMAC algorithms |
| `MCP_AUTH_JWT_PUBLIC_KEY` | *(none)* | Public key for RSA/EC algorithms |
| `MCP_AUTH_JWT_JWKS_URI` | *(none)* | JWKS endpoint URL |
| `MCP_AUTH_JWT_ISSUER` | *(none)* | Expected token issuer |
| `MCP_AUTH_JWT_AUDIENCE` | *(none)* | Expected token audience |
| `MCP_AUTH_REQUIRED_SCOPES` | *(none)* | Comma-separated default required scopes |

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.