Mifos MCP Server

Nova MFI–Mifos系统医生MCP服务器

完全独立、可部署 模型上下文协议（MCP）服务器 为Nova Microfinance乌干达的Helaplus/Mifos X平台构建。提供50多种工具，用于审计、修复、通知、总账过账、报告和完整的Fineract管理——所有这些工具都可以从任何兼容MCP的AI客户端（Claude Desktop、Cursor等）和捆绑的Next.js控制仪表板访问。

______________________________________________________________________

目录

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

______________________________________________________________________

快速开始

1.克隆和配置

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.安装和构建

npm install
npm run build

3.使用Docker Compose运行（推荐）

docker-compose up -d

服务已启动：

打开仪表板： http://localhost:3001

4.连接到克劳德桌面

添加 ~/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"
      }
    }
  }
}

______________________________________________________________________

环境变量

\*通知功能需要。

______________________________________________________________________

MCP工具参考

存款和总账

通知

客户旅程

投资组合健康状况

审核与验证

问题追踪器

Fineract管理员

______________________________________________________________________

存款明细-产品费用表

预配置产品 src/config/product-fee-schedules.json:

每个产品的费用组成：跟踪（固定）、保险（贷款百分比）、处理费（贷款百分比”）、安排费（贷款比例”）、应用费（固定），表格费（固定”）、CRB（固定“）、贷款还款钱包（剩余）。

要添加新产品，请编辑 src/config/product-fee-schedules.json --无需更改代码。

______________________________________________________________________

问题登记

17个跟踪问题，涵盖：

• ISS-001 –追加贷款扣除本金+未来利息（关键）
• ISS-004 –总账错位：钱包账户、收入账户和负债账户
• ISS-006 –对未确认存款的账面余额发出长期指示
• ISS-010 –没有生命周期过渡路径的冻结/停滞贷款
• ISS-011 –数据迁移不匹配（遗留→ 罚款）
• ISS-013 –重组后还款日期不一致
• ISS-HUB-001至ISS-HUB-606 –管道反馈回路，未被捕获的付款
• MF-001、MF-002 –总账账户结构问题
• RPT-001至RPT-008 –报告差距和不准确之处

______________________________________________________________________

发展

# Run MCP server in dev mode
npm run dev

# Run webhook server
npm run webhook

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

______________________________________________________________________

建筑

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

______________________________________________________________________

许可证

内部使用----乌干达新小额信贷。不用于公开发行。