pica

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}}`;