Nova MFI – Mifos System Doctor MCP 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.