JinDaGe - mifosx MCP Details

article

README

🚀 Apache Fineract API MCP 服务器项目

本项目为 Apache Fineract API 打造了 Model Context Protocol (MCP) 服务器，助力 AI 代理访问财务数据并进行操作。项目提供了 Python、Java (Quarkus) 和 Node.js 三种语言的实现方案。

🚀 快速开始

选择实现方式

Python (Flask)

先决条件：需要 Python 3.8 及以上版本，以及 flask、mcp.server.fastmcp 库。步骤：

安装依赖项：
```
pip install mcp[cli] uv flask
```
运行服务器：
```
mcp dev app.py
```

Java (Quarkus)

先决条件：需 JDK 17 及以上版本，以及 Maven 工具。步骤：

在 shell 或 IDE 中配置环境变量：

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

使用 JBang 快速运行：

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

（可选）构建原生可执行文件：

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

Node.js

先决条件：需要 Node.js 16 及以上版本，以及 npm 包管理器。步骤：

安装依赖项：
```
cd nodejs && npm install
```
在 .env 中配置环境变量：
```
cp .env.example .env
```
运行服务器：
```
npm run dev
```
使用内置的 inspect 脚本测试：
```
npm run inspect
```

✨ 主要特性

标准化 API 访问：通过 fineract:// URI 实现。
符合 MCP 标准：支持 STDIO/SSE 传输。
环境无关性：配置灵活。

📦 安装指南

MCP 开发工具

使用 MCP 检查器 测试和调试你的服务器：

npx @modelcontextprotocol/inspector

这会启动一个本地 Web UI，通过 STDIO 或 SSE 连接到你的 MCP 服务器。

💻 使用示例

基础用法

使用 MCP 检查器进行测试

启动你的 MCP 服务器（Python/Java/Node.js）。
运行检查器：
```
npx @modelcontextprotocol/inspector
```
使用 STDIO 传输连接到服务器。

📚 详细文档

配置

所有实现都需要以下环境变量： | 属性 | 详情 | |------|------| | FINERACT_BASE_URL | 你的 Fineract 实例的基础 URL | | FINERACT_BASIC_AUTH_TOKEN | API 认证令牌 | | FINERACT_TENANT_ID | 租户标识符（默认：default） |

注意：Java 使用 MIFOSX_ 前缀的变量（例如，MIFOSX_BASE_URL）。

可用资源

MCP 服务器公开了以下资源：

核心资源

fineract://clients：列出所有客户
fineract://clients/{clientId}：获取特定客户的详细信息
fineract://loans：列出所有贷款
fineract://loans/{loanId}：获取特定贷款的详细信息

工具

search_clients：搜索客户（按名称/属性）
create_client：创建新客户（仅限 Node.js/Python）
update_loan_status：更新贷款状态（仅限 Java/Python）

构建原生可执行文件（仅限 Java）

对于 Java (Quarkus)，创建一个原生可执行文件：

./mvnw package -Dnative -Dquarkus.native.container-build=true
./target/mcp-server-1.0.0-SNAPSHOT-runner

贡献指南

Python：修改 python/app.py 配置 .env 文件路径。
Java：在 src/main/java/org/mifos-community/ai/MCPServer.java 中配置环境变量。
Node.js：编辑 config.js 设置服务器参数。

mifosx