mcp-tenant-credit-scorer/README.md

MCP server for tenant credit scoring based on S&P corporate methodology

# MCP Tenant Credit Scorer

An MCP (Model Context Protocol) server for tenant credit scoring based on S&P's corporate methodology.

## Overview

This MCP server provides automated credit analysis for small and medium-sized enterprise (SME) tenants by:
- Parsing financial statements from PDFs or structured data
- Extracting company information from websites
- Classifying industries using S&P categories
- Calculating credit scores across multiple dimensions
- Generating comprehensive credit reports

## Features

- **Automated Data Extraction**: Parse financial data from PDFs and company information from websites
- **Industry Classification**: Match companies to S&P industry categories with appropriate risk levels
- **Multi-Component Scoring**: Evaluate industry risk, competitive position, financial risk, liquidity, and management
- **Revenue-Based Adjustments**: Apply size-based modifications to reflect SME-specific risks
- **Validation Engine**: Identify and flag scoring conflicts or inconsistencies
- **Report Generation**: Create executive summaries and detailed analysis reports

## Installation

```bash
# Clone the repository
git clone [repository-url]
cd mcp-credit-scorer

# Install dependencies
npm install
```

## Usage

### As an MCP Server

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "credit-scorer": {
      "command": "node",
      "args": ["/path/to/mcp-credit-scorer/src/index.js"]
    }
  }
}
```

### Available Tools

1. **analyze_credit** - Complete credit analysis from financial data and website
2. **score_component** - Score an individual component
3. **classify_industry** - Classify a company into S&P industry categories
4. **validate_scores** - Validate score consistency and flag conflicts

### Example Usage in Claude

```
Please analyze the credit of ABC Company using:
- Website: https://abccompany.com
- Financial statements: /path/to/financials.pdf
```

## Methodology

The scoring methodology follows these steps:

1. **Industry Classification** (20% weight)
   - Maps to S&P industry categories
   - Assigns risk level based on cyclicality

2. **Competitive Position** (20% weight)
   - Evaluates competitive advantages
   - Assesses scale, scope, and diversity
   - Measures operating efficiency

3. **Financial Risk** (40% weight)
   - Primary metric: EBITDA to Interest coverage
   - Secondary check: Debt to EBITDA
   - Volatility-adjusted thresholds

4. **Liquidity** (10% weight)
   - Current ratio analysis
   - Funding source assessment

5. **Management & Governance** (10% weight)
   - Experience and transparency evaluation

6. **Revenue Adjustment**
   - Size-based modification
   - Reflects SME-specific risks

## Output

The server generates:
- Faropoint credit score (2.0-10.0 scale)
- Bond rating equivalent
- Default probability estimates
- Key strengths and risks
- Detailed scoring breakdown
- Validation results and recommendations

## Data Requirements

### Financial Data
- Revenue (3 years preferred)
- EBITDA or operating income
- Total debt
- Current assets and liabilities
- Interest expense

### Company Information
- Business description
- Industry/products/services
- Geographic scope
- Years in business
- Customer concentration (if available)

## Configuration

The server uses embedded scoring tables and industry data, but can be configured to use external data files in the `/data` directory:

- `scoring-tables.json` - All scoring thresholds and matrices
- `industry-data.json` - Industry classifications and keywords

## Development

```bash
# Run in development mode with auto-reload
npm run dev

# Run tests
npm test
```

## Architecture

- `index.js` - MCP server setup and request handling
- `data-parser.js` - PDF and website parsing
- `industry-matcher.js` - Industry classification logic
- `score-calculator.js` - Component scoring algorithms
- `validator.js` - Score validation and consistency checks
- `report-generator.js` - Report formatting and generation

## License

MIT