Avie Money Lover MCP / 로컬 브리지

비공식 Money Lover 통합으로, 두 가지 워크플로우를 지원합니다:

1. MCP 서버 — Money Lover 읽기/쓰기 도구를 MCP 지원 클라이언트에 노출합니다.

2. GPT + 로컬 브리지 — ChatGPT가 명세서 JSON을 준비/검토하도록 하고, 사용자 본인의 컴퓨터가 Money Lover 토큰/쿠키를 보유한 채 최종 가져오기를 수행합니다.

비공식 프로젝트입니다. 이 저장소는 Money Lover와 제휴, 보증, 후원 관계가 아닙니다. Money Lover 웹 앱에서 관찰된 웹 엔드포인트를 사용합니다. 해당 엔드포인트, 인증 흐름, 카테고리 동작, 안티봇 요구 사항은 예고 없이 변경될 수 있습니다.

제공 기능

• 인증된 사용자 정보 읽기

• 지갑 및 지갑 카테고리 목록 조회

• 날짜 범위별 거래 내역 읽기

• 거래 내역을 사용하여 Money Lover user_category_v2 소스 ID를 런타임 ID로 변환

• 쓰기 없이 단일 거래 미리보기

• 중복 보호 기능이 있는 거래 추가

• 은행/카드 명세서 배치 미리보기

• 명세서 합계에 대한 지출 − 수입 대사(조정)

• 정확한 중복, 가능한 중복, 미해결 카테고리, 검토 행 플래그 지정

• 명시적 확인 후에만 순차적으로 가져오기

• 생성된 거래를 다시 읽어 검증

• 부분 가져오기 후 안전하게 재실행: 정확한 중복은 건너뜀

Related MCP server: monarch-mcp

요구 사항

• Windows 10/11, macOS 또는 Linux

• Node.js 22 이상

• 사용자가 제어하는 Money Lover 계정

• 안정적인 쓰기를 위해: 새로운 지갑 소유자 세션, 필요한 경우 최신 브라우저 쿠키/cf_clearance, 일치하는 브라우저 User-Agent

빠른 시작

git clone https://github.com/haonguyen97ftu/avie-moneylover-mcp.git
cd avie-moneylover-mcp
npm install
npm test

Windows 헬퍼 설정

scripts\setup-windows.cmd

현재 셸에서만 자격 증명을 설정합니다:

set "MONEYLOVER_ACCESS_TOKEN=YOUR_FRESH_OWNER_TOKEN"
set "MONEYLOVER_CF_CLEARANCE=YOUR_CURRENT_CF_CLEARANCE_VALUE"
set "MONEYLOVER_USER_AGENT=YOUR_EXACT_BROWSER_USER_AGENT"

그런 다음 실행:

scripts\doctor.cmd

권장 GPT + 로컬 워크플로우

Bank/card statement
        ↓
ChatGPT extracts + categorizes
        ↓
statement JSON
        ↓
local preview
        ↓
review / duplicate / reconciliation checks
        ↓
explicit IMPORT confirmation
        ↓
Money Lover
        ↓
local verification report

Money Lover 토큰, 리프레시 토큰, 비밀번호, 브라우저 쿠키 또는 cf_clearance를 ChatGPT, GitHub 이슈, 로그 또는 스크린샷에 붙여넣지 마십시오. ChatGPT에는 명세서와 생성된 미리보기/결과 JSON만 필요합니다.

명세서 미리보기

scripts\preview.cmd data\your-statement.json

검토 후 가져오기

scripts\import.cmd data\your-statement.json

가져오기 도구는 쓰기가 시작되기 전에 정확히 다음을 입력하도록 요구합니다:

IMPORT

전체 베트남어 가이드는 docs/HUONG_DAN_SU_DUNG.md를 참조하세요.

관찰된 API 동작

인증된 요청은 현재 다음을 사용합니다:

Authorization: AuthJWT <access_token>

관찰된 엔드포인트:

쓰기에는 브라우저 유사 헤더와 최신 Cloudflare 세션이 필요할 수 있습니다. 지원되는 환경 변수는 다음과 같습니다:

• MONEYLOVER_ACCESS_TOKEN

• MONEYLOVER_CF_CLEARANCE

• MONEYLOVER_COOKIE

• MONEYLOVER_USER_AGENT

• MONEYLOVER_TIMEOUT_MS

• MONEYLOVER_CATEGORY_LOOKBACK_DAYS

• MONEYLOVER_WRITE_DELAY_MS

배치 명세서 형식

data/example-statement.json에서 시작하세요. 전체 필드 문서는 docs/STATEMENT_FORMAT.md에 있습니다.

미리보기:

npm run preview -- data\your-statement.json

가져오기:

npm run import -- data\your-statement.json

선택적 플래그:

• --allow-review — 검토 후 의도적으로 review 상태로 남겨둔 행 포함

• --allow-mismatch — 명세서 대사 보호 우회; 차이를 이해한 경우에만 사용

• --allow-shared-wallet — 소유자 안전 검사 우회; 공유 지갑 쓰기는 여전히 실패할 수 있음

• --confirm IMPORT — 비대화형 확인; 일반 수동 사용에는 권장되지 않음

안전 기본값

가져오기 도구는 다음 경우에 쓰기를 거부합니다:

• blocked 행이 있는 경우

• --allow-review가 제공되지 않았는데 review 행이 존재하는 경우

• --allow-mismatch가 제공되지 않았는데 명세서 대사 차이가 0이 아닌 경우

• --allow-shared-wallet이 제공되지 않았는데 인증된 사용자가 지갑 소유자가 아닌 경우

• 확인 문구가 정확히 IMPORT가 아닌 경우

금액은 양수여야 합니다.

Category v2

일부 계정은 /category/list에서 소스/템플릿 카테고리 ID를 노출하는 반면, /transaction/add는 다른 런타임 카테고리 ID를 기대합니다. 브리지는 기존 거래에서 이 매핑을 학습합니다.

카테고리가 기록에 한 번도 나타나지 않은 경우 다음을 복사하세요:

config/runtime-category-overrides.example.json

대상:

config/runtime-category-overrides.json

그리고 실제 브라우저 거래 요청에서 관찰된 런타임 ID를 추가하세요. 로컬 재정의 파일은 Git에서 무시됩니다.

공개 저장소 안전

이 저장소는 기본적으로 로컬 금융 데이터 커밋을 방지하도록 구성되어 있습니다:

• data/*.json은 정제된 예제를 제외하고 무시됨

• out/은 무시됨

• .env*는 무시됨

• 로컬 런타임 카테고리 재정의는 무시됨

• 로컬 세션 헬퍼 파일은 무시됨

푸시 전에 다음을 실행하세요:

npm run repo:check
npm test

그런 다음 git status를 수동으로 검사하세요.

보안

토큰, 비밀번호, 리프레시 토큰, 브라우저 쿠키 또는 cf_clearance 값이 노출된 적이 있다면 손상된 것으로 간주하고 세션을 교체/폐기하세요. SECURITY.md를 참조하세요.

기여

버그 리포트와 풀 리퀘스트를 환영합니다. 변경 사항을 제출하기 전에 CONTRIBUTING.md를 읽어주세요. 이슈나 테스트 픽스처에 실제 금융 명세서, 계정 식별자, 토큰 또는 쿠키를 절대 포함하지 마세요.

문서

• 베트남어 사용 가이드

• 명세서 JSON 형식

• 아키텍처

• GitHub 게시 가이드

• 보안 정책

• 변경 로그

• GPT 명세서 정규화 프롬프트

• GPT 미리보기 검토 프롬프트

라이선스

MIT — LICENSE 참조.