Mifos X - AI - Model Context Protocol (MCP) for Apache Fineract®

Mifos MCP - Model Context Protocol (MCP)

このプロジェクトは、Mifos X エコシステム向けの Model Context Protocol (MCP) を提供し、AI エージェントが金融データや操作にアクセスできるようにします。

実装は次のとおりです:

• Go (ネイティブ) — 102 個の型付きツール（高性能、SSE/Stdio を備えたクラウドネイティブ）。
• Java (Quarkus) — 38 個の型付きツール（バックオフィスとレコメンデーションにまたがる）。
• Python (FastMCP) — 49 個の型付きツール（モジュール式のドメイン駆動設計）。
• Rust — 89 個の型付きツール（排他的な一括操作を備えた高性能非同期 I/O）。

---

アーキテクチャの概要

Mifos MCP サーバーは、あらゆる AI アシスタントまたはエージェントフレームワークを Apache Fineract バンキングバックエンドに橋渡しする、スタンドアロンでステートレスな統合層として機能します。

┌──────────────────────────────────────────────┐
│            Apache Fineract / Mifos X          │
└───────────────────────┬──────────────────────┘
                        │ REST API
┌───────────────────────────────▼───────────────────────────────┐
│                 mcp-mifosx (Primary Repo)                     │
│                                                               │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐  │
│  │   /go (Native)  │ │ /java (Quarkus) │ │/python (FastMCP)│ │  /rust (Tokio)  │  │
│  │                 │ │                 │ │                 │ │                 │  │
│  │ - 102 Tools     │ │ - 38 Tools      │ │ - 49 Tools      │ │ - 89 Tools      │  │
│  │ - Go Routines   │ │ - Backoffice    │ │ - Modular Design│ │ - Async I/O     │  │
│  │ - SSE / Stdio   │ │ - Recommend.    │ │                 │ │ - Bulk Actions  │  │
│  └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘  │
└───────────┴───────────────────┼───────────────────┼───────────────────┴───────────┘
                        │ MCP Protocol (stdio / SSE)
          ┌─────────────┼──────────────┐
          ▼             ▼              ▼
    Mifos X WebApp   Claude Code     n8n / Custom
    AI Assistant     (claude.ai)     Workflow Agent
    (your client)   (external)       (your client)

このリポジトリは フレームワーク非依存 です。クライアント（LLM ブレイン、UI、メモリ）は別のリポジトリに存在します。MCP 互換のあらゆるシステムを接続できます。

---

エージェント型プラットフォームアーキテクチャ

エージェント型ゲートウェイ は、これらの MCP サーバーを基盤として構築されており、Mifos X WebApp コパイロットの背後にある単純な LLM ゲートウェイを、専門化されたエージェントの群れを実行するエージェントハーネスに置き換えます。

• ユーザーチャネル — Mifos WebApp（チャット / コパイロット UI）、Mifos Pay、Mifos Mobile、Mifos Field Officer、Mifos Web Banking。エージェント CLI は、開発者およびパワーユーザー向けのオプションのエントリポイントです。
• エージェント型ゲートウェイ — 既存の Mifos AI Gateway エンドポイントを再利用しますが、リクエストを LLM に直接ルーティングするのではなく、エージェントハーネスにルーティングします。
• エージェントハーネス（Pi / Prime / Hermes のランタイム） — すべてのエージェントを、LLM モデルプロバイダー、LLM ファイアウォール（安全性とセキュリティ）、可観測性（ログ / モニタリング）、セッション管理（ツールオーケストレーション）でラップします。
• 専門化されたエージェント — 登録エージェント、KYC/FT レビュアー、ローンレビュアー、スコアリングレビュアー、ドキュメントレビュアーなど。Fineract のツール呼び出しは、呼び出しを行う担当者の認証情報と権限を使用します。エージェントは個別の Fineract ロールを持ちません。
• MCP ツール / AG-UI 互換ツール — Fineract、ローン、クライアント、プロダクト、ワークフロー、レポーティング、カスタムツールで、エージェントが必要に応じて呼び出します。
• Apache Fineract + Grants / RBAC — 中核となるバンキングバックエンド。Fineract は認証された担当者に対して Grants を適用します。担当者のロールに必要な Grant があれば、その呼び出し（書き込み API を含む）は成功し、そうでなければ拒否されます。
• 外部システム（ツール経由） — スコアリング、ブラックリスト、制裁リスト、国民 ID、本人確認、生体認証の各システム。

---

実装の同期

このリポジトリには 2 つの異なるプログラミング言語がホストされていますが、一貫した体験を確保するため、可能な限り 機能的な同等性 が保たれています。

どのように「同期」するか:

1. ツール仕様: すべての実装は、同じ中核バンキングツールを公開することを目指しています。
   • Go は現在 102 個のツール で先行しており、高度なクラウドネイティブ機能と SSE を備えています。
   • Rust は 89 個のツール を提供し、高並行性の一括操作と堅牢な「フェッチ・アンド・マージ」状態管理を独自に備えています。
   • Python は、モジュール式のドメイン設計を用いて 49 個のツール を提供します。
   • Java は 38 個のツール を提供します（バックオフィス操作向けに 21 個、ユーザーレコメンデーション向けに 17 個）。
2. API の整合: すべての実装は、同じ Apache Fineract REST API に対して構築されています。これらはフィールドルーティングについて同一のロジックを共有しています。
3. ステートレスな同等性: すべての実装は、厳密に ステートレス な設計に従っています。どのサーバーも、ユーザーデータ、PII、AI メモリを保存しません。
4. テストプロトコル: 共有の「スモークテスト」により、すべての実装が LLM に対して同一で予測可能な JSON 構造を返すことが保証されます。

---

プロジェクト構造

このリポジトリは、複数の実装とクライアント統合をサポートするように構成されています。

.
├── README.md               # Root entry point & cross-implementation guide
├── go/                     # Go Implementation (Native / High-Performance)
│   ├── tools/              # 102 Domain-specific tools (SSE/Stdio)
│   ├── server/             # Dual-transport logic (HTTP/SSE & Stdio)
│   └── main.go             # Server entry point
├── rust/                   # Rust Implementation (Tokio/Reqwest)
│   ├── src/                # Multi-threaded typed tools & bulk execution logic
│   └── Cargo.toml          # Rust package dependencies
├── python/                 # Python Implementation (FastMCP)
│   ├── mcp_server.py       # Main entry point for the MCP server
│   ├── tools/              # Domain-specific banking tools (Loans, Clients, etc.)
│   └── core/               # API Gateway handlers
├── java/                   # Java Implementation (Quarkus)
│   ├── backoffice/         # Core banking tools
│   └── userrecommendation/ # Recommendation engine tools
└── agentic-mifos-sandbox/  # Docker Compose sandbox: Fineract, OpenFn, Pi agents, LOS (see its README)

---

はじめに

1. 実装を選択する

Go (ネイティブ & クラウド対応)

前提条件: Go 1.21+

手順:

1. 環境の設定: go/.env.example を go/.env にコピーし、認証情報を更新します。
2. ビルドと実行:

   cd go
   go build -o mcp-server .
   ./mcp-server
   

3. SSE モード (任意): .env で PORT=8080 を定義すると、Stdio から SSE マイクロサービスモードに切り替わります。

Rust (高性能)

前提条件: Rust (Cargo)

手順:

1. 環境の設定: rust/.env.example を rust/.env にコピーし、認証情報を更新します。
2. ビルドと実行:

   cd rust
   cargo build --release
   ./target/release/mcp-rust-mifosx
   

Java (Quarkus)

前提条件: JDK 21+、Maven

手順:

1. 環境変数の設定:

   export MIFOSX_BASE_URL="https://your-fineract-instance"
   export MIFOSX_BASIC_AUTH_TOKEN="your_api_token"
   export MIFOS_TENANT_ID="default"
   

2. JBang 経由で実行:

   jbang --quiet org.mifos.community.ai:mcp-server:1.0.0-SNAPSHOT:runner
   

3. ネイティブ実行ファイルのビルド (任意):

   cd java/backoffice
   ./mvnw package -Dnative
   ./target/mcp-server-1.0.0-SNAPSHOT-runner
   

Python (FastMCP)

前提条件: Python 3.10+、pip

手順:

1. Python ディレクトリに移動します:

   cd python
   

2. 依存関係をインストールします:

   pip install -r requirements.txt
   

3. 環境の設定: .env.example を .env にコピーし、詳細を入力します。
4. サーバーを実行します:

   python mcp_server.py
   

---

利用可能なツールの概要

ツールの正確な数と分類は、デプロイされたコアサーバーの実装によって異なります:

Go (102 ツール)

ネイティブな並行ルーチンを備えた、最も機能が 완전な実装です。

• クライアント & ID: 16 ツール
• ドキュメント & レポート: 26 ツール
• ローン & 貯蓄: 23 ツール
• グループ & センター: 13 ツール
• 一括 & 複合: 19 ツール (クラウドネイティブ)
• 会計 & 統計: 5 ツール

Rust (89 ツール)

非同期スケール、一括処理、堅牢な状態認識更新のために構築されています。

• クライアント & 担保: 25 ツール
• ローン & 担保: 19 ツール
• グループ、貯蓄 & センター: 23 ツール
• スタッフ、会計 & 手数料: 11 ツール
• 一括操作: 11 ツール (Rust 限定)

Python (49 ツール)

AI を Fineract に直接接続するドメイン駆動設計。

• クライアント & グループ: 16 ツール
• ローン & 貯蓄: 20 ツール
• スタッフ & 会計: 13 ツール

Java (38 ツール)

バックオフィスとレコメンデーションエンジンに分類されるエンタープライズスイート。

• バックオフィス操作: 21 ツール (クライアント、ローン、貯蓄をカバー)
• ユーザーレコメンデーション: 17 ツール (Java 限定)

---

MCP Inspector によるテスト

MCP Inspector を使用して、サーバーを対話的にテストおよびデバッグします:

npx @modelcontextprotocol/inspector <command_to_run_yours_server>

Python の場合:

npx @modelcontextprotocol/inspector python python/mcp_server.py

---

例 - バックオフィスエージェント

動画 URL	タイトル	プロンプト	実装
https://youtu.be/MDQKRoz5GKw?si=69X77C58nFhy6Ioh	Mifos MCP に参加して試す	https://ai.mifos.community にアクセスしてください	Go / Java / Python / Rust
https://youtu.be/y5MR3j8EGM4?si=zXTurBNql4xF5CGY	クライアントの作成	名前: OCTAVIO PAZ、メール: [email protected] などを使用してクライアントを作成します	Go / Java / Python / Rust
https://youtu.be/qJsC25cd-1g?si=qQzX8DeOe0_2qhfr	クライアントの有効化	クライアント OCTAVIO PAZ を有効化します	Go / Java / Python / Rust
https://youtu.be/X1g_nVDsRnM?si=K7vsAN7gOLEC2OG0	クライアントへの住所の追加	クライアント OCTAVIO PAZ に住所 (Plaza de Loreto) を追加します	Java
https://youtu.be/xeL9_sycwA8?si=AtV6F4WhTvcDspSp	身元保証人の追加	OCTAVIO PAZ の姉妹として Maria Elena Ramírez を追加します	Java
https://youtu.be/IKGMeAJBAOk?si=N27rE64dn7qxmMBk	ローン商品の作成	「SILVER」という名前のデフォルトのローン商品を作成します (金利 10%)	Java
https://youtu.be/5EdgUyLyP0w?si=L0UdYjXlyYF6faL5	ローン申請の作成	SILVER を使用して OCTAVIO PAZ の個人ローンを申請します	Go / Java / Python / Rust
https://youtu.be/2ioN_8z_uaY?si=ZTB5rCrgS2jTpC4-	ローンの承認	ローン口座を承認します	Go / Java / Python / Rust
https://youtu.be/dDebmrn4lB0?si=0GTf4asCBHnsu27f	ローンの払い出し	送金を使用してローン口座を払い出します	Go / Java / Python / Rust
https://youtu.be/N3wnyJCh_Ik?si=gSy5LrJdFF2kfzHd	ローンの返済	口座 6 の返済を行います (金額: 6687.59)	Go / Java / Python / Rust
https://youtu.be/bOuTj97hyqU?si=9bpno4Kp0II1IfPY	貯蓄商品の作成	「WALLET」という名前のデフォルトの貯蓄商品を作成します	Java
https://youtu.be/l-Z7LlE3AnM?si=yQM4lloJL8Hu6yv8	貯蓄アプリの作成	WALLET を使用して OCTAVIO PAZ の貯蓄口座を申請します	Go / Java / Python / Rust
https://youtu.be/Q5ExlhalG8U?si=TwbsUZX30G3JeNJy	貯蓄アプリの承認	メモ「MY FIRST APPROVAL」を付けて貯蓄口座を承認します	Go / Java / Python / Rust
https://youtu.be/DJgUiRYK-rE?si=YatfVgOgpbP4wV91	貯蓄の有効化	貯蓄口座を有効化します	Go / Java / Python / Rust
https://youtu.be/Od7KFqktUtI?si=gPJNlLOB_7D74QdS	入金の実行	口座 1 に 5000 の DEPOSIT を作成します	Go / Java / Python / Rust
https://youtu.be/9OL6N5wKG7c?si=R50RjTK6GI_ODuUs	出金の実行	口座 1 に 2000 の WITHDRAWAL を作成します	Go / Java / Python / Rust

---

セキュリティとガードレール

• 普遍的な互換性 — Claude、GPT-4、Qwen、または任意の MCP クライアントで動作します。
• データ主権 — サーバーは外部呼び出しを行いません。
• RBAC の適用 — すべてのアクションは Fineract ネイティブの権限に照らして検証されます。

---

お問い合わせとコミュニティ

• Mifos Community: https://mifos.org
• Mifos MCP (Docker): https://hub.docker.com/r/openmf/mifos-mcp
• Chatbot Demo: https://ai.mifos.community