PI API MCP Server

Um servidor MCP para interagir com a API do PI Dashboard.

GitHub
8
Experimente este MCPPatrocinado

Documentação

Servidor MCP da API PI

smithery badge

Um servidor Model Context Protocol (MCP) que fornece ferramentas e recursos padronizados para interagir com a API do Painel PI. Esta implementação permite que o Claude e outros assistentes de IA compatíveis com MCP acessem e gerenciem com segurança os recursos do Painel PI, incluindo categorias e gráficos.

Utilizando PI com MCP

O seguinte demonstra cenários de uso típicos para este Servidor MCP após a conclusão da configuração.

Autenticação Inicial:

  • Execute as seguintes instruções para estabelecer uma conexão:
Ensure the PI API MCP server is running
Set the API URL to http://localhost:8224/pi/api/v2
Use the authenticate tool for authentication guidance
Check the connection status to verify everything is working
List two charts from the dashboard

Análise de Gráficos:

  • Se o gráfico ID 450 contiver informações de metadados, use o seguinte prompt:
Retrieve the metadata from chart ID 450
Extract the chart JSON data from ID 450
Identify chart IDs associated with claims
Obtain JSON data for the identified charts
Analyze the data to generate actionable insights

Exemplo de Saída:

example-response.png

Instalação

Instalando via Smithery

Para instalar o pi-api-mcp-server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @mingzilla/pi-api-mcp-server --client claude

Instalação - Usando Docker (Recomendado)

  • Nenhuma configuração do Servidor MCP necessária
  • Configuração do arquivo do cliente MCP:
{
  "mcpServers": {
    "pi-api": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_URL=http://localhost:8224/pi/api/v2",
        "-e",
        "PI_API_KEY=XXXXXXXX",
        "mingzilla/pi-api-mcp-server"
      ],
      "disabled": false,
      "autoApprove": [
        "keep-session-alive",
        "check-connection",
        "authenticate",
        "list-categories",
        "get-category",
        "list-charts", 
        "get-chart",
        "export-chart",
        "get-filterable-attributes",
        "export-chart"
      ]
    }
  }
}

Nota Importante: Se o parâmetro --api-url não for fornecido na inicialização, o servidor solicitará que você configure a URL da API usando a ferramenta set-api-url antes de executar qualquer operação. Este design permite configuração flexível em ambientes onde a URL não é predeterminada na inicialização.

Localização do Arquivo de Configuração

Acesse a configuração do aplicativo Claude for Desktop em:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: Use outras ferramentas por enquanto. Ex.: Cline - peça para mostrar o arquivo de configuração MCP

Ferramentas Disponíveis

Descoberta de Esquema

  • get-filterable-attributes: Obtenha a lista de atributos que podem ser usados para filtragem examinando uma entidade de exemplo 
    Get the filterable attributes for chart entities

Gerenciamento de Conexão

  • check-connection: Verifique se a URL da API atual e a autenticação são válidas
  • set-api-url: Configure a URL base da API para todas as solicitações 
    Set the API URL to http://localhost:8224/pi/api/v2

Autenticação

  • authenticate: Obtenha orientação sobre opções de autenticação
  • authenticate-with-credentials: Autentique com nome de usuário e senha (opção de último recurso)
  • keep-session-alive: Verifique e atualize o token de autenticação atual (também usado para autenticação baseada em token)
  • logout: Invalide o token atual e encerre a sessão
  • set-organization: Defina o ID da organização para solicitações subsequentes

Categorias

  • list-categories: Liste todas as categorias com suporte a filtros
  • get-category: Obtenha uma categoria por ID
  • create-category: Crie uma nova categoria
  • update-category: Atualize uma categoria existente
  • delete-category: Exclua uma categoria
  • list-category-objects: Liste todos os objetos de uma categoria específica

Gráficos

  • list-charts: Liste todos os gráficos com suporte a filtros
  • get-chart: Obtenha um gráfico por ID
  • delete-chart: Exclua um gráfico
  • export-chart: Exporte um gráfico em vários formatos

Recursos Disponíveis

  • auth://status: Obtenha o status da autenticação
  • categories://list: Liste todas as categorias
  • categories://{id}: Obtenha uma categoria específica
  • categories://{categoryId}/objects: Obtenha objetos de uma categoria específica
  • charts://list: Liste todos os gráficos
  • charts://{id}: Obtenha um gráfico específico
  • charts://{id}/export/{format}: Exporte um gráfico em um formato específico

Prompts Disponíveis

  • analyze-categories: Analise categorias no painel
  • analyze-charts: Analise gráficos no painel
  • compare-charts: Compare dados entre dois gráficos
  • category-usage-analysis: Analise como as categorias estão sendo usadas nos gráficos
  • use-filters: Mostra como usar filtros de forma eficaz com esta API

Exemplos de Integração com Claude

Aqui estão alguns exemplos de consultas para usar com o Claude após conectar o servidor:

Definir a URL da API

Please use the set-api-url tool to set the PI API URL to http://localhost:8224/pi/api/v2

Autenticação

Please help me authenticate to the PI API.

I have a token. Please use the keep-session-alive tool with my token: [YOUR_TOKEN_HERE]

Please check if my connection to the PI API is working properly.

Trabalhando com Categorias

List all categories in the dashboard.

Get details about category with ID 123.

Trabalhando com Gráficos

List all the charts available in the dashboard.

Export chart with ID 456 as a PDF.

Usando Filtros

Get the filterable attributes for chart entities to understand what fields I can filter on.

List charts with description containing "revenue" using the filter option.

Usando Prompts de Análise

Analyze the categories in the dashboard.

Compare data between charts 123 and 456.

Show me how to use filters effectively with this API.

Desenvolvimento

Execução Local

  • Nota: você pode usar start.sh para executar o servidor de desenvolvimento também.
# Clone the repository (SSH or HTTPS option)
git clone git@github.com:mingzilla/pi-api-mcp-server.git
cd pi-api-mcp-server

# Install dependencies
npm install
./dependencies.sh # Installs global dependencies to enable MCP client connection via "@mingzilla/pi-api-mcp-server"

# Build the project
npm run build

# Execute the server
npm start

Instalação via NPM

# Global installation
npm install -g @mingzilla/pi-api-mcp-server

# Direct execution via npx
npx @mingzilla/pi-api-mcp-server --api-url "http://localhost:8224/pi/api/v2" --auth-token "XXXXXXXX"

Configuração do Cliente MCP

Integração com Claude for Desktop:

Implementação Node.js

  • Execute as instruções na seção "Execução Local"
  • Certifique-se de que ./dependencies.sh foi executado para instalar as dependências necessárias
  • Implemente a seguinte configuração (Nota: "@mingzilla/pi-api-mcp-server" referencia o pacote instalado através da "Execução Local")
{
  "mcpServers": {
    "pi-api": {
      "command": "npx",
      "args": [
        "-y",
        "@mingzilla/pi-api-mcp-server",
        "--api-url",
        "http://localhost:8224/pi/api/v2",
        "--auth-token",
        "XXXXXXXX"
      ],
      "autoApprove": [
        "keep-session-alive",
        "check-connection",
        "authenticate",
        "list-categories",
        "get-category",
        "list-charts",
        "get-chart",
        "export-chart",
        "get-filterable-attributes",
        "export-chart"
      ]
    }
  }
}

Desenvolvimento Local

  • execute o servidor usando ./start.sh
  • defina a configuração com o caminho para o arquivo build/index.js
./start.sh

{
  "mcpServers": {
    "pi-api": {
      "command": "node",
      "args": [
        "/home/mingzilla/dev/tool-mcp-pi-api-server/build/index.js",
        "--api-url",
        "http://localhost:8224/pi/api/v2",
        "--auth-token",
        "XXXXXXXX"
      ],
      "autoApprove": [
        "keep-session-alive",
        "check-connection",
        "authenticate",
        "list-categories",
        "get-category",
        "list-charts",
        "get-chart",
        "export-chart",
        "get-filterable-attributes",
        "export-chart"
      ]
    }
  }
}

Lista de Verificação de Desenvolvimento

  • atualize o código -> inicie o servidor local -> teste o servidor local com o caminho do arquivo para index.js
  • atualize o arquivo readme.md -> altere a seção de configuração do mcpServers: docker + node + npx
  • ./publish.sh - publique no npm
  • ./dockerBuild.sh -> ./dockerPublish.sh (edite o número da versão para corresponder ao package.json) -> teste a configuração docker
  • envie o código para o github

Licença

Licença MIT

Autor

Ming Huang (mingzilla)

Verified on MseeP

smithery badge