modernbank

ModernBank MCP Server is a Spring Boot application that exposes a Minimal Chat Protocol (MCP) HTTP API to route end-user banking requests through Google Gemini function-calling workflows and ModernBank backend services. When a user sends a chat message, the MCP server uses Gemini to determine which downstream capability should be invoked (e.g., listing transactions, transferring money, or retrieving account info) and then forwards the request via Feign clients to the appropriate ModernBank service. The server also enriches responses with user context headers and can prompt the client to provide missing inputs (such as an accountId) by offering a pendingRequest with selectable options. Tools exposed to Gemini include transaction_list, transaction_create, get_user_accounts, get_user_account_details, and transfer_money, each mapped to a concrete ServiceHandler.

To use the server, start it and send requests to the /v1/api/mcp endpoints. The primary entry is POST /v1/api/mcp/process, which accepts a SendMessageRequest containing chat history and optional arguments. Gemini will propose a downstream function to invoke, and the MCP server will execute the corresponding handler (e.g., TransactionService for transaction_list, AccountService for get_user_accounts). If Gemini omits required inputs like accountId, the MissingInputResolver will fetch available accounts and respond with a pendingRequest to guide the user.

Note: The transfer_money function is registered but not yet implemented in the current service registry, so calls to that function will raise an IllegalArgumentException until the implementation is completed.

Prerequisites:

• Java 17 or newer
• Maven 3.9+ (or use the provided Maven wrapper in the project)
• Access to a Gemini API key for testing (configured via environment or Spring profile)

Installation steps:

1. Clone the repository git clone <repository-url> cd modernbank-mcp-server

2. Build the project ./mvnw clean package -DskipTests // or if you prefer Maven directly: mvn clean package -DskipTests

3. Prepare runtime configuration

   • Ensure an API key for Gemini is available (GEMINI_API_KEY environment variable or in application.yml under gemini.api.key).
   • Update Feign client base URLs in src/main/resources/application.yml to point to the actual downstream ModernBank services (account-service and transaction-service).

4. Run the server java -jar target/modernbank-mcp-server-<version>.jar // Alternatively, if using the built jar name from your build, adjust accordingly.

Optional: run with environment variables GEMINI_API_KEY=your-key FEIGN_ACCOUNT_SERVICE_URL=http://localhost:8084/api/v1 FEIGN_TRANSACTION_SERVICE_URL=http://localhost:8083/api/v1 java -jar target/modernbank-mcp-server-<version>.jar

Tips and common considerations:

• Ensure the Gemini API key is present before startup; without it, function routing will fail.
• The Feign header propagation interceptor copies Authorization, X-User-Id, X-User-Email, and X-User-Role from incoming requests to outbound calls. Include these headers in MCP requests if your clients provide them.
• If a Gemini function is not yet implemented (e.g., transfer_money), the registry will throw an IllegalArgumentException; implement the corresponding handler or adjust function mappings as needed.
• When accountId is omitted in a request, the MissingInputResolver fetches accounts and returns a pendingRequest section so the client can present options to the user.
• Verify downstream service endpoints (account-service and transaction-service) are reachable and their API contracts match what the MCP server expects (methods like getAccounts, getAccountDetails, getTransactions, transferMoneyBetweenAccounts).
• For local development, you can run the downstream services with mock endpoints or stubs to exercise the MCP flow end-to-end.