Skip to content

Update README.md #59

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
RadCod3 merged 2 commits into from
Jan 17, 2026
Merged

Update README.md #59

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
da74510
docs(README): update services layer documentation and license informa…
RadCod3 Jan 17, 2026
c7dffb5
docs(README): add reference to firefly iii
RadCod3 Jan 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 24 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# LamPyrid

A Model Context Protocol (MCP) server providing comprehensive tools for interacting with Firefly III personal finance software. LamPyrid enables automated personal finance workflows and analysis through 18 MCP tools with support for account management, transaction operations, and budget management.
A Model Context Protocol (MCP) server providing comprehensive tools for interacting with [Firefly III](https://github.com/firefly-iii/firefly-iii) personal finance software. LamPyrid enables automated personal finance workflows and analysis through 18 MCP tools with support for account management, transaction operations, and budget management.

> **What is Firefly III?** [Firefly III](https://www.firefly-iii.org/) is a free and open-source personal finance manager that helps you track expenses, income, budgets, and more. LamPyrid provides an MCP interface to automate interactions with your Firefly III instance.

## Features

Expand Down Expand Up @@ -302,11 +304,17 @@ LamPyrid/
│ ├── models/
│ │ ├── firefly_models.py # Auto-generated Firefly III API models
│ │ └── lampyrid_models.py# Simplified MCP interface models
│ ├── services/
│ │ ├── __init__.py # Services layer exports
│ │ ├── accounts.py # AccountService - account business logic
│ │ ├── transactions.py # TransactionService - transaction business logic
│ │ └── budgets.py # BudgetService - budget business logic
│ └── tools/
│ ├── __init__.py # Tool server composition coordinator
│ ├── accounts.py # Account management tools (3 tools)
│ ├── transactions.py # Transaction management tools (10 tools)
│ └── budgets.py # Budget management tools (5 tools)
├── tests/ # Unit and integration tests
├── .github/workflows/ # CI/CD workflows
├── assets/ # Project assets
├── Dockerfile # Docker image definition
Expand All @@ -320,10 +328,14 @@ LamPyrid/
LamPyrid follows a clean layered architecture with modular tool organization:

- **Server Layer** (`server.py`): FastMCP server initialization, authentication setup, and tool registration orchestration
- **Tools Layer** (`tools/`): Modular MCP tool definitions organized by domain
- **Tools Layer** (`tools/`): Thin MCP tool wrappers organized by domain that delegate to services
- `accounts.py`: Account management tools (3 tools)
- `transactions.py`: Transaction management tools (10 tools)
- `budgets.py`: Budget management tools (5 tools)
- **Services Layer** (`services/`): Business logic services that orchestrate operations between tools and the client
- `accounts.py`: `AccountService` - account operations and model conversion
- `transactions.py`: `TransactionService` - transaction CRUD, bulk operations, search query building
- `budgets.py`: `BudgetService` - budget operations, spending calculations, multi-call aggregations
- **Client Layer** (`clients/firefly.py`): HTTP client for Firefly III API with full CRUD support
- **Models Layer**:
- `firefly_models.py`: Auto-generated Pydantic models from Firefly III OpenAPI spec
Expand All @@ -333,10 +345,18 @@ LamPyrid follows a clean layered architecture with modular tool organization:
### Tool Registration Pattern
Tools are registered using FastMCP's native static composition pattern:
- Each tool module exports a `create_*_server(client)` function that returns a standalone FastMCP instance
- Tool functions are thin wrappers that delegate to corresponding service classes
- The `tools/__init__.py` module provides `compose_all_servers()` to coordinate composition
- The `server.py` uses `mcp.import_server()` to compose all domain servers into the main server
- This leverages FastMCP's built-in server composition while keeping modular organization

### Services Layer Pattern
The services layer separates business logic from tool definitions:
- Each service class takes a `FireflyClient` instance via constructor injection
- Services handle model conversion (Firefly API models to LamPyrid models)
- Complex operations (bulk transactions, spending calculations) are encapsulated in services
- This enables easier unit testing with mocked clients

The architecture enables easy extension and modification while maintaining type safety and comprehensive error handling throughout.

## Docker Deployment
Expand Down Expand Up @@ -475,7 +495,7 @@ Contributions are welcome! Please follow this workflow:

### Code Style Guidelines

- **Indentation**: Use tabs for indentation
- **Indentation**: Use spaces for indentation
- **Quotes**: Single quotes for strings
- **Line Length**: 100 character line limit
- **Type Safety**: Type hints required for all functions and methods
Expand All @@ -491,7 +511,7 @@ The main branch is protected with the following requirements:

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the [LICENSE](LICENSE) file for details.

## Support

Expand Down