Apple Health Data with Elasticsearch

Servidor MCP para Dados de Saúde da Apple com Elasticsearch - Projeto Inicial

Bem-vindo! Este repositório contém o código-fonte completo e final para o post do blog, "Desbloqueie o Potencial do seu LLM: Construindo um Servidor MCP com Elasticsearch para Dados Reais de Saúde".

Este projeto fornece uma implementação executável de um servidor personalizado do Model Context Protocol (MCP). Construído com Python e o framework FastMCP, este servidor se conecta a um índice Elasticsearch contendo dados de amostra de passos do Apple HealthKit. Esta configuração permite que um cliente LLM como o Claude consulte dados pessoais de saúde usando linguagem natural.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte instalado e em execução:

• Python 3.10+
• Elasticsearch: Uma instância do Elasticsearch 8.x rodando localmente em http://localhost:9200.
• Claude Desktop: O cliente MCP que usaremos para interagir com o servidor.
• uv: Para gerenciar pacotes Python.

Começando

Siga estes passos para configurar seu ambiente local e instalar as dependências necessárias.

1. Navegue até o Diretório do Seu Projeto

Abra seu terminal ou prompt de comando e navegue até a pasta do projeto.

cd path/to/your/folder/apple-watch-health-mcp

2. Inicialize o Projeto Python

Este passo cria o arquivo pyproject.toml, que o uv usa para gerenciar as dependências do seu projeto.

uv init

3. Crie e Ative um Ambiente Virtual

# Create the virtual environment
uv venv

# Activate the environment
# On macOS/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

4. Instale as Dependências

Instale os pacotes Python necessários. Observe que estamos especificando uma versão compatível para a biblioteca elasticsearch para corresponder ao servidor v8.x usado neste tutorial.

uv add "mcp[cli]" "elasticsearch>=8.0.0,<9.0.0" aiohttp pydantic

Configuração do Ambiente

Configurando a Chave de API

Após criar a chave de API no Elasticsearch, você precisa configurá-la no seu ambiente:

# Export the API key for the current session
export ES_API_KEY="your_encoded_api_key_here"

Instruções de Uso

Com o ambiente configurado, você agora pode executar a solução.

1. Ingira os Dados de Amostra

Primeiro, execute o script fornecido para popular sua instância do Elasticsearch com os dados de amostra. Este script criará o índice com o mapeamento correto e inserirá os 30 documentos de amostra.

python ingest_data.py

Você deve ver uma saída confirmando que os documentos foram ingeridos com sucesso.

2. Teste o Servidor com o MCP Inspector

Antes de instalar no Claude, você pode verificar se o servidor está funcionando corretamente usando a ferramenta MCP Inspector.

mcp dev apple_watch_mcp.py

Isso abrirá uma interface web onde você pode testar interativamente os recursos, ferramentas e prompts do servidor.

3. Instale e Use no Claude

Este é o passo final para conectar seu servidor MCP ao cliente Claude Desktop.

1. Instale o servidor: Execute este comando no seu terminal.

   mcp install apple_watch_mcp.py --name "Apple Health Steps"
   

   Este comando registra o servidor no arquivo de configuração do Claude Desktop.

   Execute o comando abaixo para visualizar o conteúdo deste arquivo.

   
       cat ~/Library/Application\ Support/Claude/claude_desktop_config.json  
   
   

Você deve ver uma estrutura semelhante a esta dentro do arquivo, sob a chave "mcpServers":

{
 "mcpServers": {
   "Apple Health Steps": {
     "command": "/full/path/to/your/uv",
     "args": [
       "--directory",
       "/path/to/repository/apple-watch-health-mcp",
       "run",
       "apple_watch_mcp.py"
       // Other arguments may appear depending on your setup
     ]
   }
   // ... other servers might be listed here
 }
}

2. Reinicie o Claude Desktop: Você deve fechar e reabrir o aplicativo Claude Desktop para que ele carregue a nova configuração do servidor.

3. Comece a Conversar: Após reiniciar, o Claude executará automaticamente seu servidor MCP em segundo plano. Agora você pode fazer perguntas sobre seus dados de saúde em linguagem natural. Experimente estes exemplos do post do blog:

   • "Qual foi meu dia mais ativo esta semana?"
   • "Compare minha atividade entre Apple Watch e iPhone"
   • Ou use os comandos de barra integrados como /daily_report ou /trend_analysis.

Descrições dos Arquivos

• apple_watch_mcp.py: O script completo e final para o servidor MCP, contendo todos os Recursos, Ferramentas e Prompts implementados.
• ingest_data.py: Um script auxiliar que popula sua instância do Elasticsearch com os dados de amostra.
• sample_data.json: Um arquivo JSON contendo dados fictícios de contagem de passos do Apple Health para teste.
• README.md: Este arquivo, fornecendo instruções para executar a solução completa.