# Splitwise MCP Server
## Project Overview
This is a Model Context Protocol (MCP) server for managing Splitwise expenses with atomic duplicate prevention. It enables AI assistants like Claude to create, query, and manage shared expenses.
## Architecture
```
src/splitwise_mcp/
├── server.py - MCP server with tool definitions
├── client.py - Splitwise API client wrapper
├── cache.py - Local SQLite caching layer
├── tools.py - Tool handler implementations
└── config.py - Configuration loading utilities
```
## Key Features
1. **Atomic Reservation Pattern** - Reserve-then-create prevents duplicate expenses
2. **Duplicate Detection** - Fuzzy matching on description, amount, and date
3. **Local SQLite Cache** - Fast lookups without API calls
4. **Flexible Split Ratios** - Support for any percentage (50/50, 75/25, etc.)
5. **Order ID Tracking** - Link expenses to source orders for traceability
## Development Commands
```bash
# Install in development mode
pip install -e .[dev]
# Run tests
PYTHONPATH=src pytest tests/ -v
# Start MCP server
python -m splitwise_mcp.server
# Test with MCP Inspector
npx @modelcontextprotocol/inspector python -m splitwise_mcp.server
```
## Configuration
The server loads configuration in this priority order:
1. Environment variables (SPLITWISE_API_KEY, SPLITWISE_GROUP_ID, etc.)
2. File specified by SPLITWISE_CONFIG_PATH environment variable
3. ./config.json in the current directory
Required configuration fields:
- `api_key` - Splitwise API key
- `group_id` - Target group ID
- `payer_id` - Primary payer's user ID
- `partner_id` - Partner's user ID
## MCP Tools
| Tool | Description |
|------|-------------|
| `splitwise_check_duplicate` | Check if expense would be a duplicate |
| `splitwise_reserve_expense` | Atomically reserve an expense slot |
| `splitwise_create_expense` | Create expense with reservation |
| `splitwise_sync_cache` | Sync local cache with Splitwise API |
| `splitwise_get_expenses` | Query cached expenses |
| `splitwise_delete_expense` | Delete an expense |
| `splitwise_find_by_order_id` | Find expense by order ID |
## Testing
Tests are in the `tests/` directory:
- `test_config.py` - Configuration loading tests
- `test_soft_delete.py` - Soft delete functionality tests
Run with: `PYTHONPATH=src pytest tests/ -v`
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run the test suite
5. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) file.
