지출 추적 에이전트

자연어 요청을 구조화된 데이터베이스 작업으로 변환하는 AI 기반 개인 지출 추적기입니다. 이 프로젝트는 반응형 Streamlit 인터페이스, Claude 도구 사용, MCP 서버 및 로컬 SQLite 저장소를 결합합니다.

이 프로젝트가 보여주는 것

• 실제 데이터베이스 워크플로를 위한 에이전트 기반 다단계 도구 사용

• 언어 모델, MCP 전송 및 데이터 계층 간의 명확한 분리

• 오케스트레이션 프레임워크 없이 직접 Claude 도구 호출 루프

• 입력 검증, 범위가 지정된 어시스턴트 동작 및 안전한 로컬 데이터 처리

• 자동화된 스모크 테스트 및 지속적 통합

• 입력, 대화 및 지출 인사이트를 위한 반응형 사용자 인터페이스

Related MCP server: Expense Tracker MCP Server

제품 기능

• 양식 또는 자연어 요청을 통해 지출 추가

• 각 거래의 날짜, 금액, 카테고리 및 설명 저장

• MCP 도구를 통해 지출 검색, 업데이트, 삭제 및 요약

• 총계, 최근 거래 및 카테고리별 지출 검토

• 데이터베이스 기반 인사이트를 위해 집중된 재무 어시스턴트에게 질문

• 지출 데이터를 SQLite 파일에 로컬로 유지

아키텍처

flowchart LR
    U[User] --> UI[Streamlit or CLI]
    UI --> A[Claude agent]
    A -->|Tool request| C[MCP client]
    C -->|stdio| S[MCP server]
    S -->|DB-API 2.0| D[(SQLite)]
    D --> S
    S -->|Structured result| A
    A --> UI

Claude는 SQLite에 직접 접근하지 않습니다. MCP 도구 스키마에서 선택하며, 서버가 모든 검증된 데이터베이스 읽기 및 쓰기를 소유합니다.

예시 에이전트 워크플로

기술

빠른 시작

요구 사항:

• Python 3.11 이상

• 어시스턴트용 Anthropic API 키

가상 환경 생성 및 활성화:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

macOS 또는 Linux의 경우 다음으로 환경을 활성화하세요:

source .venv/bin/activate

로컬 환경 파일을 만들고 ANTHROPIC_API_KEY를 추가하세요:

Copy-Item .env.example .env

데이터베이스 스키마와 시작 카테고리를 만든 다음 앱을 실행하세요:

python db_setup.py
streamlit run streamlit_app.py

MCP 서버는 stdio를 사용하며 클라이언트가 연결되면 자동으로 시작됩니다.

품질 검사

개발 종속성을 설치하고 CI에서 사용하는 동일한 검사를 실행하세요:

python -m pip install -r requirements-dev.txt
python -m black --check .
python -m compileall -q agent.py client_test.py db_setup.py mcp_client.py server.py streamlit_app.py
python -m pytest -q
python client_test.py

client_test.py는 18개의 모든 MCP 도구를 실행하며 스모크 테스트가 완료되면 임시 레코드를 제거합니다.

MCP 도구

서버는 18개의 도구를 제공합니다:

• 카테고리 관리: list_categories, add_category, rename_category, delete_category, get_category_name

• 지출 관리: add_expense, update_expense, delete_expense, list_expenses, search_expenses, expenses_by_category, total_expense_by_category, total_expense, monthly_summary

• 지원 쿼리: current_date, find_category, get_expense, expenses_between

프로젝트 구조

구성

.env 파일과 expenses.db는 Git에서 제외됩니다. API 키와 개인 지출 데이터는 저장소 외부에 유지됩니다.

빈 지출 테이블로 데이터베이스를 다시 생성하려면:

python db_setup.py --reset