PI API MCP Server

Instructions

Implementation Reference

• build/index.js:350-390 (registration)

  Registration of the 'authenticate' tool including its inline handler function. This tool serves as a guide, checking if already authenticated and providing instructions for token-based or credentials-based authentication.
  server.tool("authenticate", "Guide for authenticating with the PI API", {}, async () => { try { // Check if already authenticated successfully if (authToken && await verifyConnection()) { return { content: [{ type: "text", text: "✅ You are already authenticated and your token is valid. You can use the API without further authentication." }] }; } // Check if API URL is set if (!apiUrlSet) { return { isError: true, content: [{ type: "text", text: "API URL not set. Please set the API URL first using the set-api-url tool." }] }; } return { content: [{ type: "text", text: "Authentication options:\n\n" + "1. If you have a token (strongly preferred):\n" + " - Use the keep-session-alive tool with your token\n" + " - This will verify and set your token in one step\n\n" + "2. If you don't have a token (last resort):\n" + " - Use the authenticate-with-credentials tool\n" + " - Format: authenticate-with-credentials with \"username password\"" }] }; } catch (error) { return { isError: true, content: [{ type: "text", text: `Error during authentication guide: ${getErrorMessage(error)}` }] }; } });
• build/index.js:144-162 (helper)

  Helper function verifyConnection() used by the authenticate tool to check if the current authentication is valid.
  async function verifyConnection() { if (!apiUrlSet || !API_BASE_URL) { return false; } if (!authToken) { return false; } try { // Try a lightweight request to verify the connection await authenticatedRequest("/tokens/keepAlive", "POST"); connectionVerified = true; return true; } catch (error) { logError(`Connection verification failed: ${getErrorMessage(error)}`); connectionVerified = false; return false; } }
• build/index.js:57-125 (helper)

  Core helper function for making authenticated API requests, used throughout including by verifyConnection which supports the authenticate tool.
  async function authenticatedRequest(endpoint, method = "GET", body = null, queryParams = {}) { if (!apiUrlSet) { throw new Error("API URL not set. Please set the API URL using the set-api-url tool."); } if (!authToken) { throw new Error("Not authenticated. Please authenticate first."); } // Build URL with query parameters let url = `${API_BASE_URL}${endpoint}`; // Add orgId if available if (orgId !== null) { queryParams.orgId = orgId.toString(); } // Add query parameters if any if (Object.keys(queryParams).length > 0) { const queryString = Object.entries(queryParams) .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`) .join("&"); url = `${url}?${queryString}`; } logInfo(`Making ${method} request to ${url}`); const headers = { "Authorization": `bearer ${authToken}`, "Content-Type": "application/json" }; const options = { method, headers }; if (body !== null && ["POST", "PUT"].includes(method)) { options.body = JSON.stringify(body); logInfo(`Request body: ${JSON.stringify(body)}`); } try { const response = await fetch(url, options); if (!response.ok) { const errorText = await response.text(); logError(`API request failed with status ${response.status}: ${errorText}`); throw new Error(`API request failed with status ${response.status}: ${response.statusText}`); } // Check if the response is JSON or binary const contentType = response.headers.get("content-type") || ""; if (contentType.includes("application/json")) { const jsonData = await response.json(); logInfo(`Received JSON response: ${JSON.stringify(jsonData).substring(0, 200)}...`); return jsonData; } else if (contentType.includes("text/csv")) { // For binary/file responses, return a base64 encoded string const buffer = await response.arrayBuffer(); const base64 = Buffer.from(buffer).toString("base64"); logInfo(`Received binary response of type ${contentType}, length: ${base64.length}`); return { contentType, data: base64 }; } else { // Otherwise, return as text const text = await response.text(); logInfo(`Received text response: ${text.substring(0, 200)}...`); return text; } } catch (error) { logError(`API request error: ${getErrorMessage(error)}`); throw error; } }