# jarca-ledger-mcp

Jarca 가계부 전용 MCP 서버입니다. 계좌/카드, 수입·지출 거래, 예산, 월간 현금흐름, 고정비, 투자 여력 분석을 SQLite에 저장하고 MCP 도구로 제공합니다.

## 설치

```bash
cd /root/projects/jarca-ledger-mcp
python3.11 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev,dashboard]'
```

기본 DB 위치는 `~/.local/share/jarca/ledger.sqlite3`입니다. 바꾸려면 `.env`에 설정하세요.

```bash
cp .env.example .env
# JARCA_LEDGER_DB_PATH=/원하는/경로/ledger.sqlite3
```

## Hermes 등록

```bash
hermes mcp add jarca-ledger --command /root/projects/jarca-ledger-mcp/.venv/bin/jarca-ledger-mcp
hermes mcp test jarca-ledger
```

게이트웨이/현재 세션에는 `/reload-mcp` 또는 재시작 후 반영됩니다.

## Streamlit Dashboard

로컬 웹 대시보드는 실제 기본 DB `~/.local/share/jarca/ledger.sqlite3`를 읽고 씁니다.

```bash
cd /root/projects/jarca-ledger-mcp
. .venv/bin/activate
streamlit run dashboard/app.py --server.address 0.0.0.0 --server.port 8501
```

주요 화면:

- 요약: 실제 수입/지출과 계좌 입출금을 분리 표시, 월별 현금흐름, 지출 카테고리 차트
- 거래내역: 검색/필터 및 개별 거래 카테고리 수정
- 미분류: 미분류 거래 요약, 거래별 분류, 규칙 저장
- 분류 규칙: 규칙 seed/preview/apply, 사용자 규칙 생성
- 카테고리: 대/소분류 추가, 비활성화/삭제, 사용 건수 확인
- 계좌: 등록 계좌/잔액 확인
- Import: PDF/CSV/API import batch 조회 및 rollback

## 주요 도구

- `ledger_health_check`
- `create_ledger_account`, `list_ledger_accounts`
- `create_ledger_transaction`, `list_ledger_transactions`, `update_ledger_transaction`, `delete_ledger_transaction`
- `create_ledger_budget`, `list_ledger_budgets`
- `get_monthly_cashflow_report`
- `get_category_spending_report`
- `get_fixed_cost_report`
- `get_budget_vs_actual_report`
- `get_investable_cashflow_report`
- `preview_ledger_csv_import`
- `preview_kb_bank_pdf_import`, `import_kb_bank_pdf`
- `list_ledger_import_batches`, `rollback_ledger_import_batch`
- `create_category_rule`, `seed_default_category_rules`, `list_category_rules`
- `preview_categorization`, `apply_categorization_rules`
- `list_uncategorized_transactions`, `get_uncategorized_merchant_summary`
- `create_ledger_category`, `seed_default_ledger_categories`, `list_ledger_categories`, `delete_ledger_category`

## 설계 원칙

- 금액은 원화 정수 원 단위로 저장합니다.
- 거래 금액은 양수로 넣고, `type`이 `income`, `expense`, `transfer`, `refund`, `adjustment` 중 하나로 방향을 나타냅니다.
- 금융 데이터이므로 Jarca 본체 MCP와 분리된 DB/서버로 운영합니다.
- 국민은행 PDF import는 암호화 PDF 비밀번호를 입력받아 PyMuPDF로 표를 추출하고, `transaction_datetime`, `counterparty`, `balance_after`, `branch`, `raw_summary`, `raw_payload`에 원본 세부 정보를 보존합니다.
- CSV/PDF/API import는 `import_batches`에 묶음 이력을 남기고, 잘못 가져온 batch는 `rollback_ledger_import_batch`로 되돌릴 수 있습니다.
- 카테고리에는 `cashflow_kind`를 저장해 실제 가계부 수입/지출(`income`, `expense`)과 계좌이체/투자이동/분석제외(`transfer`, `investment`, `exclude`, `debt_payment`, `unknown`)를 분리합니다.
- CSV import는 먼저 preview 후 저장하는 흐름으로 확장합니다.