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