Fair Value MCP Server

Fair Value

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

mcp-name: com.ascent-partners/fair-value

Overview

A single valuation core — exposed as an MCP server, a REST API, and a Python library — whose **14 native calculate_* tools / 135 methods cover corporate, startup, and intangible valuation aligned to IVS 2025 and IFRS/IAS**:

• DCF / NAV / CCA / residual income, market multiples, cost of capital (WACC, Fama-French 5-Factor, build-up)
• Options, fixed income (term-structure curves), convertible bonds, structured products
• IFRS 9 / HKFRS 9 credit risk (ECL, PD/LGD, CVA/DVA), actuarial PV (IFRS 17, IAS 19, IAS 37)
• Fair-value adjustments (IFRS 13), expected value, and loss-making-company methods

Every result is a deterministic-first envelope carrying the centre value, solution_type, statistics (σ / percentiles, and seeded samples for the few stochastic methods), and citations resolving to verbatim IVS/IFRS clauses. 120 / 135 methods carry standards citations and the taxonomy has 0 orphan clauses, enforced by a conformance gate in CI.

Quick start (≤ 5 minutes)

Fastest path — no install:

• Hosted MCP (Streamable HTTP): https://fair-value.ascent-partners.com/mcp
• Hosted REST: https://fair-value.ascent-partners.com/v1/health
• Frontage & docs: https://fair-value.ascent-partners.com/
• Run locally, no install: uvx --from "fair-value[mcp]" fair-value-mcp

Then call any of the 14 calculate_* tools (add -help / help=true for the generated transparency record). Client config: MCP Server.

Architecture

flowchart LR

CLIENT["AI agent / OpenCode"] -->|"stdio (uvx) or Streamable HTTP"| MCP["fair-value-mcp 14 calculate_* tools · 135 methods"] HOST["Hosted · fair-value.ascent-partners.com docs/landing at / · MCP at /mcp · REST at /v1"] --> CLIENT MCP --> REG["method-spec registry (valuation://methods)"] REG --> STD["standards taxonomy + corpus IVS 2025 · IFRS/IAS · (valuation://standards)"] REG --> CORE["valuation engine DCF · NAV · CCA · WACC (FF5) · derivatives credit risk · actuarial"] CORE --> DATA["inputs from apdb-etl (cited)"] CORE --> ENV["result envelope value + statistics + citations"]

Installation

pip install -r requirements.txt   # dev workflow

or, as a package:

pip install . # base library pip install ".[mcp]" # + MCP server dependencies (fastmcp)

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 14 native calculate_* tools spanning DCF, cost of capital, market multiples, residual/asset valuation, options, expected value, credit risk, actuarial PV, sector metrics, fair-value adjustments, convertible bonds, structured products, loss-making companies, and fixed income — all derived from one method-spec registry. Add -help to any tool (or help=true) for its generated documentation with formula reference, inputs, and governing clauses.

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).

REST API

The same core is exposed at /v1 (served next to MCP by mcp_server.asgi:app):

curl -s localhost:8000/v1/health

curl -s -X POST localhost:8000/v1/calculate/calculate_dcf \ -H 'content-type: application/json' \ -d '{"method":"dcf","cash_flows":[100,110],"discount_rate":0.1}'

Endpoints: /v1/health, /v1/tools, /v1/methods, /v1/standards, /v1/openapi.json, /v1/docs (Swagger UI), /v1/help/{tool}, POST /v1/calculate/{tool}. See REST API.

Web frontage (Next.js)

The hosted domain serves a Next.js frontage — landing, complete docs, methods catalogue (one page per method), standards browser, and an API playground — alongside the MCP/REST function in one Vercel project. It is data-driven: the catalogue is generated from the registry at build time (scripts/gen_web_data.py → data/catalog.json).

pnpm install

pnpm dev # http://localhost:3000 (expects /v1 from the API for the playground) pnpm build # prebuild regenerates data/catalog.json pnpm typecheck && pnpm lint

Routing: / and /docs/* are Next.js; /mcp and /v1/* are rewritten to the Python function (api/index.py). The frontage is localized — en at /, zh at /zh, hk at /hk — via per-locale root layouts with hreflang.

Quick Start (Python)

from valuation_engine import run_valuation

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

Standards & citations

The standards alignment is data, not code: standards/taxonomy.json maps each method to its IVS and IFRS/IAS clauses, standards/source/*.md holds the verbatim clause text (with standards/provenance.json recording edition and source), and standards/coverage-baseline.json is the coverage ratchet. The engine attaches solution_type and citations to every envelope, and scripts/check_conformance.py fails CI if a published method loses its citation or the taxonomy/corpus drifts. See Standards reference.

Module structure

flowchart LR

SEED["method_spec_seed.py method tables · 135 methods"] --> SPEC["method_spec.py parameter vocabulary"] SPEC --> SURF["tool_surface.py 15 calculate_* tools"] SPEC --> STD["standards.py taxonomy · citations"] SURF --> SRV["server.py (FastMCP)"] SRV --> STDIO["stdio · uvx fair-value-mcp"] SRV --> HTTP["Streamable HTTP · fair-value-mcp --http"] ASGI["asgi.py (+ rest.py, openapi.py)"] --> HOST["Hosted · / + /v1"] SRV --> DOCS["docs.py -help transparency records"] STD -.->|resources| RES["valuation://methods · valuation://standards"] SRV -.-> DOCS

src/ ├── constants.py # standards references ├── valuation/ # DCF, NAV, CCA, asset standards (relief-from-royalty, MPEEM, residual) ├── cost_of_capital/ # WACC, FF5, KMV ├── credit_risk/ # ECL, PD/LGD, CVA/DVA ├── derivatives/ # options, swaps, convertible bonds, structured products, fixed income └── output/ # shared result envelope (value + statistics + citations) mcp_server/ ├── method_spec.py + method_spec_seed.py # single source of truth for tools/methods ├── standards.py # taxonomy loader, citations, coverage ├── tool_surface.py · engine.py · handlers.py · server.py ├── docs.py · rest.py · openapi.py · asgi.py └── catalog.py · prompts.py # valuation:// resources + guided prompts standards/ # taxonomy.json · source/*.md · provenance · baseline scripts/ # check_conformance.py · gen_docs.py

Request lifecycle

sequenceDiagram

autonumber participant C as MCP / REST / Python caller participant E as validation + dispatch participant R as method-spec registry participant S as standards taxonomy participant M as computation modules (src/) participant O as output envelope C->>E: calculate_*(...) / POST /v1/calculate/* E->>R: resolve method + validate parameters (no defaults) R-->>E: method spec E->>M: dispatch to valuation / cost_of_capital / credit_risk / derivatives E->>S: attach solution_type + citations M-->>E: value + steps + assumptions E->>O: ok() / error() envelope (value · statistics · citations) O-->>C: status · method · value · statistics · assumptions · citations · disclaimer

Development

CI and deployment run through the APG workbench pipeline.

Requirements

• Python 3.10+
• pandas, numpy, scipy, python-dateutil
• fastmcp (MCP extra), openpyxl, pdfplumber, python-docx
• QuantLib, pandas_datareader, pytesseract/easyocr (all optional, with native fallbacks)

Documentation

• Docs site: mkdocs build (see mkdocs.yml); method reference auto-generated by scripts/gen_docs.py
• MCP Server & REST · REST API · Hosting
• Methods · Standards reference · Status & Roadmap
• SKILL.md — capability spec; valuation://methods / valuation://standards — machine-readable catalogues

Standards compliance

• IVS 2025 — International Valuation Standards (103, 105, 210, 220, 230, 300, 400, 410, 500)
• IFRS 13 Fair Value Measurement; IFRS 9 Financial Instruments; IFRS 16 Leases; IFRS 17 Insurance Contracts
• IAS 36 Impairment of Assets; IAS 19 Employee Benefits; IAS 37 Provisions, Contingent Liabilities and Contingent Assets

License

Released under the MIT License.