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 규칙을 추가.