Get Action Knowledge

Instructions

Implementation Reference

• src/index.ts:233-259 (handler)

  Core handler function executing the tool: fetches knowledge from PicaClient.getActionKnowledge, formats with buildActionKnowledgeWithGuidance helper, returns formatted text content.

  async function handleGetActionKnowledge(args: GetPicaActionKnowledgeArgs) {
    try {
      const actionId = args.actionId;
      const { knowledge, method } = await picaClient.getActionKnowledge(actionId);
  
      const knowledgeWithGuidance = buildActionKnowledgeWithGuidance(
        knowledge,
        method,
        picaClient.getBaseUrl(),
        args.platform,
        actionId
      );
  
      return {
        content: [
          {
            type: "text" as const,
            text: knowledgeWithGuidance,
          },
        ],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to retrieve action knowledge: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }

• src/index.ts:105-112 (registration)

  MCP server tool registration, linking name, config/schema, and handler function.

  server.registerTool(
    "get_pica_action_knowledge",
    getPicaActionKnowledgeToolConfig,
    async (args: z.infer<typeof getPicaActionKnowledgeZodSchema>) => {
      await initializePica();
      return await handleGetActionKnowledge(args as GetPicaActionKnowledgeArgs);
    }
  );

• src/schemas.ts:103-107 (schema)

  Tool configuration including title, description, and input schema reference used for registration.

  export const getPicaActionKnowledgeToolConfig = {
      title: "Get Action Knowledge",
      description: "Get comprehensive documentation for a specific action including parameters, requirements, and usage examples. MANDATORY: You MUST call this tool before execute_pica_action to understand the action's requirements, parameter structure, caveats, and proper usage. This loads the action documentation into context and is required for successful execution.",
      inputSchema: getPicaActionKnowledgeInputSchema
  };

• src/schemas.ts:27-33 (schema)

  Zod input schema definition for tool parameters (actionId and platform).

  /**
   * Schema for getting action knowledge
   */
  export const getPicaActionKnowledgeInputSchema = {
      actionId: z.string().describe("The action ID to get knowledge for (from the actions list returned by search_pica_platform_actions). REQUIRED: This tool must be called before execute_pica_action to load the action's documentation into context."),
      platform: z.string().describe("The platform name to get knowledge for (e.g., 'ship-station', 'shopify'). This is the kebab-case version of the platform name that comes from the list_pica_integrations tool AVAILABLE PLATFORMS section.")
  };

• src/helpers.ts:91-123 (helper)

  Helper function that formats raw action knowledge with API request structure guidance, appended to the response.

  export function buildActionKnowledgeWithGuidance(
    knowledge: string,
    method: string,
    baseUrl: string,
    platform: string,
    actionId: string
  ): string {
    const cleanBaseUrl = baseUrl.replace(/\/$/, '');
  
    return `${knowledge}
  
  API REQUEST STRUCTURE
  ======================
  URL: ${cleanBaseUrl}/v1/passthrough/{{PATH}}
  
  IMPORTANT: When constructing the URL, only include the API endpoint path after the base URL.
  Do NOT include the full third-party API URL.
  
  Examples:
  ✅ Correct: ${cleanBaseUrl}/v1/passthrough/crm/v3/objects/contacts/search
  ❌ Incorrect: ${cleanBaseUrl}/v1/passthrough/https://api.hubapi.com/crm/v3/objects/contacts/search
  
  METHOD: ${method}
  
  HEADERS:
  - x-pica-secret: {{process.env.PICA_SECRET}}
  - x-pica-connection-key: {{process.env.PICA_${platform.toUpperCase()}_CONNECTION_KEY}}
  - x-pica-action-id: ${actionId}
  - ... (other headers)
  
  BODY: {{BODY}}
  
  QUERY PARAMS: {{QUERY_PARAMS}}`;