fixed-income-mcp

fixed-income-mcp

AI エージェント向けの債券分析機能です。モデルが実際に犯す誤りを見抜くチェックを備えています。

固定利付債の価格を算出し、金利感応度を測定します。単なる計算機とは異なる点が二つあります。分析的に求めたデュレーションをすべて、慣例に依存しない数値計算によるデュレーションと照合し、すべての評価額が正しい答えの満たすべき範囲内にあるかを検証します。

中核となる価格計算と分析機能（bondmath.bond、.pricing、.analytics、.checks、.daycount、.schedule）は標準ライブラリのみで動作します。配布パッケージには MCP SDK もインストールされます。これは bondmath.server に必要です。この依存関係が任意ではない理由については、MCP サーバーとして利用するを参照してください。

---

理由

ある言語モデルに普通社債の修正デュレーションを尋ねたところ、3.0942年と回答しました。正しい値は3.1686です。年2回利払いの債券なのに、マコーレー・デュレーションを、年利ではなく利払い期間ごとの利回りに1を足した値で割ってしまったためです。

その後、さらに興味深いことが起きました。デュレーションとコンベクシティによる近似が正確な再評価と一致しなくなると、その差を「テイラー級数の3次の項」と説明したのです。その年限の債券に100 bpの変動を与えた場合、本来の3次の項は0.09 bpです。説明されていた残差は、モデル自身が計算を誤ったデュレーションに由来するものでした。誤りを理論として返していたのです。

別のセッションでは、額面の97.80％で取引されている債券の利回りを4.01％と回答しました。これは現在利回りの4.09％を下回っており、したがって答えとしてあり得る範囲外です。

詳しい解説は joselillotrax-cell/bond-deskにあります。

このライブラリは、こうした問題への答えです。計算を正しく行うツールをエージェントに提供し、そのツールに結果を明示させます。

設計

ニュートン・ラフソン法ではなく、二分法を採用します。 ニュートン法は収束が速い一方、発散したり、価格計算の方程式を解かずに反復条件だけを満たす値に落ち着いたりすることがあります。まさに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に対応しています。クーポンの頻度は年1回、半年ごと、四半期ごと、毎月です。スケジュールは満期から逆算して生成されるため、通常の利払日以外に発行された債券でも、初回の不規則な利息計算期間を正しく処理できます。

MCP サーバーとして利用する

ツールは6種類あります。エージェントがこうした計算を頭の中でする必要はありません。

ツール	機能
yield_from_price_tool	市場価格から最終利回りを算出します
price_from_yield_tool	指定利回りでのクリーン価格とダーティ価格を算出します
bond_analytics_tool	デュレーション、DV01、コンベクシティを算出し、両方の方法で照合します
cashflow_schedule_tool	残存キャッシュフロー、割引係数、現在価値を算出します
scenario_shock_tool	正確な再評価と1次・2次の推定値を比較します
check_consistency_tool	別の方法で算出された利回りを監査します

モデルが単に呼び出せるだけでなく、実際に使えるものにするため、二つの設計上の判断を採用しています。

パラメーター名に単位を含めています。 coupon_rate というフィールド名では、4％を 4 と 0.04 のどちらで表すのか迷いが生じます。誤った値を指定すると、見た目にはもっともらしいまま100倍の誤差になります。ここではすべて coupon_rate_pct、clean_price_pct_of_face、ytm_pct のように単位を明示しています。推測は不要です。

評価結果には必ず判定が付属します。 結果には all_checks_passed フラグと、判定の根拠となる制約条件の一覧が含まれます。これにより、モデルは数値だけでなく、その値が妥当な範囲内にあるかどうかも確認できます。

インストール

pip install bondmath

mcpは任意の追加機能ではなく、必須の依存関係です。MCP レジストリは、パッケージのidentifierをPyPI上のプロジェクト名と完全一致で検証するため、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固有の問題が2つ発生しました。Python 3.14は隠し.pthファイルを警告なしに読み飛ばし、iCloud Driveは~/Desktop内のファイルを警告なしに隠しファイルとして扱うことがあります。また、起動されたサブプロセスが~/Desktop、~/Documents、~/Downloadsからファイルを読み取るには、明示的な許可が必要です。これらのフォルダー以外（~/dev、~/codeなど、クラウドと同期されない場所）にインストールすれば、両方の問題を回避できます。

実際の使用例

Claude Desktopで自然言語の質問を使ってテストし、各ツール独自の出力と個別に照合した、3つのやり取りを紹介します。パラメーターは事前に入力していません。

「同僚が、半年ごとに4％の利息が支払われる債券が……額面の97.80％で取引されていて、利回りは4.01％だと言っています。これは妥当ですか？」 — 最初から再計算するのではなく、check_consistency_toolを直接呼び出し、67.67 bpの誤差を正しく特定して、追加のやり取りなしにその理由を説明しました。「債券は額面を下回る価格で取引されているため、クーポン利回り < 現在利回り < 最終利回りでなければなりません。」

「2032年に満期を迎えるクーポン3.5％の債券が96.4で取引されています。利回りはいくらですか？」 — 額面、発行日、利払い頻度がすべて不足していました。スキーマの必須フィールドissue_dateによって最初の呼び出しは拒否され（MCP error -32602: invalid_type）、モデルは仮定を勝手に補うことなく、置いた仮定を明らかにしました。また、利払い頻度の仮定で答えがほとんど変わらないことを示すため、半年ごとの場合と年1回の場合の両方を計算しました。

「金利リスクが大きいのはどちらですか。A（4％、2029年満期、価格98）とB（2％、2035年満期、価格85）では？」 — ツールを2回連続で呼び出し、正しくB（7.43年対2.14年）と判定しました。また、影響する2つの要因を分けて説明しました。満期が長いことに加え、クーポンが低いため、債券価値に占める最終的な元本返済額の割合が大きくなります。さらに、2つの債券は同じ価格で取引されていないため、通貨単位での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。