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

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-26 22:24
• 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
• Accounts: create_ledger_account, list_ledger_accounts
• 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
• 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

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.
• 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.
• Do not write secrets or raw passwords 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.

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.

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.
• 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 acceptance criteria for Streamlit flows are not yet captured as REQ documents.
• CI contract for tests/lint is not yet present.

Change Log

• 2026-06-26 22:24 KST: Created by bootstrap-baseline from repository observation.