Moneybags

대화할 수 있는 자체 호스팅 개인 금융 원장입니다.

명세서를 가져오거나 은행을 동기화하세요. 거래는 먼저 규칙으로, 그다음 모델로 분류되며, 당신이 수정할 때마다 규칙을 학습하여 같은 가맹점이 두 번 잘못 분류되지 않습니다. 그런 다음 평범한 언어로 돈에 대해 물어보세요 — Moneybags는 MCP 서버를 실행하므로 Claude가 원장을 직접 읽습니다.

"How much did I spend on groceries in August?"
"I just bought coffee, about six dollars"
"That Venmo payment was for tree work, not uncategorized"

배포 하나, 소유자 하나. 거래 내역은 당신의 데이터베이스에 있고, API 키는 당신의 것이며, 중간에 서비스가 없습니다.

이것이 무엇인지, 무엇이 아닌지

이것은 자신이 통제하는 데이터베이스에 금융 데이터를 보관하고, 수정 가능한 분류기와 대시보드에 붙은 챗봇이 아닌 대화형 인터페이스를 원하는 사람을 위한 원장입니다.

이것은 모바일 클라이언트와 지원 팀이 있는 예산 앱이 아닙니다. 가입, 멀티 테넌시, 호스팅 버전이 없습니다. 가족이 휴대폰으로 로그인할 수 있는 앱을 원한다면 Monarch나 YNAB를 사용하세요 — 정말로, 그들은 그런 면에서 훌륭하며 이것은 그렇게 되려고 하지 않습니다.

실행 비용은 데이터베이스와 API 키 비용만큼입니다. Neon의 무료 티어에서 명세서 업로드만 사용하는 개인 원장이라면 비용은 0입니다.

Related MCP server: OpenCoffer

디자인이 이렇게 된 이유

이 코드베이스의 거의 모든 어려운 결정은 조용히 돈을 잃지 않는 것에 관한 것입니다. 충돌이 아니라 손실입니다. 카테고리를 놓치는 원장은 짜증나지만, 6,000달러를 놓치고도 잔액이 맞는 원장은 위험합니다. 올바르게 보이기 때문입니다.

그로부터 따르는 규칙은 다음과 같습니다:

돈은 정수 센트입니다. 스키마에서는 bigint, TypeScript에서는 number입니다. 부동 소수점은 포맷팅 경계에서만 나타납니다. 어떤 것도 부동 소수점을 합산하지 않습니다.

음수는 돈이 나갔음을 의미합니다. 파싱, 저장, 원장 계산, UI에 적용되어 기간의 순현금흐름은 행별 분기 없이 단순한 SUM(amount_cents)입니다. 이것을 반대로 이해한 가져오기 어댑터는 내부적으로 일관되지만 완전히 잘못된 원장을 생성하므로, 어댑터에 두 번 알려주는 유일한 사항입니다.

is_transfer는 카테고리가 아닙니다. 이 정확한 달러가 이 원장의 다른 곳에서 이미 계산되었다는 뜻입니다 — 다른 계좌를 명시하는 내부 이체, 또는 구매 내역도 가져온 신용카드 결제를 의미합니다. Venmo, Zelle, Cash App, ATM 출금, 저축 기여금에는 절대 사용하지 않습니다. 나간 돈은 어떤 경로로 이동했든 지출입니다.

결제 수단은 가맹점이 아닙니다. "Venmo"는 돈이 어떻게 이동했는지 알려줄 뿐 무엇을 샀는지는 알려주지 않습니다. 그러한 행은 즉시 지출로 청구되어 — 답이 없는 질문이 조용히 월 총액을 줄이지 않도록 — 레이블을 붙이기 위해 대기열에 들어갑니다. 하나의 답변은 상대방을 키로 하는 규칙을 학습합니다.

수동 분류는 절대 덮어쓰지 않습니다. 모든 자동 패스는 classification_source <> 'manual'로 필터링합니다. 당신의 답변은 어떤 규칙과 모델보다 우선합니다.

중복 제거는 명세서가 아닌 지문(fingerprint)으로 합니다. 고유 인덱스가 있는 sha256(account, date, amount, normalized description)입니다. 겹치는 명세서를 어떤 순서로든 업로드하세요. 이미 있는 행은 건너뜁니다. 계좌가 지문의 일부이므로, 계좌가 두 개 이상이면 분류되지 않은 가져오기가 거부됩니다.

수입은 한 가지 방법으로만 손실될 수 있습니다. 합계는 부호로 나뉘므로 양수 금액은 어떤 카테고리에 들어가든 수입으로 계산됩니다 — 불완전한 카테고리도 여전히 계산되며, 분류 실패는 비용이 들지 않습니다. is_transfer는 단일 실패 지점이므로, 규칙은 패턴이 결제를 명시하거나 다른 계좌를 명시할 때만 유입에 설정할 수 있습니다. pnpm db:audit-income는 모든 유입과 현재 하나를 제외할 수 있는 모든 규칙을 나열합니다.

분류기는 추측을 거부합니다. 규칙이 먼저 실행됩니다. 남은 것은 모델로 갑니다. 여전히 해결되지 않은 것은 확신에 찬 오답이 아니라 검토 대기열에 들어갑니다 — 그리고 구조적으로 목적을 담을 수 없는 설명은 모델을 완전히 건너뜁니다. 매번 "알 수 없음"이라고 답하면서 비용이 들기 때문입니다.

설정

Node 20+, pnpm, 그리고 Postgres 데이터베이스가 필요합니다.

git clone https://github.com/YOUR-USERNAME/moneybags && cd moneybags
pnpm install
cp .env.example .env.local

세 가지를 입력하세요:

# 1. Your database
DATABASE_URL="postgresql://..."

# 2. A session secret
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

# 3. A password
pnpm auth:hash 'the password you want'      # prints APP_PASSWORD_HASH=...

그런 다음:

pnpm db:migrate
pnpm db:seed        # idempotent; seeds the category taxonomy
pnpm dev

그러면 CSV 명세서 가져오기가 가능한 작동하는 원장이 됩니다. 아래의 모든 것은 선택 사항이며, 앱은 각각이 추가하는 것이 무엇인지 정직하게 알려줍니다.

선택 사항: 모델

AI_API_KEY를 설정하세요. 규칙이 인식하지 못하는 가맹점에 대한 모델 지원 분류, 정리된 인사이트, PDF/이미지 명세서 읽기를 얻을 수 있습니다.

없이도 규칙은 여전히 분류하고, 일치하지 않는 행은 검토 대기열로 가며, CSV 가져오기는 영향을 받지 않습니다. 이것은 지원되는 실행 방식이지, 망가진 방식이 아닙니다.

어떤 제공자든 작동합니다 — Anthropic, OpenAI, OpenRouter, Groq, 또는 로컬 Ollama나 LM Studio. docs/ai.md를 참조하세요. PDF 읽기는 Anthropic이 필요합니다. 다른 모든 기능은 어디서나 작동합니다.

선택 사항: 은행 동기화

명세서를 업로드하는 대신 Plaid를 통해 계좌를 연결하세요. Plaid의 무료 티어는 10개의 연결을 포함하며 거래 내역도 포함합니다.

이것은 필요하지 않습니다. 명세서 업로드는 앱을 사용하는 완전한 방법이며, Plaid를 건너뛰면 은행 자격 증명을 보유한 제3자가 하나 줄어듭니다. docs/plaid.md를 참조하세요. 시작 전에 알아두면 좋은 무료 티어의 함정도 설명되어 있습니다.

선택 사항: 대화하기

설정 → MCP 토큰을 발급한 다음, 해당 베어러 토큰으로 모든 MCP 클라이언트를 https://your-host/api/mcp에 연결하세요. 읽기, 기록, 수정을 위한 14개의 도구가 있습니다. 의도적으로 삭제 도구가 없습니다 — 잘못 들은 지시가 기록을 파괴할 수 없어야 합니다.

배포

두 가지 문서화된 경로가 있으며, 어느 쪽도 우월하지 않습니다:

Docker Compose — 앱과 Postgres, 다른 것은 필요 없습니다:

cp .env.example .env    # set APP_PASSWORD_HASH and SESSION_SECRET
docker compose up -d

Vercel + Neon — 무료 티어, 실행할 서버 없음.

둘 다 docs/deploy.md에 있으며, Authelia나 Tailscale 뒤에 두고 싶다면 리버스 프록시 설정도 포함되어 있습니다.

인증

세 가지 방법이 있습니다. 최소 하나를 구성하지 않으면 앱은 URL을 찾는 사람에게 금융 정보를 제공하는 대신 시작을 거부합니다.

로그인은 속도 제한이 있으며, 비밀번호는 일정 시간에 비교되고, 세션은 SESSION_VERSION을 통해 일괄 취소 가능한 서명된 JWT이며, Plaid 액세스 토큰은 저장 시 AES-256-GCM으로 암호화됩니다. 위협 모델과 보호하지 않는 것에 대해서는 docs/security.md를 참조하세요.

구성 가능성

거래는 하나의 경계인 src/lib/sources를 통해 들어옵니다. 다운스트림의 모든 것 — 중복 제거, 조정, 분류, 원장 — 은 ParsedTransaction[]만 보며 행이 업로드로 왔는지 동기화로 왔는지 알 수 없습니다.

은행, 집계자, 또는 까다로운 CSV 방언을 추가하는 것은 어댑터일 뿐입니다:

registerFileSource({
  id: "my-bank",
  label: "My Bank CSV",
  accepts: ({ filename }) => filename.startsWith("mybank-"),
  parse: ({ bytes }) => ({ transactions: parseMyBank(bytes), warnings: [] }),
});

모델 제공자도 같은 종류의 이음새 뒤에 있습니다 — src/lib/ai 외부에서는 공급업체 SDK를 가져오지 않습니다. docs/extending.md는 분류 체계, 규칙, 소스, 동기화 제공자 및 MCP 도구를 다룹니다.

명령어

기술 스택

Next.js 15 (App Router), Drizzle을 통한 Postgres, Tailwind. Anthropic SDK와 Plaid SDK는 모두 런타임에 선택 사항이며 인터페이스 뒤에 격리되어 있습니다.

기여

CLAUDE.md는 사물이 왜 그런 방식인지 문서화하며, 대개 원인이 된 버그를 명명합니다. src/lib/classify 또는 src/lib/reconcile을 건드리기 전에 읽으세요 — 여러 회귀가 테스트로 고정되어 있으며, 주석은 되돌리면 무엇이 깨지는지 알려줍니다.

분류기를 변경할 때의 일반 규칙: 과대 일치보다 과소 일치를 선호하세요. 다시는 발화하지 않는 규칙은 재수정 한 번의 비용이 듭니다. 과대 일치하는 규칙은 이미 확인한 기록을 조용히 다시 씁니다.

라이선스

MIT — LICENSE를 참조하세요.

이것은 실제 금융 데이터를 처리합니다. 보증 없이 제공되며, 배포, 키, 백업은 당신의 책임입니다.