Агент отслеживания расходов

Персональный трекер расходов на базе ИИ, преобразующий запросы на естественном языке в структурированные операции с базой данных. Проект объединяет адаптивный интерфейс 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 или новее

• Ключ API Anthropic для ассистента

Создайте и активируйте виртуальное окружение:

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