Invoice MCP Server

A Model Context Protocol (MCP) server for invoice management with modular architecture.

Documentation

Examples Guide - Comprehensive usage examples, workflows, and error handling
Development Guide - Developer setup, testing, and contributing
Architecture Guide - Technical architecture and component details
API Reference - MCP tools, resources, and prompts reference
Contributing - Contribution guidelines

Features

MCP Protocol Support: Full implementation of Tools, Resources, and Prompts
Multiple Transports: STDIO and HTTP/SSE support
Dual GUI: CLI and Web interfaces
SDK Layer: All operations through unified SDK
Modular Design: Swappable components without code changes

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      GUI Layer                              │
│              ┌─────────┐    ┌─────────┐                     │
│              │   CLI   │    │   Web   │                     │
│              └────┬────┘    └────┬────┘                     │
├───────────────────┴──────────────┴──────────────────────────┤
│                      SDK Layer                              │
│   CustomerOperations │ InvoiceOperations │ ReportOperations │
├─────────────────────────────────────────────────────────────┤
│                    MCP Server                               │
│   ┌─────────┐    ┌───────────┐    ┌─────────┐              │
│   │  Tools  │    │ Resources │    │ Prompts │              │
│   └─────────┘    └───────────┘    └─────────┘              │
├─────────────────────────────────────────────────────────────┤
│                  Transport Layer                            │
│              ┌─────────┐    ┌─────────┐                     │
│              │  STDIO  │    │  HTTP   │                     │
│              └─────────┘    └─────────┘                     │
├─────────────────────────────────────────────────────────────┤
│                 Infrastructure                              │
│     Database │ Repositories │ Lock Manager │ Config         │
└─────────────────────────────────────────────────────────────┘

Quick Start

# 1. Clone and install
git clone <repository-url>
cd MCP_Server
pip install -e ".[dev]"

# 2. Test the CLI
python -m invoice_mcp_server cli customer list

# 3. Run the MCP server
python -m invoice_mcp_server stdio

Installation

Requirements

Python 3.10+
pip

Install for Development

# Install with dev dependencies (pytest, mypy, ruff)
pip install -e ".[dev]"

Install for Production

pip install -e .

Configuration

All configuration via environment variables or .env file:

# Server
SERVER_HOST=127.0.0.1
SERVER_PORT=8080

# Database
DB_PATH=data/invoices.db

# Invoice
VAT_RATE=0.17
CURRENCY=ILS

# Transport
TRANSPORT_TYPE=stdio

# Logging
LOG_LEVEL=INFO

Running the Server

MCP Server (STDIO) - For MCP Clients

python -m invoice_mcp_server stdio

Use this mode when connecting from Claude Desktop or other MCP clients.

MCP Server (HTTP)

python -m invoice_mcp_server http

Web Interface

python -m invoice_mcp_server web
# Access at http://localhost:8080

Help

python -m invoice_mcp_server --help

CLI Reference

The CLI provides direct access to all operations for testing and management.

Customer Commands

# List all customers
python -m invoice_mcp_server cli customer list

# Create a new customer
python -m invoice_mcp_server cli customer create --name "Acme Corp" --email "contact@acme.com"

# Create with all fields
python -m invoice_mcp_server cli customer create --name "Acme Corp" --email "contact@acme.com" --address "123 Main St" --phone "555-1234"

# Delete a customer
python -m invoice_mcp_server cli customer delete <customer-id>

Invoice Commands

# List all invoices
python -m invoice_mcp_server cli invoice list

# Create a new invoice
python -m invoice_mcp_server cli invoice create --customer-id <customer-id>

# Create with due date and notes
python -m invoice_mcp_server cli invoice create --customer-id <customer-id> --due-date "2024-12-31" --notes "Project payment"

# Add item to invoice
python -m invoice_mcp_server cli invoice add-item --invoice-id <invoice-id> --description "Consulting services" --quantity 10 --price 150.00

# Send invoice
python -m invoice_mcp_server cli invoice send <invoice-id>

# Record payment
python -m invoice_mcp_server cli invoice pay --invoice-id <invoice-id> --amount 1500.00 --method "bank_transfer"

Report Commands

# Show statistics
python -m invoice_mcp_server cli report stats

# Show overdue invoices
python -m invoice_mcp_server cli report overdue

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "invoice-server": {
      "command": "python",
      "args": ["-m", "invoice_mcp_server", "stdio"],
      "cwd": "/path/to/MCP_Server"
    }
  }
}

Testing MCP Connection

You can test the MCP server by sending JSON-RPC messages via stdio:

# Start the server and send an initialize request
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | python -m invoice_mcp_server stdio

MCP Primitives

Tools (Write Operations)

create_customer - Create new customer
update_customer - Update customer details
delete_customer - Delete customer
create_invoice - Create new invoice
add_invoice_item - Add item to invoice
update_invoice_status - Change invoice status
record_payment - Record payment
send_invoice - Send invoice to customer

Resources (Read Operations)

invoice://config - Server configuration
invoice://vat-rates - VAT rates
invoice://customers/list - Customer list
invoice://invoices/list - Invoice list
invoice://invoices/recent - Recent invoices
invoice://invoices/overdue - Overdue invoices
invoice://statistics/overview - Statistics

Prompts (Model Guidance)

create_invoice - Guide for invoice creation
manage_customer - Guide for customer management
process_payment - Guide for payment processing
generate_report - Guide for report generation

Testing

Run All Tests

pytest

Run with Coverage Report

pytest --cov=src/invoice_mcp_server --cov-report=term-missing

Run Specific Test Files

# Test models
pytest tests/test_models.py -v

# Test database
pytest tests/test_database.py -v

# Test SDK
pytest tests/test_sdk.py -v

# Test MCP server
pytest tests/test_mcp_server.py -v

Run Tests by Pattern

# Run all customer-related tests
pytest -k "customer" -v

# Run all invoice-related tests
pytest -k "invoice" -v

Code Quality

# Type checking
mypy src/invoice_mcp_server

# Linting
ruff check src/invoice_mcp_server

# Format check
ruff format --check src/invoice_mcp_server

Example Workflow

# 1. Create a customer
python -m invoice_mcp_server cli customer create --name "Test Company" --email "test@company.com"
# Returns: {"id": "uuid-here", "name": "Test Company", ...}

# 2. List customers to get the ID
python -m invoice_mcp_server cli customer list

# 3. Create an invoice for the customer
python -m invoice_mcp_server cli invoice create --customer-id <customer-id-from-step-2>

# 4. Add items to the invoice
python -m invoice_mcp_server cli invoice add-item --invoice-id <invoice-id> --description "Service" --quantity 1 --price 100

# 5. Check statistics
python -m invoice_mcp_server cli report stats

License

MIT

Name		Name	Last commit message	Last commit date
src/invoice_mcp_server		src/invoice_mcp_server
tests		tests
.env.example		.env.example
.gitignore		.gitignore
API_REFERENCE.md		API_REFERENCE.md
ARCHITECTURE.md		ARCHITECTURE.md
CONTRIBUTING.md		CONTRIBUTING.md
Class_8.txt		Class_8.txt
DEVELOPMENT.md		DEVELOPMENT.md
EXAMPLES.md		EXAMPLES.md
GIT_WORKTREE_WORKFLOW.md		GIT_WORKTREE_WORKFLOW.md
HW_8.txt		HW_8.txt
README.md		README.md
pyproject.toml		pyproject.toml
self-assessment-guide-V2-Eng.pdf		self-assessment-guide-V2-Eng.pdf
software_submission_guidelines_V2_Eng.pdf		software_submission_guidelines_V2_Eng.pdf

Latest commit

History

Folders and files

Repository files navigation