Skip to main content

SooTool logo

SooTool

Precision Calc MCP for LLM tool use.

CI PyPI version Python 3.12+ License: MIT

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은 이 계산을 세 가지 장치로 고정한다.

  • 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천만 원의 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/kr_4insurance_2026@2026-07-01.yaml  2026-07-01 ~ 2026-10-31  ◀── as_of="2026-08-15"
policies/payroll/kr_4insurance_2026@2026-11-01.yaml  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개 admin, 18 계산 도메인 + 운영 도구)

Namespace Count 대표 도구
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 내부 오류

파이썬 라이브러리로 쓰기

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"]   # 재실행 검증용 영수증

샌드박스에서 에이전트가 파이썬을 실행하는 구성은 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 참조.

Metadata

Release files for sootool 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sootool 0.3.1
File Size Uploaded Provenance Actions
sootool-0.3.1.tar.gz 630.0 kB With provenance Details for sootool-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sootool 0.3.1
File Interpreter ABI Platform Actions
sootool-0.3.1-py3-none-any.whl Python 3 none any Details for sootool-0.3.1-py3-none-any.whl

Total release size: 1.5 MB

Release files / sootool-0.3.1.tar.gz

Download URL sootool-0.3.1.tar.gz
Size 630.0 kB
Tags Source
SHA-256 checksum
How to use checksums
0c55671b4c157e9b6f6b600e4667db070665478512dc09b8d133c14091ef2adf
BLAKE2b-256 checksum
How to use checksums
ac79461f9ed64ecde854a13bfcd61f04ddce565dc4d5f7c103e750465156c313
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / sootool-0.3.1-py3-none-any.whl

Download URL sootool-0.3.1-py3-none-any.whl
Size 841.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
30fb316bd6d6e248d6253244def582951d112de8e2a56affb3788d5ccf2a7b5d
BLAKE2b-256 checksum
How to use checksums
3ce0d380dcce18fcb37125a6da43bd6d572392fb5d7c1aee03b87e159d86fd52
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for sootool 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sootool-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page