spring-mcp-financial-demo

rcantore/spring-mcp-financial-demo

3.3

If you are the rightful owner of spring-mcp-financial-demo and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This project is a Model Context Protocol (MCP) server designed to provide real-time financial data using Java 21, Maven, and Spring Boot.

Tools
3
Resources
0
Prompts
0

MCP Financial Server

Servidor MCP demo para consultar datos financieros en tiempo real usando Java 21, Maven y Spring Boot.

Que es este proyecto

Este es un servidor MCP (Model Context Protocol) que expone herramientas para consultar precios de acciones y criptomonedas. El proyecto sirve como ejemplo para:

  • Como crear un servidor MCP usando Spring Boot
  • Integracion con APIs externas (Alpha Vantage y CoinGecko)
  • Patrones de diseno en Spring (Dependency Injection, Configuration, Services)
  • Buenas practicas de desarrollo en Java 21

Que es MCP (Model Context Protocol)

MCP es un protocolo abierto desarrollado por Anthropic que permite a los modelos de IA (como Claude) interactuar con herramientas externas de forma estandarizada. Piensa en MCP como un "puente" que conecta la inteligencia de Claude con datos y funcionalidades del mundo real.

Conceptos clave de MCP

Servidor MCP: Una aplicacion que expone herramientas (tools) que pueden ser invocadas por clientes MCP.

Tool: Una funcion especifica que realiza una operacion (ej: consultar el precio de una accion).

Cliente MCP: Una aplicacion que consume los tools del servidor (ej: Claude Desktop, aplicaciones personalizadas).

Protocolo stdio: Comunicacion via entrada/salida estandar, permitiendo integracion simple entre procesos.

Como funciona

Cliente MCP (Claude)  <--> Protocolo MCP <--> Servidor MCP (esta aplicacion)
                                                    |
                                                    v
                                            APIs Externas (Alpha Vantage, CoinGecko)

Requisitos previos

  • JDK 21 o superior
  • Maven 3.8+
  • Cuenta en Alpha Vantage (API key gratuita)
  • Conexion a internet para llamadas a APIs

Estructura del proyecto

mcp-financial-server/
ā”œā”€ā”€ src/
ā”‚   ā”œā”€ā”€ main/
ā”‚   ā”‚   ā”œā”€ā”€ java/
ā”‚   ā”‚   ā”‚   ā””ā”€ā”€ com/educational/mcp/financial/
ā”‚   ā”‚   ā”‚       ā”œā”€ā”€ config/              # Configuracion de Spring
ā”‚   ā”‚   ā”‚       ā”‚   ā”œā”€ā”€ ApiConfiguration.java
ā”‚   ā”‚   ā”‚       ā”‚   ā””ā”€ā”€ WebClientConfig.java
ā”‚   ā”‚   ā”‚       ā”œā”€ā”€ models/              # DTOs y modelos de datos
ā”‚   ā”‚   ā”‚       ā”‚   ā”œā”€ā”€ StockQuote.java
ā”‚   ā”‚   ā”‚       ā”‚   ā”œā”€ā”€ CryptoQuote.java
ā”‚   ā”‚   ā”‚       ā”‚   ā””ā”€ā”€ HistoricalData.java
ā”‚   ā”‚   ā”‚       ā”œā”€ā”€ services/            # Logica de negocio
ā”‚   ā”‚   ā”‚       ā”‚   ā”œā”€ā”€ StockService.java
ā”‚   ā”‚   ā”‚       ā”‚   ā””ā”€ā”€ CryptoService.java
ā”‚   ā”‚   ā”‚       ā”œā”€ā”€ tools/               # Tools MCP
ā”‚   ā”‚   ā”‚       ā”‚   ā”œā”€ā”€ StockPriceTool.java
ā”‚   ā”‚   ā”‚       ā”‚   ā”œā”€ā”€ CryptoPriceTool.java
ā”‚   ā”‚   ā”‚       ā”‚   ā””ā”€ā”€ MarketSummaryTool.java
ā”‚   ā”‚   ā”‚       ā””ā”€ā”€ McpFinancialServerApplication.java
ā”‚   ā”‚   ā””ā”€ā”€ resources/
ā”‚   ā”‚       ā””ā”€ā”€ application.yml          # Configuracion de la aplicacion
ā”‚   ā””ā”€ā”€ test/
ā”‚       ā””ā”€ā”€ java/                        # Tests unitarios
ā”œā”€ā”€ pom.xml                              # Dependencias Maven
ā””ā”€ā”€ README.md                            # Este archivo

Configuracion

1. Obtener API Key de Alpha Vantage

  1. Visita: https://www.alphavantage.co/support/#api-key
  2. Completa el formulario para obtener tu API key gratuita
  3. Copia la API key proporcionada

2. Configurar variables de entorno

Configura la API key como variable de entorno:

En Linux/Mac:

export ALPHA_VANTAGE_API_KEY=tu_api_key_aqui

En Windows (CMD):

set ALPHA_VANTAGE_API_KEY=tu_api_key_aqui

En Windows (PowerShell):

$env:ALPHA_VANTAGE_API_KEY="tu_api_key_aqui"

Nota: Si no configuras la API key, la aplicacion usara "demo" como valor predeterminado, que tiene limitaciones severas de rate limiting.

Instalacion y ejecucion

1. Compilar el proyecto

cd /Users/rcantore/dev/pocs/mcp-financial-server
mvn clean install

Este comando:

  • Descarga todas las dependencias necesarias
  • Compila el codigo fuente
  • Ejecuta los tests (si existen)
  • Genera el JAR ejecutable en target/

2. Ejecutar el servidor

mvn spring-boot:run

O ejecutar el JAR directamente:

java -jar target/mcp-financial-server-1.0.0.jar

3. Verificar que el servidor esta funcionando

El servidor se comunicara via stdio (entrada/salida estandar), por lo que no veras una interfaz web. Los logs indicaran que el servidor inicio correctamente:

Iniciando MCP Financial Server...
El servidor se comunicara via stdio (entrada/salida estandar)
Tools disponibles:
  - get_stock_price: Consulta precio de acciones
  - get_crypto_price: Consulta precio de criptomonedas
  - get_market_summary: Resumen del mercado
MCP Financial Server iniciado correctamente

Herramientas (Tools) disponibles

1. get_stock_price

Consulta el precio actual de una accion.

Parametros:

  • symbol (string, requerido): Simbolo bursatil (ej: AAPL, GOOGL, MSFT)

Ejemplo de respuesta:

{
  "symbol": "AAPL",
  "name": "AAPL",
  "price": 178.25,
  "change": 2.15,
  "change_percent": 1.22,
  "open_price": 176.10,
  "high_price": 179.30,
  "low_price": 175.80,
  "volume": 48567234,
  "last_updated": "2024-01-15"
}

2. get_crypto_price

Consulta el precio actual de una criptomoneda.

Parametros:

  • crypto_id (string, requerido): Identificador en CoinGecko (ej: bitcoin, ethereum, cardano)

Ejemplo de respuesta:

{
  "id": "bitcoin",
  "symbol": "BTC",
  "name": "Bitcoin",
  "current_price": 42500.00,
  "market_cap": 831245678900,
  "market_cap_rank": 1,
  "total_volume": 25678901234,
  "high_24h": 43100.00,
  "low_24h": 41800.00,
  "price_change_percentage_24h": 2.35,
  "market_cap_change_percentage_24h": 2.12,
  "last_updated": "2024-01-15T10:30:00.000Z"
}

3. get_market_summary

Obtiene un resumen rapido del mercado con activos populares.

Parametros: Ninguno

Ejemplo de respuesta:

{
  "stocks": {
    "AAPL": { ... },
    "GOOGL": { ... },
    "MSFT": { ... }
  },
  "cryptocurrencies": {
    "bitcoin": { ... },
    "ethereum": { ... }
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "description": "Resumen del mercado con activos principales"
}

Integracion con Claude Desktop

Para usar este servidor con Claude Desktop:

1. Compilar el JAR

mvn clean package

2. Configurar Claude Desktop

Edita el archivo de configuracion de Claude Desktop:

En Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

En Windows: %APPDATA%\Claude\claude_desktop_config.json

Agrega la siguiente configuracion:

{
  "mcpServers": {
    "financial-data": {
      "command": "java",
      "args": [
        "-jar",
        "/Users/rcantore/dev/pocs/mcp-financial-server/target/mcp-financial-server-1.0.0.jar"
      ],
      "env": {
        "ALPHA_VANTAGE_API_KEY": "tu_api_key_aqui"
      }
    }
  }
}

3. Reiniciar Claude Desktop

Cierra completamente Claude Desktop y vuelve a abrirlo.

4. Verificar la conexion

En Claude Desktop, deberias ver un icono de herramientas que indica que el servidor MCP esta conectado. Puedes preguntar:

"Cual es el precio actual de Apple?" o "Muestrame el resumen del mercado"

Claude usara automaticamente las herramientas del servidor para responder.

Arquitectura del proyecto

Capa de Tools (tools/)

Define las herramientas que seran expuestas via MCP. Cada tool:

  • Esta anotado con @ServerMcpTool
  • Define parametros con @McpToolParameter
  • Retorna respuestas en formato JSON

Capa de Services (services/)

Contiene la logica de negocio:

  • StockService: Interactua con Alpha Vantage API
  • CryptoService: Interactua con CoinGecko API
  • Maneja errores y transformaciones de datos

Capa de Models (models/)

Define los DTOs (Data Transfer Objects):

  • StockQuote: Datos de acciones
  • CryptoQuote: Datos de criptomonedas
  • HistoricalData: Datos historicos

Capa de Configuration (config/)

Configuracion de Spring Boot:

  • ApiConfiguration: Lee configuracion desde application.yml
  • WebClientConfig: Configura cliente HTTP reactivo

Patrones de diseno utilizados

1. Dependency Injection (DI)

Los servicios se inyectan automaticamente en los tools:

@RequiredArgsConstructor
public class StockPriceTool {
    private final StockService stockService;
    // Spring inyecta automaticamente stockService
}

2. Builder Pattern

Los DTOs usan el patron Builder de Lombok:

StockQuote quote = StockQuote.builder()
    .symbol("AAPL")
    .price(new BigDecimal("178.25"))
    .build();

3. Service Layer Pattern

La logica de negocio esta separada en servicios reutilizables:

Tool -> Service -> External API

Siguientes pasos para extender el proyecto

Ideas de mejoras

  1. Agregar mas tools:

    • Consultar datos historicos de acciones
    • Calcular indicadores tecnicos (RSI, MACD, etc.)
    • Comparar rendimiento de multiples activos
    • Alertas de precio

  2. Mejorar el manejo de errores:

    • Implementar reintentos automaticos
    • Cache de respuestas para reducir llamadas a APIs
    • Manejo de rate limiting mas sofisticado

  3. Agregar persistencia:

    • Guardar consultas en base de datos
    • Historial de precios consultados
    • Configuracion de usuarios

  4. Implementar tests:

    • Tests unitarios con JUnit 5
    • Tests de integracion con WireMock
    • Tests de los tools MCP

  5. Agregar mas fuentes de datos:

    • Yahoo Finance
    • Finnhub
    • IEX Cloud
    • Polygon.io

  6. Mejorar observabilidad:

    • Metricas con Micrometer
    • Logs estructurados
    • Health checks y readiness probes

Ejercicio practico

Implementa un nuevo tool llamado compare_stocks que:

  1. Reciba una lista de simbolos de acciones
  2. Consulte el precio de cada una
  3. Retorne una comparacion con el mejor y peor rendimiento del dia
@ServerMcpTool(
    name = "compare_stocks",
    description = "Compara el rendimiento de multiples acciones"
)
public String compareStocks(
    @McpToolParameter(name = "symbols", required = true)
    String symbols
) {
    // Tu implementacion aqui
}

Recursos adicionales

Documentacion oficial

Aprendizaje

Solucion de problemas

Error: "API key invalido"

Verifica que la variable de entorno ALPHA_VANTAGE_API_KEY este configurada correctamente.

Error: "Rate limit excedido"

Alpha Vantage tiene limites de:

  • API key gratuita: 25 requests por dia, 5 por minuto
  • Considera usar cache o esperar antes de realizar mas consultas

Error: "No se encontraron datos para el simbolo"

Verifica que el simbolo de la accion sea correcto. Alpha Vantage usa simbolos del mercado estadounidense por defecto.

El servidor no responde en Claude Desktop

  1. Verifica que el path al JAR sea correcto en la configuracion
  2. Revisa los logs de Claude Desktop para errores
  3. Asegurate de que Java 21 este instalado y accesible

Licencia

Este proyecto es de uso demostrativo y se proporciona sin garantias.

Contribuciones

Este es un proyecto libre y demostrativo. Sientete libre de:

  • Hacer fork del proyecto
  • Experimentar con mejoras
  • Agregar nuevas funcionalidades
  • Compartir tus aprendizajes

Autor

Proyecto creado para demostrar la creacion de servidores MCP con Java y Spring Boot.