sw-settlement-mcp

사회복지시설 결산 검증 도구 — CLI & MCP 서버

---

소개

사회복지법인·시설에서 매년 작성하는 결산서(세입결산서, 세출결산서, 각종 명세서)의 숫자 정합성을 자동 검증하는 도구입니다.

희망이음(사회서비스정보시스템)에서 다운로드한 B형 결산 통합양식(엑셀 15개 시트)을 입력으로 받아, 재원합산·증감계산·항/관합계·교차시트 일치 여부를 자동으로 확인합니다.

희망이음 B형은 전국 사회복지시설이 동일한 구조를 사용하므로, 어떤 시설의 결산서든 그대로 적용할 수 있습니다.

대상 사용자

• 사회복지법인/시설 회계 담당자 — 결산서 제출 전 자체 검증
• AI 도구 활용 복지사 — Claude Desktop, Cursor 등에서 MCP 서버로 연동
• 감사·평가 담당자 — 결산서 정합성 일괄 점검

핵심 기능

구분	내용
파서 16개	표지, 세입/세출결산서, 세입세출명세서, 수지계산서, 현금및예금, 미수금, 고정자산, 정부보조금, 후원금사용, 인건비, 사업비, 사무비, 보조금반납결의서, 세입세출집계표
V규칙 14개	단일 시트 내부 검증 (재원합산, 증감계산, 항/관합계, 합계행 일치, 음수탐지 등)
X규칙 7개	교차 시트 검증 (세입↔세출 잉여금, 세출↔명세서, 보조금 매칭, 집계표 일치 등)
CLI	터미널에서 즉시 실행, HTML 리포트 출력 지원
MCP 서버	Claude Desktop 등 AI 도구에서 직접 호출 가능 (도구 4개 제공)

MCP 도구 목록

도구	설명
validate_settlement	전체 V+X규칙 일괄 검증
parse_settlement	엑셀 파싱 → 구조화된 JSON 반환
validate_single	특정 규칙 1개만 실행 (V1V14, X1X7)
compare_settlements	두 결산서(전년/당해) 증감 비교

설치

git clone https://github.com/psa0426/sw-settlement-mcp.git
cd sw-settlement-mcp
npm install

의존성

패키지	용도
@modelcontextprotocol/sdk	MCP 서버
xlsx	엑셀 파싱
zod	입력 스키마 검증
typescript	타입 시스템
tsx	TypeScript 직접 실행

사용법

CLI

# 전체 검증
npx tsx src/cli/index.ts validate 결산검증_통합양식.xlsx

# HTML 리포트 출력
npx tsx src/cli/index.ts validate 결산검증_통합양식.xlsx --output report.html

# 특정 시트 파싱 결과 확인
npx tsx src/cli/index.ts parse 결산검증_통합양식.xlsx --sheet 세입결산서

MCP 서버 등록

Claude Desktop의 claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "sw-settlement-mcp": {
      "command": "npx",
      "args": ["tsx", "src/mcp/server.ts"],
      "cwd": "/path/to/sw-settlement-mcp"
    }
  }
}

등록 후 Claude Desktop에서 "결산 파일 검증해줘" 등의 요청으로 사용할 수 있습니다.

테스트

npm test

파서 16개 + V규칙 14개 + X규칙 7개에 대한 총 88개 테스트가 실행됩니다. 더미 데이터(tests/fixtures/dummy/)만으로 전체 테스트가 통과합니다.

프로젝트 구조

sw-settlement-mcp/
├── src/
│   ├── cli/
│   │   └── index.ts          # CLI 진입점
│   ├── mcp/
│   │   └── server.ts          # MCP 서버 (도구 4개)
│   ├── parser/
│   │   ├── index.ts           # 통합 파서 진입점
│   │   ├── utils.ts           # 파서 유틸리티
│   │   ├── parse-cover.ts     # 표지
│   │   ├── parse-income.ts    # 세입결산서
│   │   ├── parse-expense.ts   # 세출결산서
│   │   ├── parse-budget-statement.ts  # 세입세출명세서
│   │   ├── parse-balance.ts   # 수지계산서
│   │   ├── parse-cash.ts      # 현금및예금명세서
│   │   ├── parse-receivable.ts # 미수금명세서
│   │   ├── parse-asset.ts     # 고정자산명세서
│   │   ├── parse-subsidy.ts   # 정부보조금명세서
│   │   ├── parse-donation-usage.ts # 후원금사용명세서
│   │   ├── parse-labor.ts     # 인건비명세서
│   │   ├── parse-project-cost.ts # 사업비명세서
│   │   ├── parse-admin-cost.ts # 사무비명세서
│   │   ├── parse-refund.ts    # 보조금반납결의서
│   │   └── parse-ledger.ts    # 세입세출집계표
│   ├── types/
│   │   └── index.ts           # 타입 정의
│   ├── utils/
│   │   └── logger.ts          # 로거
│   └── validator/
│       ├── v-rules.ts         # V규칙 통합 진입점
│       ├── v-rules-budget.ts  # V1~V5 (결산서 검증)
│       ├── v-rules-sheets.ts  # V6~V14 (명세서 검증)
│       ├── x-rules.ts         # X규칙 통합 진입점
│       ├── x-rules-utils.ts   # X규칙 공유 유틸리티
│       ├── x-rules-budget.ts  # X1~X3 (결산서 교차검증)
│       └── x-rules-sheets.ts  # X4~X7 (명세서 교차검증)
├── tests/
│   ├── run-all.ts             # 테스트 실행기
│   ├── helpers.ts             # 테스트 유틸리티
│   ├── fixtures/
│   │   └── dummy/             # 더미 테스트 데이터
│   ├── parser/
│   │   └── test-all-parsers.ts
│   └── validator/
│       ├── test-v-rules.ts
│       └── test-x-rules.ts
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md

기여 가이드

1. Fork → 브랜치 생성 → 변경 → PR
2. npm test로 88/88 PASS 확인 후 PR
3. 파일당 400줄 이내, 한국어 주석 권장
4. 새 규칙 추가 시 PASS/FAIL 테스트 쌍 필수

라이선스

MIT - Kim Sangyong (김상용)