120 lines
7.7 KiB
Markdown
120 lines
7.7 KiB
Markdown
# Jarca Ledger MCP Interface Contract
|
|
|
|
- Baseline Mode: observed
|
|
- Baseline Seed: `.stage-pilot/bootstrap/baseline.yaml`
|
|
- Status: draft
|
|
- Owner: Jarca / project maintainer
|
|
- Last Updated (KST): 2026-06-29
|
|
- Source Discovery / Batch: bootstrap-baseline
|
|
|
|
## Project Summary
|
|
- Jarca 가계부 전용 MCP 서버와 Streamlit 대시보드로 계좌/카드 거래, 예산, 분류 규칙, import, 현금흐름 분석을 SQLite에 저장하고 운영한다.
|
|
|
|
## Purpose
|
|
- This document captures the current external and operator-facing interface baseline.
|
|
- It is a reference for future Discovery, REQ, Batch, and Release work that changes tool signatures, dashboard behavior, or file import contracts.
|
|
|
|
## Interface: MCP Tool Surface
|
|
- Type: internal-service
|
|
- Actors: Hermes Agent and MCP clients
|
|
- Entrypoint: `jarca-ledger-mcp` script -> `jarca_ledger_mcp.server:main`
|
|
- Stability: internal but should preserve existing success response shapes for compatibility.
|
|
|
|
### Representative Tool Groups
|
|
- Health: `ledger_health_check`, `get_ledger_db_status`
|
|
- Operational backup: `create_ledger_backup`, `list_ledger_backups`, `get_ledger_backup_status` (restore is intentionally not exposed as MCP)
|
|
- Accounts: `create_ledger_account`, `list_ledger_accounts`, `update_ledger_account`; account payloads include additive `liquidity_bucket` for asset-liquidity reporting.
|
|
- Transactions: `create_ledger_transaction`, `list_ledger_transactions`, `update_ledger_transaction`, `delete_ledger_transaction`
|
|
- Budgets/reports: `create_ledger_budget`, `list_ledger_budgets`, monthly/category/fixed/budget/investable reports, `get_asset_liquidity_report`
|
|
- Imports: KB Bank PDF, Toss Bank PDF, Toss Securities PDF, SeoulPay XLSX, CSV preview/import where implemented
|
|
- Categories/rules: category CRUD, rule CRUD, categorization preview/apply, uncategorized summaries
|
|
- Reconciliation: cross-account preview/run/review queue, self-transfer candidates/linking, cancel-original candidates/linking
|
|
- Manual balance reconciliation: `get_balance_reconciliation_report` returns preview-only account reconciliation for `manual_only`/`partial_import` accounts.
|
|
|
|
### Inputs
|
|
- Structured MCP tool arguments as declared in `server.py` signatures.
|
|
- File paths and optional passwords for encrypted or password-protected documents.
|
|
- Transaction/account/category identifiers for update, delete, and link operations.
|
|
|
|
### Outputs
|
|
- Python dictionary payloads containing success data, counts, records, previews, reports, or error details.
|
|
- Backup/status tools return metadata-only DB evidence: path, size, mtime, sha256, integrity check, table row counts, and aggregate totals.
|
|
- Existing success shape compatibility is preferred; new fields should be additive where possible.
|
|
|
|
### Errors
|
|
- Validation errors for invalid parameters or missing IDs.
|
|
- Parser errors for unreadable or unsupported source files.
|
|
- Password/validation errors for encrypted import files.
|
|
- Candidate-not-found errors for link operations when the chosen pair is not in the preview set.
|
|
|
|
### Compatibility Rules
|
|
- Preserve existing success response shapes unless a migration/REQ explicitly approves a breaking change.
|
|
- Additive backup/status/list/hash tools are allowed; restore execution must not be added as an MCP tool.
|
|
- Do not write secrets, raw passwords, raw_payload, full merchant/counterparty dumps, or full account identifiers into persistent output, skill files, or committed documentation.
|
|
- Source evidence should remain auditable through raw fields and import batch records.
|
|
|
|
## Interface: Streamlit Dashboard
|
|
- Type: web-app
|
|
- Actors: Local operator
|
|
- Entrypoint: `streamlit run dashboard/app.py --server.address 0.0.0.0 --server.port 8501`
|
|
- Stability: internal operator UI
|
|
|
|
### Pages
|
|
- 요약
|
|
- 거래내역
|
|
- 확인필요 큐
|
|
- 미분류
|
|
- 분류 규칙
|
|
- 카테고리
|
|
- 계좌
|
|
- Import
|
|
|
|
### Inputs
|
|
- Local SQLite database selected by `JARCA_LEDGER_DB_PATH` or default path.
|
|
- Uploaded transaction history files.
|
|
- User edits for categories, rules, transactions, and manual links.
|
|
|
|
### Outputs
|
|
- Tables, charts, dialogs, previews, import results, and transaction/category updates.
|
|
- Browser evidence runs produce local PNG screenshots, DOM snapshot HTML files, and a manifest JSON for QC review.
|
|
|
|
### UI Contract Rules
|
|
- Surface `cashflow_kind` where classification affects actual cashflow interpretation.
|
|
- Keep actual income/expense separated from account movement summaries.
|
|
- Rule page should support create/edit/delete and condition fields `amount_min`, `amount_max`, `day_of_month`.
|
|
- Dialog-based triage actions should avoid losing context where possible.
|
|
- Account page should display/edit `statement_status` and show a minimal manual balance reconciliation report without adding an automatic schedule or dedicated workbench.
|
|
- Account page should display/edit `liquidity_bucket`; overview uses it with `last_balance` for asset liquidity/composition/debt/net-worth sections.
|
|
- Overview top priority is KST current-month actual income/expense/net cashflow/savings rate based on `transaction_date` and `cashflow_kind`.
|
|
- UI/dashboard-impacting batches require browser screenshot/snapshot evidence from synthetic/validation DBs. Non-UI batches may omit browser evidence, and docs-only batches do not require it.
|
|
|
|
## Interface: File Import Contracts
|
|
- KB Bank PDF: encrypted/password-protected PDF account history; preserve transaction datetime, counterparty, balance, branch, raw summary, and raw payload.
|
|
- Toss Bank PDF: transaction history PDF parsed into ledger transaction candidates.
|
|
- Toss Securities PDF: securities transaction history with investment movement, dividend, interest, and external transfer handling.
|
|
- SeoulPay XLSX: possibly encrypted Office XLSX/OLE file; decrypt with supplied password and import usage details as actual spending evidence.
|
|
- CSV: generic preview-first import path.
|
|
|
|
## Shared Constraints
|
|
- All import flows should support preview before mutation where implemented.
|
|
- Dedupe should use deterministic source/external IDs or same-account/date/type/amount/merchant evidence.
|
|
- Import batch metadata should support rollback and audit.
|
|
- Broad mutation workflows should capture metadata-only DB status and backup evidence before/after risky operations.
|
|
- Restore execution is limited to script/runbook workflows and explicit approval, not MCP tools.
|
|
- Manual balance reconciliation is preview/report-first. `REVIEW_NEEDED` suggests manual decision values (`계좌이동`, `실지출`, `실수입`, `투자이동`, `분석제외`, `확인필요`) but does not auto-confirm mutations.
|
|
- Asset liquidity reporting is account-based: `liquidity_bucket='loan'` is debt/net-worth only, and missing `last_balance` rows must not be inferred from transaction totals.
|
|
- Browser evidence screenshots/snapshots must use synthetic or validation DBs only and must not include real account identifiers, source financial filenames, passwords, or raw payloads.
|
|
- Financial data and passwords are sensitive runtime inputs and should not be committed.
|
|
|
|
## Current Gaps / Planned Changes
|
|
- Formal versioning for MCP response contracts is not yet defined.
|
|
- Browser-level UI evidence criteria are captured in REQ-004; broader CI automation is still not present.
|
|
- CI contract for tests/lint is not yet present.
|
|
|
|
## Change Log
|
|
- 2026-06-26 22:24 KST: Created by `bootstrap-baseline` from repository observation.
|
|
- 2026-06-27 10:17 KST: BAT-002/REQ-002 기준으로 backup/status/list/hash MCP contract와 restore 비노출 정책 추가.
|
|
- 2026-06-29 KST: REQ-003/BAT-003 기준으로 account statement status update와 balance reconciliation report contract 추가.
|
|
- 2026-06-29 KST: REQ-004/BAT-004 기준으로 Streamlit browser evidence 산출물과 UI evidence gate 규칙 추가.
|
|
- 2026-06-29 KST: REQ-005/BAT-005 기준으로 account `liquidity_bucket`, `get_asset_liquidity_report`, dashboard operations hub contract 추가.
|