Korean Capital Gains Tax Advisor Server

바로바로 양도소득세는 대한민국 부동산 양도 사건을 구조화하고, 계산 가능 여부를 먼저 검증한 뒤 예상 양도소득세와 개인지방소득세를 설명 가능한 형태로 계산하는 MCP 서버입니다.

이 서비스의 결과는 검토용 예상값이며 확정 신고세액이나 세무 자문이 아닙니다. 현재 세법 규칙은 pending_professional_review 상태입니다.

서비스가 해결하는 문제

부동산 양도소득세는 자산 유형, 취득·양도 시점, 필요경비, 보유·거주기간, 주택 수, 공동명의 여부에 따라 결과가 달라집니다. 사용자가 일부 조건을 누락한 채 바로 계산하면 잘못된 결과가 나올 위험이 큽니다.

이 MCP는 다음 순서로 동작합니다.

1. 개인정보 없이 필요한 거래 정보를 질문으로 수집합니다.
2. 날짜 표현을 YYYY-MM-DD 형식으로 정규화합니다.
3. 금액 표현을 원 단위 숫자로 정규화합니다.
4. 계산 전 체크리스트로 누락값, 모순된 조건, 미지원 사건을 구분합니다.
5. 입력 사건이 계산 가능한지 검증합니다.
6. 검증을 통과한 사건만 결정론적으로 계산합니다.
7. 세액, 계산 단계, 적용 규칙 버전과 주의사항을 반환합니다.

주요 기능

• 양도가액·취득가액·필요경비 기반 양도차익 계산
• 보유기간과 거주기간 검증
• 장기보유특별공제와 기본공제 계산
• 양도소득세와 개인지방소득세 계산
• 단독명의·공동명의 지분별 계산
• 공동명의와 단독명의 가정 결과 비교
• 2026.01.01, 260101, 20250101~20260101 같은 날짜 입력 정규화
• 7.5억, 7억5000만, 750,000,000 같은 금액 입력 정규화
• 아파트, 상가, 사업용 토지 같은 자산 종류 정규화
• 샀어요, 상속받음, 증여 같은 취득 방법 정규화
• 네, 아니요, 모름 같은 예/아니오 답변 정규화
• 1채, 한 채, 두 채 같은 주택 수 정규화
• 세무사가 확인했어요, 아직 검증 안 했어요 같은 비과세 검증 상태 정규화
• 단독명의, 부부 반반, 저 60 배우자 40 같은 소유 형태 정규화
• 취득세, 복비, 법무사비, 자본적 지출 같은 필요경비 정규화
• 목적 caseData 필드 기준 통합 정규화와 caseDataPatch 생성
• 계산 전 누락값 질문과 위험 체크리스트 생성
• 1세대 1주택 비과세 요청의 일관성 검증
• 규칙 적용기간과 양도일 불일치 차단
• 상속·증여 취득과 동일 연도 복수 양도 등 미지원 사건 차단
• 증빙이 확인되지 않은 필요경비 차단

MCP 도구

normalize_case_input

양도일, 양도가액, 취득일, 취득가액, 취득 방법, 자산 종류, 소유 형태, 주택 수, 거주기간, 예/아니오 답변, 비과세 검증 상태, 필요경비 같은 사용자 답변을 목적 caseData 필드에 맞게 정규화하고 caseDataPatch를 반환합니다.

지원 예시:

• targetField=transfer.price, rawValue=7억 5천만 → { "transfer": { "price": 750000000 } }
• targetField=acquisition.date, rawValue=250101 → { "acquisition": { "date": "2025-01-01" } }
• targetField=annualContext.otherTransfersExist, rawValue=아니요 → { "annualContext": { "otherTransfersExist": false } }

normalize_asset_input

아파트, 빌라, 상가, 사업용 토지, 비사업용 토지 같은 사용자 표현을 asset.subType 후보로 변환합니다.

normalize_acquisition_method_input

샀어요, 매매, 상속받음, 증여 같은 사용자 표현을 acquisition.method 값으로 변환합니다.

normalize_boolean_input

네, 아니요, 없음, 모름 같은 답변을 boolean 또는 unknown으로 변환합니다.

normalize_duration_input

2년, 2년 6개월, 30개월, 거주 안 함 같은 답변을 household.residenceYears에 사용할 정수 연 단위 값으로 변환합니다.

normalize_count_input

1채, 한 채, 두 채, 없음 같은 답변을 household.houseCount에 사용할 정수 값으로 변환합니다.

normalize_exemption_verification_input

세무사가 확인했어요, 아직 검증 안 했어요, 해당 없음, 모르겠어요 같은 답변을 household.exemptionVerificationStatus 값으로 변환합니다.

normalize_ownership_input

단독명의, 부부 공동명의, 반반, 저 60 배우자 40 같은 답변을 ownership 구조로 변환합니다.

normalize_expense_input

취득세 1200만원 증빙 있음, 복비 500만원, 법무사비 같은 답변을 expenses 항목 구조로 변환합니다.

normalize_date_input

사용자가 입력한 날짜 또는 기간 표현을 계산 도구가 사용하는 YYYY-MM-DD 형식으로 변환합니다.

지원 예시:

• 2026.01.01 → 2026-01-01
• 260101 → 2026-01-01
• 2025.01.01.-2026.01.01 → 2025-01-01, 2026-01-01
• 250101-260101 → 2025-01-01, 2026-01-01
• 20250101~20260101 → 2025-01-01, 2026-01-01

normalize_amount_input

사용자가 입력한 금액 표현을 계산 도구가 사용하는 원 단위 정수로 변환합니다.

지원 예시:

• 750,000,000 → 750000000
• 7.5억 → 750000000
• 7억 → 700000000
• 7억5000만 → 750000000
• 7억 5천만 → 750000000

prepare_capital_gains_case_checklist

사용자 답변을 누적한 caseData를 기준으로 계산 전 체크리스트와 질문 그룹을 생성합니다.

확인 항목:

• 거래 핵심값: 양도일, 취득일, 양도가액, 취득가액
• 자산 종류와 토지 사업용 여부
• 단독명의·공동명의와 지분율
• 주택 수, 거주기간, 조정대상지역 여부
• 1세대 1주택 비과세 요청과 전문가 검증 여부
• 상속·증여 취득, 동일 연도 복수 양도 등 미지원 위험
• 필요경비와 증빙 보유 여부

반환값에는 기존 questions 배열과 함께 questionGroups가 포함됩니다. questionGroups는 거래 정보, 자산 정보, 소유 형태, 세대 및 비과세, 과세연도 맥락, 필요경비 및 증빙, 지원 범위, 검증 결과 확인 순서로 질문을 묶어 반환합니다.

validate_capital_gains_case

계산 전에 필수 입력, 날짜, 소유 지분, 비과세 조건, 필요경비 증빙과 지원 범위를 검사합니다.

서비스 범위는 국내 등기 자산으로 고정되어 있으며, 국내 자산 여부와 등기 여부는 사용자에게 별도로 입력받지 않습니다.

주요 결과:

• complete: 계산 가능
• invalid: 입력 누락 또는 모순
• unsupported: 현재 엔진의 지원 범위 밖
• validForCalculation: 계산 도구 호출 가능 여부
• issues: 수정하거나 확인해야 할 항목

calculate_capital_gains_tax

검증된 사건을 받아 예상 양도소득세와 개인지방소득세를 계산합니다.

주요 결과:

• 총 예상세액
• 양도소득세와 개인지방소득세
• 양도차익, 공제액과 과세표준
• 적용 세율 유형
• 공동명의 소유자별 결과
• 규칙 버전, 가정과 경고

list_supported_capital_gains_scenarios

지원 기준일, 계산 가능한 사건, 미지원 사건과 사용상 주의사항을 반환합니다.

대화 사용 예시

사용자: 2018년에 3억원에 산 아파트를 2026년에 6억원에 팔 예정입니다.
       취득세와 중개수수료로 2천만원을 지출했습니다. 예상 세금을 계산해 주세요.

AI: 계산에 필요한 주택 수, 거주기간, 조정대상지역 여부,
    비과세 적용 요청과 증빙 상태를 추가로 확인합니다.

AI는 사용자 답변이 자연어로 들어오면 해당 normalize_* 도구로 계산 스키마에 맞게 변환한 뒤 caseData에 누적합니다. 이후 prepare_capital_gains_case_checklist, validate_capital_gains_case 순서로 호출하고, 검증을 통과한 경우에만 calculate_capital_gains_tax를 호출해야 합니다.

각 정규화 도구는 targetField, normalizedValue, readyForCaseData를 공통으로 반환합니다. readyForCaseData=false이면 사용자 확인을 먼저 받아야 합니다.

PlayMCP 호환성

• MCP 프로토콜: 2025-03-26 ~ 2025-11-25
• 전송 방식: Streamable HTTP
• 서버 방식: Stateless
• 도구 개수: 14개
• 도구 이름: PlayMCP 문자 규칙 준수
• 도구 설명: 영문 중심, 영문·국문 서비스명 병기
• 필수 annotations 제공
  • title
  • readOnlyHint=true
  • destructiveHint=false
  • openWorldHint=false
  • idempotentHint=true

카카오클라우드 배포

Agentic Player 10 제출용 배포에는 저장소 루트의 Dockerfile을 사용합니다. Dockerfile.kakao도 같은 배포 설정을 유지합니다.

PlayMCP in KC의 Git 소스 빌드 화면에 다음 값을 입력합니다.

Git URL: 이 저장소의 URL
브랜치/ref: main
Dockerfile 경로: Dockerfile.kakao
PAT: 공개 저장소라면 비워두기

카카오용 이미지는 다음 조건으로 실행됩니다.

• linux/amd64
• Node.js 20
• 컨테이너 포트 3000
• POST /mcp: MCP Endpoint
• GET /health: 상태 확인
• API 키와 Authorization 헤더 불필요
• 사용자 입력과 계산 결과를 서버에 저장하지 않음
• 요청 본문을 로그에 기록하지 않음

상세 절차는 docs/kakao-cloud-deployment.md를 참고하세요.

로컬 검증

npm ci
npm run check
npm run smoke:http:kakao

검증 항목:

• TypeScript 빌드
• 단위·회귀 테스트
• Streamable HTTP 초기화
• 도구 목록과 PlayMCP annotations
• 무인증 Endpoint 호출

카카오용 Docker 이미지 직접 빌드:

docker build --platform linux/amd64 \
  -f Dockerfile.kakao \
  -t kr-capital-gains-tax-mcp:kakao .

프로젝트 구조

src/
├─ http-server.ts          Streamable HTTP 서버
├─ mcp-server.ts           MCP 도구 등록과 annotations
├─ domain/                 계산·검증 도메인 로직
├─ rules/                  기준일별 세법 규칙 데이터
└─ tools/                  MCP 입력 스키마와 도구 어댑터

tests/
├─ unit/                   날짜·세율·검증·공동명의 테스트
└─ regression/             대표 계산 사례 회귀 테스트

안전장치

• 누락값을 임의로 추정하지 않습니다.
• 검증 실패 사건은 계산하지 않습니다.
• 규칙 적용기간 밖의 사건은 계산하지 않습니다.
• 미검증 비과세 요청은 계산하지 않습니다.
• 무증빙·기타 필요경비는 자동 공제하지 않습니다.
• 각 결과에 규칙 버전, 가정과 경고를 포함합니다.
• 계산 도구는 외부 상태를 변경하지 않습니다.

현재 지원하지 않는 사건

• 동일 과세기간 복수 양도와 양도차손 통산
• 상속·증여·부담부증여 취득
• 일시적 2주택, 상속주택과 특례주택 판정
• 조합원입주권과 분양권
• 감면, 가산세, 외국납부세액
• 국외 자산, 법인과 비거주자
• 전자신고와 신고서 자동 제출

중요 고지

현재 규칙 데이터는 공식 법령과 신고 서식에 대한 최종 전문 검토가 완료되지 않았습니다. 실제 신고, 납세 의사결정 또는 고객 제공 전에는 세무 전문가의 검토가 필요합니다.