Domain Reference

Each domain module maps MCP tools to REST API endpoints. This reference details the parameters and API calls for each tool.

Inventory Tools

`list_products`

Parameters: search?: str, category_id?: str, status?: str, low_stock?: bool, page?: int, page_size?: int
API: GET /inventory/products

`create_product`

Parameters: name: str, category_id?: str, sku?: str, barcode?: str, cost_price?: float, selling_price?: float, stock?: int, reorder_point?: int, tax_rate?: float, description?: str, is_service?: bool
API: POST /inventory/products

`get_product`

Parameters: product_id: str
API: GET /inventory/products/{id}

`update_product`

Parameters: product_id: str, name?: str, selling_price?: float, cost_price?: float, stock?: int, ...
API: PATCH /inventory/products/{id}

`delete_product`

Parameters: product_id: str
API: DELETE /inventory/products/{id}
⚠️ Destructive - requires confirmation

`list_categories`

API: GET /inventory/categories

`create_category`

Parameters: name: str, description?: str
API: POST /inventory/categories

`update_category`

Parameters: category_id: str, name?: str, description?: str
API: PATCH /inventory/categories/{id}

`delete_category`

Parameters: category_id: str
API: DELETE /inventory/categories/{id}
⚠️ Destructive - requires confirmation

`get_product_by_barcode`

Parameters: barcode: str
API: GET /inventory/products/barcode/{code}

`adjust_stock`

Parameters: product_id: str, qty_change: int, reason: str, note?: str
API: POST /inventory/products/{id}/adjust

`list_stock_adjustments`

Parameters: product_id: str, limit?: int
API: GET /inventory/products/{id}/adjustments

`list_low_stock_products`

API: GET /inventory/low-stock

Transaction Tools

`complete_sale`

Parameters: lines: list[{product_id, qty}], payment_method: str, payment_reference?: str, discount_pct?: float, customer_name?: str, customer_phone?: str, customer_id?: str, notes?: str
API: POST /pos/sale
Payment methods: Cash, M-Pesa, Tigo Pesa, Bank, Credit

`list_transactions`

Parameters: status?: str, method?: str, search?: str, customer_id?: str, date_from?: str, date_to?: str, page?: int, page_size?: int
API: GET /pos/transactions

`get_transaction`

Parameters: transaction_id: str
API: GET /pos/transactions/{id}

`refund_transaction`

Parameters: transaction_id: str, reason?: str
API: POST /pos/transactions/{id}/refund
⚠️ Destructive - requires confirmation

`void_transaction`

Parameters: transaction_id: str, reason?: str
API: POST /pos/transactions/{id}/void
⚠️ Destructive - requires confirmation

`get_sales_summary`

Parameters: date_from?: str, date_to?: str
API: GET /pos/summary

`get_hourly_sales`

Parameters: date?: str
API: GET /pos/summary/hourly

Customer Tools

`list_customers`

Parameters: search?: str, segment?: str, has_credit?: bool, page?: int, page_size?: int
API: GET /customers

`create_customer`

Parameters: name: str, phone?: str, email?: str, segment?: str, credit_limit?: int, notes?: str
API: POST /customers

`get_customer`

Parameters: customer_id: str
API: GET /customers/{id}

`update_customer`

Parameters: customer_id: str, name?: str, phone?: str, credit_limit?: int, ...
API: PATCH /customers/{id}

`list_credit_customers`

Parameters: overdue?: bool
API: GET /customers/credits

Credit Tools

`list_credit_tabs`

Parameters: status?: str, customer_id?: str, overdue?: bool, page?: int, page_size?: int
API: GET /credits

`get_customer_credit`

Parameters: customer_id: str
API: GET /credits/customers/{id}

`record_credit_payment`

Parameters: customer_id: str, amount: int, method?: str, reference?: str, note?: str
API: POST /credits/customers/{id}/payments

`send_credit_reminder`

Parameters: customer_id: str
API: POST /credits/customers/{id}/remind
⚠️ Sends real SMS - requires confirmation

`log_credit_communication`

Parameters: customer_id: str, kind: str, body: str
API: POST /credits/customers/{id}/messages
Kind: whatsapp, call, sms

`add_credit_note`

Parameters: customer_id: str, body: str
API: POST /credits/customers/{id}/notes

`write_off_credit`

Parameters: tab_id: str, reason?: str
API: POST /credits/{id}/write-off
⚠️ Destructive - requires confirmation

Supplier Tools

`list_suppliers`

Parameters: search?: str, status?: str, page?: int, page_size?: int
API: GET /suppliers

`create_supplier`

Parameters: name: str, category?: str, rep?: str, phone?: str, email?: str, address?: str, payment_terms?: int
API: POST /suppliers

`get_supplier`

Parameters: supplier_id: str
API: GET /suppliers/{id}

`update_supplier`

Parameters: supplier_id: str, name?: str, status?: str, ...
API: PATCH /suppliers/{id}

`deactivate_supplier`

Parameters: supplier_id: str
API: DELETE /suppliers/{id}
⚠️ Destructive - requires confirmation

`get_supplier_stats`

API: GET /suppliers/stats

`list_deliveries`

Parameters: unpaid?: bool, supplier_id?: str, page?: int, page_size?: int
API: GET /suppliers/deliveries

`create_delivery`

Parameters: supplier_id: str, invoice_number?: str, delivery_date?: str, items_count?: int, total_value?: int, status?: str, notes?: str
API: POST /suppliers/deliveries

`get_delivery`

Parameters: delivery_id: str
API: GET /suppliers/deliveries/{id}

`update_delivery`

Parameters: delivery_id: str, status?: str, total_value?: int, ...
API: PATCH /suppliers/deliveries/{id}

`delete_delivery`

Parameters: delivery_id: str
API: DELETE /suppliers/deliveries/{id}
⚠️ Destructive - requires confirmation

`list_payments`

Parameters: supplier_id?: str, page?: int, page_size?: int
API: GET /suppliers/payments

`pay_supplier`

Parameters: supplier_id: str, amount: int, payment_method?: str, reference?: str, notes?: str
API: POST /suppliers/{id}/pay

Staff Tools

`list_staff`

Parameters: search?: str, role?: str, status?: str, shift?: str, include_stats?: bool, page?: int, size?: int
API: GET /staff

`create_staff`

Parameters: first_name: str, last_name?: str, phone: str, role?: str, shift?: str, pin?: str, can_refund?: bool, can_discount?: bool
API: POST /staff

`get_staff`

Parameters: staff_id: str
API: GET /staff/{id}

`update_staff`

Parameters: staff_id: str, first_name?: str, shift?: str, ...
API: PATCH /staff/{id}

`deactivate_staff`

Parameters: staff_id: str
API: DELETE /staff/{id}
⚠️ Destructive - requires confirmation

`get_staff_kpis`

API: GET /staff/kpis

`get_staff_stats`

Parameters: staff_id: str
API: GET /staff/{id}/stats

`get_staff_activity`

Parameters: staff_id: str, date?: str
API: GET /staff/{id}/activity

`update_staff_shift`

Parameters: staff_id: str, shift?: str, employment_status?: str
API: PATCH /staff/{id}/shift

`update_staff_permissions`

Parameters: staff_id: str, can_refund?: bool, can_discount?: bool, can_view_reports?: bool
API: PATCH /staff/{id}/permissions

Store Tools

`list_stores`

Parameters: status?: str
API: GET /stores

`create_store`

Parameters: name: str, code?: str, phone?: str, area?: str, address?: str
API: POST /stores

`get_store`

Parameters: store_id: str
API: GET /stores/{id}

`update_store`

Parameters: store_id: str, name?: str, status?: str, ...
API: PATCH /stores/{id}

`get_store_stats`

API: GET /stores/stats

`set_store_status`

Parameters: store_id: str, status: str
API: PATCH /stores/{id}/status
Status: open, closed, busy

`get_store_weekly_performance`

Parameters: store_id: str
API: GET /stores/{id}/week

Expense Tools

`list_expenses`

Parameters: search?: str, category?: str, payment_method?: str, ordering?: str, page?: int, page_size?: int
API: GET /expenses

`create_expense`

Parameters: title: str, category: str, amount: int, payment_method?: str, notes?: str
API: POST /expenses

`get_expense`

Parameters: expense_id: str
API: GET /expenses/{id}

`update_expense`

Parameters: expense_id: str, title?: str, amount?: int, ...
API: PATCH /expenses/{id}

`delete_expense`

Parameters: expense_id: str
API: DELETE /expenses/{id}
⚠️ Destructive - requires confirmation

`get_expense_summary`

API: GET /expenses/summary

Report Tools

`list_report_types`

API: GET /reports/types

`generate_report`

Parameters: report_type: str, format?: str, date_from?: str, date_to?: str
API: POST /reports/generate
Report types: sales, inventory, tax, credit

`list_report_exports`

Parameters: limit?: int, report_type?: str
API: GET /reports/exports

`download_report_export`

Parameters: export_id: str
API: GET /reports/exports/{id}/download

`list_scheduled_reports`

API: GET /reports/scheduled

`create_scheduled_report`

Parameters: report_type: str, name?: str, frequency?: str, date_range_preset?: str, recipients?: list[str]
API: POST /reports/scheduled

`update_scheduled_report`

Parameters: schedule_id: str, name?: str, frequency?: str, ...
API: PATCH /reports/scheduled/{id}

`delete_scheduled_report`

Parameters: schedule_id: str
API: DELETE /reports/scheduled/{id}
⚠️ Destructive - requires confirmation

`send_scheduled_report`

Parameters: schedule_id: str
API: POST /reports/scheduled/{id}/send

Analytics Tools

`get_analytics_overview`

Parameters: sections?: str, date_from?: str, date_to?: str
API: GET /analytics/overview

`get_analytics_summary`

Parameters: date_from?: str, date_to?: str
API: GET /analytics/summary

`get_analytics_trend`

Parameters: date_from?: str, date_to?: str
API: GET /analytics/trend

`get_payment_mix`

Parameters: date_from?: str, date_to?: str
API: GET /analytics/payment-mix

`get_top_products`

Parameters: date_from?: str, date_to?: str, limit?: int
API: GET /analytics/top-products

`get_sales_report`

Parameters: date_from?: str, date_to?: str
API: GET /analytics/sales

`get_product_performance`

Parameters: date_from?: str, date_to?: str, category?: str
API: GET /analytics/products

`get_customer_analytics`

Parameters: date_from?: str, date_to?: str
API: GET /analytics/customers

`get_cashflow`

Parameters: date_from?: str, date_to?: str
API: GET /analytics/cashflow

`get_dashboard`

API: GET /analytics/dashboard

Account Tools

`get_profile`

API: GET /accounts/me

`update_profile`

Parameters: first_name?: str, last_name?: str, email?: str
API: PATCH /accounts/me

`get_organisation`

API: GET /accounts/organisation

`update_organisation`

Parameters: name?: str, tin?: str, region?: str, ...
API: PATCH /accounts/organisation

`switch_store`

Parameters: store_id: str
API: POST /accounts/switch-store

`list_users`

API: GET /accounts/users

`create_user`

Parameters: first_name: str, phone: str, role?: str
API: POST /accounts/users

`get_ai_credits`

API: GET /accounts/ai-credits

Communication Tools

`send_sms`

Parameters: to: str, message: str
Provider: SendAfrica API
⚠️ Sends real SMS - requires confirmation

`get_sms_balance`

Provider: SendAfrica API

`send_email`

Parameters: to: str, subject: str, body: str
Provider: MailAfrica API
⚠️ Sends real email - requires confirmation

`get_email_balance`

Provider: MailAfrica API

Image Tools

`suggest_product_image`

Parameters: product_name: str, category?: str
Provider: Wikimedia Commons API -> MinIO upload
Returns: {url, source, title, content_type, size}

All Tools Configuration