Wesleyribeirobarbosa Mcp Server

Servidor MCP para Smart Cities

Este servidor MCP (Model Context Protocol) permite que IAs interajam com dados de dispositivos IoT de uma cidade inteligente, incluindo iluminação pública, medidores de água e gás.

> Atenção: > - Este servidor MCP permite atualmente apenas conexão via Stdio (entrada/saída padrão). > - Foi testado e validado utilizando Cursor e GitHub Copilot no VSCode como MCP Clients.

Logs da Aplicação

Os logs do servidor MCP são salvos em arquivos na pasta logs do projeto (por padrão, logs/server.log e arquivos rotacionados).

> Motivo: > - Como a comunicação entre MCP Client e MCP Server é feita via Stdio (entrada/saída padrão), qualquer saída de log no console pode interferir na troca de mensagens entre cliente e servidor. > - Por isso, todos os logs são direcionados para arquivos, garantindo que a comunicação MCP funcione corretamente.

Para consultar os logs, basta abrir os arquivos na pasta logs com qualquer editor de texto ou usar comandos como:

cat logs/server.log

Os arquivos são rotacionados automaticamente para evitar crescimento excessivo.

📚 Documentação do Projeto

Este projeto possui uma documentação estruturada e específica para diferentes necessidades e públicos. Cada arquivo foi criado com um propósito específico para maximizar a produtividade e facilitar o entendimento do projeto.

🎯 Visão Geral dos Documentos

| Arquivo | Público Alvo | Propósito | Leitura | |---------|--------------|-----------|---------| | .cursorrules | Cursor AI | Contexto automático | Automática | | .github/copilot-instructions.md | GitHub Copilot | Instruções para VSCode | Automática | | .vscode/mcp.json | VSCode/Copilot | Configuração MCP | Manual/Automática | | QUICKSTART.md | Todos | Setup rápido | Primeiro acesso | | docs/DEVELOPMENT.md | Desenvolvedores | Padrões e arquitetura | Durante desenvolvimento | | docs/AI_CONTEXT.md | IAs/Cursor | Interação otimizada | Consulta automática | | README.md | Geral | Documentação completa | Referência |

---

🤖 .cursorrules - Contexto Automático para IA

Propósito: Arquivo lido automaticamente pelo Cursor para entender o contexto do projeto sem necessidade de explicações manuais.

Quando usar:

• ✅ Sempre - O Cursor lê automaticamente ao abrir o projeto
• ✅ Ao fazer perguntas sobre o projeto pela primeira vez
• ✅ Quando o Cursor precisa entender convenções específicas

Como será usado:

• Cursor: Lê automaticamente e mantém contexto durante toda a sessão
• Desenvolvedores: Consulta manual quando precisar entender convenções
• Novas IAs: Primeiro arquivo a ser consultado para contexto

Conteúdo:

• Estrutura do projeto e tecnologias
• Convenções de código (IDs, timestamps, logs)
• Comandos importantes
• Considerações específicas do MCP

Exemplo de uso:

Você: "Crie uma nova ferramenta MCP para monitorar tráfego"
Cursor: (lê .cursorrules) "Entendo que preciso seguir o padrão Zod, usar logs em arquivo, e registrar no server.ts..."

---

🆕 .github/copilot-instructions.md - Instruções para GitHub Copilot

Propósito: Arquivo de instruções específicas para GitHub Copilot no VSCode, fornecendo contexto detalhado do projeto.

Quando usar:

• 🎯 VSCode com Copilot - Lido automaticamente pelo GitHub Copilot
• 🔧 Desenvolvimento em VSCode - Para sugestões contextualizadas
• 📋 Padrões de código - Segue automaticamente as convenções do projeto

Como será usado:

• GitHub Copilot: Contexto automático para sugestões inteligentes
• VSCode: Integração nativa com o ambiente de desenvolvimento
• Desenvolvedores: Consulta para entender padrões específicos

Conteúdo:

• Contexto completo do projeto Smart Cities
• Convenções de desenvolvimento específicas
• Estrutura das ferramentas MCP implementadas
• Padrões para implementação de novas funcionalidades
• Instruções de validação e tratamento de erros

Exemplo de uso:

Você: Começa a digitar uma nova função MCP no VSCode
Copilot: (lê .github/copilot-instructions.md) Sugere automaticamente padrão Zod, timestamps UNIX, logs em arquivo

---

🔧 .vscode/mcp.json - Configuração MCP para VSCode

Propósito: Configuração específica do VSCode para conexão com o servidor MCP, otimizada para GitHub Copilot.

Quando usar:

• 🖥️ VSCode - Configuração automática do MCP
• 🤝 GitHub Copilot - Integração direta com as ferramentas
• ⚙️ Desenvolvimento - Setup automático do ambiente

Como será usado:

• VSCode: Carrega automaticamente as configurações MCP
• GitHub Copilot: Acesso direto às ferramentas do servidor
• Desenvolvedores: Setup simplificado sem configuração manual

Conteúdo:

• Configuração do servidor MCP para stdio
• Variáveis de ambiente seguras (com inputs)
• Caminho para o servidor compilado
• Configurações específicas do MongoDB

Exemplo de uso:

1. Abrir projeto no VSCode
2. VSCode detecta .vscode/mcp.json automaticamente
3. Solicita credenciais do MongoDB (primeira vez)
4. Copilot tem acesso às 13 ferramentas MCP

---

⚡ QUICKSTART.md - Guia de Início Rápido

Propósito: Colocar o projeto funcionando em menos de 5 minutos, sem precisar ler documentação extensa.

Quando usar:

• 🚀 Primeira vez que acessa o projeto
• 🔧 Problemas - quando algo não está funcionando
• 👥 Demonstrações - setup rápido para mostrar funcionando
• 🧪 Testes - validação rápida após mudanças
• 📅 Futuro - quando você esquecer como rodar (6 meses depois)

Como será usado:

• Novos desenvolvedores: Primeiro arquivo a ler
• Você mesmo: Referência rápida de comandos
• Demonstrações: Setup para clientes/colegas
• CI/CD: Base para scripts de automação

Conteúdo:

• 3 passos para setup completo
• Comandos de teste e validação
• Troubleshooting básico
• Prompts de exemplo prontos
• IDs e timestamps de referência
• NOVO: Configuração VSCode/Copilot

Exemplo de uso:

Cenário: Novo membro da equipe
1. Lê QUICKSTART.md (3 min)
2. Executa 3 comandos
3. Configura VSCode/Copilot
4. Testa com prompts prontos
5. Projeto funcionando ✅

---

🏗️ docs/DEVELOPMENT.md - Guia de Desenvolvimento

Propósito: Padrões de código, arquitetura e boas práticas para desenvolvimento e manutenção.

Quando usar:

• 🔨 Desenvolvimento ativo - ao escrever/modificar código
• 🏗️ Arquitetura - entender estrutura e design patterns
• ➕ Novas features - adicionar ferramentas MCP
• 🐛 Debugging - entender fluxo e logs
• 📖 Code review - verificar aderência aos padrões

Como será usado:

• Desenvolvedores: Consulta durante codificação
• Code reviews: Verificação de padrões
• Refatoração: Guia para manter consistência
• Onboarding: Entendimento técnico profundo

Conteúdo:

• Arquitetura detalhada do projeto
• Padrões de validação com Zod
• Estrutura de resposta MCP
• Convenções de paginação
• Como adicionar novas ferramentas
• Exemplos de código
• NOVO: Configuração VSCode e Copilot

Exemplo de uso:

Tarefa: Adicionar ferramenta de monitoramento de temperatura
1. Consulta DEVELOPMENT.md para padrões
2. Segue estrutura de validação Zod
3. Implementa paginação conforme exemplo
4. Registra no server.ts seguindo convenção
5. Testa com VSCode/Copilot

---

🧠 docs/AI_CONTEXT.md - Contexto para Interação com IA

Propósito: Otimizar interação entre humanos, IA e dados IoT com exemplos específicos e limitações conhecidas.

Quando usar:

• 💬 Prompts complexos - consultas avançadas de dados
• 📊 Análises - quando precisar de insights dos dados
• 🗺️ Consultas geográficas - dados por região
• ⏰ Dados temporais - análises históricas
• 🤔 Dúvidas sobre capacidades - o que é possível fazer

Como será usado:

• Cursor: Consultado automaticamente para prompts mais eficazes
• GitHub Copilot: Contexto para sugestões de código
• Usuários: Exemplos de como fazer perguntas
• Outras IAs: Contexto sobre estrutura de dados
• Desenvolvimento: Entender casos de uso comuns

Conteúdo:

• Exemplos de prompts naturais eficazes
• Estrutura detalhada dos dados
• Limitações e considerações de performance
• Cenários de uso comum
• Formatos de resposta esperados
• Dicas para melhor interação
• NOVO: Exemplos específicos para VSCode/Copilot

Exemplo de uso:

Você: "Quero analisar eficiência energética"
Cursor/Copilot: (consulta AI_CONTEXT.md) "Baseado nos exemplos, sugiro consultar consumo por período específico..."
Resultado: Prompt mais eficaz e dados mais relevantes

---

📖 README.md - Documentação Completa

Propósito: Documentação completa e oficial do projeto, referência principal para todas as informações.

Quando usar:

• 📚 Referência completa - informações detalhadas sobre todas as ferramentas
• 🔍 Busca específica - detalhes sobre parâmetros e respostas
• 📋 Documentação oficial - para links e referências externas
• 🎓 Aprendizado profundo - entender completamente o projeto
• 📝 Documentação para terceiros - material oficial

Como será usado:

• Referência oficial: Link para documentação externa
• Consulta detalhada: Quando QUICKSTART não é suficiente
• Integração: Informações para outros sistemas
• Treinamento: Material completo para equipe

Conteúdo:

• Todas as ferramentas MCP detalhadas
• Exemplos completos de uso
• Configuração detalhada
• NOVO: Integração com VSCode/Copilot
• Estrutura do banco de dados
• Limitações e considerações

---

🎯 Fluxo de Uso Recomendado

Para Primeiro Acesso:

1. QUICKSTART.md → Setup rápido e teste
2. Configurar VSCode → .vscode/mcp.json automático
3. README.md → Entendimento completo
4. docs/AI_CONTEXT.md → Exemplos de uso

Para Desenvolvimento:

1. .cursorrules → Contexto automático (Cursor)
2. .github/copilot-instructions.md → Contexto automático (VSCode/Copilot)
3. docs/DEVELOPMENT.md → Padrões e arquitetura
4. README.md → Referência de APIs

Para Uso Diário:

1. VSCode/Copilot → Integração automática com MCP
2. docs/AI_CONTEXT.md → Prompts eficazes
3. QUICKSTART.md → Comandos rápidos
4. README.md → Detalhes específicos

Para Problemas:

1. QUICKSTART.md → Troubleshooting básico
2. docs/DEVELOPMENT.md → Debugging avançado
3. Logs → logs/server.log
4. VSCode → Verificar configuração MCP

💡 Dicas de Produtividade

• Cursor Users: O .cursorrules e AI_CONTEXT.md trabalham juntos para dar contexto automático
• VSCode Users: O .github/copilot-instructions.md e .vscode/mcp.json fornecem integração completa
• Desenvolvimento: DEVELOPMENT.md evita quebrar convenções
• Demonstrações: QUICKSTART.md + configuração automática = setup em minutos
• Manutenção: Cada arquivo tem responsabilidade específica, facilitando atualizações

Configuração

Opção 1: VSCode com GitHub Copilot (Recomendado)

1. Instale as dependências:

npm install

1. Abra o projeto no VSCode:

code .

1. O VSCode detectará automaticamente o arquivo .vscode/mcp.json e solicitará a configuração do MongoDB

1. Inicie o banco de dados:

cd db-init && docker-compose up --build -d

1. Compile e inicie o servidor:

npm run build
npm start

Opção 2: Cursor (Tradicional)

1. Instale as dependências:

npm install

1. Configure as variáveis de ambiente (opcional):

MONGO_URI=mongodb://cursor-mcp-client:cursor-mcp-password@localhost:27017/smart_city_iot

1. Inicie o servidor:

npm start

Ferramentas Disponíveis

1. Listar Dispositivos de Iluminação

listLightingDevices({
    region?: string,    // Filtro opcional por região (nome ou busca geoespacial)
    status?: string,    // Filtro opcional por status
    geoJson?: boolean  // Se true, retorna FeatureCollection GeoJSON
})

• Retorna uma lista de dispositivos de iluminação pública.
• Se region for fornecida, filtra por proximidade geográfica (usando coordenadas e polígono da região).
• Se geoJson=true, retorna no formato GeoJSON (FeatureCollection).

Exemplos de prompts:

• "Liste todos os dispositivos de iluminação na região Sudeste"
• "Me retorne os dispositivos de iluminação próximos ao Centro-Oeste em GeoJSON"
• "Quais dispositivos de iluminação estão ativos no Sul?"
• "Me dê um GeoJSON dos dispositivos de iluminação do Nordeste"

2. Consultar Telemetria de Iluminação

getLightingTelemetry({
    deviceId: string,   // ID do dispositivo
    startTime: number,  // Timestamp inicial (UNIX)
    endTime: number     // Timestamp final (UNIX)
})

Retorna dados de telemetria de um dispositivo específico em um período, incluindo:

• Temperatura
• Estado (ligado/desligado)
• Corrente
• Tensão
• Energia acumulada
• Fator de potência
• Nível de iluminação
• Consumo de potência
• Horas de operação

3. Analisar Consumo de Energia

analyzeEnergyConsumption({
    deviceId: string,   // ID do dispositivo
    startTime: number,  // Timestamp inicial (UNIX)
    endTime: number     // Timestamp final (UNIX)
})

Retorna análise detalhada do consumo de energia:

• Energia total consumida
• Potência média
• Potência máxima
• Potência mínima

4. Detectar Vazamentos de Água

detectWaterLeaks({
    startTime: number,  // Timestamp inicial (UNIX)
    endTime: number     // Timestamp final (UNIX)
})

Retorna todos os registros de vazamentos detectados no período, incluindo:

• ID do dispositivo
• Localização
• Vazão
• Pressão
• Temperatura
• Consumo

5. Analisar Consumo de Gás

analyzeGasConsumption({
    region: string,     // Nome da região
    startTime: number,  // Timestamp inicial (UNIX)
    endTime: number     // Timestamp final (UNIX)
})

Retorna análise detalhada do consumo de gás por região:

• Consumo total
• Vazão média
• Número de vazamentos detectados

🚀 Ferramentas Avançadas (Novas)

6. Estatísticas Regionais Comparativas

getRegionalStatistics({
    startTime: number,      // Timestamp inicial (UNIX)
    endTime: number,        // Timestamp final (UNIX)
    includeComparison?: boolean  // Se true, inclui comparações entre regiões
})

Retorna estatísticas detalhadas comparativas entre todas as regiões:

• Consumo de energia, água e gás por região
• Métricas de performance e eficiência
• Contagem de dispositivos e vazamentos
• Análise de uptime e confiabilidade

7. Relatório de Saúde dos Dispositivos

getDeviceHealthReport({
    deviceType?: 'lighting' | 'water' | 'gas' | 'all',  // Tipo de dispositivo
    region?: string,        // Filtro por região
    healthThreshold?: number // Limiar de saúde (0-100)
})

Retorna análise detalhada da "saúde" dos dispositivos:

• Score de saúde calculado (0-100)
• Métricas específicas por tipo de dispositivo
• Dispositivos que precisam de manutenção
• Predição de tempo de vida útil

8. Dashboard Completo da Cidade

getCityDashboard({
    timeRange?: 'hour' | 'day' | 'week' | 'month',  // Período de análise
    includeAlerts?: boolean  // Se true, inclui alertas inteligentes
})

Retorna visão geral completa da cidade:

• Estatísticas gerais de todos os sistemas
• Resumo de consumos e eficiência
• Alertas críticos, avisos e informativos
• KPIs principais da cidade inteligente

9. Predição de Manutenção

predictMaintenance({
    deviceType?: 'lighting' | 'water' | 'gas' | 'all',  // Tipo de dispositivo
    predictionDays?: number,    // Dias para predição (1-90)
    riskThreshold?: number      // Limiar de risco (0-100)
})

Retorna predições baseadas em machine learning:

• Dispositivos em risco de falha
• Score de risco de manutenção
• Dias estimados até falha
• Manutenção urgente vs preventiva

10. Detecção de

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wesleyribeirobarbosa
• Source: wesleyribeirobarbosa/mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.