Fair Value

Professional financial valuation system for OpenCode with IFRS/IVS compliance.

mcp-name: io.github.simonmak-ascent/fair-value

Overview

This project provides comprehensive financial valuation capabilities including:

• DCF, NAV, and CCA valuations
• Fama-French 5-Factor cost of equity
• KMV credit risk model
• Derivatives pricing (Options, Swaps, CB)
• Excel model review and validation
• PDF/Word/Image document analysis

Installation

pip install -r requirements.txt   # dev workflow (unchanged)
# or, as a package:
pip install .                     # base library
pip install ".[mcp]"              # + MCP server dependencies (A-004)

The console command fair-value-mcp runs the MCP server (stdio; add --http for Streamable HTTP).

MCP Server

# run locally without installing (stdio)
uvx --from "fair-value[mcp]" fair-value-mcp

# or install and run
pip install "fair-value[mcp]"
fair-value-mcp            # stdio
fair-value-mcp --http     # Streamable HTTP

The server exposes the native valuation, cost-of-capital, derivatives, credit-risk, and report-review tools, and delegates the startup-valuation and intangible-valuation tool families, so it is a strict superset of both.

Adoption target: ≥ 100 PyPI downloads and ≥ 1 directory listing within 90 days of the first release (tracked via the PyPI stats API and the directory listing).

Quick Start

from valuation_engine import run_valuation, review_report, scan_directory

# Run DCF valuation
result = run_valuation('9988.HK', 'dcf')

# Review Excel model
review = review_report('/path/to/model.xlsx')

# Scan for valuation files
files = scan_directory('/path/to/reports/')

Module Structure

src/
├── constants.py           # Standards references
├── fetch_data.py          # Data fetching (yfinance)
├── valuation/             # DCF, NAV, CCA
├── cost_of_capital/       # WACC, FF5, KMV
├── credit_risk/           # ECL calculations
├── derivatives/            # Options, Swaps, CB
├── report_review/          # Excel, PDF, Word, Image analysis
└── output/                # Report formatting

Requirements

• Python 3.8+
• yfinance
• pandas, numpy, scipy
• QuantLib-Python
• openpyxl
• pdfplumber
• python-docx

Documentation

See IMPLEMENTATION_PLAN.md for detailed specifications.

Standards Compliance

• IVS 2025
• IFRS 13 (Fair Value Measurement)
• IAS 36 (Impairment)
• HKFRS 9 (ECL)

License

Released under the MIT License.