QGold

Un servidor para el procesamiento de lenguaje natural de precios de activos y modelado financiero para el análisis del impacto de la tasa de retiro.

GitHubPrueba este MCPPatrocinado

Documentación

QGold

QGold es un Servidor MCP que facilita el procesamiento de lenguaje natural y la comprensión de ciertos precios de activos, como Oro, Plata, Paladio, Cobre, Bitcoin y Ethereum. Por diversión, también incluye una herramienta simple de modelado financiero para ayudar a comprender mejor los posibles impactos de una tasa de retiro del 4% (o la que sea) sobre el capital ahorrado a lo largo del tiempo.

Este proyecto surgió de la participación en el Hackathon AWS Lambda de DEVPOST 2025.

Aquí hay un video introductorio.

Arquitectura

alt text

  • AWS Lambda:
    • qgold-api-data-function: Ejecuta código para obtener datos de precios de múltiples activos y los almacena en DynamoDB
    • qgold-quote-analysis-function: El proxy Lambda de MCP responsable de recuperar datos de DynamoDB para su análisis
  • EventBridge Scheduler: Activa la función Lambda entre semana (L-V) a las 22:00 PM UTC / 5:00 PM EST
  • DynamoDB: Almacena los datos de precios recuperados con un índice basado en fechas para facilitar las consultas
  • Q CLI: Cliente LLM para el Servidor MCP como herramienta de PLN para aprender sobre los precios de activos almacenados en DynamoDB

El directorio 'functions' contiene las funciones Lambda de AWS.

El directorio 'mcp_server' contiene el servidor MCP que se utilizará en el AWS Q CLI.

El Makefile consolida algunos comandos útiles para compilar y probar las funciones Lambda.

Activos Rastreados

La función Lambda obtiene datos de precios para los siguientes activos:

  • XAU (Oro)
  • XAG (Plata)
  • XPD (Paladio)
  • HG (Cobre)
  • BTC (Bitcoin)
  • ETH (Ethereum)

Endpoint de API

La función Lambda qgold-api-data-function realiza solicitudes al siguiente endpoint de API pública externa para obtener precios de activos:

https://api.gold-api.com/price/{symbol}

Donde {symbol} se reemplaza con cada símbolo de activo (XAU, XAG, XPD, HG, BTC, ETH).

Estructura de Datos

La función Lambda espera que la API devuelva datos de precios en el siguiente formato:

{
  "name": "Gold",
  "price": 3433.399902,
  "symbol": "XAU",
  "updatedAt": "2025-06-14T22:54:24Z",
  "updatedAtReadable": "a few seconds ago"
}

Los datos se almacenan en DynamoDB con la siguiente estructura:

{
  "id": "uuid-generated-for-record",
  "name": "gold-2025-06-14",  // Composite key of asset name and date
  "asset_name": "gold",       // Original asset name in lowercase for querying
  "price": 3433.399902,
  "symbol": "XAU",
  "sourceUpdatedAt": "2025-06-14T22:54:24Z",
  "sourceUpdatedAtReadable": "a few seconds ago",
  "recordedAt": "2025-06-14T23:00:00Z",
  "date": "2025-06-14"
}

Requisitos Previos del Entorno de Desarrollo del Proyecto

  • Desarrollado y probado en shell bash de Ubuntu 22.04
  • Una cuenta de AWS
  • AWS CLI instalado y configurado
  • AWS SAM CLI instalado
  • Python 3.10 o posterior (alias como python3)
  • AWS Q CLI instalado e inicio de sesión con cuenta de desarrollador

Instrucciones de Despliegue de QGold Lambda

Las funciones Lambda se encuentran en el directorio 'functions'.

Pasos para Desplegar

  1. Despliegue la aplicación de AWS usando sam:

Para desplegar usando la CLI de sam y la plantilla CloudFormation template.yaml proporcionada:

sam build
sam deploy --guided --capabilities CAPABILITY_NAMED_IAM

El Makefile incluido también le permitirá usar estos comandos para compilar y desplegar:

make deploy

  1. Durante el despliegue guiado, se le pedirá que proporcione (o acepte los valores predeterminados):

    • Nombre de la pila
    • Región de AWS
    • URL del endpoint de API
    • Nombre de la tabla de DynamoDB

  2. Verifique el Despliegue

make test-quote-retrieval

Nota: cuando tenga éxito, esta prueba debería poblar la tabla QGoldPriceDataTable de DynamoDB con un conjunto inicial de registros. De lo contrario, la base de datos permanecerá vacía hasta que el cronograma de EventBridge se ejecute para ejecutar la función Lambda de carga de datos.

Una respuesta exitosa de la prueba debería verse así:

{
	"statusCode": 200,
	"body": "{\"message\": \"Price data processing complete\", \"timestamp\": \"2025-06-16T16:14:30.379948\", \"successful\": [\"XAU\", \"XAG\", \"XPD\", \"HG\", \"BTC\", \"ETH\"], \"failed\": []}"
}

Para asegurarse de que la función Lambda de análisis de cotizaciones esté funcionando, ejecute la siguiente prueba:

make test-quote-analysis

La respuesta esperada debería verse así:

{"statusCode": 200, "body": "{\"count\": 1, \"items\": [{\"date\": \"2025-06-16\", \"symbol\": \"XAU\", \"sourceUpdatedAtReadable\": \"a few seconds ago\", \"asset_name\": \"gold\", \"sourceUpdatedAt\": \"2025-06-16T16:14:27Z\", \"price\": 3401.129883, \"id\": \"330cfe64-64e9-4f75-b930-dc163b4c5ebf\", \"recordedAt\": \"2025-06-16T16:14:30.379948\", \"name\": \"gold-2025-06-16\"}]}"}

Configuración

Puede modificar los siguientes parámetros:

  • ApiEndpointBase: La URL base de la API para obtener datos (https://api.gold-api.com/price)
  • TableName: El nombre de la tabla de DynamoDB
  • LogLevel: El nivel de registro para la función Lambda (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Sin embargo, probablemente sea mejor dejar estos valores sin cambios.

Personalización

  • Para cambiar el cronograma, modifique ScheduleExpression en el recurso WeekdayScheduleRule en template.yaml
  • Para modificar la lógica de procesamiento de datos, actualice el archivo lambda_function.py

Los índices de DynamoDB están configurados de modo que los datos se actualizan diariamente (en lugar de tener en cuenta también la hora).

Limpieza

Para eliminar todos los recursos creados por esta aplicación:

sam delete

Servidor MCP de QGold

Este servidor MCP (Protocolo de Contexto de Modelo) proporciona herramientas para recuperar información de precios de divisas desde las funciones Lambda de QGold.

NOTA: Asegúrese de cambiar al directorio 'mcp_server' para lo siguiente.

Configuración

Instalar dependencias:

# Using pip
pip install -r mcp_server/requirements.txt

# Or using uv (faster)
uv pip install -r mcp_server/requirements.txt

Uso del Servidor MCP en Q CLI

Agregar Servidor MCP

Ejecute los siguientes comandos dentro del directorio mcp_server:

q mcp add --name qgold --command python3

Edite el archivo mcp.json para que se vea como el siguiente:

vim .amazonq/mcp.json

{
  "mcpServers": {
    "qgold": {
      "command": "python3",
      "args": ["server.py"]
    }
  }
}

Ejecute q cli de esta manera:

q login

Luego confíe en la herramienta del Servidor MCP para comenzar:

q chat --trust-tools=qgold___get_asset_prices,qgold___model_financial_projections

get_asset_prices

Recupera información de precios de divisas utilizando rangos de fechas específicos.

Parámetros:

  • name (obligatorio): El nombre de la divisa (por ejemplo, oro, plata)
  • start_date (opcional): Fecha de inicio en formato AAAA-MM-DD
  • end_date (opcional): Fecha de fin en formato AAAA-MM-DD
Sesiones de Chat de Ejemplo
> what about today's copper price
Let me check the current price of copper for you.


🛠️  Using tool: get_asset_prices (trusted) from mcp server qgold
 ⋮ 
 ● Running get_asset_prices with the param:
 ⋮  {
 ⋮    "arguments": {
 ⋮      "name": "copper"
 ⋮    },
 ⋮    "name": "get_asset_prices"
 ⋮  }
 ⋮ 
 ● Completed in 0.66s
Based on the latest data, the current price of copper is $4.41 per pound as of June 16, 2025. This price was last updated just a few seconds ago at 16:14:28 UTC today.

> What are the prices of XAG today?
I'll help you check the current price of silver (XAG) today.


🛠️  Using tool: get_asset_prices (trusted) from mcp server qgold
 ⋮ 
 ● Running get_asset_prices with the param:
 ⋮  {
 ⋮    "arguments": {
 ⋮      "name": "silver"
 ⋮    },
 ⋮    "name": "get_asset_prices"
 ⋮  }
 ⋮ 
 ● Completed in 0.51s
Based on the latest data, the current price of silver (XAG) is $36.42 per troy ounce as of June 16, 2025. This price was last updated just a few seconds ago at 16:14:26 UTC today.

> what are today's prices for gold, silver, copper and btc?
I'll retrieve the current prices for gold, silver, copper, and bitcoin for you.


🛠️  Using tool: get_asset_prices (trusted) from mcp server qgold
 ⋮ 
 ● Running get_asset_prices with the param:
 ⋮  {
 ⋮    "arguments": {
 ⋮      "name": "gold"
 ⋮    },
 ⋮    "name": "get_asset_prices"
 ⋮  }
 ⋮ 
 ● Completed in 0.74s



🛠️  Using tool: get_asset_prices (trusted) from mcp server qgold
 ⋮ 
 ● Running get_asset_prices with the param:
 ⋮  {
 ⋮    "arguments": {
 ⋮      "name": "silver"
 ⋮    },
 ⋮    "name": "get_asset_prices"
 ⋮  }
 ⋮ 
 ● Completed in 0.54s



🛠️  Using tool: get_asset_prices (trusted) from mcp server qgold
 ⋮ 
 ● Running get_asset_prices with the param:
 ⋮  {
 ⋮    "arguments": {
 ⋮      "name": "copper"
 ⋮    },
 ⋮    "name": "get_asset_prices"
 ⋮  }
 ⋮ 
 ● Completed in 0.62s



🛠️  Using tool: get_asset_prices (trusted) from mcp server qgold
 ⋮ 
 ● Running get_asset_prices with the param:
 ⋮  {
 ⋮    "arguments": {
 ⋮      "name": "bitcoin"
 ⋮    },
 ⋮    "name": "get_asset_prices"
 ⋮  }
 ⋮ 
 ● Completed in 0.44s
Here are today's prices for all the assets you requested (June 16, 2025):

• Gold (XAU): $3,401.13 per troy ounce
• Silver (XAG): $36.42 per troy ounce
• Copper (HG): $4.41 per pound
• Bitcoin (BTC): $107,604.82

All prices were last updated just a few seconds ago, around 16:14 UTC today.

model_financial_projections

Esta herramienta MCP fue creada para satisfacer una necesidad puntual. Ayuda a proporcionar una idea del crecimiento anual de un monto de capital durante un período de 30 años, así como el impacto que ciertas tasas de retiro frente a tasas de crecimiento podrían tener sobre ese capital en el mismo período. La herramienta también permite simular tasas de interés de crecimiento aleatorias durante el período de treinta años para, quizás, una visión más estilo 'Chaos Monkeys' de posibles escenarios financieros.

Existen mejores formas de modelar estos escenarios, probablemente. Por ejemplo, el S&P 500 probablemente ha experimentado menos años negativos de los que la generación aleatoria arrojará en una ejecución determinada, por lo que este modelo probablemente sea demasiado pesimista (pero interesante de todos modos). Además, ejecutar estos escenarios en una simulación de Monte Carlo y almacenar los resultados en caché en REDIS o DynamoDB también podría proporcionar un análisis Q beneficioso, pendiente de definir.

El siguiente es un ejemplo de uso de la herramienta model_financial_projections para simular un retiro del 4% de un fondo de ahorro en un posible escenario de jubilación:

> Model the withdraw scenarios over 30 years with a starting principal amount of $800k with random annual growth.  If there is negative growth in a year, do not withdraw funds the following year.  Print the results in a table.
I'll model the withdrawal scenarios over 30 years with your specifications. Let me use the financial projection tool to calculate this.


🛠️  Using tool: model_financial_projections (trusted) from mcp server qgold
 ⋮ 
 ● Running model_financial_projections with the param:
 ⋮  {
 ⋮    "arguments": {
 ⋮      "growth_rate": 7,
 ⋮      "initial_amount": 800000,
 ⋮      "skip_withdrawal_after_loss": true,
 ⋮      "use_random_growth": true,
 ⋮      "withdrawal_rate": 4
 ⋮    },
 ⋮    "name": "model_financial_projections"
 ⋮  }
 ⋮ 
 ● Completed in 0.2s
## 30-Year Financial Projection with Random Growth

Here's the 30-year financial projection with an initial amount of $800,000, using random annual growth rates and skipping withdrawals after years with negative growth:

| Year | Starting Balance | Withdrawal | Balance After Withdrawal | Growth Rate | Growth Amount | Ending Balance |
|------|------------------|------------|--------------------------|-------------|---------------|----------------|
| 1    | $800,000.00      | $32,000.00 | $768,000.00              | 13.71%      | $105,294.45   | $873,294.45    |
| 2    | $873,294.45      | $34,931.78 | $838,362.67              | 3.54%       | $29,645.90    | $868,008.57    |
| 3    | $868,008.57      | $34,720.34 | $833,288.23              | -2.38%      | -$19,796.44   | $813,491.79    |
| 4    | $813,491.79      | $0.00      | $813,491.79              | 24.22%      | $197,055.96   | $1,010,547.75  |
| 5    | $1,010,547.75    | $40,421.91 | $970,125.84              | -14.24%     | -$138,175.17  | $831,950.67    |
| 6    | $831,950.67      | $0.00      | $831,950.67              | 6.07%       | $50,496.12    | $882,446.79    |
| 7    | $882,446.79      | $35,297.87 | $847,148.91              | -5.88%      | -$49,808.19   | $797,340.73    |
| 8    | $797,340.73      | $0.00      | $797,340.73              | -24.15%     | -$192,590.29  | $604,750.44    |
| 9    | $604,750.44      | $0.00      | $604,750.44              | 4.38%       | $26,503.18    | $631,253.62    |
| 10   | $631,253.62      | $25,250.14 | $606,003.48              | 15.50%      | $93,921.36    | $699,924.84    |
| 11   | $699,924.84      | $27,996.99 | $671,927.85              | -21.06%     | -$141,486.30  | $530,441.55    |
| 12   | $530,441.55      | $0.00      | $530,441.55              | -18.77%     | -$99,585.47   | $430,856.09    |
| 13   | $430,856.09      | $0.00      | $430,856.09              | 4.13%       | $17,785.55    | $448,641.63    |
| 14   | $448,641.63      | $17,945.67 | $430,695.97              | -7.99%      | -$34,415.90   | $396,280.07    |
| 15   | $396,280.07      | $0.00      | $396,280.07              | 31.36%      | $124,291.45   | $520,571.52    |
| 16   | $520,571.52      | $20,822.86 | $499,748.66              | -11.07%     | -$55,325.43   | $444,423.22    |
| 17   | $444,423.22      | $0.00      | $444,423.22              | 6.62%       | $29,419.11    | $473,842.34    |
| 18   | $473,842.34      | $18,953.69 | $454,888.64              | 3.92%       | $17,808.92    | $472,697.56    |
| 19   | $472,697.56      | $18,907.90 | $453,789.66              | -13.34%     | -$60,545.00   | $393,244.66    |
| 20   | $393,244.66      | $0.00      | $393,244.66              | 7.64%       | $30,036.21    | $423,280.87    |
| 21   | $423,280.87      | $16,931.23 | $406,349.64              | 1.75%       | $7,127.53     | $413,477.16    |
| 22   | $413,477.16      | $16,539.09 | $396,938.08              | 11.25%      | $44,642.72    | $441,580.80    |
| 23   | $441,580.80      | $17,663.23 | $423,917.57              | 3.50%       | $14,824.10    | $438,741.67    |
| 24   | $438,741.67      | $17,549.67 | $421,192.01              | 5.43%       | $22,878.99    | $444,070.99    |
| 25   | $444,070.99      | $17,762.84 | $426,308.15              | 5.90%       | $25,141.68    | $451,449.84    |
| 26   | $451,449.84      | $18,057.99 | $433,391.84              | -21.56%     | -$93,442.92   | $339,948.92    |
| 27   | $339,948.92      | $0.00      | $339,948.92              | 8.91%       | $30,295.74    | $370,244.66    |
| 28   | $370,244.66      | $14,809.79 | $355,434.87              | 1.30%       | $4,631.10     | $360,065.97    |
| 29   | $360,065.97      | $14,402.64 | $345,663.34              | 16.63%      | $57,498.45    | $403,161.79    |
| 30   | $403,161.79      | $16,126.47 | $387,035.32              | -0.02%      | -$91.53       | $386,943.79    |

### Summary:
• Initial amount: $800,000.00
• Final balance after 30 years: $386,943.79
• Total withdrawals over 30 years: $457,092.10

Note that in years following negative growth (years 4, 6, 8, 9, 12, 13, 15, 17, 20, and 27), no withdrawals were made as specified in your requirements. The model used a 4% withdrawal rate in years when withdrawals were permitted.

Autor y Licencia

  • Autor: James Caple
  • Licencia: MIT