Nova MFI – Mifos System Doctor Server

A fully independent, deployable Model Context Protocol (MCP) server built for Nova Microfinance Uganda's Helaplus / Mifos X platform. Provides 50+ tools for audit, repair, notifications, GL posting, reporting, and complete Fineract administration — all accessible from any MCP-compatible AI client (Claude Desktop, Cursor, etc.) and from the bundled Next.js control dashboard.

---

Contents

Mifos-MCP-Server/
├── src/
│   ├── index.ts                    # MCP server – 50+ tools over stdio
│   ├── types/index.ts              # Shared TypeScript types
│   ├── utils/
│   │   ├── fineract-client.ts      # Fineract REST client (paginated)
│   │   └── formatter.ts            # Table + date helpers
│   ├── tools/
│   │   ├── deposit-breakdown.ts    # Deposit fee calculator + GL posting
│   │   ├── notification-engine.ts  # Africa's Talking SMS/WhatsApp + Twilio
│   │   ├── action-queue.ts         # Officer action queue + bulk notify
│   │   ├── customer-journey.ts     # Full loan lifecycle reconstruction
│   │   ├── fineract-admin.ts       # Full CRUD for all Fineract entities
│   │   ├── portfolio-snapshot.ts   # PAR, aging, collection efficiency
│   │   ├── audit-gl-mapping.ts     # GL mapping audit
│   │   ├── validate-topup.ts       # Top-up loan validator
│   │   └── issue-tracker.ts        # Issues register tracker
│   ├── webhook-server/
│   │   └── index.ts               # Express webhook receiver + REST API bridge
│   └── config/
│       ├── product-fee-schedules.json   # Fee schedules: HAOJUE, SIMBA BOSS, SIMBA RAPTOR, TVS, HONDA
│       └── issues-register.json         # 17 tracked system issues
├── dashboard/                      # Next.js 14 control panel
│   ├── app/
│   │   ├── page.tsx                # Portfolio overview + KPIs
│   │   ├── deposit-calculator/     # Deposit breakdown UI + GL post
│   │   ├── notifications/          # Manual/bulk SMS+WhatsApp
│   │   ├── workflow/               # Officer action queue
│   │   ├── reports/                # Report runner (CSV export)
│   │   ├── issues/                 # Issue tracker
│   │   ├── admin/                  # Fineract entity management
│   │   └── api/                    # Next.js API routes (breakdown, post-gl)
│   └── ...
├── Dockerfile                      # MCP + webhook server image
├── docker-compose.yml              # 3-service stack
├── .env.example                    # All environment variables documented
└── package.json

---

Quick Start

1. Clone and configure

git clone https://github.com/Chrl3y/Mifos-MCP-Server.git
cd Mifos-MCP-Server
cp .env.example .env
# Edit .env with your Fineract URL, tenant, and Africa's Talking credentials

2. Install and build

npm install
npm run build

3. Run with Docker Compose (recommended)

docker-compose up -d

Services started:

Service	Port	Description
mifos-system-doctor	stdio	MCP server (connect from Claude Desktop)
mifos-webhook-server	4000	Fineract event receiver + REST API bridge
mifos-dashboard	3001	Next.js control panel

Open the dashboard: http://localhost:3001

4. Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nova-mfis": {
      "command": "node",
      "args": ["/path/to/Mifos-MCP-Server/dist/index.js"],
      "env": {
        "FINERACT_BASE_URL": "https://your-helaplus.com/fineract-provider/api/v1",
        "FINERACT_TENANT_ID": "default",
        "FINERACT_USERNAME": "mifos",
        "FINERACT_PASSWORD": "your-password",
        "AT_API_KEY": "your-africas-talking-api-key",
        "AT_USERNAME": "your-at-username",
        "AT_SENDER_ID": "NovaLoan"
      }
    }
  }
}

---

Environment Variables

Variable	Required	Description
FINERACT_BASE_URL	Yes	Base URL e.g. https://helaplus.novamfi.co.ug/fineract-provider/api/v1
FINERACT_TENANT_ID	Yes	Tenant ID (usually default)
FINERACT_USERNAME	Yes	Mifos admin username
FINERACT_PASSWORD	Yes	Mifos admin password
AT_API_KEY	Yes*	Africa's Talking API key
AT_USERNAME	Yes*	Africa's Talking username
AT_SENDER_ID	No	SMS sender ID (default: NovaLoan)
AT_WHATSAPP_NUMBER	No	AT WhatsApp business number
TWILIO_ACCOUNT_SID	No	Twilio SID (WhatsApp fallback)
TWILIO_AUTH_TOKEN	No	Twilio auth token
DEFAULT_NOTIFICATION_CHANNEL	No	sms or whatsapp (default: whatsapp)
WEBHOOK_PORT	No	Webhook server port (default: 4000)
DASHBOARD_PORT	No	Dashboard port (default: 3001)

*Required for notification features.

---

MCP Tools Reference

Deposit & GL

Tool	Description
calculate_deposit_breakdown	Compute DR/CR lines for a client deposit by product
post_deposit_to_gl	Post a calculated breakdown as a Fineract journal entry

Notifications

Tool	Description
send_notification	Send SMS or WhatsApp to one or more phone numbers
get_action_queue	Scan loan notes for pending officer actions
notify_officers_of_pending_actions	Bulk-notify all officers with outstanding actions
get_checker_queue	List loans waiting for checker approval

Customer Journey

Tool	Description
get_customer_journey	Full lifecycle reconstruction for a loan ID
get_nova_sop	Return Nova Microfinance standard operating procedure document

Portfolio Health

Tool	Description
get_portfolio_snapshot	PAR, aging, collection efficiency
get_par_aging	PAR bucketed by overdue day ranges

Audit & Validation

Tool	Description
audit_gl_mapping	Check GL account assignments on all loan products
validate_topup_loan	Validate top-up using principalOutstanding only
scan_standing_instructions	Check for standing instructions firing on book balance
check_reconciliation	Reconcile Fineract vs external payment records

Issue Tracker

Tool	Description
list_issues	List all tracked issues with optional filters
get_issue	Get full details for one issue by ID
update_issue_status	Update status / assignee for an issue

Fineract Admin

Tool	Description
list_loan_products / get_loan_product / create_loan_product / update_loan_product	Loan product CRUD
list_gl_accounts / create_gl_account / update_gl_account	GL account management
list_users / create_user / update_user	User management
list_staff / create_staff	Staff management
list_charges / create_charge	Charge configuration
list_offices / create_office	Office management
list_payment_types / create_payment_type	Payment type configuration
list_reports / run_report / create_report / update_report	Reporting
list_webhooks / create_webhook / delete_webhook	Webhook management
get_audit_log	Fineract audit trail
approve_loan / disburse_loan / reject_loan	Loan lifecycle actions
add_loan_note	Add note + auto-notify assigned officer via WhatsApp
get_loan_notes	Retrieve all notes for a loan

---

Deposit Breakdown – Product Fee Schedules

Pre-configured products in src/config/product-fee-schedules.json:

Product Key	Label	Example Loan	Down Payment %
HAOJUE	Haojue Motorcycle	630,000 UGX	varies
SIMBA_BOSS_110	Simba Boss 110cc	450,000 UGX	varies
SIMBA_RAPTOR	Simba Raptor	510,000 UGX	varies
TVS	TVS Motorcycle	configurable	varies
HONDA	Honda Motorcycle	configurable	varies

Fee components per product: Tracking (fixed), Insurance (% loan), Processing Fee (% loan), Arrangement Fee (% loan), App Fee (fixed), Form Fee (fixed), CRB (fixed), Loan Repayment Wallet (remainder).

To add a new product, edit src/config/product-fee-schedules.json — no code changes needed.

---

Issues Register

17 tracked issues covering:

• ISS-001 – Top-up loan deducts principal + future interest (CRITICAL)
• ISS-004 – GL misalignment: wallet vs revenue vs liability accounts
• ISS-006 – Standing instructions firing on book balance not confirmed deposits
• ISS-010 – Frozen/stuck loans with no lifecycle transition path
• ISS-011 – Data migration mismatches (legacy → Fineract)
• ISS-013 – Repayment date misalignment after restructure
• ISS-HUB-001 through ISS-HUB-006 – Pipeline feedback loops, uncaptured payments
• MF-001, MF-002 – GL account structure issues
• RPT-001 through RPT-008 – Reporting gaps and inaccuracies

---

Development

# Run MCP server in dev mode
npm run dev

# Run webhook server
npm run webhook

# Run dashboard
cd dashboard && npm install && npm run dev

---

Architecture

Claude Desktop / AI Client
        │
        │ stdio (MCP protocol)
        ▼
  MCP Server (src/index.ts)
        │
        ├─── Fineract REST API (your Helaplus instance)
        ├─── Africa's Talking (SMS / WhatsApp)
        └─── Twilio (WhatsApp fallback)

Fineract Webhooks ──► Webhook Server (port 4000)
                              │
                              ├─── Notification Engine (auto-notify officers)
                              └─── REST API bridge (dashboard ↔ MCP tools)

Next.js Dashboard (port 3001)
  ├── Portfolio Overview
  ├── Deposit Calculator
  ├── Notifications
  ├── Action Queue
  ├── Reports
  ├── Issue Tracker
  └── Fineract Admin

---

License

Internal use — Nova Microfinance Uganda. Not for public distribution.