APsystems MCP Server

APsystems MCP Server ☀️🛰️

Um servidor Model Context Protocol (MCP) pronto para produção, escrito em Go, que encapsula a APsystems OpenAPI, dando a assistentes de IA como o Claude acesso direto aos seus dados de monitoramento solar. Inclui um painel web opcional para monitoramento visual.

Sumário

• APsystems MCP Server ☀️🛰️
  • Sumário
  • Recursos
  • Início Rápido
    • 🚀 Pré-requisitos
    • Instalação e Execução
    • Com Transporte SSE
    • Com Painel
  • Demonstração do Painel
    • iniciar com Podman
  • Tabela de Variáveis de Ambiente
  • Segurança
  • Referência de Ferramentas MCP
    • Ferramentas do Sistema
    • Ferramentas ECU
    • Ferramentas do Inversor
    • Ferramentas do Medidor
    • Ferramentas de Armazenamento
  • Usando com Claude Desktop
  • Usando com Claude CLI
    • 1. Inicie o Servidor MCP
    • 2. Configure o Claude CLI
    • 3. Exemplo de Uso
  • Estrutura do Projeto
  • Detalhes de Autenticação
  • Desenvolvimento
  • Códigos de Erro da API
  • Solução de Problemas
  • Comunidade e Suporte
  • Contribuindo
  • Links Rápidos

Recursos

• 16 ferramentas MCP cobrindo todos os endpoints da API APsystems: detalhes do sistema, resumos de energia, dados de ECU/inversor/medidor/armazenamento
• Autenticação por assinatura HMAC-SHA256 — implementa o protocolo de assinatura da APsystems
• Painel web integrado — aplicativo de página única com tema escuro e visualizações de energia com Chart.js
• Limitação de taxa — controle de requisições configurável para respeitar os limites da API
• Tentativas automáticas — back-off exponencial em erros transitórios e respostas de limite de taxa
• Transporte duplo — stdio (padrão) ou SSE via HTTP, selecionável por variável de ambiente
• Registro estruturado — logs JSON via slog com níveis configuráveis
• Suporte a Podman — Containerfile multi-estágio para imagens de produção mínimas
• CI/CD — GitHub Actions para testes, linting e lançamentos multiplataforma

Início Rápido

🚀 Pré-requisitos

Antes de começar, certifique-se de ter:

• 🦫 Go (versão mais recente recomendada)
• 🔑 Credenciais da APsystems OpenAPI (APP_ID e APP_SECRET)
• 🆔 ID do Sistema (SID) — Encontre-o no aplicativo APsystems EMA em Settings → Account Details

Instalação e Execução

git clone https://github.com/mjrgr/apsystems-mcp-server.git
cd mcp-server

# Install dependencies
go mod tidy

# Set credentials
export APS_SYS_ID="your_fake_sid_1234567890"
export APS_APP_ID="your_fake_app_id_32charslong1234567890abcd"
export APS_APP_SECRET="your_fake_secret12"

# Build and run
go run ./cmd/server

Com Transporte SSE

Por padrão, o servidor usa stdio (entrada/saída padrão) para comunicação MCP. Defina APS_MCP_TRANSPORT=sse para iniciar um servidor HTTP com Server-Sent Events:

export APS_MCP_TRANSPORT=sse
export APS_MCP_SSE_ADDR=:8888     # optional, defaults to :8888
go run ./cmd/server
# SSE endpoint: http://localhost:8888/sse
# Message endpoint: http://localhost:8888/message

Isso é útil quando você deseja conectar clientes MCP remotos via HTTP em vez de executar o servidor como um processo filho.

Com Painel

export APS_DASHBOARD=true
export APS_DASH_ADDR=:8080
go run ./cmd/server
# Dashboard available at http://localhost:8080

Demonstração do Painel

iniciar com Podman

podman build -t apsystems-mcp -f Containerfile .
podman run --rm \
  -e APS_SYS_ID="your_fake_sid_1234567890" \
  -e APS_APP_ID="your_fake_app_id_32charslong1234567890abcd" \
  -e APS_APP_SECRET="your_fake_secret12" \
  -e APS_DASHBOARD=true \
  -p 8080:8080 \
  apsystems-mcp

Para executar com transporte SSE em vez de stdio:

podman run --rm \
  -e APS_SYS_ID="your_fake_sid_1234567890" \
  -e APS_APP_ID="your_fake_app_id_32charslong1234567890abcd" \
  -e APS_APP_SECRET="your_fake_secret12" \
  -e APS_MCP_TRANSPORT=sse \
  -e APS_MCP_SSE_ADDR=:8888 \
  -e APS_DASHBOARD=true \
  -p 8888:8888 -p 8080:8080 \
  apsystems-mcp
# SSE endpoint: http://localhost:8888/sse

Tabela de Variáveis de Ambiente

Segurança

🔒 Boas Práticas de Segurança

• Nunca envie credenciais ou segredos reais de API para o controle de versão. Use .env.local ou variáveis de ambiente para desenvolvimento local.
• Rotacione seu APP_SECRET e SID se suspeitar que foram comprometidos.
• Reporte vulnerabilidades abrindo uma issue de segurança ou enviando e-mail aos mantenedores.
• Para produção, use um gerenciador de segredos ou injeção de ambiente (não arquivos em texto puro).

Referência de Ferramentas MCP

Ferramentas do Sistema

Ferramentas ECU

Ferramentas do Inversor

Ferramentas do Medidor

Ferramentas de Armazenamento

Usando com Claude Desktop

Usando com Claude CLI

Você também pode conectar este servidor MCP ao Claude CLI para acesso direto e scriptável aos seus dados solares a partir do terminal.

1. Inicie o Servidor MCP

Certifique-se de que seu servidor MCP esteja em execução e acessível (local ou remotamente):

go run ./cmd/server
# or with Podman/Docker as shown above

2. Configure o Claude CLI

Adicione seu servidor MCP ao Claude CLI usando o comando integrado:

claude mcp add apsystems -s local -- podman run -i --rm -p 8888:8080 -e APS_DASHBOARD=true -e APS_SYS_ID=your_fake_sid_1234567890 -e APS_APP_ID=your_fake_app_id_32charslong1234567890abcd -e APS_APP_SECRET=your_fake_secret12 docker.io/mehdijrgr/apsystems-mcp-server 2>&1

claude mcp add apsystems -s local -- docker  run -i --rm -p 8888:8080 -e APS_DASHBOARD=true -e APS_SYS_ID=your_fake_sid_1234567890 -e APS_APP_ID=your_fake_app_id_32charslong1234567890abcd -e APS_APP_SECRET=your_fake_secret12 docker.io/mehdijrgr/apsystems-mcp-server 2>&1

Isso atualizará automaticamente a configuração do seu Claude CLI para incluir o servidor MCP apsystems.

3. Exemplo de Uso

Peça ao Claude CLI para consultar seus dados solares via servidor MCP:

claude ask "Show me my solar production for today"

Ou use qualquer ferramenta MCP suportada, por exemplo:

claude ask "List all my inverters"

claude ask "what's the average monthly solar production?"

Você pode criar scripts e automatizar consultas, integrar com outras ferramentas ou usar o Claude CLI em seus fluxos de trabalho!

Para usar o Claude Desktop com Docker ou Podman, atualize seu claude_desktop_config.json da seguinte forma:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "aps_sys_id",
      "description": "APsystems System ID"
    },
    {
      "type": "promptString",
      "id": "aps_app_id",
      "description": "APsystems App ID"
    },
    {
      "type": "promptString",
      "id": "aps_app_secret",
      "description": "APsystems App Secret",
      "password": true
    }
  ],
  "mcpServers": {
    "apsystems": {
      "command": "podman",
      "args": [
        "run", "-i", "--rm", "-p", "8888:8080",
        "-e", "APS_DASHBOARD=true",
        "-e", "APS_SYS_ID=${input:aps_sys_id}",
        "-e", "APS_APP_ID=${input:aps_app_id}",
        "-e", "APS_APP_SECRET=${input:aps_app_secret}",
        "docker.io/mehdijrgr/apsystems-mcp-server"
      ]
    }
  }
}

Ou para Docker:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "aps_sys_id",
      "description": "APsystems System ID"
    },
    {
      "type": "promptString",
      "id": "aps_app_id",
      "description": "APsystems App ID"
    },
    {
      "type": "promptString",
      "id": "aps_app_secret",
      "description": "APsystems App Secret",
      "password": true
    }
  ],
  "mcpServers": {
    "apsystems": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-p", "8888:8080",
        "-e", "APS_DASHBOARD=true",
        "-e", "APS_SYS_ID=${input:aps_sys_id}",
        "-e", "APS_APP_ID=${input:aps_app_id}",
        "-e", "APS_APP_SECRET=${input:aps_app_secret}",
        "docker.io/mehdijrgr/apsystems-mcp-server"
      ]
    }
  }
}

Para transporte SSE (modo remoto/rede), use o campo url em vez de command:

{
  "mcpServers": {
    "apsystems": {
      "url": "http://localhost:8888/sse"
    }
  }
}

Você também pode montar um arquivo de configuração ou credenciais conforme necessário:

{
  "mcpServers": {
    "apsystems": {
      "command": "podman run -i --rm --env-file /path/to/env.local mehdijrgr/apsystems-mcp-server 2>&1",
      "env": {}
    }
  }
}

Então pergunte ao Claude coisas como:

• "Mostre-me minha produção solar de hoje"
• "Quanta energia meu sistema produziu este mês?"
• "Qual é o status dos meus inversores?"
• "Compare minha produção diária desta semana"

Estrutura do Projeto

├── cmd/server/          # CLI entry point
├── internal/
│   ├── api/             # HTTP client with auth, retries, rate limiting
│   ├── auth/            # HMAC-SHA256 signature implementation
│   ├── dashboard/       # Optional web UI (embedded HTML)
│   ├── mcp/             # MCP tool definitions and handlers
│   └── models/          # Go structs for API responses
├── .devcontainer/       # VS Code dev container config
├── .github/workflows/   # CI/CD pipelines
├── .vscode/             # Editor settings and launch configs
├── Containerfile        # Multi-stage Podman/OCI build
├── Makefile             # Build, test, lint targets
└── go.mod

Detalhes de Autenticação

A API da APsystems usa autenticação por assinatura HMAC. Cada requisição inclui cinco cabeçalhos personalizados:

1. X-CA-AppId — seu identificador de aplicativo
2. X-CA-Timestamp — timestamp Unix em milissegundos
3. X-CA-Nonce — string hexadecimal única de 32 caracteres (UUID sem hífens)
4. X-CA-Signature-Method — HmacSHA256
5. X-CA-Signature — Base64(HMAC-SHA256(stringToSign, appSecret))

A string a ser assinada é composta por:

timestamp/nonce/appId/requestPath/HTTPMethod/HmacSHA256

onde requestPath é o último segmento do caminho da URL.

Desenvolvimento

# Run tests
make test

# Lint
make lint

# Build for all platforms
make build

Códigos de Erro da API

Solução de Problemas

ℹ️ Nota: Se você encontrar erros de API, verifique se suas credenciais (APP_ID, APP_SECRET, SID) estão corretas e se sua conta tem acesso à API habilitado. Se você vir erros de limite de taxa, tente novamente mais tarde ou ajuste a frequência das suas requisições.

• P: Recebo erros de 'Não autorizado' ou 'Conta de aplicativo inválida'.
  • R: Verifique novamente seu APP_ID, APP_SECRET e SID. Certifique-se de que sua conta foi aprovada para acesso à API pela APsystems.
• P: O Claude CLI não consegue se conectar ao servidor MCP.
  • R: Certifique-se de que o servidor está em execução e que o endereço/porta corresponde à configuração do seu CLI. Verifique o firewall ou os mapeamentos de porta do contêiner.
• P: O painel não carrega.
  • R: Certifique-se de que APS_DASHBOARD está definido como true e que o servidor está em execução. Acesse a porta correta no seu navegador.

Comunidade e Suporte

• GitHub Issues — para relatórios de bugs e solicitações de recursos
• Discussions — para perguntas e respostas, ideias e ajuda da comunidade
• E-mail: support@apsystems.com (para solicitações de credenciais de API)

Contribuindo

Contribuições são bem-vindas! Para começar:

1. Faça um fork do repositório
2. Crie um novo branch para sua funcionalidade ou correção
3. Faça suas alterações e adicione testes se necessário
4. Abra um pull request com uma descrição clara

Consulte CONTRIBUTING.md se disponível, ou abra uma issue para discutir mudanças importantes primeiro.

Links Rápidos

• 📚 Documentação
• Referência da API
• Issues Abertas
• Discussões
• Versões
• Licença