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<br/>14 calculate_* tools · 135 methods"]
HOST["Hosted · fair-value.ascent-partners.com<br/>docs/landing at / · MCP at /mcp · REST at /v1"] --> CLIENT
MCP --> REG["method-spec registry<br/>(valuation://methods)"]
REG --> STD["standards taxonomy + corpus<br/>IVS 2025 · IFRS/IAS · (valuation://standards)"]
REG --> CORE["valuation engine<br/>DCF · NAV · CCA · WACC (FF5) · derivatives<br/>credit risk · actuarial"]
CORE --> DATA["inputs from apdb-etl (cited)"]
CORE --> ENV["result envelope<br/>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<br/>method tables · 135 methods"] --> SPEC["method_spec.py<br/>parameter vocabulary"]
SPEC --> SURF["tool_surface.py<br/>15 calculate_* tools"]
SPEC --> STD["standards.py<br/>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<br/>-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
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(seemkdocs.yml); method reference auto-generated byscripts/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.
Metadata
Release files for fair-value 0.2.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fair_value-0.2.7.tar.gz | 123.8 kB | Without provenance | Details for fair_value-0.2.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fair_value-0.2.7-py3-none-any.whl | Python 3 | none | any | Details for fair_value-0.2.7-py3-none-any.whl |
Total release size: 233.9 kB
Release files / fair_value-0.2.7.tar.gz
| Download URL | fair_value-0.2.7.tar.gz |
|---|---|
| Size | 123.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
116ca04c3ba1b08048ba862c25ca37b21812fcd154557133309e753bd11e1015
|
|
BLAKE2b-256 checksum How to use checksums |
d90c2243d205c5541f991096dea815ced59b050e576078ba2166c19362eb964b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / fair_value-0.2.7-py3-none-any.whl
| Download URL | fair_value-0.2.7-py3-none-any.whl |
|---|---|
| Size | 110.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
355722d9fd100b1d19b0ad86a72edc5b7c9d8875dfbe58b249db01c8aa79a708
|
|
BLAKE2b-256 checksum How to use checksums |
cb906796e1ccbe3fbaba33c4d128dc8a5118e8b07be0bc7ae42b7ac18af39ca2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for fair-value 0.2.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.