Fair Value MCP Server

公允价值

面向 OpenCode 的专业财务估值系统，符合 IFRS/IVS 要求。

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

概述

一个估值核心，同时以 MCP 服务、REST API 和 Python 库的形式提供，其 14 个原生 calculate_* 工具 / 135 种方法涵盖企业、初创公司和无形资产估值，并符合 IVS 2025 和 IFRS/IAS：

• DCF / NAV / CCA / 剩余收益、市场倍数、资本成本（WACC、Fama-French 五因子、累加法）
• 期权、固定收益（期限结构曲线）、可转换债券、结构性产品
• IFRS 9 / HKFRS 9 信用风险（ECL、PD/LGD、CVA/DVA）、精算现值（IFRS 17、IAS 19、IAS 37）
• 公允价值调整（IFRS 13）、预期价值和亏损企业估值方法

每项结果都采用确定性优先的封装格式，其中包含中心值、solution_type、statistics（σ / 百分位数，以及少数随机方法采用的带种子样本）和 citations，可定位到原文 IVS/IFRS 条款。135 种方法中有 120 种附有准则引用，分类体系中没有孤立条款，并通过 CI 中的符合性门禁进行强制检查。

快速开始（≤ 5 分钟）

最快的方式——无需安装：

• 托管 MCP（Streamable HTTP）： https://fair-value.ascent-partners.com/mcp
• 托管 REST： https://fair-value.ascent-partners.com/v1/health
• 网站与文档： https://fair-value.ascent-partners.com/
• 本地运行，无需安装： uvx --from "fair-value[mcp]" fair-value-mcp

然后调用 14 个 calculate_* 工具中的任意一个（添加 -help / help=true 以查看生成的透明度记录）。客户端配置： MCP 服务。

架构

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"]

安装

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

控制台命令 fair-value-mcp 用于运行 MCP 服务（stdio；添加 --http 可启用 Streamable HTTP）。

MCP 服务

# 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

该服务提供 14 个原生 calculate_* 工具，涵盖 DCF、资本成本、市场倍数、剩余收益 / 资产估值、期权、预期价值、信用风险、精算现值、行业指标、公允价值调整、可转换债券、结构性产品、亏损企业和固定收益——所有工具均源自同一方法规范注册表。为任意工具添加 -help（或使用 help=true），即可查看生成的文档，其中包含公式参考、输入项和适用条款。

采用目标： 首次发布后的 90 天内达到 ≥ 100 次 PyPI 下载，并至少被一个目录收录（通过 PyPI 统计 API 和目录收录情况进行跟踪）。

REST API

同一核心还通过 /v1 提供服务（由 mcp_server.asgi:app 与 MCP 一同提供）：

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}'

端点：/v1/health、/v1/tools、/v1/methods、/v1/standards、 /v1/openapi.json、/v1/docs（Swagger UI）、/v1/help/{tool}、 POST /v1/calculate/{tool}。请参阅 REST API。

Web 网站（Next.js）

托管域名提供 Next.js 网站，包含首页、完整文档、方法目录（每种方法单独设有页面）、准则浏览器和 API 试用区，并在同一个 Vercel 项目中提供 MCP/REST 功能。网站由数据驱动：目录在构建时根据注册表生成 （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

路由：/ 和 /docs/* 使用 Next.js；/mcp 和 /v1/* 则重写到 Python 函数（api/index.py）。网站支持本地化，通过各语言的根布局和 hreflang 提供 en（/）、zh（/zh）和 hk（/hk）。

快速开始（Python）

from valuation_engine import run_valuation

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

标准与引用

标准对齐是数据，而非代码：standards/taxonomy.json 将每种方法映射到其 IVS 和 IFRS/IAS 条款，standards/source/*.md 保存条款原文（standards/provenance.json 记录版本和来源），而 standards/coverage-baseline.json 是覆盖率门槛。引擎会为每个封装附加 solution_type 和 citations；如果已发布的方法缺少引用，或分类体系／语料库发生偏差，scripts/check_conformance.py 就会导致 CI 失败。请参阅标准参考。

模块结构

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

请求生命周期

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

开发

CI 和部署通过 APG workbench 流水线运行。

要求

• Python 3.10+
• pandas、numpy、scipy、python-dateutil
• fastmcp（MCP extra）、openpyxl、pdfplumber、python-docx
• QuantLib、pandas_datareader、pytesseract/easyocr（均为可选，并提供原生回退方案）

文档

• 文档站点：mkdocs build（参见 mkdocs.yml）；方法参考由 scripts/gen_docs.py 自动生成
• MCP 服务与 REST · REST API · 托管
• 方法 · 标准参考 · 状态与路线图
• SKILL.md — 能力规范；valuation://methods / valuation://standards — 机器可读目录

标准合规性

• IVS 2025 — 国际评估准则（103、105、210、220、230、300、400、410、500）
• IFRS 13 公允价值计量；IFRS 9 金融工具；IFRS 16 租赁；IFRS 17 保险合同
• IAS 36 资产减值；IAS 19 雇员福利；IAS 37 准备、或有负债和或有资产

许可证

基于 MIT License 发布。