QGold

Um servidor para processamento de linguagem natural de preços de ativos e modelagem financeira para análise de impacto da taxa de retirada.

GitHubExperimente este MCPPatrocinado

Documentação

QGold

O QGold é um MCP Server que facilita o processamento de linguagem natural e a compreensão de determinados preços de ativos, como Ouro, Prata, Paládio, Cobre, Bitcoin e Ethereum. Por diversão, ele também inclui uma ferramenta simples de modelagem financeira para ajudar a entender melhor os impactos potenciais de uma taxa de retirada de 4% (ou qualquer outro valor) sobre o principal poupado ao longo do tempo.

Este projeto resultou da participação no AWS Lambda Hackathon da DEVPOST 2025.

Aqui está um vídeo de introdução.

Arquitetura

alt text

  • AWS Lambda:
    • qgold-api-data-function: Executa código para buscar dados de preços de múltiplos ativos e armazena no DynamoDB
    • qgold-quote-analysis-function: O proxy Lambda do MCP responsável por recuperar dados do DynamoDB para análise
  • EventBridge Scheduler: Aciona a função Lambda nos dias úteis (segunda a sexta) às 22:00 UTC / 17:00 EST
  • DynamoDB: Armazena os dados de preços recuperados com um índice baseado em data para consultas fáceis
  • Q CLI: Cliente LLM para o MCP Server como uma ferramenta de PLN para aprender sobre preços de ativos armazenados no DynamoDB

O diretório 'functions' contém as funções AWS Lambda.

O diretório 'mcp_server' contém o servidor MCP a ser usado no AWS Q CLI.

O Makefile consolida alguns comandos úteis para construir e testar as funções Lambda.

Ativos Rastreados

A função Lambda busca dados de preços para os seguintes ativos:

  • XAU (Ouro)
  • XAG (Prata)
  • XPD (Paládio)
  • HG (Cobre)
  • BTC (Bitcoin)
  • ETH (Ethereum)

Endpoint da API

A função Lambda qgold-api-data-function faz requisições ao seguinte endpoint de API pública externa para buscar preços de ativos:

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

Onde {symbol} é substituído por cada símbolo de ativo (XAU, XAG, XPD, HG, BTC, ETH).

Estrutura de Dados

A função Lambda espera que a API retorne dados de preços no seguinte formato:

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

Os dados são armazenados no DynamoDB com a seguinte estrutura:

{
  "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"
}

Pré-requisitos do Ambiente de Desenvolvimento do Projeto

  • Desenvolvido e testado no shell bash do Ubuntu 22.04
  • Uma conta AWS
  • AWS CLI instalado e configurado
  • AWS SAM CLI instalado
  • Python 3.10 ou posterior (aliased como python3)
  • AWS Q CLI instalado e login de conta de desenvolvedor

Instruções de Implantação do Lambda QGold

As funções Lambda estão no diretório 'functions'.

Etapas para Implantar

  1. Implante o aplicativo AWS usando sam:

Para implantar usando o CLI sam e o modelo CloudFormation template.yaml fornecido:

sam build
sam deploy --guided --capabilities CAPABILITY_NAMED_IAM

O Makefile incluído também permitirá que você use estes comandos para construir e implantar:

make deploy

  1. Durante a implantação guiada, você será solicitado a fornecer (ou aceitar padrões):

    • Nome da stack
    • Região AWS
    • URL do endpoint da API
    • Nome da tabela DynamoDB

  2. Verifique a Implantação

make test-quote-retrieval

Nota: quando bem-sucedido, este teste deve popular a tabela QGoldPriceDataTable do DynamoDB com um conjunto inicial de registros. Caso contrário, o banco de dados permanecerá vazio até que o agendamento do EventBridge execute a função de carregamento de dados.

Uma resposta bem-sucedida do teste deve ser assim:

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

Para garantir que a função Lambda de análise de cotações esteja funcionando, execute o seguinte teste:

make test-quote-analysis

A resposta esperada deve ser assim:

{"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\"}]}"}

Configuração

Você pode modificar os seguintes parâmetros:

  • ApiEndpointBase: A URL base da API para buscar dados (https://api.gold-api.com/price)
  • TableName: O nome da tabela DynamoDB
  • LogLevel: O nível de registro de log para a função Lambda (DEBUG, INFO, WARNING, ERROR, CRITICAL)

No entanto, provavelmente é melhor deixar esses valores como estão.

Personalização

  • Para alterar o agendamento, modifique o ScheduleExpression no recurso WeekdayScheduleRule em template.yaml
  • Para modificar a lógica de processamento de dados, atualize o arquivo lambda_function.py

Os índices do DynamoDB são configurados para que os dados sejam atualizados diariamente (em vez de levar em conta também o horário).

Limpeza

Para remover todos os recursos criados por este aplicativo:

sam delete

Servidor MCP QGold

Este servidor MCP (Model Context Protocol) fornece ferramentas para recuperar informações de preços de moedas das funções Lambda QGold.

NOTA: Certifique-se de mudar para o diretório 'mcp_server' para o seguinte.

Configuração

Instalar dependências:

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

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

Usando o Servidor MCP no Q CLI

Adicionar Servidor MCP

Execute os seguintes comandos dentro do diretório mcp_server:

q mcp add --name qgold --command python3

Edite o arquivo mcp.json para ficar como abaixo:

vim .amazonq/mcp.json

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

Execute o q cli assim:

q login

Em seguida, confie na ferramenta do Servidor MCP para iniciar:

q chat --trust-tools=qgold___get_asset_prices,qgold___model_financial_projections

get_asset_prices

Recupera informações de preços de moedas usando intervalos de datas especificados.

Parâmetros:

  • name (obrigatório): O nome da moeda (ex.: ouro, prata)
  • start_date (opcional): Data de início no formato AAAA-MM-DD
  • end_date (opcional): Data de término no formato AAAA-MM-DD
Exemplos de Sessões de Chat
> 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 ferramenta MCP foi criada apenas para satisfazer uma curiosidade. Ela ajuda a fornecer uma ideia do crescimento anual de um valor principal ao longo de um período de 30 anos, bem como o impacto de certas taxas de retirada versus taxas de crescimento sobre esse principal no mesmo período. A ferramenta também permite simular taxas de juros de crescimento aleatórias ao longo do período de trinta anos para, talvez, uma visão mais "Caos e Macacos" de possíveis cenários financeiros.

Existem maneiras melhores de modelar esses cenários, provavelmente. Por exemplo, o S&P 500 provavelmente experimentou menos anos de queda do que a geração aleatória produzirá em uma determinada execução, então este modelo é provavelmente pessimista demais (mas interessante mesmo assim). Além disso, executar esses cenários em uma simulação de Monte Carlo e armazenar os resultados em cache no REDIS ou DynamoDB também pode fornecer uma análise Q benéfica, a definir.

O seguinte é um exemplo de uso da ferramenta model_financial_projections para simular uma retirada de 4% de uma reserva de poupança em um cenário potencial de aposentadoria:

> 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 e Licença

  • Autor: James Caple
  • Licença: MIT