Sistema de contabilidad personal sin interfaz gráfica para agentes de IA

Un sistema de contabilidad personal sin interfaz gráfica diseñado específicamente para el consumo por parte de agentes de IA. No tiene GUI orientada a humanos; en su lugar, todas las interacciones se realizan mediante la API REST o la interfaz stdio del servidor del Model Context Protocol (MCP).

Arquitectura del sistema

• Lenguaje: Python 3.12+

• Base de datos: SQLite (archivo único, almacenamiento local)

• Servidor API: FastAPI (con documentación OpenAPI automática en /docs)

• Servidor MCP: SDK de Python mcp que expone herramientas a través del transporte stdio

• Despliegue: Docker y Docker Compose

Related MCP server: accounting-mcp-server

Estructura de carpetas

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

Primeros pasos (Configuración nativa)

1. Instalar dependencias

Asegúrate de tener instalado Python 3.12+. Clona el repositorio y ejecuta:

# 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. Ejecutar el servidor de la API REST

Inicia el servidor FastAPI en el puerto 8900:

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

Puedes ver la documentación interactiva de la API en: http://localhost:8900/docs

3. Ejecutar el servidor MCP

Ejecuta el servidor MCP localmente a través de la entrada/salida estándar (stdio):

python -m app.mcp_server

4. Ejecutar pruebas unitarias

Para ejecutar la suite de pruebas, ejecuta:

pytest

Despliegue (Configuración con Docker)

Puedes compilar y desplegar la aplicación en un host remoto o local usando Docker y Docker Compose (probado en Ubuntu 24.04 LTS con Docker 29.x).

1. Iniciar el contenedor

Inicia el contenedor en modo desacoplado (detached). La base de datos SQLite se almacenará de forma persistente dentro del volumen nombrado accounting-data en /data/accounting.db dentro del contenedor.

docker compose up -d --build

2. Comprobar el estado del servicio

Asegúrate de que el servicio esté en ejecución y en buen estado:

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

# Show container status & health status
docker ps

Conexión de agentes de IA (Configuración de MCP)

Para permitir que los clientes LLM (como Claude Desktop) interactúen directamente con tu sistema de contabilidad, añade el servidor a tu archivo de configuración del cliente.

Para ejecución local nativa

Añade esto a tu archivo de configuración de Claude Desktop (normalmente en %APPDATA%\Claude\claude_desktop_config.json en Windows o ~/Library/Application Support/Claude/claude_desktop_config.json en 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"
      }
    }
  }
}

Para despliegue con Docker

Si el servidor de contabilidad se está ejecutando dentro del contenedor Docker, configura Claude Desktop para ejecutar comandos dentro del contenedor activo:

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

Ejemplos de uso de la API (comandos curl)

1. Crear una nueva cuenta

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. Listar todas las cuentas

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

3. Registrar un gasto (el ID 1 representa 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. Registrar una transferencia (mover 2000 yenes de Savings Bank a Wallet Cash)

Supón que el ID de Savings Bank es 2 y el de Wallet Cash es 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. Obtener informes agregados

Obtén un informe mensual de tus ingresos, gastos y desglose por categoría/cuenta:

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

6. Actualizar una transacción (corregir errores)

Actualización parcial — solo se modifican los campos que proporcionas. Los saldos de las cuentas se recalculan automáticamente:

# 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. Eliminar una transacción (deshacer un error)

Eliminar una transacción revierte su efecto en el saldo de la cuenta (el ingreso se resta de nuevo, el gasto se suma de nuevo):

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

8. Eliminar una transferencia

Eliminar una transferencia revierte el efecto en ambos saldos de cuenta:

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

9. Eliminar una cuenta

Eliminar una cuenta es rechazado (400) mientras todavía tenga transacciones o transferencias que la referencien. Elimínalas primero y luego elimina la cuenta:

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