jarca-ledger-mcp/docs/interface-contract.md

# Jarca Ledger MCP Interface Contract

- Baseline Mode: observed
- Baseline Seed: `.stage-pilot/bootstrap/baseline.yaml`
- Status: governed
- Owner: Jarca / project maintainer
- Last Updated (KST): 2026-07-01
- Source Discovery / Batch: bootstrap-baseline, dcy-007, BAT-007, BAT-008, BAT-009

## 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`
- Asset valuation reads/writes: `list_manual_assets`, `create_manual_asset`, `update_manual_asset`, `deactivate_manual_asset`, `preview_asset_snapshot_close`, `close_asset_snapshot`, `get_asset_snapshot_report`, `get_net_worth_timeseries`; these use the same valuation policy as the dashboard and preserve append-only snapshot correction semantics.
- 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.
- Contract version metadata is not exposed in runtime success payloads for version `1.0`; version governance is tracked in this document and contract regression snapshot metadata.

### 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.
- MCP success response contract version uses `major.minor`; the initial governed contract version is `1.0`.
- Increment `major` for breaking changes, including required key removal, existing key type change, or nested object/list structure changes that break existing consumers.
- Increment `minor` for backward-compatible additive changes, including optional field additions or documentation/test metadata that preserves existing payload semantics.
- Ambiguous response-shape changes must identify contract impact in the owning REQ/BAT and be reviewed against this document before implementation.
- 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.

### MCP Response Contract Version Governance
- Source of truth: this `docs/interface-contract.md` section defines the active contract version, change classification rules, and runtime exposure policy.
- Snapshot metadata: representative contract regression fixtures live under `tests/contract_snapshots/` and must carry the same contract version as this document.
- Runtime exposure policy: `contract_version` remains unexposed in MCP success responses for `1.0`; adding it to runtime payloads requires a future approved REQ/migration because it changes every success envelope, even if additive.
- Required first-wave regression scopes: health/status, list, report, and mutation success envelope responses.
- Additive policy: contract tests intentionally assert a required subset and required types so newly added optional fields do not fail the gate.
- Breaking-change policy: removing a required key, changing a required key type, or changing a required nested shape must fail contract regression unless an approved REQ/BAT updates the contract version and snapshot metadata.
- Every REQ/BAT that changes MCP success response shapes must state one of: `contract impact: none`, `contract impact: additive minor`, or `contract impact: breaking major`.

### MCP Response Contract Version Log
| Version | Date (KST) | Change Type | Source | Notes |
| --- | --- | --- | --- | --- |
| 1.0 | 2026-06-30 | Initial governed baseline | dcy-007 / REQ-007 / BAT-007 | Formalizes compatibility governance without exposing runtime version fields or changing success payload shapes. |

### Asset Valuation Read/Mutation Tools
- `list_manual_assets(active_only=true)` returns `success`, `manual_assets`, `count`, and `valuation_policy`. Each item exposes `name`, `valuation_amount`, `valuation_date`, `liquidity_bucket`, `source_note`, `memo`, and `authority_source='manual_assets'`.
- `create_manual_asset`, `update_manual_asset`, and `deactivate_manual_asset` return dcy-007-compatible success/error envelopes. Mutation success includes the affected `manual_asset` payload or deactivation metadata; soft delete (`active=false`) is the default.
- `preview_asset_snapshot_close(basis_date='')` returns `success`, `basis_date`, `source='live_authority'`, `is_closed_snapshot=false`, item lists, bucket totals, total assets/liabilities, net worth, and warnings. It is side-effect free.
- `close_asset_snapshot(basis_date='', source_note='', memo='', correction_reason='')` writes item-level snapshot rows and returns `source='snapshot'`, `is_closed_snapshot=true`, `snapshot_run_id`, correction metadata, inserted count, totals, and warnings. If rows already exist for the same basis date, `correction_reason` is required and the close appends a correction run instead of overwriting.
- `get_asset_snapshot_report(basis_date='')` returns `success`, `basis_date`, `source`, `is_closed_snapshot`, `snapshot_count`, `buckets`, `total_assets`, `total_liabilities`, `net_worth`, `included_items`, `excluded_items`, and `valuation_policy`.
  - If `asset_snapshots` rows exist for `basis_date`, `source='asset_snapshots'`, `is_closed_snapshot=true`, and values come from the latest stored close run when run metadata exists.
  - If no snapshot rows exist, `source='live_authority'`, `is_closed_snapshot=false`, and the report reads `accounts.last_balance` plus active `manual_assets`.
- `get_net_worth_timeseries(start_date='', end_date='', months=12)` returns `success`, requested date bounds, `points`, `count`, and `valuation_policy`; each point contains `basis_date`, `total_assets`, `total_liabilities`, `net_worth`, `source`, and `item_count`.
- Contract impact: additive minor. Existing success payloads are preserved; `get_asset_liquidity_report` gains optional explanatory fields (`manual_assets`, `manual_asset_count`, `included_items`, `excluded_items`, `valuation_policy`) while preserving existing keys, and BAT-009 adds new mutation/preview scopes to contract regression.

## Interface: CI Required-Check Contract
- Required-check source of truth in code: `.github/workflows/ci.yml` job names are stable and must be mirrored by repository branch protection settings.
- Required-check default set for PR/push merge blocking: `pytest-regression`, `dashboard-app-test`, `dashboard-http-smoke`, `db-safety-smoke`, `contract-regression`, `lint`.
- `contract-regression` runs `pytest tests/test_contract_regression.py` against synthetic temp fixtures and representative response snapshot metadata.
- `lint` runs `ruff check .` with the conservative BAT-007 initial rule set (`E9`, `F`) as a required blocking gate.
- Actual GitHub branch protection toggles are repository settings outside this codebase; this document and the workflow define the intended contract for the operator to apply and audit.
- CI contract tests, AppTest, HTTP smoke, and DB safety smoke must use synthetic/temp DBs only and must not read the default operating DB path.

## 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 the shared service valuation report for asset liquidity/composition/debt/net-worth sections.
- Overview asset/net-worth display must keep the REQ-005 account-only fallback when `manual_assets`/`asset_snapshots` are empty, and may additionally show manual asset rows when present.
- 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 uses the shared valuation policy: account-backed values from `accounts.last_balance`, non-transaction assets/liabilities from `manual_assets`, `loan` as debt/net-worth only, and missing values excluded with explanation rather than 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 MCP response contract versioning is defined for version `1.0`; full tool-surface snapshot coverage remains a future expansion beyond the representative BAT-007 scope.
- Browser-level UI evidence criteria are captured in REQ-004 and remain local evidence rather than a required CI gate unless a future REQ changes that policy.
- CI tests/lint required-check contract is defined for the six stable jobs listed above; actual branch protection enforcement remains an operator-managed repository setting.
- BAT-008 adds read-only asset valuation MCP tools. Mutation MCP for manual asset CRUD or snapshot creation remains out of scope/future work.

## 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 추가.
- 2026-06-30 KST: REQ-007/REQ-008/BAT-007 기준으로 MCP response contract `1.0` governance, representative contract-regression scope, `ruff` lint, six-job required-check contract를 추가.
- 2026-06-30 KST: REQ-009/REQ-010/BAT-008 기준으로 `list_manual_assets`, `get_asset_snapshot_report`, `get_net_worth_timeseries` read MCP contract와 dashboard valuation alignment 규칙을 추가.