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:

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

*Required for notification features.

MCP Tools Reference

Deposit & GL

Notifications

Customer Journey

Portfolio Health

Audit & Validation

Issue Tracker

Fineract Admin

Deposit Breakdown – Product Fee Schedules

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

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.