FinLedger

세 가지 조회 영역을 가진 로컬 금융 원장이며, 에이전트가 이를 질의할 수 있도록 MCP 서버를 제공합니다:

• expenses: 지출 계좌. 동료 상환 내역과 대사됩니다.

• investments: 증권사 잔고, 보유 종목, 거래 내역

• income: 급여(총액, 공제액, 실수령액)

지출과 투자는 저장소만 공유하며 그 외에는 공유하는 것이 없습니다. 계정에는 명시적인 domain이 있으며 모든 지출 쿼리는 이를 통해 조인되므로, 주식 매수 건이 상환 매처에 도달할 수 없습니다.

매처는 규칙 우선(rules-first) 방식입니다. 확신이 없으면 기권합니다. 매치가 순 지출을 줄이려면 사람이나 에이전트의 확인이 먼저 필요합니다.

실제 거래, 급여 명세서, API 키는 사용자 머신에만 보관됩니다 (~/.finledger/ledger.db, .env). 이 저장소는 코드와 합성(synthetic) 평가 집합만 제공합니다.

설치

Python 3.10+가 필요합니다. 원장, 매처, MCP 루프, 평가 하네스는 표준 라이브러리로 구현되어 있습니다. pypdf는 선택 사항이며 급여 명세서 PDF를 가져올 때만 필요합니다.

pip install -e .

Related MCP server: MCP Agent - AI Expense Tracker

MCP 서버

python3 -m finledger.mcp_server --db ~/.finledger/ledger.db

18개 도구가 expenses_*, investments_*, income_* 네임스페이스로 제공되며, savings_rate, accounts, sync, reconcile가 추가로 있습니다.

Cursor 예시 (~/.cursor/mcp.json):

{
  "mcpServers": {
    "finledger": {
      "command": "python3",
      "args": ["-m", "finledger.mcp_server"]
    }
  }
}

기본 원장 경로는 ~/.finledger/ledger.db입니다.

CLI

finledger sync
finledger reconcile
finledger review
finledger serve

finledger serve는 :8770에서 로컬 데스크를 엽니다. macOS에서는 scripts/Expense Desk.command를 더블클릭할 수도 있습니다.

선택적 실시간 소스 (자격 증명은 .env에 넣고 절대 커밋하지 마세요):

.env.example을 .env로 복사하세요.

공개 평가

공개된 골드 집합은 합성 데이터입니다. scripts/make_sample_data.py로 생성되며 data-sample/에 있습니다. 모든 거래 행은 synthetic: true로 표시됩니다. 이는 매처 동작(clean match, fan-in, bundling, peer-outbound parent, merchant credits, weak notes, cross-source twins)에 대한 커버리지 집합입니다. 익명화된 실제 데이터가 아닙니다.

python3 scripts/eval_public.py
# equivalent:
python3 -m reconcile.eval --matcher rules_v0

이 저장소에서 재현할 수 있는 수치

data-sample/에서 rules_v0(윈도우 ±90일, 자동 매치 임계값 0.75)로 측정했습니다:

이 수치를 새로고침하려면 python3 scripts/eval_public.py를 다시 실행하세요. 샘플에 남아 있는 두 개의 false positive는 실제 매처 약점이며, 이모지 재현율 상향(recall-lift) 규칙이 과도하게 적용된 것도 포함됩니다.

이 저장소에 없는 것

개발 중에는 약 92개의 레이블이 지정된 예시로 구성된 비공개 골드 집합이 사용되었습니다. 여기에는 실제 인물과 실제 구매 내역이 포함되어 있어 공개되지 않았습니다. 샘플 수치를 해당 집합의 재현으로 취급하지 마십시오. 다른 말뭉치, 다른 규모, 다른 점수입니다.

이 저장소는 100% 자동 매치 정밀도를 주장하지 않습니다.

매처

reconcile/README.md를 참조하세요. 요약:

샘플 말뭉치에 레이블을 지정하려면 python3 labeling/app.py를 사용하세요 (기본값은 data-sample/).

라이선스

MIT