fixed-income-mcp

fixed-income-mcp

面向 AI Agent 的固定收益分析，并内置可捕捉模型实际会犯错误的检查。

为固定息票债券定价并衡量其利率敏感度。它与计算器的不同之处有两点：每种解析久期都会通过与不依赖惯例的数值久期进行比对来验证；每项估值都会根据正确答案必须满足的界限进行检查。

定价与分析核心（bondmath.bond、.pricing、.analytics、.checks、.daycount、.schedule）仅使用标准库。按此分发的包还会安装 MCP SDK，这是 bondmath.server 所必需的依赖——请参阅作为 MCP 服务，了解为何该依赖不可省略。

---

原因

有人让大模型计算一只普通债券的修正久期，模型给出了 3.0942 年。正确值是 3.1686。它用麦考利久期除以 1 加上年化收益率，而不是除以 1 加上每期收益率——对于每年付息两次的债券，这是错误的除数。

接着它做了件更有意思的事。它自己的久期加凸性近似值开始与精确定价不符，于是把差距解释为“泰勒级数的三阶项”。对于该期限的债券和 100 bp 的变动，真正的三阶项只有 0.09 bp。它用来解释差距的残差，实际上源自它自己算错的久期，却被它当作理论交了回来。

另一次会话给出了一只交易价格为面值 97.80% 的债券，其收益率为 4.01%——低于 4.09% 的当前收益率，因此超出了可能答案的范围。

完整说明见 joselillotrax-cell/bond-desk。

这个库正是对此问题的解决方案：给 Agent 一个能正确计算的工具，并让工具明确说明计算正确。

设计

二分法，而非牛顿-拉夫森法。 牛顿法收敛更快，但可能发散，也可能停在一个满足迭代条件、却没有解出定价方程的值上。这正是 4.01% 错误的由来。二分法不会出现这种情况。

除了解析久期，还提供有效久期。 对定价函数进行中心差分不涉及年化，因此数值结果不会继承惯例错误。两者不一致时，错的就是解析久期。

故意计算错误答案。 Analytics.naive_modified 会保留错误除数产生的数值。这对一个库来说并不寻常，但这样工具才能标记错误，而不是悄悄避开它。

使用

from datetime import date
from bondmath import Bond, DayCount, yield_from_price, analytics, check_consistency

bond = Bond(
    face=1000,
    coupon_rate=0.04,
    frequency=2,
    issue=date(2024, 3, 15),
    maturity=date(2029, 3, 15),
    basis=DayCount.ACT_ACT_ICMA,
)
settle = date(2025, 9, 11)

quote = yield_from_price(bond, settle, 978.00)   # 97.80% of par
print(f"{quote.dirty:.4f}")          # 997.5652
print(f"{quote.ytm:.4%}")            # 4.6867%

metrics = analytics(bond, settle, quote.ytm)
print(f"{metrics.modified:.4f}")     # 3.1686  <- correct
print(f"{metrics.naive_modified:.4f}")  # 3.0976  <- the common error
print(f"{metrics.effective:.4f}")    # 3.1694  <- numerical arbiter

print(check_consistency(bond, settle, quote, metrics))
# [PASS] below_par_ordering: trading below par at 97.8000%, so
#        coupon < current yield < YTM must hold: 4.0000% < 4.0900% < 4.6867%
# ...

情景分析可以单独展示真实的高阶残差：

from bondmath import scenario

s = scenario(bond, settle, quote.ytm, shock_bp=100)
print(f"{s.exact:.2f}")          # 966.55
print(f"{s.residual_bp:+.2f}")   # +0.09 bp, not the six the model claimed

惯例

ACT/ACT ICMA、30/360（美国债券惯例）、ACT/365 和 ACT/360。年度、半年、季度和月度付息。付息计划从到期日向前生成，因此对于非周期发行的债券，可以正确处理不规则的首个计息期。

作为 MCP 服务

提供六种工具，让 Agent 不必再在脑中做这些计算。

工具	功能
yield_from_price_tool	根据市场价格求到期收益率
price_from_yield_tool	计算给定收益率下的净价和全价
bond_analytics_tool	久期、DV01、凸性——并提供两项交叉检查
cashflow_schedule_tool	剩余现金流、贴现因子、现值
scenario_shock_tool	精确定价与一阶、二阶估算的对比
check_consistency_tool	审核他人计算出的收益率

两个设计决定让模型能实际使用这些工具，而不只是调用它们。

单位写在参数名中。 名为 coupon_rate 的字段会让人疑惑 4% 应写作 4 还是 0.04；猜错后数值会相差一百倍，看起来却依然合理。这里所有参数名都明确标注单位：coupon_rate_pct、clean_price_pct_of_face、ytm_pct。无需猜测。

每项估值都会给出自己的判定。 结果中包含 all_checks_passed 标记和用于判定的界限列表，让模型知道该数值是否合理，而不只是知道它是多少。

安装

pip install bondmath

mcp 是必需依赖，而不是可选扩展——MCP 注册表会根据 PyPI 上的精确项目名称验证包的 identifier，像 bondmath[mcp] 这样的带扩展名称无法通过验证。普通安装必须足以运行服务。

然后进行注册。在 Claude Desktop 中，将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "fixed-income": {
      "command": "fixed-income-mcp"
    }
  }
}

在 Claude Code 中：

claude mcp add fixed-income -- fixed-income-mcp

**如果找不到命令：**通过 pip 安装的脚本可能不在启动进程的 PATH 中。请改用绝对路径——在安装所用的环境中通过 which fixed-income-mcp 查找，并将完整路径填入 command。

**如果你使用 macOS，且服务显示“disconnected”但没有明确错误：**先检查 ~/Library/Logs/Claude/mcp-server-fixed-income.log——面板中的错误消息并非真正的错误。开发期间，这个项目遇到了两个 macOS 特有的问题：Python 3.14 会静默跳过隐藏的 .pth 文件，iCloud Drive 也可能在不发出警告的情况下将 ~/Desktop 中的文件标记为隐藏；此外，~/Desktop、~/Documents 和 ~/Downloads 都需要明确授权，启动的子进程才能读取其中的文件。安装到这些文件夹以外的位置（如 ~/dev、~/code 或任何未与云端同步的位置）即可避免这两个问题。

实际使用

以下是使用 Claude Desktop 测试时的三段对话：通过自然语言提问，而非预先填入参数，并独立对照每个工具自身的输出进行了交叉核验：

“有个同事告诉我，一只半年付息、票息为 4% 的债券……报价为 97.80%，收益率为 4.01%。这合理吗？” — 直接调用了 check_consistency_tool，而非从头重新计算；正确识别出 67.67 bp 的误差，并解释了原因，无需反复尝试：“债券折价交易，因此票息 < 当前收益率 < 到期收益率。”

“一只票息为 3.5%、2032 年到期的债券，报价为 96.4。它的收益率是多少？” — 面值、发行日期和付息频率均未提供。该架构中的必填字段 issue_date 拒绝了第一次调用尝试（MCP error -32602: invalid_type）；模型说明了之后采用的假设，而不是悄悄编造信息，并分别计算了半年付息和年付息两种情形，显示付息频率假设对答案影响很小。

“哪只债券的利率风险更高：A（4%，2029 年到期，报价为 98）还是 B（2%，2035 年到期，报价为 85）？” — 连续调用了两个工具，给出了正确结论（B，7.43 年对比 2.14 年），并解释了两个起作用的因素：更长期限，以及较低票息将更多债券价值推到了最终本金偿付部分。它还主动指出，以货币金额比较 DV01，得出的比率不同于以百分比比较修正久期，因为这两只债券的交易价格不同。

审核可疑数据

check_consistency_tool 是为本项目启动时遇到的情况而设计的——核查别人已经算出的数字：

claimed_ytm_pct        4.01
correct_ytm_pct        4.686736
error_bp               -67.67
all_checks_passed      false

[FAIL] below_par_ordering: trading below par at 97.8000%, so
       coupon < current yield < YTM must hold:
       4.0000% < 4.0900% < 4.0100%

开发环境安装

pip install -e ".[dev]"
python -m pytest -q

共有 59 个测试。其中一些会固定说明文档中的数值：如果有人把除数换回去，test_naive_divisor_is_the_one_that_disagrees 就会失败。另一些则会检查 MCP 架构本身——test_every_parameter_carries_a_description 的存在，是因为此服务的早期版本没有任何参数描述，模型只能靠猜测才能发现这一点。

未涵盖的内容

嵌入式期权、浮动票息、偿债基金、摊还结构、除息惯例、信用风险和结算延迟。这是用于教学和核查的工具，不是交易系统。

许可证

MIT。