# Headless Personal Accounting System for AI Agents

A headless personal accounting system designed specifically for AI agent consumption. It has **no human-facing GUI**; instead, all interactions are performed using the REST API or the Model Context Protocol (MCP) server stdio interface.

## System Architecture
- **Language**: Python 3.12+
- **Database**: SQLite (single-file, local storage)
- **API Server**: FastAPI (with automatic OpenAPI docs at `/docs`)
- **MCP Server**: Python `mcp` SDK exposing tools over stdio transport
- **Deployment**: Docker and Docker Compose

---

## Folder Structure
```
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
```

---

## Getting Started (Native Setup)

### 1. Install Dependencies
Make sure Python 3.12+ is installed. Clone the repository and run:

```bash
# 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. Run the REST API Server
Start the FastAPI server on port 8900:
```bash
uvicorn app.main:app --host 0.0.0.0 --port 8900 --reload
```
You can view the interactive API documentation at: **`http://localhost:8900/docs`**

### 3. Run the MCP Server
Run the MCP server locally over standard input/output (stdio):
```bash
python -m app.mcp_server
```

### 4. Run Unit Tests
To execute the test suite, run:
```bash
pytest
```

---

## Deployment (Docker Setup)

You can build and deploy the application to a remote or local host using Docker and Docker Compose (tested on Ubuntu 24.04 LTS with Docker 29.x).

### 1. Start the Container
Start the container in detached mode. The SQLite database will be stored persistently inside the named volume `accounting-data` at `/data/accounting.db` inside the container.
```bash
docker compose up -d --build
```

### 2. Check Service Health
Ensure that the service is running and healthy:
```bash
# Verify REST API
curl http://localhost:8900/health

# Show container status & health status
docker ps
```

---

## Connecting AI Agents (MCP Configuration)

To allow LLM clients (like Claude Desktop) to interface directly with your accounting system, add the server to your client configuration file.

### For Local Native Run
Add this to your Claude Desktop configuration file (typically at `%APPDATA%\Claude\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "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"
      }
    }
  }
}
```

### For Docker Deployment
If the accounting server is running inside the Docker container, configure Claude Desktop to run commands inside the active container:

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

---

## API Usage Examples (`curl` Commands)

### 1. Create a New Account
```bash
curl -X POST http://localhost:8900/accounts \
  -H "Content-Type: application/json" \
  -d '{"name": "Wallet Cash", "type": "cash", "balance": 5000}'
```

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

### 2. List All Accounts
```bash
curl -X GET http://localhost:8900/accounts
```

### 3. Record an Expense (ID 1 represents Wallet Cash)
```bash
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. Record a Transfer (Move 2000 Yen from Savings Bank to Wallet Cash)
Assume `Savings Bank` ID is 2 and `Wallet Cash` ID is 1.
```bash
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. Retrieve Aggregated Reports
Get a monthly report of your income, expenses, and category/account breakdown:
```bash
curl -X GET "http://localhost:8900/report?frequency=monthly"
```

### 6. Update a Transaction (Correct Mistakes)
Partial update — only the fields you provide are changed. Account balances are recalculated automatically:
```bash
# 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. Delete a Transaction (Undo a Mistake)
Deleting a transaction reverses its effect on the account balance (income is subtracted back, expense is added back):
```bash
curl -X DELETE http://localhost:8900/transactions/1
```

### 8. Delete a Transfer
Deleting a transfer reverses the effect on both account balances:
```bash
curl -X DELETE http://localhost:8900/transfers/1
```

### 9. Delete an Account
Deleting an account is **refused (400)** while it still has transactions or transfers referencing it. Remove those first, then delete:
```bash
curl -X DELETE http://localhost:8900/accounts/1
```