PI API MCP Server

Instructions

Implementation Reference

• build/index.js:392-457 (registration)

  Full registration of the 'keep-session-alive' tool, including name, description, input schema, and inline handler function that verifies/sets auth token via /tokens/keepAlive API call.

  server.tool("keep-session-alive", "Verify and refresh the current authentication token (also used for token-based authentication)", {
      token: z.string().optional().describe("Optional: Provide a token to use for authentication")
  }, async ({ token }) => {
      try {
          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."
                      }]
              };
          }
          // If a token is provided, use it instead of the current one
          const originalToken = authToken;
          if (token) {
              authToken = token;
              logInfo("Token provided via keep-session-alive tool");
          }
          if (!authToken) {
              return {
                  isError: true,
                  content: [{
                          type: "text",
                          text: "No token available. Please provide a token or authenticate with credentials."
                      }]
              };
          }
          try {
              // Try to keep the session alive
              await authenticatedRequest("/tokens/keepAlive", "POST");
              connectionVerified = true;
              // If we got here, the token is valid
              return {
                  content: [{
                          type: "text",
                          text: token
                              ? "✅ Token validated and set successfully. You are now authenticated."
                              : "✅ Session kept alive successfully. Your token is valid."
                      }]
              };
          }
          catch (error) {
              // If validation fails and we were using a provided token, restore the original
              if (token) {
                  authToken = originalToken;
              }
              connectionVerified = false;
              return {
                  isError: true,
                  content: [{
                          type: "text",
                          text: token
                              ? `❌ The provided token is invalid or expired: ${getErrorMessage(error)}\nPlease try with another token or use authenticate-with-credentials.`
                              : `❌ Your session token is invalid or expired: ${getErrorMessage(error)}\nPlease authenticate again.`
                      }]
              };
          }
      }
      catch (error) {
          return {
              isError: true,
              content: [{ type: "text", text: `Error keeping session alive: ${getErrorMessage(error)}` }]
          };
      }
  });

• build/index.js:394-457 (handler)

  Handler function that optionally sets a new token, verifies it by POST to /tokens/keepAlive, updates global auth state, and returns success/error messages.

  }, async ({ token }) => {
      try {
          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."
                      }]
              };
          }
          // If a token is provided, use it instead of the current one
          const originalToken = authToken;
          if (token) {
              authToken = token;
              logInfo("Token provided via keep-session-alive tool");
          }
          if (!authToken) {
              return {
                  isError: true,
                  content: [{
                          type: "text",
                          text: "No token available. Please provide a token or authenticate with credentials."
                      }]
              };
          }
          try {
              // Try to keep the session alive
              await authenticatedRequest("/tokens/keepAlive", "POST");
              connectionVerified = true;
              // If we got here, the token is valid
              return {
                  content: [{
                          type: "text",
                          text: token
                              ? "✅ Token validated and set successfully. You are now authenticated."
                              : "✅ Session kept alive successfully. Your token is valid."
                      }]
              };
          }
          catch (error) {
              // If validation fails and we were using a provided token, restore the original
              if (token) {
                  authToken = originalToken;
              }
              connectionVerified = false;
              return {
                  isError: true,
                  content: [{
                          type: "text",
                          text: token
                              ? `❌ The provided token is invalid or expired: ${getErrorMessage(error)}\nPlease try with another token or use authenticate-with-credentials.`
                              : `❌ Your session token is invalid or expired: ${getErrorMessage(error)}\nPlease authenticate again.`
                      }]
              };
          }
      }
      catch (error) {
          return {
              isError: true,
              content: [{ type: "text", text: `Error keeping session alive: ${getErrorMessage(error)}` }]
          };
      }
  });

• build/index.js:393-393 (schema)

  Zod input schema defining optional 'token' parameter as string.

  token: z.string().optional().describe("Optional: Provide a token to use for authentication")