🚀 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 库。 步骤：

1. 安装依赖项：

   pip install mcp[cli] uv flask
   

2. 运行服务器：

   mcp dev app.py
   

Java (Quarkus)

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

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

   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. （可选）构建原生可执行文件：

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

Node.js

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

1. 安装依赖项：

   cd nodejs && npm install
   

2. 在 .env 中配置环境变量：

   cp .env.example .env
   

3. 运行服务器：

   npm run dev
   

4. 使用内置的 inspect 脚本测试：

   npm run inspect
   

✨ 主要特性

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

📦 安装指南

MCP 开发工具

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

npx @modelcontextprotocol/inspector

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

💻 使用示例

基础用法

使用 MCP 检查器进行测试

1. 启动你的 MCP 服务器（Python/Java/Node.js）。
2. 运行检查器：

   npx @modelcontextprotocol/inspector
   

3. 使用 STDIO 传输连接到服务器。

📚 详细文档

配置

所有实现都需要以下环境变量：

注意：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 设置服务器参数。