SooTool

SooTool

LLM のツール利用向け高精度計算。

LLM に代わって計算を担う MCP サーバーです。税金、給与、金融、統計、工学計算を Decimal で正確に実行し、計算根拠も返します。18 の計算ドメインにわたる 276 個の基本ツールと 10 個の admin ポリシーツール、一度に最大 500 件の並列計算（core.batch）、ステップをつなぐ計算（core.pipeline）、4 種類のトランスポート（stdio／Streamable HTTP／Unix、廃止予定の SSE）を提供します。Python 3.12 以上が必要です。

なぜ必要なのか

LLM は数値を計算するのではなく、もっともらしい数値を生成します。そのため、累進課税の区分境界、丸め方向、年度ごとの税率でよく間違えます。以下は同じ 20 問を解いた結果です（2026-04-24 測定）。

解答主体	正解（exact）	近似（誤差 0.01% 以内）	不正解
SooTool	20	0	0
gemini-3-pro-preview	12	4	4
claude-opus-4-7	9	3	8
gpt-5.4	5	3	12

モデルが違っても、間違える箇所はよく似ています。所得税の区分境界、譲渡所得税の長期保有特別控除、付加価値税の丸め、交流インピーダンスの精度です。問題の構成と元データは bench/ にあります。

SooTool は、次の 3 つの仕組みによって計算を固定します。

• Decimal 専用の計算。 入力数値は文字列または Decimal で受け取ります。浮動小数点誤差が計算に入り込みません。
• 法令の値を外部化。 税率、控除額、保険料率は、根拠条文と施行日を添えてポリシーファイル（YAML）に保存します。時点（as_of）を指定すると、その日に施行されていた値で計算します。
• 計算根拠を返す。 すべての応答に、数式、入力、中間値、結果を含む trace と、再実行による検証用のレシート（_meta.integrity）が付きます。

構成

 LLM 에이전트 / CLI / 파이썬 코드
        │
        │  MCP(stdio, HTTP, Unix)        sootool call ...        from sootool.sdk import tax
        ▼                                      ▼                          ▼
 ┌──────────────────────────────────────────────────────────────────────────────┐
 │ 경계 검사   인자 이름·타입·크기 검증, 숫자 문자열 → Decimal, 인증 범위 확인     │
 ├──────────────────────────────────────────────────────────────────────────────┤
 │ 레지스트리   도구 286개를 이름으로 찾아 실행 (core.batch / core.pipeline 포함)   │
 ├───────────────────────────────┬──────────────────────────────────────────────┤
 │ 도메인 도구                     │ 정책 로더                                      │
 │ tax · payroll · finance ·      │ policies/<도메인>/<이름>_<연도>.yaml           │
 │ realestate · stats · ...       │ 해시 검증 → as_of 시점의 시행 버전 선택         │
 └───────────────────────────────┴──────────────────────────────────────────────┘
        │
        ▼
 { 결과 필드, trace(공식·입력·단계·출력), 정책 출처와 근거 조문, _meta.integrity(영수증) }

3 つのエントリーポイント（MCP、CLI、SDK）は、同じレジストリを通ります。同じ入力なら、どの経路で呼び出しても結果とレシートは同じです。

クイックスタート

インストール

pip install sootool                 # 기호 계산(symbolic.*)까지 쓰려면 pip install "sootool[symbolic]"

Claude Code への登録

claude mcp add --scope user sootool -- uvx sootool

リポジトリを取得し、開発中のコードを起動するには、次のように登録します。

git clone https://github.com/JinHo-von-Choi/SooTool.git
cd SooTool && uv sync
claude mcp add --scope user sootool -- uv run --directory "$PWD" python -m sootool

最初の計算

MCP クライアントで「課税標準 5,000 万ウォンの 2026 年の所得税は？」と尋ねると、エージェントが tax.kr_income を呼び出します。ターミナルから同じツールを直接実行することもできます。

sootool call tax.kr_income --arg taxable_income=50000000 --arg year=2026 --format raw

{
  "tax": "6240000",
  "effective_rate": "0.12480000",
  "marginal_rate": "0.15",
  "breakdown": [ ... 구간별 과세표준과 세액 ... ],
  "policy_effective_date": "2026-01-01",
  "policy_citations": [{"law": "소득세법", "article": "제55조제1항", "url": "https://www.law.go.kr/법령/소득세법/제55조"}]
}

応答の読み方

finance.npv(rate="0.08", cashflows=["-1000","300","400","500","200"], rounding="HALF_EVEN", decimals=2) の実際の応答です。

{
  "npv": "164.64",
  "trace": {
    "tool": "finance.npv",
    "formula": "NPV = sum(CF_t / (1+r)^t, t=0..n)",
    "inputs": {"rate": "0.08", "cashflows": ["-1000", "300", "400", "500", "200"], "rounding": "HALF_EVEN", "decimals": 2},
    "steps": [{"label": "npv_raw", "value": "164.63539696786661172171511042618089308126395968697"}],
    "output": "164.64"
  },
  "_meta": {
    "integrity": {
      "tool": "finance.npv",
      "input_hash": "00da5199...",
      "result_hash": "d7a0ecfe...",
      "tool_version": "1.0.0",
      "sootool_version": "0.3.1"
    },
    "engine": "decimal"
  }
}

フィールド	意味
npv などの結果フィールド	計算結果です。数値はすべて文字列です。
trace.steps	丸め前の値を含む中間計算です。結果を人が検算するときに確認します。
policy_*	ポリシーツールにのみ付きます。適用したポリシーファイルの施行日、ステータス、根拠条文、ハッシュです。
_meta.integrity	レシートです。入力と結果のハッシュなので、sootool receipt verify で同じ計算を再実行して照合できます。
_meta.engine	計算エンジンです。decimal（正確）、mpmath（指定桁数）、float64（近似）、composite、none があります。
_meta.hints	次に呼び出すツールの候補です。結果の値には影響しません。

主な機能

丸め方法は呼び出し側が選択

丸めの慣例が状況によって異なる金融・会計ツール（付加価値税、キャッシュフロー、減価償却、外貨両替など）は、rounding（HALF_EVEN、HALF_UP、DOWN、UP、FLOOR、CEIL）と decimals を受け取ります。付加価値税の逆算ではウォン単位で切り捨て（DOWN）、一般的な会計では HALF_EVEN のように、用途ごとに規則が異なるためです。法令が端数処理を定めている税目（健康保険料・介護保険料、月給からの源泉徴収による地方所得税、自動車税・登録免許税は 10 ウォン単位で切り捨て）は、その規則に従い、ツールの説明に記載しています。所得税の算出税額と個人地方所得税の算出税額は、ウォン未満を切り捨てます。

時点を指定したポリシー計算

税法や保険料率は年の途中でも変更されます。ポリシーツールは year のほかに、as_of（YYYY-MM-DD）と include_proposed を受け取ります。

policies/payroll/kr_4insurance_2026.yaml             2026-01-01 ~ 2026-06-30
policies/payroll/[email protected]  2026-07-01 ~ 2026-10-31  ◀── as_of="2026-08-15"
policies/payroll/[email protected]  2026-11-01 ~ 2026-12-31

as_of가 속한 버전으로 계산하고, 응답에 그 버전의 시행일과 근거 조문을 싣는다.

as_of を指定しない場合は、その年の確定バージョンのうち施行日が最も遅いものを使用します。国会で確定する前の改正案（status: proposed）は、include_proposed=true の場合にのみ使用します。サーバーを再デプロイせずにポリシーファイルを更新する手順は、docs/policy_management.md にあります。

複数件をまとめて処理：batch と pipeline

core.batch     독립 계산 N건을 병렬로             core.pipeline   앞 단계 결과를 다음 단계 입력으로
                                                 
 ┌ s1: finance.npv(rate=0.05) ┐                  annual = core.mul(3000000, 12)
 ├ s2: finance.npv(rate=0.08) ┼─▶ id 순서로 결과       │  ${annual.result.result}
 └ s3: finance.npv(rate=0.10) ┘                       ▼
                                                  tax = tax.kr_income(annual, 2026)
 최대 500건, 항목당 10초, 전체 60초              최대 50단계, 깊이 10, 단계당 2초, 전체 30초

core.batch は項目ごとに成功、エラー、タイムアウトを個別に記録し、結果を入力順に返します。core.pipeline は前のステップが失敗すると、後続のステップを skipped として表示します。また、失敗した箇所から再実行する core.pipeline_resume（10 分間保持）もあります。

{
  "name": "core.pipeline",
  "arguments": {
    "steps": [
      {"id": "annual", "tool": "core.mul",      "args": {"operands": ["3000000", "12"]}},
      {"id": "tax",    "tool": "tax.kr_income", "args": {"taxable_income": "${annual.result.result}", "year": 2026}}
    ]
  }
}

実際の業務では、次のように使います。

作業	規模	組み合わせ
給与締め	従業員 500 人	core.batch + payroll.kr_salary
投資の感度分析	割引率 9 種類 × キャッシュフロー 5 案	core.batch + finance.npv、finance.irr
取引明細書の付加価値税の分離	数百件	core.batch + accounting.vat_extract
月給から手取り額まで	4 ステップ	core.pipeline

逆算、比較、説明

• core.solve_for：目標結果となる入力値を探します。例：手取り月給 300 万ウォンとなる税引き前の月給。
• core.compare：基準案に対するシナリオごとの値と差を表にします。
• core.explain：計算過程と適用したポリシーを韓国語または英語の文章で説明します。数値は変更しません。

レシートの再実行検証

sootool receipt verify --tool finance.fv \
  --arguments '{"present_value":"1000","rate":"0.05","periods":10}' \
  --receipt receipt.json

同じツールを再実行し、ツール名、入力ハッシュ、結果ハッシュ、ツールのバージョン、ポリシーハッシュを照合します。SOOTOOL_RECEIPT_KEY_FILE に ed25519 秘密鍵ファイルを指定すると、レシートに署名が付きます。

ツールカタログ（標準 276 個＋管理者用 10 個、18 の計算ドメイン＋運用ツール）

名前空間	数	代表的なツール
core	11	add, sub, mul, div, calc（数式）, batch, pipeline, pipeline_resume, solve_for, compare, explain
accounting	12	vat_extract, vat_add, balance, 減価償却 3 種, dupont 2 種, ratios, income_statement, cashflow_operating, break_even
finance	18	pv, fv, npv, irr, roi, cagr, payback_period, loan_schedule, bond_ytm, bond_duration, black_scholes, var 2 種, sharpe, sortino
tax	17	kr_income, kr_comprehensive_income_tax, kr_withholding_simple, capital_gains_kr, kr_gift, kr_inheritance, kr_corporate, kr_eitc, 地方税付加 3 種
tax_us	4	federal_income, capital_gains, state_tax, fica
payroll	15	kr_salary, kr_gross_from_net, kr_severance_pay, kr_year_end_tax_settlement, kr_overtime_pay, kr_minimum_wage_check, 控除 4 種
realestate	10	kr_acquisition_tax, kr_transfer_tax, kr_property_tax, kr_comprehensive, kr_ltv, kr_dti, kr_dsr, kr_subscription_score
stats	14	descriptive, t 検定 3 種, anova_oneway, regression_linear, ci_mean, bootstrap_ci, ノンパラメトリック検定
probability	30	正規、二項、ポアソン、ガンマ、ベータ、指数、対数正規、カイ二乗、F 分布の pdf・cdf・ppf, bayes, nCr, nPr
datetime	14	営業日計算, day_count, age, diff, tz_convert, 陰陽暦変換, 24 節気, 会計年度, 所得税課税期間
math	10	数値積分 2 種, 数値微分 2 種, 補間 2 種, polynomial_roots, polynomial_horner, fft, ifft
geometry	15	面積・体積 7 種, ベクトル 3 種, 行列 4 種, haversine
engineering	56	電気・交流回路、流体、熱伝達、材料力学、制御、信頼性、SI 接頭辞変換
units	8	convert, fx_convert, fx_triangulate, temperature, エネルギー・圧力・データ容量・時間の変換
medical	12	bmi, bsa, egfr, dose_weight_based, pregnancy_weeks, cha2ds2_vasc, has_bled, framingham_cvd_10y, QTc 4 種
science	11	half_life, ideal_gas, molar_mass, stoichiometry, nernst, snell_law, thin_lens, bragg など
crypto	10	gcd, lcm, egcd, modinv, modpow, crt, is_prime, euler_totient, carmichael_lambda, hash
pm	5	critical_path, pert, evm, earned_schedule, monte_carlo_schedule
symbolic	2	solve, diff（sootool[symbolic] インストール時）
sootool	2+10	skill_guide, verify_receipt, ポリシー管理 10 種（書き込み 4 種は管理者モード）

ツールごとのバージョン、精度レベル、説明はdocs/tool_catalog.mdにあります。このファイルはレジストリから自動生成されます。

サーバーの起動

sootool                                                    # stdio (MCP 클라이언트 기본)
sootool --transport http --http-port 10535                 # Streamable HTTP
sootool --transport unix --socket /tmp/sootool.sock        # Unix 소켓
sootool --transport stdio,http --socket /tmp/sootool.sock  # 여러 전송 동시 기동

トランスポート	用途	備考
stdio	Claude Code、Claude Desktop などのローカルクライアント	デフォルト
http	リモート接続（Streamable HTTP）	ステートレスなので、ロードバランサーの背後に配置できます。デフォルトポートは 10535
unix	同じホスト上の別のプロセス	ソケットファイルの権限（デフォルト 0600）でアクセスを制御します
sse-legacy	MCP 2024-11 クライアントとの互換性	廃止予定です。--enable-sse-legacyでのみ有効になります。デフォルトポートは 10536

ネットワークトランスポートのセキュリティ規則は次のとおりです。

• デフォルトのバインド先は127.0.0.1です。--host 0.0.0.0で外部に公開するには、--auth-token（またはSOOTOOL_AUTH_TOKEN）が設定されていなければ起動しません。
• ポリシーを変更する書き込みツール 4 種は、stdio と Unix ソケットでのみ公開されます。ネットワーク経由で書き込みを行うには、--admin --remote-admin --admin-token <トークン>のすべてが必要で、管理者トークンで認証されたリクエストのみが書き込みを実行します。

公開プロファイル

sootool --profile full   # 기본값. 도구 286개를 모두 노출
sootool --profile lean   # sootool.search, describe, call, skill_guide 4개만 노출

leanでは、すべてのツール定義をコンテキストに読み込みません。エージェントはsootool.searchでツールを検索し、sootool.describeで引数を確認してから、sootool.callで実行します。結果とレシートは直接呼び出した場合と同じです。sootool.callが実行するのは読み取り専用ツールのみです。

コマンドライン

サブコマンドを指定すると、サーバーを起動せずにツールを直接実行します。

sootool call core.add --arg 'operands=["1.5","2.5"]'
sootool call finance.npv --arg-json '{"rate":"0.1","cashflows":["-100","50","60","70"]}'
sootool call payroll.kr_gross_from_net --arg net_monthly=3000000 --arg year=2026 --format raw
sootool tools list --search 양도세        # 줄임말과 일상 표현으로 검색
sootool tools describe tax.kr_income     # 인자와 정책 인자 확인
sootool batch -f items.json              # -f - 는 표준입력
sootool policy show --arg domain=tax --arg name=kr_income --arg year=2026
sootool skill-guide --section triggers
sootool version

項目	内容
引数	--arg 名前=値を繰り返すか、--arg-jsonですべての引数を一度に渡します。文字列の引数は値をそのまま指定し、整数・ブール値・リスト・オブジェクトは JSON として読み込みます。
出力形式	--format pretty（デフォルト）、json（全体）、raw（trace と _metaを除く）、trace
出力先	結果は標準出力に、エラーは標準エラーに JSON で出力します。
終了コード	0 成功、1 ツールエラー、2 入力エラー、3 管理者モードが必要（SOOTOOL_ADMIN_MODE=1）、70 内部エラー

Python ライブラリとして使う

MCP サーバーを使わずに、同じツールを関数として呼び出します。結果、レシート、as_ofの処理は MCP と同じで、結果の型が宣言されているため、型チェッカーでフィールドを確認できます。

from sootool.sdk import tax

out = tax.kr_income(taxable_income=50_000_000, year=2026)
out["tax"]                                # "6240000"
out["_meta"]["integrity"]["input_hash"]   # 재실행 검증용 영수증

サンドボックスでエージェントが Python を実行する構成については、docs/sdk.mdを参照してください。

エージェントに利用ルールを伝える

ツールを登録しても、エージェントが自分で暗算してしまうことがあります。以下のいずれかで、「数値計算には SooTool を使う」というルールを設定します。

• セッション開始時にsootool.skill_guideを呼び出すようにします。いつどのツールを呼び出すかをまとめたトリガー表、例、禁止パターン、プレイブックが返されます（section: triggers, examples, anti_patterns, playbooks, all / lang: ko, en）。
• クライアント設定ファイルに貼り付けるルール：Claude Code、Cursor、AGENTS.md

문서

문서	내용
사용자 가이드	도메인별 도구 개요, 공통 인자, 응답 규칙
도구 카탈로그	도구 286개의 버전, 정확도 등급, 설명
정책 관리	정책 파일 구조, 시점 선택, 갱신·롤백 절차, 감사 로그
SDK	파이썬 라이브러리 사용법과 샌드박스 구성
외부 정책 팩	서명된 정책 묶음의 생성, 검증, 설치
안정성 계약	호환을 약속하는 범위와 폐기 절차
쿡북	세무, 금융, 전기 공학 시나리오별 호출 예시
아키텍처 결정 기록	설계 결정과 근거(ADR)
릴리스 절차	버전 올리기부터 PyPI 게시까지

개발

uv sync --extra symbolic
make test        # pytest와 커버리지
make lint        # ruff
make typecheck   # mypy
uv run python scripts/mcp_smoke_test.py   # stdio 연결 점검 (http, sse, unix 스크립트도 있다)

새 도구는 src/sootool/modules/<도메인>/에 함수를 만들고 @REGISTRY.tool(namespace, name, description, version)을 붙인 뒤 도메인 __init__.py에서 불러오면 등록된다. 도구 설명이나 타입을 바꾸면 scripts/gen_tool_catalog.py와 scripts/gen_sdk_stubs.py로 생성 문서를 다시 만든다. 정책 파일을 고치면 scripts/policy_stamp.py로 해시를 갱신한다.

라이선스

MIT. LICENSE 참조.