SooTool

SooTool

供 LLM 工具调用使用的精密计算 MCP。

一个替代 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）。

解题方	正确（精确）	近似（误差在 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 通过三种机制确保计算准确。

• 仅使用 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(영수증) }

三个入口（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 年的所得税是多少？”，Agent 就会调用 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 韩元单位舍去）则遵循相应规则，并在工具说明中注明。所得税应纳税额和个人地方所得税应纳税额均舍去不足 1 韩元的部分。

指定时点进行策略计算

税法和保险费率即使在年中也可能变更。策略工具除 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，则使用该年度已确认版本中生效日期最晚的版本。只有在 include_proposed=true 时，才会使用国会最终确认前的修订案（status: proposed）。无需重新部署服务即可修改策略文件，具体流程见 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 个 admin 工具，18 个计算领域 + 运维工具）

命名空间	数量	代表工具
core	11	add、sub、mul、div、calc（公式）、batch、pipeline、pipeline_resume、solve_for、compare、explain
accounting	12	vat_extract、vat_add、balance、3 种折旧、2 种 dupont、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、2 种 var、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、3 种 t 检验、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、4 种 QTc
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 不会将完整的工具定义加载到上下文中。Agent 使用 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 输出到标准输出，错误以 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"]   # 재실행 검증용 영수증

有关在沙盒中配置 Agent 执行 Python 的说明，请参阅 docs/sdk.md。

告知 Agent 使用规则

即使注册了工具，Agent 有时仍会直接心算。可通过以下任一方式加入“数字计算请使用 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 참조.