PI API MCP Server

Un servidor MCP para interactuar con la API de PI Dashboard.

Documentación

Servidor MCP de PI API

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona herramientas y recursos estandarizados para interactuar con la API del Panel de PI. Esta implementación permite a Claude y otros asistentes de IA compatibles con MCP acceder y gestionar de forma segura los recursos del Panel de PI, incluyendo categorías y gráficos.

Utilizando PI con MCP

A continuación se muestran escenarios de uso típicos para este Servidor MCP después de completar la configuración.

Autenticación inicial:

Ejecute las siguientes instrucciones para establecer una conexión:

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álisis de gráficos:

Si el gráfico con ID 450 contiene información de metadatos, use el siguiente mensaje:

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

Ejemplo de salida:

Instalación

Instalación mediante Smithery

Para instalar pi-api-mcp-server para Claude Desktop automáticamente a través de Smithery:

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

Instalación - Usando Docker (Recomendado)

No se necesita configuración del Servidor MCP
Configuración del archivo del 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: Si el parámetro --api-url no se proporciona en la inicialización, el servidor le solicitará configurar la URL de la API usando la herramienta set-api-url antes de ejecutar cualquier operación. Este diseño permite una configuración flexible en entornos donde la URL no está predeterminada al inicio.

Ubicación del Archivo de Configuración

Acceda a la configuración de la aplicación Claude for Desktop en:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: Use otras herramientas por ahora. Por ejemplo, Cline - pídale que le muestre el archivo de configuración de MCP

Herramientas Disponibles

Descubrimiento de Esquema

get-filterable-attributes: Obtenga la lista de atributos que se pueden usar para filtrar examinando una entidad de muestra
```
Get the filterable attributes for chart entities
```

Gestión de Conexión

check-connection: Verifique si la URL de la API actual y la autenticación son válidas
set-api-url: Configure la URL base de la API para todas las solicitudes
```
Set the API URL to http://localhost:8224/pi/api/v2
```

Autenticación

authenticate: Obtenga orientación sobre las opciones de autenticación
authenticate-with-credentials: Autentíquese con nombre de usuario y contraseña (opción de último recurso)
keep-session-alive: Verifique y actualice el token de autenticación actual (también se usa para autenticación basada en tokens)
logout: Invalide el token actual y finalice la sesión
set-organization: Establezca el ID de organización para solicitudes posteriores

Gráficos

list-charts: Liste todos los gráficos con soporte de filtrado
get-chart: Obtenga un gráfico por ID
delete-chart: Elimine un gráfico
export-chart: Exporte un gráfico en varios formatos

Recursos Disponibles

auth://status: Obtenga el estado de autenticación
categories://list: Liste todas las categorías
categories://{id}: Obtenga una categoría específica
categories://{categoryId}/objects: Obtenga objetos de una categoría específica
charts://list: Liste todos los gráficos
charts://{id}: Obtenga un gráfico específico
charts://{id}/export/{format}: Exporte un gráfico en un formato específico

Mensajes Disponibles

analyze-categories: Analice categorías en el panel
analyze-charts: Analice gráficos en el panel
compare-charts: Compare datos entre dos gráficos
category-usage-analysis: Analice cómo se utilizan las categorías en los gráficos
use-filters: Muestra cómo usar los filtros de manera efectiva con esta API

Ejemplos de Integración con Claude

Aquí hay algunas consultas de ejemplo para usar con Claude después de conectar el servidor:

Establecer la URL de la API

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

Autenticación

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.

Trabajando con Categorías

List all categories in the dashboard.

Get details about category with ID 123.

Trabajando con 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 Mensajes de Análisis

Analyze the categories in the dashboard.

Compare data between charts 123 and 456.

Show me how to use filters effectively with this API.

Desarrollo

Ejecución Local

Nota: también puede usar start.sh para ejecutar el servidor de desarrollo.

# 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

Instalación mediante 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"

Configuración del Cliente MCP

Integración con Claude for Desktop:

Implementación en Node.js

Ejecute las instrucciones de la sección "Ejecución Local"
Asegúrese de que ./dependencies.sh se haya ejecutado para instalar las dependencias requeridas
Implemente la siguiente configuración (Nota: "@mingzilla/pi-api-mcp-server" hace referencia al paquete instalado mediante "Ejecución 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"
      ]
    }
  }
}

Desarrollo Local

ejecute el servidor usando ./start.sh
configure la configuración con la ruta al archivo 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 Verificación de Desarrollo

actualice el código -> inicie el servidor local -> pruebe el servidor local con la ruta del archivo a index.js
actualice el archivo readme.md -> cambie la sección de configuración de mcpServers: docker + node + npx
./publish.sh - publique en npm
./dockerBuild.sh -> ./dockerPublish.sh (edite el número de versión para que coincida con package.json) -> pruebe la configuración de docker
envíe el código a github

Licencia

Licencia MIT

Autor

Ming Huang (mingzilla)