# 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개만 실행 (V1~V14, X1~X7) |
| `compare_settlements` | 두 결산서(전년/당해) 증감 비교 |

## 설치

```bash
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

```bash
# 전체 검증
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`에 추가:

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

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

## 테스트

```bash
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](./LICENSE) - Kim Sangyong (김상용)