SooTool

[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 측정).

틀리는 지점은 모델이 달라도 비슷하다. 소득세 구간 경계, 양도소득세 장기보유특별공제, 부가세 반올림, 교류 임피던스 정밀도다. 문제 구성과 원자료는 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.gitcd SooTool && uv syncclaude 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"  }}

주요 기능

반올림은 호출자가 고른다

반올림 관행이 상황마다 갈리는 금융·회계 도구(부가세, 현금흐름, 감가상각, 환전 등)는 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-30policies/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}}    ]  }}

실무에서는 다음처럼 쓴다.

역산, 비교, 설명

• 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 계산 도메인 + 운영 도구)

도구별 버전, 정확도 등급, 설명은 docs/tool_catalog.md에 있다. 이 파일은 레지스트리에서 자동 생성한다.

서버 실행

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

네트워크 전송의 보안 규칙은 다음과 같다.

• 기본 바인딩은 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 rawsootool 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=2026sootool skill-guide --section triggerssootool version

파이썬 라이브러리로 쓰기

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

문서

개발

uv sync --extra symbolicmake test        # pytest와 커버리지make lint        # ruffmake typecheck   # mypyuv 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 참조.