AI导哈

微金融系统管理服务器

一个为Nova Microfinance Uganda的Helaplus/Mifos X平台构建的独立可部署的模型上下文协议(MCP)服务器，提供50多种工具用于审计、修复、通知、GL过账、报告和完整的Fineract管理。

  • by Chrl3y
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Chrl3y/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

服务已启动：

服务 端口 描述
mifos-system-doctor stdio MCP服务器（从克劳德桌面连接）
mifos-webhook-server 4000 Finract事件接收器+REST API桥接器
mifos-dashboard 3001 Next.js控制面板

打开仪表板： 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"
      }
    }
  }
}

环境变量

变量 必填 描述
FINERACT_BASE_URL 是 基本URL，例如。 https://helaplus.novamfi.co.ug/fineract-provider/api/v1
FINERACT_TENANT_ID 是 租户ID（通常 default)
FINERACT_USERNAME 是 Mifos管理员用户名
FINERACT_PASSWORD 是 Mifos管理员密码
AT_API_KEY 是* 非洲会说话的API关键
AT_USERNAME 是* 非洲的Talking用户名
AT_SENDER_ID 否 短信发送者ID（默认值： NovaLoan)
AT_WHATSAPP_NUMBER 否 WhatsApp商业号码
TWILIO_ACCOUNT_SID 否 Twilio SID（WhatsApp回退）
TWILIO_AUTH_TOKEN 否 Twilio身份验证令牌
DEFAULT_NOTIFICATION_CHANNEL 没有 sms 或 whatsapp （默认值： whatsapp)
WEBHOOK_PORT 否 Webhook服务器端口（默认值：4000）
DASHBOARD_PORT 否 仪表板端口（默认值：3001）

*通知功能需要。

MCP工具参考

存款和总账

工具 说明
calculate_deposit_breakdown 按产品计算客户存款的DR/CR额度
post_deposit_to_gl 将计算出的明细作为Fineract日记账分录发布

通知

工具 说明
send_notification 向一个或多个电话号码发送短信或WhatsApp
get_action_queue 扫描贷款票据以查找待处理的官员行动
notify_officers_of_pending_actions 批量通知所有未完成行动的官员
get_checker_queue 列出等待检查员批准的贷款

客户旅程

工具 说明
get_customer_journey 贷款ID的完整生命周期重建
get_nova_sop 返回Nova小额信贷标准操作程序文件

投资组合健康状况

工具 说明
get_portfolio_snapshot 标准杆数、老化、收集效率
get_par_aging 按逾期天数范围划分的标准杆数

审核与验证

工具 说明
audit_gl_mapping 检查所有贷款产品的总账账户分配
validate_topup_loan 仅使用principalOutstanding验证充值
scan_standing_instructions 检查账簿余额是否有长期指示
check_reconciliation 核对Fineract与外部付款记录

问题追踪器

工具 说明
list_issues 使用可选筛选器列出所有跟踪的问题
get_issue 按ID获取一个问题的完整详细信息
update_issue_status 更新问题的状态/受让人

Fineract管理员

工具 说明
list_loan_products / get_loan_product / create_loan_product / update_loan_product 贷款产品CRUD
list_gl_accounts / create_gl_account / update_gl_account 总账账户管理
list_users / create_user / update_user 用户管理
list_staff / create_staff 员工管理
list_charges / create_charge 充电配置
list_offices / create_office 办公室管理
list_payment_types / create_payment_type 付款类型配置
list_reports / run_report / create_report / update_report 报告
list_webhooks / create_webhook / delete_webhook Webhook管理
get_audit_log Fineract审计跟踪
approve_loan / disburse_loan / reject_loan 贷款生命周期行动
add_loan_note 通过WhatsApp添加备注+自动通知指定官员
get_loan_notes 检索贷款的所有票据

存款明细-产品费用表

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

产品密钥 标签 贷款示例 首付百分比
HAOJUE 豪爵摩托车 630000 UGX 各不相同
SIMBA_BOSS_110 辛巴老板110cc 450000 UGX 各不相同
SIMBA_RAPTOR 辛巴猛禽 510000 UGX 各不相同
TVS TVS摩托车 可配置 各不相同
HONDA 本田摩托车 可配置 各不相同

每个产品的费用组成：跟踪（固定）、保险（贷款百分比）、处理费（贷款百分比”）、安排费（贷款比例”）、应用费（固定），表格费（固定”）、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

许可证

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

相关 MCP