spring-ai -wallet

This MCP server exposes wallet management capabilities as AI tools via the Spring AI MCP integration. The server is built with Java 17 and Spring Boot, using H2 in-memory storage for easy testing. The exposed tools correspond to standard wallet operations such as creating a wallet, listing wallets, fetching a wallet by ID, updating a wallet, deleting a wallet, and recording expenses or income. Tools are annotated in the service layer with @Tool, making them accessible to AI agents through the MCP interface. To use the server, start the MCP-enabled application and connect an MCP client or agent to the wallet-mcp endpoint; the agent can invoke the tools by name (for example, create-wallet, get-all-wallets, get-wallet-by-id, update-wallet, delete-wallet, add-expense, add-income). The server handles validation and error reporting, returning structured results and appropriate HTTP-like responses through the MCP tool layer. You can also interact with the included REST APIs if you want to test directly in a browser or via curl, alongside the MCP exposure. Tools are designed to be composable, so you can chain create-wallet with subsequent get-all-wallets or get-wallet-by-id calls in your AI workflow.

Prerequisites:

• Java 17+ JDK installed
• Maven installed or use a compatible JDK with mvn
• Basic knowledge of running Java applications

Step-by-step:

1. Clone the repository or download the project sources.
2. Build the project: mvn clean package
3. Start the MCP-enabled wallet application: java -jar target/finance-wallet-0.0.1-SNAPSHOT.jar
4. (Optional) Configure MCP via application.properties to set server name, version, and port as shown in the README. Example: spring.main.web-application-type=none spring.ai.mcp.server.name=wallet-mcp spring.ai.mcp.server.version=0.0.1 server.port=8091
5. If you want to run via MCP JSON configuration, ensure the path to the jar is valid and run the same jar with the appropriate mcp.json mapping as shown in the README.

Notes:

• The wallet API uses an H2 in-memory database for simple testing and does not require external DB setup for local runs.
• The MCP integration requires tool callbacks to be registered, typically via a bean that returns ToolCallbacks.from(walletService).

Tips and common considerations:

• The MCP server name is defined as wallet-mcp in application.properties; this name is used when referencing the MCP server in configurations.
• The example mcp.json shows how to register the wallet MCP server and point to the jar path for runtime discovery by an MCP client.
• If you encounter port conflicts, change server.port in application.properties to an available port.
• H2 Console is available at http://localhost:8091/h2-console with JDBC URL jdbc:h2:mem:walletdb; username sa; password (empty).
• Ensure your ToolCallback registration (walletTools bean) is properly wired to expose the wallet service methods as MCP tools.
• If you modify tool names or add new tools, update the @Tool annotations and the ToolCallbacks configuration accordingly.