Headless-система персонального учёта для ИИ-агентов

Headless-система персонального учёта, предназначенная специально для использования ИИ-агентами. В ней нет графического интерфейса для человека; вместо этого все взаимодействия выполняются через REST API или stdio-интерфейс сервера Model Context Protocol (MCP).

Архитектура системы

• Язык: Python 3.12+

• База данных: SQLite (один файл, локальное хранилище)

• API-сервер: FastAPI (с автоматической документацией OpenAPI по адресу /docs)

• MCP-сервер: Python mcp SDK, предоставляющий инструменты через stdio-транспорт

• Развёртывание: Docker и Docker Compose

Related MCP server: accounting-mcp-server

Структура папок

AI/
├── app/
│   ├── __init__.py
│   ├── db.py          # SQLAlchemy SQLite connection & tables setup
│   ├── models.py      # Pydantic schemas for data validation
│   ├── crud.py        # Database operations (CRUD, reports, config)
│   ├── main.py        # FastAPI API endpoints
│   └── mcp_server.py  # MCP (Model Context Protocol) server configuration
├── tests/
│   ├── __init__.py
│   └── test_core.py   # Complete Pytest unit tests suite
├── Dockerfile         # Multi-stage optimized Docker file
├── docker-compose.yml # Docker compose configuration (Port 8900, volume mount)
├── .dockerignore
├── pyproject.toml     # Poetry/Pip project dependencies
├── SCHEMA.md          # Database schema reference for AI models
└── README.md          # This manual

Начало работы (локальная установка)

1. Установка зависимостей

Убедитесь, что установлен Python 3.12+. Клонируйте репозиторий и выполните:

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install required packages
pip install fastapi uvicorn sqlalchemy pydantic mcp
# Install development packages for tests
pip install pytest httpx

2. Запуск REST API-сервера

Запустите сервер FastAPI на порту 8900:

uvicorn app.main:app --host 0.0.0.0 --port 8900 --reload

Вы можете просмотреть интерактивную документацию API по адресу: http://localhost:8900/docs

3. Запуск MCP-сервера

Запустите MCP-сервер локально через стандартный ввод/вывод (stdio):

python -m app.mcp_server

4. Запуск модульных тестов

Чтобы выполнить набор тестов, запустите:

pytest

Развёртывание (настройка Docker)

Вы можете собрать и развернуть приложение на удалённом или локальном хосте с помощью Docker и Docker Compose (протестировано на Ubuntu 24.04 LTS с Docker 29.x).

1. Запуск контейнера

Запустите контейнер в фоновом режиме (detached mode). База данных SQLite будет постоянно храниться внутри именованного тома accounting-data по пути /data/accounting.db в контейнере.

docker compose up -d --build

2. Проверка работоспособности сервиса

Убедитесь, что сервис работает и находится в здоровом состоянии:

# Verify REST API
curl http://localhost:8900/health

# Show container status & health status
docker ps

Подключение ИИ-агентов (настройка MCP)

Чтобы позволить LLM-клиентам (например, Claude Desktop) напрямую взаимодействовать с вашей системой учёта, добавьте сервер в файл конфигурации вашего клиента.

Для локального запуска (native)

Добавьте это в файл конфигурации Claude Desktop (обычно он находится по пути %APPDATA%\Claude\claude_desktop_config.json в Windows или ~/Library/Application Support/Claude/claude_desktop_config.json в macOS):

{
  "mcpServers": {
    "personal-accounting": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "app.mcp_server"],
      "cwd": "/path/to/your/project/directory",
      "env": {
        "DATABASE_URL": "sqlite:////path/to/your/project/directory/accounting.db"
      }
    }
  }
}

Для развёртывания в Docker

Если сервер учёта работает внутри Docker-контейнера, настройте Claude Desktop на выполнение команд внутри активного контейнера:

{
  "mcpServers": {
    "personal-accounting-docker": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "accounting-api",
        "python",
        "-m",
        "app.mcp_server"
      ]
    }
  }
}

Примеры использования API (команды curl)

1. Создание нового счёта

curl -X POST http://localhost:8900/accounts \
  -H "Content-Type: application/json" \
  -d '{"name": "Wallet Cash", "type": "cash", "balance": 5000}'

curl -X POST http://localhost:8900/accounts \
  -H "Content-Type: application/json" \
  -d '{"name": "Savings Bank", "type": "bank", "balance": 150000}'

2. Список всех счетов

curl -X GET http://localhost:8900/accounts

3. Запись расхода (ID 1 означает Wallet Cash)

curl -X POST http://localhost:8900/transactions \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-08-02",
    "amount": 850,
    "type": "expense",
    "category": "Food",
    "description": "Lunch at restaurant",
    "account_id": 1,
    "tags": ["lunch", "outing"]
  }'

4. Запись перевода (переместить 2000 иен со счёта Savings Bank на счёт Wallet Cash)

Предположим, ID счёта Savings Bank равен 2, а ID счёта Wallet Cash равен 1.

curl -X POST http://localhost:8900/transfers \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-08-02",
    "amount": 2000,
    "from_account_id": 2,
    "to_account_id": 1,
    "description": "ATM withdrawal to wallet"
  }'

5. Получение сводных отчётов

Получите ежемесячный отчёт о ваших доходах, расходах и разбивке по категориям/счетам:

curl -X GET "http://localhost:8900/report?frequency=monthly"

6. Обновление транзакции (исправление ошибок)

Частичное обновление — изменяются только те поля, которые вы указали. Остатки на счетах пересчитываются автоматически:

# Change the amount of transaction ID 1 from 850 to 950
curl -X PUT http://localhost:8900/transactions/1 \
  -H "Content-Type: application/json" \
  -d '{"amount": 950}'

7. Удаление транзакции (отмена ошибки)

Удаление транзакции отменяет её влияние на остаток счёта (доход вычитается обратно, расход прибавляется обратно):

curl -X DELETE http://localhost:8900/transactions/1

8. Удаление перевода

Удаление перевода отменяет его влияние на остатки обоих счетов:

curl -X DELETE http://localhost:8900/transfers/1

9. Удаление счёта

Удаление счёта отклоняется (400), пока на него ссылаются транзакции или переводы. Сначала удалите их, затем удалите счёт:

curl -X DELETE http://localhost:8900/accounts/1