SF_studio_alpha by jdlan2wm - MCP Server

MCP Securitization Server

Status: Version 0.3.11 - Phase 2: Core Operations (22/62 tools, 35%) 🟡

A Model Context Protocol (MCP) server providing comprehensive securitization modeling capabilities for Rated Note Feeders (RFF) and Collateralized Fund Obligations (CFO). Combines TypeScript MCP interface with high-performance Python calculation engine.

🎯 Current State

Version 0.3.11 Released - Covenant Configuration Loader

✅ Foundation Complete: 10 tools operational (Phase 1)
✅ Audit Tools (MANDATORY): Cash conservation, balance reconciliation, covenant compliance
✅ Portfolio Tools: Load, analyze, simulate, ramp status tracking
✅ Cashflow Tools: Run cashflows, multi-scenario analysis
✅ Rating Calculators: KBRA QD, DBRS ACR, WARF, WARF PD
✅ Ramp Infrastructure Complete: Load ramp plans, LP/GP commitments, capital call schedules (3/3 tools) 🎉
✅ Phase Management: Phase definitions, waterfall configuration (2/2 loader tools) 🎉
✅ Covenant Tools: OC/IC checkers, covenant loader (3/4 tools) 🎉
✅ Facilities Tools: Liquidity facilities configuration (1/4 tools) 🎉
🟡 Phase 2 Active: Building core operations (Target: 25/62 tools, 88% complete)
⏸️ 40 Tools Remaining: Systematic implementation in progress
🎯 Next Priority: Balance sheet projections, sources & uses, template validation

📈 Progress Metrics

Metric	Current	Target	Status
Tools Implemented	22/62 (35%)	62/62 (100%)	🟡 On Track
Golden Tests	23/23 (100%)	100%	✅ Excellent
Test Variance	<0.01	<0.01	✅ Excellent
Phase	2: Core Ops	4: Complete	🟡 Phase 2

🚀 Quick Start

Installation

# Clone repository
cd C:\Users\johnd\mcp-securitization-server

# Install Node.js dependencies
npm install

# Setup Python virtual environment
python -m venv venv
.\venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

Build & Test

# Build TypeScript
npm run build

# Run golden tests
npm test

# Test portfolio.load directly
npm run test:portfolio

# Start MCP server
npm start

Claude Desktop Configuration

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "securitization": {
      "command": "node",
      "args": ["C:\\Users\\johnd\\mcp-securitization-server\\dist\\index.js"]
    }
  }
}

📊 Tools (16/62 Implemented)

✅ Portfolio Tools (4/8)

portfolio.load - Load and validate asset portfolio with summary statistics
portfolio.analyze - Calculate portfolio quality metrics (WARF, diversity, expected loss)
portfolio.simulate - Run default/recovery scenario analysis
portfolio.ramp_status - Calculate ramp completion percentage

✅ Structure Tools (1/7)

structure.load - Load and validate deal structure with tranches

✅ Cashflow Tools (2/3)

cashflow.run - Execute period-by-period cashflow with phase-aware waterfall
cashflow.run_scenarios - Run multiple stress scenarios (base, 2x, 2.7x)

✅ Ramp & Commitment Tools (3/6) - Ramp Infrastructure Complete 🎉

ramp.load - Load ramp plan with asset arrival schedule
commitments.load - Load LP/GP capital commitments
calls.load - Load capital call schedule (NEW in 0.3.5)

✅ Rating Tools (4/8)

ratings.warf - Calculate Weighted Average Rating Factor
ratings.dbrs_acr - Calculate DBRS Asset Coverage Ratio with diversity scoring
ratings.kbra_qd - Calculate KBRA Quantitative Determinant (5-component) ⚠️
ratings.warf_pd - Calculate WARF PD projections with stress scenarios ⚠️

✅ Audit & Validation Tools (2/10) - NEW in 0.3.0

audit.check_conservation - Validate cash conservation (sources == uses within $0.01) 🔴 MANDATORY
audit.reconcile_balances - Validate balance sheet reconciliation (Assets == Liabilities + Equity) 🔴 MANDATORY

✅ Covenant Tools (1/4) - NEW in 0.3.0

covenant.check - Check covenant compliance (OC_A, OC_B, IC, DSCR)

🔄 In Progress - Phase 2 (Target: 25/62 tools)

portfolio.ramp_status - Track ramp completion percentage
cashflow.run_scenarios - Multi-scenario cashflow analysis
ramp.load, commitments.load, calls.load - Ramp infrastructure (3 tools)
phases.load, waterfall.load - Phase and waterfall configuration (2 tools)
waterfall.compile_smart, waterfall.explain, waterfall.trace - Waterfall tools (3 tools)

⏸️ Remaining (51 tools)

See for complete tool specifications

🧪 Testing

Running All Golden Tests

# Run all golden tests via npm
npm test

# Expected output:
# ================================================================================
# MCP Securitization Server - Golden Test Suite
# ================================================================================
# Found 23 golden test(s)
# ...
# Total:  23
# Passed: 23 ✅
# Failed: 0 ❌

Running Core Cashflow Engine Test

IMPORTANT: The cashflow.run golden test MUST be executed from the project root directory.

# Navigate to project root
cd C:\Users\johnd\mcp-securitization-server

# Run the cashflow.run golden test
node golden/cashflow_run/test.js

Expected Results (Perfect Accuracy - $0.00 Variance):

✅ Period count: 3 periods

Period 1:
  ✅ Collections: $3,530,827.76 (variance $0.00)
  ✅ Class A interest: $333,333.33 (variance $0.00)
  ✅ Cash conservation: ending cash = $0

Period 2:
  ✅ Collections: $3,432,818.06 (variance $0.00)
  ✅ Class A interest: $333,333.33 (variance $0.00)
  ✅ Cash conservation: ending cash = $0

Period 3:
  ✅ Collections: $3,337,528.95 (variance $0.00)
  ✅ Class A interest: $333,333.33 (variance $0.00)
  ✅ Cash conservation: ending cash = $0

✅ Audit certification: "AUDIT PASSED: Cash conservation validated for 3 periods (max variance: $0.00)"
✅ Max variance: $0.0000
✅ Execution time: ~3,300ms

What This Test Validates:

✅ 3-period harvest phase simulation ($100M portfolio, 2 tranches)
✅ Cash conservation validation (sources == uses, $0.00 variance)
✅ Balance roll-forward accuracy (Assets == Liabilities + Equity)
✅ Waterfall payment calculations (interest, principal, distributions)
✅ Audit certification framework
✅ Phase-aware cashflow execution

Why Run From Project Root: The test uses relative paths to import the Python cashflow engine. Running from subdirectories will cause Python import errors. Always execute from the top-level mcp-securitization-server/ directory.

Test Coverage

✅ cashflow.run: 1 golden test (3 periods, $0.00 variance) 🎉 PRODUCTION READY
✅ portfolio.load: 1 golden test passing
✅ ratings.kbra_qd: 1 golden test (5-component scoring)
✅ ratings.dbrs_acr: 1 golden test (ACR/AR calculations with diversity)
✅ ratings.warf_pd: 1 golden test (7-year PD projections with 3 scenarios)
✅ covenant.check_oc: 3 golden tests (100% pass)
✅ covenant.check_ic: 3 golden tests (100% pass)
✅ covenants.load: 2 golden tests (100% pass)
✅ facilities.configure: 3 golden tests (100% pass)
✅ waterfall.load: 1 golden test (100% pass)
✅ Phase 2 Complete: 23/23 tests passing (100% pass rate)
⏸️ Other tools: Not yet tested

📐 Architecture

┌─────────────────────────────────────┐
│   Claude Code (MCP Client)         │
└──────────────┬──────────────────────┘
               │ MCP Protocol
┌──────────────▼──────────────────────┐
│  TypeScript MCP Server              │
│  - 62 MCP Tools (4 implemented)     │
│  - JSON Schema Validation (Ajv)     │
│  - Subprocess Bridge                │
└──────────────┬──────────────────────┘
               │ subprocess.spawn()
┌──────────────▼──────────────────────┐
│  Python Calculation Engine          │
│  - NumPy/Pandas/SciPy               │
│  - Portfolio Analytics ✅           │
│  - Rating Calculators ✅            │
│    • KBRA QD (5-component)          │
│    • DBRS ACR (diversity-aware)     │
│    • WARF PD (7Y projections)       │
│  - Cashflow Engine (pending)        │
│  - Audit Validation (pending)       │
└─────────────────────────────────────┘

🎓 Example: portfolio.load

// Via MCP protocol (in Claude Code)
const result = await mcp.call({
  tool: "portfolio.load",
  arguments: {
    source: "inline",
    validate: true,
    data: {
      version: "1.0",
      assets: [
        {
          id: "ASSET-001",
          obligor: "Acme Corp",
          par: 10000000,
          spread_bps: 550,
          tenor_m: 60,
          pd_quality_label: "BBB",
          recovery: 0.40
        }
        // ... more assets
      ]
    }
  }
});

// Returns:
// {
//   ok: true,
//   data: {
//     portfolio: { /* original data */ },
//     validation: { schema_valid: true, warnings: [] },
//     summary: {
//       total_par: 30000000,
//       asset_count: 3,
//       warf: 614.67,
//       wa_spread: 646.67,
//       wa_life: 4.53,
//       diversity_score: 2.92,
//       expected_loss: 0.00920,
//       concentrations: { /* metrics */ }
//     }
//   }
// }

📚 Documentation

Implementation Log: See IMPLEMENTATION_LOG.md for detailed session notes
Developer Guide: See CLAUDE.md for complete development reference
Tool Registry: All 62 tools documented in code with schemas

🔑 Key Features

Completed ✅

MCP Server: Full protocol implementation with 62 tools registered
Python Bridge: Subprocess communication for calculations
Schema Validation: Ajv-based JSON validation
Structured Logging: Winston with audit trail
Error Handling: 15 error codes with context
Portfolio Analytics: WARF, diversity, concentrations, expected loss
Golden Tests: Automated test runner with variance checking

In Progress 🚧

Cashflow Engine: Period-by-period calculation (Week 4-5)
Phase-Aware Waterfall: Investment/Harvest/Terminal phases
Cash Conservation: MANDATORY audit validation

🎯 Acceptance Criteria

✅ First tool (portfolio.load) complete with golden test
⏸️ 120-period cashflow in < 5 seconds
⏸️ All 32 templates work without modification
⏸️ 40+ golden tests passing with variance < $0.01
⏸️ Cash conservation validation enforced (MANDATORY)

🚨 Critical Requirements

Audit-First Philosophy

Every cashflow execution MUST validate:

sources = uses (within $0.01)

If validation fails:

❌ Block export/save operations
❌ Return error with variance details
❌ Do NOT return cashflow results

Template Fidelity

All 32 templates in templates/structures/ must work without modification. Any changes to cashflow/validation logic must be tested against ALL templates.

📈 Progress Tracker

Week 1 Achievements (Foundation):

✅ Project setup and MCP server skeleton
✅ Python bridge and subprocess communication
✅ JSON Schema validation with Ajv
✅ Structured logging and error handling

Week 2 Achievements (First Tool):

✅ Python virtual environment setup
✅ Portfolio analyzer implementation (338 lines)
✅ portfolio.load tool (109 lines)
✅ Schema integration
✅ Test infrastructure
✅ First golden test passing

Week 3 Achievements (Rating Calculators):

✅ KBRA QD calculator (530 lines Python, 80 lines TS)
✅ DBRS ACR calculator (380 lines Python, 100 lines TS)
✅ WARF PD calculator (350 lines Python, 90 lines TS)
✅ Three rating MCP tools integrated
✅ Three golden tests created and documented
✅ Build verification successful
✅ CHANGELOG.md documentation complete

Next Session Goals (Week 4):

🎯 Start cashflow engine implementation
🎯 Design phase-aware waterfall structure
🎯 Implement cash conservation validator

🛠️ Development

Project Structure

mcp-securitization-server/
├── src/                      # TypeScript MCP server
│   ├── index.ts              # ✅ MCP server entry point
│   ├── tools/                # ✅ Tool implementations (4/62 done)
│   │   ├── portfolio.ts      # ✅ Portfolio load & analysis
│   │   └── ratings/          # ✅ Rating calculators
│   │       ├── kbra-qd.ts    # ✅ KBRA QD
│   │       ├── dbrs-acr.ts   # ✅ DBRS ACR
│   │       └── warf-pd.ts    # ✅ WARF PD
│   ├── utils/                # ✅ Python bridge, logger, errors
│   └── schemas/              # ✅ JSON Schema validator
├── python/                   # Python calculation engine
│   ├── portfolio/            # ✅ Portfolio analytics
│   ├── rating/               # ✅ Rating calculators
│   │   ├── kbra_qd.py        # ✅ KBRA QD (530 lines)
│   │   ├── dbrs_acr.py       # ✅ DBRS ACR (380 lines)
│   │   └── warf_pd.py        # ✅ WARF PD (350 lines)
│   ├── cashflow/             # ⏸️ Cashflow engine (pending)
│   └── audit/                # ⏸️ Validation (pending)
├── schemas/                  # ✅ JSON schemas
├── golden/                   # ✅ Golden test cases
│   ├── portfolio/            # ✅ 1 test passing
│   └── ratings/              # ✅ 3 tests (kbra-qd, dbrs-acr, warf-pd)
├── templates/                # ✅ 32 structure templates
└── dist/                     # ✅ Compiled output

Adding New Tools

Create Python module in python/<category>/<module>.py
Implement tool handler in src/tools/<category>.ts
Wire handler in src/index.ts tool registry
Create golden test in golden/<category>/
Run npm test to validate

📝 License

ISC

Last Updated: 2025-10-20 (Week 3 Complete) Version: 0.3.0 (Rating Calculators Phase) Status: Active Development - 4 Tools Complete ✅