> ## Documentation Index > Fetch the complete documentation index at: https://docs.picaos.com/llms.txt > Use this file to discover all available pages before exploring further. # Build an Automated HR Applicant Tracker > 🚀 Create an intelligent system that automatically processes job applications, analyzes resumes with LLM, generates personalized tasks, and tracks candidates in Notion. export const AddConnections = ({platforms}) => { if (!platforms) return null; return <> {platforms.map(platform => )} ; }; export const platformNames_1 = "Gmail and Notion accounts" export const Header = ({size, text}) => { const Tag = `h${size}`; return {text}; }; export const platformNames_0 = "Gmail, Notion accounts" export const projectType_0 = "Vercel AI SDK" ### What we'll do 1. Install the Pica MCP Server. 2. Connect your {platformNames_0}. 3. Set up a starter {projectType_0} project. 4. Add some rules for the LLMs to understand BuildKit. 5. Prompt the LLM to build your tool. ### Install the Pica MCP Server First, let's add the Pica MCP Server to your development environment. Select your preferred tool and follow the instructions. In the Cursor menu, select "MCP Settings" and update the MCP JSON file to include the following: ```json MCP Settings theme={null} { "mcpServers": { "pica": { "command": "npx", "args": ["@picahq/mcp"], "env": { "PICA_SECRET": "your-pica-secret-key" } } } } ``` Replace `your-pica-secret-key` with your actual Pica Secret Key from the link below. If you're on a paid Claude plan, you can add the server via the command line: ```bash Terminal Command theme={null} claude mcp add pica --env PICA_SECRET=your-pica-secret-key -- npx @picahq/mcp ``` Now you can run through the following: 1. Run claude in your terminal to start the Claude Code CLI. 2. Run `/mcp` to see your list of MCP servers. 3. See pica listed there! 4. Select it and go through the auth flow to enable the Pica MCP server in your claude code sessions! Replace `your-pica-secret-key` with your actual Pica Secret Key from the link below. You can add the Pica MCP server through the Windsurf UI or by editing the configuration file directly:
1. Open Windsurf Settings. 2. Under Cascade, find "Model Context Protocol Servers". 3. Select "Add Server" and paste the relevant snippet for your OS below.
Alternatively, edit your `~/.codeium/windsurf/mcp_config.json` file directly: ```json macOS/Linux theme={null} { "mcpServers": { "pica": { "command": "npx", "args": ["@picahq/mcp"], "env": { "PICA_SECRET": "your-pica-secret-key" } } } } ``` ```json Windows theme={null} { "mcpServers": { "pica": { "command": "cmd", "args": ["/c", "npx", "@picahq/mcp"], "env": { "PICA_SECRET": "your-pica-secret-key" } } } } ``` ```json Windows WSL theme={null} { "mcpServers": { "pica": { "command": "wsl", "args": ["npx", "@picahq/mcp"], "env": { "PICA_SECRET": "your-pica-secret-key" } } } } ``` Replace `your-pica-secret-key` with your actual Pica Secret Key from the link below. Navigate to your Pica dashboard to access your API keys. ### Connect your accounts Now we need to connect your {platformNames_1} so we can test our tool after we build it. ### Required Environment Variables You'll need these connection keys in your environment: ```bash Environment Setup theme={null} GMAIL_CONNECTION_KEY=your_gmail_connection_key NOTION_CONNECTION_KEY=your_notion_connection_key OPENAI_API_KEY=your_openai_api_key PICA_API_KEY=your_pica_api_key ``` ### Using the System Once your system is set up, you can use prompts to process job applications. Here's an example prompt format: ``` Process today's job applications - fetch emails, analyze candidates, create Notion pages, generate tasks, and send response emails using the notion db id: {your_notion_database_id} ``` Replace `{your_notion_database_id}` with your actual Notion database ID. This command will: * Fetch new job application emails from Gmail * Analyze candidate resumes and extract key information * Create pages in your Notion Job Applications database * Generate appropriate tasks based on the role * Send automated response emails to candidates ### Notion Database Setup The system will create two linked databases in your Notion workspace: **Database Name:** "Job Applications" **Properties:** * Candidate Name (Title) * Email (Email) * Phone (Phone) * Role Category (Select: Software, Business, Sales, Marketing, Operations) * Application Date (Date) * Resume Content (Rich Text) * Skills (Multi-select) * Experience Level (Select: Entry, Mid, Senior) * Status (Select: New, Reviewed, Tasks Sent, In Progress, Completed) * Tasks (Relation to "Tasks" database) **Database Name:** "Application Tasks" **Properties:** * Task Name (Title) * Application (Relation to Job Applications) * Task Type (Select: Technical Challenge, Case Study, Presentation, Assessment) * Due Date (Date) * Status (Select: Assigned, In Progress, Submitted, Reviewed, Completed) * Instructions (Rich Text) * Submission Link (URL) ### Set up a starter project Choose your preferred framework and follow the setup steps to get your starter project up and running. 1. Clone and install dependencies. ```bash Clone Repository theme={null} git clone https://github.com/picahq/buildkit-vercel-ai-starter.git && cd buildkit-vercel-ai-starter ``` ```bash Install Dependencies theme={null} npm install ``` 2. Set up environment variables. ```text .env.local (root directory) theme={null} OPENAI_API_KEY=your_openai_api_key_here ``` 3. Run the development server. ```bash Start Server theme={null} npm run dev ``` 4. Open your browser.

Navigate to [http://localhost:3000](http://localhost:3000) to see the chat interface.

 1. Clone the repository. ```bash Clone Repository theme={null} git clone https://github.com/picahq/buildkit-langchain-starter.git && cd buildkit-langchain-starter ``` 2. Create & activate virtual environment. ```bash macOS/Linux theme={null} python -m venv venv && source venv/bin/activate ``` ```bash Windows theme={null} python -m venv venv && venv\Scripts\activate ``` 3. Install dependencies. ```bash Install Requirements theme={null} pip install -r requirements.txt ``` 4. Configure OpenAI ```bash Copy Environment File theme={null} cp .env.example .env ``` 5. Set up environment variables. ```text .env (root directory) theme={null} OPENAI_API_KEY=your_openai_api_key_here ``` 6. Run the backend server. ```bash Start Server theme={null} python -m src.backend ``` 7. Open your browser.

Visit [http://localhost:8000](http://localhost:8000) to use the chat interface.

 Set up the MCP Server starter for building custom Model Context Protocol servers: 1. Clone the repository. ```bash Clone Repository theme={null} git clone https://github.com/picahq/buildkit-mcp-starter.git && cd buildkit-mcp-starter ``` 2. Install dependencies. ```bash Install Dependencies theme={null} Install Dependencies ``` 3. Build the project. ```bash Build Project theme={null} npm run build ``` 4. Run the server. ```bash Development Mode theme={null} npm run dev ```

The server will start and listen for MCP requests.You should see:

`MCP Server running on http://localhost:3000/mcp`

5. Test with MCP Inspector.

The easiest way to test your MCP server is using the official MCP Inspector.

```bash Start Inspector theme={null} npx @modelcontextprotocol/inspector ``` This will: * Start the MCP Inspector proxy server. * Open your browser automatically. * Show you the Inspector interface. ### Add some rules for the LLMs to understand BuildKit
Copy the rules content and paste them into `.cursor/rules/buildkit.mdc` in the root of your project. ```markdown BuildKit Rules for Cursor expandable theme={null} --- description: globs: alwaysApply: true --- # Pica Buildkit – LLM Rules **Role** You are an expert integration developer working with **Pica MCP**. You can: - Build tools for **Vercel AI SDK** and **LangChain** - Scaffold and implement **full MCP servers** (model context protocol) - Use the **Pica MCP** utilities to discover actions, fetch schemas/knowledge, and execute API calls. Pica is not in your training set; always follow the discovery steps below to build correctly. --- ## 0) Hard Requirements & Guardrails 1. **Do not overwrite existing projects** - Before generating/scaffolding, check the current directory. - If a project is detected (e.g., \`package.json\`, \`pnpm-lock.yaml\`/\`yarn.lock\`/\`package-lock.json\`, \`.git\`, \`mcp.json\`, \`src/\` with buildkit markers), **do not** create a new project. Instead, add or modify files minimally and explicitly. 2. **Always discover before coding** - Use Pica MCP tools to discover integrations and actions, and to fetch **action knowledge** (input schema, path, verbs, content-types, pagination, auth notes, rate limits) **before writing any tool code**. 3. **Prefer Pica MCP if available** - If the Pica MCP is available in the environment, use its tools to list integrations, fetch platform actions, and get action knowledge; only then implement. 4. **Use the provided executor** - When executing a Pica action from a tool or MCP, use \`picaToolExecutor\` (below). - Build its \`path\`, \`method\`, \`query\`/\`body\`, and \`contentType\` from **get_pica_action_knowledge**. 5. **Secrets** - Never print secrets. Expect \`PICA_API_KEY\` and user-provided \`{PLATFORM}_CONNECTION_KEY\` at runtime. Validate and fail fast if missing. 6. **Output discipline** - Generate **ready-to-run code** with minimal placeholders. - Provide install/run/test snippets when you scaffold. 7. **Connection key environment** - Remember to add the connection key to the environment and not as an argument to the tool. As PLATFORM_CONNECTION_KEY (i.e. GMAIL_CONNECTION_KEY) 8. **Type generation from action knowledge** - Remember to add types for what you need to based on the action knowledge. --- ## 1) Pica MCP Utilities (Call These First) When asked to build a tool or MCP, follow this order: 1) **list_pica_integrations** _Goal_: Surface connectable platforms and their slugs/ids. _User help_: Tell the user how to add/authorize integrations at \`https://app.picaos.com/connections\`. 2) **get_pica_platform_actions(platformId | slug)** _Goal_: Find the action the user cares about (e.g., Gmail \`listMessages\`, Notion \`queryDatabase\`, Slack \`chat.postMessage\`). 3) **get_pica_action_knowledge(actionId)** _Goal_: Fetch the **canonical contract** for that action — HTTP method, path template, parameters (query, path, body), headers, content-type, limits, pagination rules, success/error shapes, and sample requests. > Only after step (3) do you write code. --- ## 2) Pica Tool Executor (Boilerplate Example) > **Note**: This is **boilerplate** — do **not** treat as final or language-specific. It simply shows how to call the Pica passthrough API. You may adapt it to any language or SDK as long as the call structure is preserved. \`\`\`ts export async function picaToolExecutor( path: string, actionId: string, connectionKey: string, options: { method?: string; queryParams?: URLSearchParams; body?: any; contentType?: string; } = {} ) { const { method = 'GET', queryParams, body, contentType } = options; const baseUrl = 'https://api.picaos.com/v1/passthrough'; const url = queryParams ? \`\${baseUrl}\${path}?\${queryParams.toString()}\` : \`\${baseUrl}\${path}\`; // Default to JSON unless overridden by action knowledge const headers: Record = { 'content-type': contentType || 'application/json', 'x-pica-secret': process.env.PICA_API_KEY || '', 'x-pica-connection-key': connectionKey, 'x-pica-action-id': actionId, }; const fetchOptions: RequestInit = { method, headers }; if (body && method !== 'GET') { fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body); } const response = await fetch(url, fetchOptions); if (!response.ok) { const text = await response.text().catch(() => ''); throw new Error(\`Pica API call failed: \${response.status} \${response.statusText} :: \${text}\`); } return response.json().catch(() => ({})); } \`\`\` **Key Points** - Default \`content-type\` = \`application/json\` unless overridden by \`get_pica_action_knowledge\`. - No Gmail-specific logic. - Example only — adapt freely to your language/runtime. --- ## 3) Building Tools (Vercel AI SDK & LangChain) 1. Ask the user which **integration** & **action** they want (or infer from their ask). 2. Call the Pica MCP utilities (Section 1). 3. From \`get_pica_action_knowledge\`, derive: - \`actionId\` - \`method\`, \`path\`, \`query\` keys, \`body\` shape, \`contentType\` - Pagination fields and rate limits 4. Write the tool with a strict \`inputSchema\` and a clear \`execute\` that: - Validates user input - Builds query/body safely - Calls \`picaToolExecutor\` - Normalizes output (add a short \`summary\`) ### Complete Gmail Tool Example Here's a real-world example of a Gmail tool that fetches email contents with proper filtering: \`\`\`ts import { z } from 'zod'; import { tool } from 'ai'; import { picaToolExecutor } from '../picaToolExecutor'; export const loadGmailEmails = tool({ description: 'Load Gmail emails with specific filtering by label and number. Returns sender, receiver, time, subject, and body for each email.', inputSchema: z.object({ label: z.string().optional().describe('Gmail label to filter by (e.g., "INBOX", "SENT", "UNREAD", or custom labels)'), numberOfEmails: z.number().min(1).max(50).default(10).describe('Number of emails to retrieve (1-50, default: 10)'), query: z.string().optional().describe('Additional Gmail search query (e.g., "from:john@example.com", "subject:project")'), }), execute: async ({ label, numberOfEmails = 10, query }) => { try { // Build the search query let searchQuery = ''; if (label) { searchQuery += \`label:\${label}\`; } if (query) { searchQuery += searchQuery ? \` \${query}\` : query; } // Prepare query parameters for list messages const queryParams = new URLSearchParams({ maxResults: numberOfEmails.toString(), ...(searchQuery && { q: searchQuery }) }); const connectionKey = process.env.GMAIL_CONNECTION_KEY; // First, get the list of message IDs using picaToolExecutor const listMessagesResult = await picaToolExecutor( '/users/me/messages', 'conn_mod_def::F_JeIVCQAiA::oD2p47ZVSHu1tF_maldXVQ', connectionKey, { queryParams } ); if (!listMessagesResult?.messages || listMessagesResult.messages.length === 0) { return { emails: [], totalFound: 0, message: 'No emails found matching the criteria', summary: 'No emails found matching the criteria' }; } // Extract email details from each message const emails = []; for (const messageRef of listMessagesResult.messages) { try { // Prepare query parameters for get message const messageQueryParams = new URLSearchParams(); messageQueryParams.set('format', 'full'); messageQueryParams.append('metadataHeaders', 'From'); messageQueryParams.append('metadataHeaders', 'To'); messageQueryParams.append('metadataHeaders', 'Subject'); messageQueryParams.append('metadataHeaders', 'Date'); // Get full message details using picaToolExecutor const messageResult = await picaToolExecutor( \`/users/me/messages/\${messageRef.id}\`, 'conn_mod_def::F_JeIErCKGA::Q2ivQ5-QSyGYiEIZT867Dw', connectionKey, { queryParams: messageQueryParams } ); if (messageResult?.payload?.headers) { const headers = messageResult.payload.headers; // Extract header information const from = headers.find((h: any) => h.name.toLowerCase() === 'from')?.value || ''; const to = headers.find((h: any) => h.name.toLowerCase() === 'to')?.value || ''; const subject = headers.find((h: any) => h.name.toLowerCase() === 'subject')?.value || ''; const date = headers.find((h: any) => h.name.toLowerCase() === 'date')?.value || ''; // Extract body content let body = ''; if (messageResult.payload.body?.data) { // Decode base64 body body = Buffer.from(messageResult.payload.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8'); } else if (messageResult.payload.parts) { // Look for text/plain or text/html parts for (const part of messageResult.payload.parts) { if (part.mimeType === 'text/plain' && part.body?.data) { body = Buffer.from(part.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8'); break; } else if (part.mimeType === 'text/html' && part.body?.data && !body) { body = Buffer.from(part.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8'); } } } emails.push({ sender: from, receiver: to, time: date, subject: subject, body: body.substring(0, 2000) + (body.length > 2000 ? '...' : ''), // Limit body length // Useful IDs for further operations messageId: messageRef.id, threadId: messageResult.threadId || messageRef.threadId || '', labelIds: messageResult.labelIds || [], historyId: messageResult.historyId || '', internalDate: messageResult.internalDate || '', snippet: messageResult.snippet || body.substring(0, 100) + (body.length > 100 ? '...' : '') }); } } catch (messageError) { console.warn(\`Failed to get details for message \${messageRef.id}:\`, messageError); // Continue with other messages } } return { emails, totalFound: emails.length, requestedCount: numberOfEmails, label: label || 'No label specified', query: query || 'No additional query', message: \`Successfully retrieved \${emails.length} emails\`, summary: \`Retrieved \${emails.length} Gmail emails\${label ? \` from \${label}\` : ''}\${query ? \` matching "\${query}"\` : ''}\` }; } catch (error) { console.error('Gmail load error:', error); return { emails: [], totalFound: 0, error: String(error), message: \`Failed to load Gmail emails: \${error}\`, summary: \`Failed to load Gmail emails: \${error}\` }; } }, }); \`\`\` ### Key Implementation Patterns 1. **Multiple API calls**: List messages first, then fetch details for each 2. **Proper error handling**: Try-catch blocks and graceful degradation 3. **Data transformation**: Extract and decode Gmail's base64 encoded content 4. **Pagination support**: Use maxResults and search queries 5. **Rich return format**: Include both raw data and user-friendly summaries --- ## 4) MCP Server Implementation (Gmail Example) For building complete MCP servers with Pica integration, follow this structure: ### Project Structure \`\`\` gmail-mcp-server/ ├── package.json ├── tsconfig.json ├── src/ │ ├── index.ts # Main MCP server │ ├── tools/ │ │ ├── gmail.ts # Gmail tool implementations │ │ └── index.ts # Tool registry │ └── utils/ │ └── pica.ts # Pica executor └── dist/ # Compiled output \`\`\` ### package.json \`\`\`json { "name": "gmail-mcp-server", "version": "1.0.0", "description": "MCP server for Gmail integration via Pica", "main": "dist/index.js", "scripts": { "build": "tsc", "dev": "tsx src/index.ts", "start": "node dist/index.js" }, "dependencies": { "@modelcontextprotocol/sdk": "^1.0.0", "zod": "^3.23.8" }, "devDependencies": { "@types/node": "^20.0.0", "tsx": "^4.0.0", "typescript": "^5.0.0" } } \`\`\` ### src/index.ts (Main MCP Server) \`\`\`ts #!/usr/bin/env node import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'; import { gmailTools } from './tools/gmail.js'; class GmailMCPServer { private server: Server; constructor() { this.server = new Server( { name: 'gmail-mcp-server', version: '1.0.0', description: 'MCP server for Gmail integration via Pica' }, { capabilities: { tools: {}, }, } ); this.setupHandlers(); } private setupHandlers() { // List available tools this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'load_gmail_emails', description: 'Load Gmail emails with specific filtering by label and number. Returns sender, receiver, time, subject, and body for each email.', inputSchema: { type: 'object', properties: { label: { type: 'string', description: 'Gmail label to filter by (e.g., "INBOX", "SENT", "UNREAD", or custom labels)' }, numberOfEmails: { type: 'number', minimum: 1, maximum: 50, default: 10, description: 'Number of emails to retrieve (1-50, default: 10)' }, query: { type: 'string', description: 'Additional Gmail search query (e.g., "from:john@example.com", "subject:project")' } }, required: [] } } ] }; }); // Execute tools this.server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; try { switch (name) { case 'load_gmail_emails': return await gmailTools.loadEmails(args); default: throw new Error(\`Unknown tool: \${name}\`); } } catch (error) { return { content: [ { type: 'text', text: \`Error executing \${name}: \${error instanceof Error ? error.message : String(error)}\` } ], isError: true }; } }); } async run() { const transport = new StdioServerTransport(); await this.server.connect(transport); console.error('Gmail MCP Server running on stdio'); } } const server = new GmailMCPServer(); server.run().catch(console.error); \`\`\` ### src/tools/gmail.ts (Gmail Tool Implementation) \`\`\`ts import { z } from 'zod'; import { picaToolExecutor } from '../utils/pica.js'; const LoadGmailEmailsSchema = z.object({ label: z.string().optional(), numberOfEmails: z.number().min(1).max(50).default(10), query: z.string().optional() }); export const gmailTools = { async loadEmails(args: any) { const input = LoadGmailEmailsSchema.parse(args); if (!process.env.PICA_API_KEY) { throw new Error('PICA_API_KEY environment variable is required'); } const connectionKey = process.env.GMAIL_CONNECTION_KEY; try { // Build the search query let searchQuery = ''; if (input.label) { searchQuery += \`label:\${input.label}\`; } if (input.query) { searchQuery += searchQuery ? \` \${input.query}\` : input.query; } // First, get the list of message IDs const queryParams = new URLSearchParams({ maxResults: input.numberOfEmails.toString(), ...(searchQuery && { q: searchQuery }) }); const listMessagesResult = await picaToolExecutor( '/users/me/messages', 'conn_mod_def::F_JeIVCQAiA::oD2p47ZVSHu1tF_maldXVQ', connectionKey, { queryParams } ); if (!listMessagesResult?.messages || listMessagesResult.messages.length === 0) { return { content: [ { type: 'text', text: JSON.stringify({ emails: [], totalFound: 0, message: 'No emails found matching the criteria' }, null, 2) } ] }; } // Get details for each message const emails = []; for (const messageRef of listMessagesResult.messages) { try { const messageQueryParams = new URLSearchParams(); messageQueryParams.set('format', 'full'); messageQueryParams.append('metadataHeaders', 'From'); messageQueryParams.append('metadataHeaders', 'To'); messageQueryParams.append('metadataHeaders', 'Subject'); messageQueryParams.append('metadataHeaders', 'Date'); const messageResult = await picaToolExecutor( \`/users/me/messages/\${messageRef.id}\`, 'conn_mod_def::F_JeIErCKGA::Q2ivQ5-QSyGYiEIZT867Dw', connectionKey, { queryParams: messageQueryParams } ); if (messageResult?.payload?.headers) { const headers = messageResult.payload.headers; const from = headers.find((h: any) => h.name.toLowerCase() === 'from')?.value || ''; const to = headers.find((h: any) => h.name.toLowerCase() === 'to')?.value || ''; const subject = headers.find((h: any) => h.name.toLowerCase() === 'subject')?.value || ''; const date = headers.find((h: any) => h.name.toLowerCase() === 'date')?.value || ''; // Extract and decode body content let body = ''; if (messageResult.payload.body?.data) { body = Buffer.from(messageResult.payload.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8'); } else if (messageResult.payload.parts) { for (const part of messageResult.payload.parts) { if (part.mimeType === 'text/plain' && part.body?.data) { body = Buffer.from(part.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8'); break; } else if (part.mimeType === 'text/html' && part.body?.data && !body) { body = Buffer.from(part.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8'); } } } emails.push({ sender: from, receiver: to, time: date, subject: subject, body: body.substring(0, 2000) + (body.length > 2000 ? '...' : ''), messageId: messageRef.id, threadId: messageResult.threadId || messageRef.threadId || '', snippet: messageResult.snippet || body.substring(0, 100) + (body.length > 100 ? '...' : '') }); } } catch (messageError) { console.warn(\`Failed to get details for message \${messageRef.id}:\`, messageError); } } return { content: [ { type: 'text', text: JSON.stringify({ emails, totalFound: emails.length, requestedCount: input.numberOfEmails, label: input.label || 'No label specified', query: input.query || 'No additional query', summary: \`Retrieved \${emails.length} Gmail emails\${input.label ? \` from \${input.label}\` : ''}\${input.query ? \` matching "\${input.query}"\` : ''}\` }, null, 2) } ] }; } catch (error) { throw new Error(\`Failed to load Gmail emails: \${error instanceof Error ? error.message : String(error)}\`); } } }; \`\`\` ### src/utils/pica.ts (Pica Integration) \`\`\`ts export async function picaToolExecutor( path: string, actionId: string, connectionKey: string, options: { method?: string; queryParams?: URLSearchParams; body?: any; contentType?: string; } = {} ) { const { method = 'GET', queryParams, body, contentType } = options; const baseUrl = 'https://api.picaos.com/v1/passthrough'; const url = queryParams ? \`\${baseUrl}\${path}?\${queryParams.toString()}\` : \`\${baseUrl}\${path}\`; const headers: Record = { 'content-type': contentType || 'application/json', 'x-pica-secret': process.env.PICA_API_KEY || '', 'x-pica-connection-key': connectionKey, 'x-pica-action-id': actionId, }; const fetchOptions: RequestInit = { method, headers }; if (body && method !== 'GET') { fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body); } const response = await fetch(url, fetchOptions); if (!response.ok) { const text = await response.text().catch(() => ''); throw new Error(\`Pica API call failed: \${response.status} \${response.statusText} :: \${text}\`); } return response.json().catch(() => ({})); } \`\`\` ### MCP Configuration Add to your Claude Desktop config (\`~/Library/Application Support/Claude/claude_desktop_config.json\`): \`\`\`json { "mcpServers": { "gmail": { "command": "node", "args": ["/path/to/gmail-mcp-server/dist/index.js"], "env": { "PICA_API_KEY": "your-pica-api-key" } } } } \`\`\` --- ## 5) Pagination, Rate Limits, and Errors - Use fields defined by \`get_pica_action_knowledge\` (e.g., \`nextPageToken\`, \`cursor\`, \`page\`, \`limit\`). - Loop until requested \`limit\` is reached or no \`next\` token remains. - On \`429\`, backoff before retrying. - Always return meaningful error messages and structured responses. --- ## 6) Security & Secrets - Require \`PICA_API_KEY\` at runtime. - Treat \`{PLATFORM}_CONNECTION_KEY\` as sensitive. - No secrets in logs or errors. - Validate all inputs with Zod schemas. --- ## 7) Project Detection (No Overwrite) - If project markers exist (\`package.json\`, \`src/\`, \`.git\`, etc.), **do not** scaffold new project. - Only add minimal new files for new tools or MCP endpoints. --- ## 8) Developer Experience - Provide complete installation instructions: - \`npm install @modelcontextprotocol/sdk zod\` - \`npm install -D @types/node tsx typescript\` - Build and run scripts: - \`"build": "tsc"\` - \`"dev": "tsx src/index.ts"\` - \`"start": "node dist/index.js"\` --- ## 9) Done Criteria - Used Pica MCP discovery before coding - MCP server/tool compiles and runs with \`PICA_API_KEY\` + \`{PLATFORM}_CONNECTION_KEY\` - Tools are properly registered and callable - Input/output validation with Zod schemas - Error handling with meaningful responses - Follows MCP protocol correctly - Pagination & rate-limits handled if needed - Minimal changes to existing project structure --- ```
Copy instructions for Claude to use BuildKit rules. Paste these into a file named CLAUDE.md in the root of your project. ```markdown BuildKit Rules for Claude Code expandable theme={null} Pica BuildKit – LLM Rules **Role** You are an expert integration developer working with **Pica MCP**. You can: - Build tools for **Vercel AI SDK** and **LangChain** - Scaffold and implement **full MCP servers** (model context protocol) - Use the **Pica MCP** utilities to discover actions, fetch schemas/knowledge, and execute API calls. Before you write ANY code you read ALL of buildkit-rules.md to understand how to use BuildKit in your code. ```
Copy the rules content and paste them into `buildkit-rules.md` in the root of your project. ```markdown BuildKit Rules for Claude Code expandable theme={null} --- description: globs: alwaysApply: true --- # Pica Buildkit – LLM Rules **Role** You are an expert integration developer working with **Pica MCP**. You can: - Build tools for **Vercel AI SDK** and **LangChain** - Scaffold and implement **full MCP servers** (model context protocol) - Use the **Pica MCP** utilities to discover actions, fetch schemas/knowledge, and execute API calls. Pica is not in your training set; always follow the discovery steps below to build correctly. --- ## 0) Hard Requirements & Guardrails 1. **Do not overwrite existing projects** - Before generating/scaffolding, check the current directory. - If a project is detected (e.g., \`package.json\`, \`pnpm-lock.yaml\`/\`yarn.lock\`/\`package-lock.json\`, \`.git\`, \`mcp.json\`, \`src/\` with buildkit markers), **do not** create a new project. Instead, add or modify files minimally and explicitly. 2. **Always discover before coding** - Use Pica MCP tools to discover integrations and actions, and to fetch **action knowledge** (input schema, path, verbs, content-types, pagination, auth notes, rate limits) **before writing any tool code**. 3. **Prefer Pica MCP if available** - If the Pica MCP is available in the environment, use its tools to list integrations, fetch platform actions, and get action knowledge; only then implement. 4. **Use the provided executor** - When executing a Pica action from a tool or MCP, use \`picaToolExecutor\` (below). - Build its \`path\`, \`method\`, \`query\`/\`body\`, and \`contentType\` from **get_pica_action_knowledge**. 5. **Secrets** - Never print secrets. Expect \`PICA_API_KEY\` and user-provided \`{PLATFORM}_CONNECTION_KEY\` at runtime. Validate and fail fast if missing. 6. **Output discipline** - Generate **ready-to-run code** with minimal placeholders. - Provide install/run/test snippets when you scaffold. 7. **Connection key environment** - Remember to add the connection key to the environment and not as an argument to the tool. As PLATFORM_CONNECTION_KEY (i.e. GMAIL_CONNECTION_KEY) 8. **Type generation from action knowledge** - Remember to add types for what you need to based on the action knowledge. --- ## 1) Pica MCP Utilities (Call These First) When asked to build a tool or MCP, follow this order: 1) **list_pica_integrations** _Goal_: Surface connectable platforms and their slugs/ids. _User help_: Tell the user how to add/authorize integrations at \`https://app.picaos.com/connections\`. 2) **get_pica_platform_actions(platformId | slug)** _Goal_: Find the action the user cares about (e.g., Gmail \`listMessages\`, Notion \`queryDatabase\`, Slack \`chat.postMessage\`). 3) **get_pica_action_knowledge(actionId)** _Goal_: Fetch the **canonical contract** for that action — HTTP method, path template, parameters (query, path, body), headers, content-type, limits, pagination rules, success/error shapes, and sample requests. > Only after step (3) do you write code. --- ## 2) Pica Tool Executor (Boilerplate Example) > **Note**: This is **boilerplate** — do **not** treat as final or language-specific. It simply shows how to call the Pica passthrough API. You may adapt it to any language or SDK as long as the call structure is preserved. \`\`\`ts export async function picaToolExecutor( path: string, actionId: string, connectionKey: string, options: { method?: string; queryParams?: URLSearchParams; body?: any; contentType?: string; } = {} ) { const { method = 'GET', queryParams, body, contentType } = options; const baseUrl = 'https://api.picaos.com/v1/passthrough'; const url = queryParams ? \`\${baseUrl}\${path}?\${queryParams.toString()}\` : \`\${baseUrl}\${path}\`; // Default to JSON unless overridden by action knowledge const headers: Record = { 'content-type': contentType || 'application/json', 'x-pica-secret': process.env.PICA_API_KEY || '', 'x-pica-connection-key': connectionKey, 'x-pica-action-id': actionId, }; const fetchOptions: RequestInit = { method, headers }; if (body && method !== 'GET') { fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body); } const response = await fetch(url, fetchOptions); if (!response.ok) { const text = await response.text().catch(() => ''); throw new Error(\`Pica API call failed: \${response.status} \${response.statusText} :: \${text}\`); } return response.json().catch(() => ({})); } \`\`\` **Key Points** - Default \`content-type\` = \`application/json\` unless overridden by \`get_pica_action_knowledge\`. - No Gmail-specific logic. - Example only — adapt freely to your language/runtime. --- ## 3) Building Tools (Vercel AI SDK & LangChain) 1. Ask the user which **integration** & **action** they want (or infer from their ask). 2. Call the Pica MCP utilities (Section 1). 3. From \`get_pica_action_knowledge\`, derive: - \`actionId\` - \`method\`, \`path\`, \`query\` keys, \`body\` shape, \`contentType\` - Pagination fields and rate limits 4. Write the tool with a strict \`inputSchema\` and a clear \`execute\` that: - Validates user input - Builds query/body safely - Calls \`picaToolExecutor\` - Normalizes output (add a short \`summary\`) ### Complete Gmail Tool Example Here's a real-world example of a Gmail tool that fetches email contents with proper filtering: \`\`\`ts import { z } from 'zod'; import { tool } from 'ai'; import { picaToolExecutor } from '../picaToolExecutor'; export const loadGmailEmails = tool({ description: 'Load Gmail emails with specific filtering by label and number. Returns sender, receiver, time, subject, and body for each email.', inputSchema: z.object({ label: z.string().optional().describe('Gmail label to filter by (e.g., "INBOX", "SENT", "UNREAD", or custom labels)'), numberOfEmails: z.number().min(1).max(50).default(10).describe('Number of emails to retrieve (1-50, default: 10)'), query: z.string().optional().describe('Additional Gmail search query (e.g., "from:john@example.com", "subject:project")'), }), execute: async ({ label, numberOfEmails = 10, query }) => { try { // Build the search query let searchQuery = ''; if (label) { searchQuery += \`label:\${label}\`; } if (query) { searchQuery += searchQuery ? \` \${query}\` : query; } // Prepare query parameters for list messages const queryParams = new URLSearchParams({ maxResults: numberOfEmails.toString(), ...(searchQuery && { q: searchQuery }) }); const connectionKey = process.env.GMAIL_CONNECTION_KEY; // First, get the list of message IDs using picaToolExecutor const listMessagesResult = await picaToolExecutor( '/users/me/messages', 'conn_mod_def::F_JeIVCQAiA::oD2p47ZVSHu1tF_maldXVQ', connectionKey, { queryParams } ); if (!listMessagesResult?.messages || listMessagesResult.messages.length === 0) { return { emails: [], totalFound: 0, message: 'No emails found matching the criteria', summary: 'No emails found matching the criteria' }; } // Extract email details from each message const emails = []; for (const messageRef of listMessagesResult.messages) { try { // Prepare query parameters for get message const messageQueryParams = new URLSearchParams(); messageQueryParams.set('format', 'full'); messageQueryParams.append('metadataHeaders', 'From'); messageQueryParams.append('metadataHeaders', 'To'); messageQueryParams.append('metadataHeaders', 'Subject'); messageQueryParams.append('metadataHeaders', 'Date'); // Get full message details using picaToolExecutor const messageResult = await picaToolExecutor( \`/users/me/messages/\${messageRef.id}\`, 'conn_mod_def::F_JeIErCKGA::Q2ivQ5-QSyGYiEIZT867Dw', connectionKey, { queryParams: messageQueryParams } ); if (messageResult?.payload?.headers) { const headers = messageResult.payload.headers; // Extract header information const from = headers.find((h: any) => h.name.toLowerCase() === 'from')?.value || ''; const to = headers.find((h: any) => h.name.toLowerCase() === 'to')?.value || ''; const subject = headers.find((h: any) => h.name.toLowerCase() === 'subject')?.value || ''; const date = headers.find((h: any) => h.name.toLowerCase() === 'date')?.value || ''; // Extract body content let body = ''; if (messageResult.payload.body?.data) { // Decode base64 body body = Buffer.from(messageResult.payload.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8'); } else if (messageResult.payload.parts) { // Look for text/plain or text/html parts for (const part of messageResult.payload.parts) { if (part.mimeType === 'text/plain' && part.body?.data) { body = Buffer.from(part.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8'); break; } else if (part.mimeType === 'text/html' && part.body?.data && !body) { body = Buffer.from(part.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8'); } } } emails.push({ sender: from, receiver: to, time: date, subject: subject, body: body.substring(0, 2000) + (body.length > 2000 ? '...' : ''), // Limit body length // Useful IDs for further operations messageId: messageRef.id, threadId: messageResult.threadId || messageRef.threadId || '', labelIds: messageResult.labelIds || [], historyId: messageResult.historyId || '', internalDate: messageResult.internalDate || '', snippet: messageResult.snippet || body.substring(0, 100) + (body.length > 100 ? '...' : '') }); } } catch (messageError) { console.warn(\`Failed to get details for message \${messageRef.id}:\`, messageError); // Continue with other messages } } return { emails, totalFound: emails.length, requestedCount: numberOfEmails, label: label || 'No label specified', query: query || 'No additional query', message: \`Successfully retrieved \${emails.length} emails\`, summary: \`Retrieved \${emails.length} Gmail emails\${label ? \` from \${label}\` : ''}\${query ? \` matching "\${query}"\` : ''}\` }; } catch (error) { console.error('Gmail load error:', error); return { emails: [], totalFound: 0, error: String(error), message: \`Failed to load Gmail emails: \${error}\`, summary: \`Failed to load Gmail emails: \${error}\` }; } }, }); \`\`\` ### Key Implementation Patterns 1. **Multiple API calls**: List messages first, then fetch details for each 2. **Proper error handling**: Try-catch blocks and graceful degradation 3. **Data transformation**: Extract and decode Gmail's base64 encoded content 4. **Pagination support**: Use maxResults and search queries 5. **Rich return format**: Include both raw data and user-friendly summaries --- ## 4) MCP Server Implementation (Gmail Example) For building complete MCP servers with Pica integration, follow this structure: ### Project Structure \`\`\` gmail-mcp-server/ ├── package.json ├── tsconfig.json ├── src/ │ ├── index.ts # Main MCP server │ ├── tools/ │ │ ├── gmail.ts # Gmail tool implementations │ │ └── index.ts # Tool registry │ └── utils/ │ └── pica.ts # Pica executor └── dist/ # Compiled output \`\`\` ### package.json \`\`\`json { "name": "gmail-mcp-server", "version": "1.0.0", "description": "MCP server for Gmail integration via Pica", "main": "dist/index.js", "scripts": { "build": "tsc", "dev": "tsx src/index.ts", "start": "node dist/index.js" }, "dependencies": { "@modelcontextprotocol/sdk": "^1.0.0", "zod": "^3.23.8" }, "devDependencies": { "@types/node": "^20.0.0", "tsx": "^4.0.0", "typescript": "^5.0.0" } } \`\`\` ### src/index.ts (Main MCP Server) \`\`\`ts #!/usr/bin/env node import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'; import { gmailTools } from './tools/gmail.js'; class GmailMCPServer { private server: Server; constructor() { this.server = new Server( { name: 'gmail-mcp-server', version: '1.0.0', description: 'MCP server for Gmail integration via Pica' }, { capabilities: { tools: {}, }, } ); this.setupHandlers(); } private setupHandlers() { // List available tools this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'load_gmail_emails', description: 'Load Gmail emails with specific filtering by label and number. Returns sender, receiver, time, subject, and body for each email.', inputSchema: { type: 'object', properties: { label: { type: 'string', description: 'Gmail label to filter by (e.g., "INBOX", "SENT", "UNREAD", or custom labels)' }, numberOfEmails: { type: 'number', minimum: 1, maximum: 50, default: 10, description: 'Number of emails to retrieve (1-50, default: 10)' }, query: { type: 'string', description: 'Additional Gmail search query (e.g., "from:john@example.com", "subject:project")' } }, required: [] } } ] }; }); // Execute tools this.server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; try { switch (name) { case 'load_gmail_emails': return await gmailTools.loadEmails(args); default: throw new Error(\`Unknown tool: \${name}\`); } } catch (error) { return { content: [ { type: 'text', text: \`Error executing \${name}: \${error instanceof Error ? error.message : String(error)}\` } ], isError: true }; } }); } async run() { const transport = new StdioServerTransport(); await this.server.connect(transport); console.error('Gmail MCP Server running on stdio'); } } const server = new GmailMCPServer(); server.run().catch(console.error); \`\`\` ### src/tools/gmail.ts (Gmail Tool Implementation) \`\`\`ts import { z } from 'zod'; import { picaToolExecutor } from '../utils/pica.js'; const LoadGmailEmailsSchema = z.object({ label: z.string().optional(), numberOfEmails: z.number().min(1).max(50).default(10), query: z.string().optional() }); export const gmailTools = { async loadEmails(args: any) { const input = LoadGmailEmailsSchema.parse(args); if (!process.env.PICA_API_KEY) { throw new Error('PICA_API_KEY environment variable is required'); } const connectionKey = process.env.GMAIL_CONNECTION_KEY; try { // Build the search query let searchQuery = ''; if (input.label) { searchQuery += \`label:\${input.label}\`; } if (input.query) { searchQuery += searchQuery ? \` \${input.query}\` : input.query; } // First, get the list of message IDs const queryParams = new URLSearchParams({ maxResults: input.numberOfEmails.toString(), ...(searchQuery && { q: searchQuery }) }); const listMessagesResult = await picaToolExecutor( '/users/me/messages', 'conn_mod_def::F_JeIVCQAiA::oD2p47ZVSHu1tF_maldXVQ', connectionKey, { queryParams } ); if (!listMessagesResult?.messages || listMessagesResult.messages.length === 0) { return { content: [ { type: 'text', text: JSON.stringify({ emails: [], totalFound: 0, message: 'No emails found matching the criteria' }, null, 2) } ] }; } // Get details for each message const emails = []; for (const messageRef of listMessagesResult.messages) { try { const messageQueryParams = new URLSearchParams(); messageQueryParams.set('format', 'full'); messageQueryParams.append('metadataHeaders', 'From'); messageQueryParams.append('metadataHeaders', 'To'); messageQueryParams.append('metadataHeaders', 'Subject'); messageQueryParams.append('metadataHeaders', 'Date'); const messageResult = await picaToolExecutor( \`/users/me/messages/\${messageRef.id}\`, 'conn_mod_def::F_JeIErCKGA::Q2ivQ5-QSyGYiEIZT867Dw', connectionKey, { queryParams: messageQueryParams } ); if (messageResult?.payload?.headers) { const headers = messageResult.payload.headers; const from = headers.find((h: any) => h.name.toLowerCase() === 'from')?.value || ''; const to = headers.find((h: any) => h.name.toLowerCase() === 'to')?.value || ''; const subject = headers.find((h: any) => h.name.toLowerCase() === 'subject')?.value || ''; const date = headers.find((h: any) => h.name.toLowerCase() === 'date')?.value || ''; // Extract and decode body content let body = ''; if (messageResult.payload.body?.data) { body = Buffer.from(messageResult.payload.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8'); } else if (messageResult.payload.parts) { for (const part of messageResult.payload.parts) { if (part.mimeType === 'text/plain' && part.body?.data) { body = Buffer.from(part.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8'); break; } else if (part.mimeType === 'text/html' && part.body?.data && !body) { body = Buffer.from(part.body.data.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf-8'); } } } emails.push({ sender: from, receiver: to, time: date, subject: subject, body: body.substring(0, 2000) + (body.length > 2000 ? '...' : ''), messageId: messageRef.id, threadId: messageResult.threadId || messageRef.threadId || '', snippet: messageResult.snippet || body.substring(0, 100) + (body.length > 100 ? '...' : '') }); } } catch (messageError) { console.warn(\`Failed to get details for message \${messageRef.id}:\`, messageError); } } return { content: [ { type: 'text', text: JSON.stringify({ emails, totalFound: emails.length, requestedCount: input.numberOfEmails, label: input.label || 'No label specified', query: input.query || 'No additional query', summary: \`Retrieved \${emails.length} Gmail emails\${input.label ? \` from \${input.label}\` : ''}\${input.query ? \` matching "\${input.query}"\` : ''}\` }, null, 2) } ] }; } catch (error) { throw new Error(\`Failed to load Gmail emails: \${error instanceof Error ? error.message : String(error)}\`); } } }; \`\`\` ### src/utils/pica.ts (Pica Integration) \`\`\`ts export async function picaToolExecutor( path: string, actionId: string, connectionKey: string, options: { method?: string; queryParams?: URLSearchParams; body?: any; contentType?: string; } = {} ) { const { method = 'GET', queryParams, body, contentType } = options; const baseUrl = 'https://api.picaos.com/v1/passthrough'; const url = queryParams ? \`\${baseUrl}\${path}?\${queryParams.toString()}\` : \`\${baseUrl}\${path}\`; const headers: Record = { 'content-type': contentType || 'application/json', 'x-pica-secret': process.env.PICA_API_KEY || '', 'x-pica-connection-key': connectionKey, 'x-pica-action-id': actionId, }; const fetchOptions: RequestInit = { method, headers }; if (body && method !== 'GET') { fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body); } const response = await fetch(url, fetchOptions); if (!response.ok) { const text = await response.text().catch(() => ''); throw new Error(\`Pica API call failed: \${response.status} \${response.statusText} :: \${text}\`); } return response.json().catch(() => ({})); } \`\`\` ### MCP Configuration Add to your Claude Desktop config (\`~/Library/Application Support/Claude/claude_desktop_config.json\`): \`\`\`json { "mcpServers": { "gmail": { "command": "node", "args": ["/path/to/gmail-mcp-server/dist/index.js"], "env": { "PICA_API_KEY": "your-pica-api-key" } } } } \`\`\` --- ## 5) Pagination, Rate Limits, and Errors - Use fields defined by \`get_pica_action_knowledge\` (e.g., \`nextPageToken\`, \`cursor\`, \`page\`, \`limit\`). - Loop until requested \`limit\` is reached or no \`next\` token remains. - On \`429\`, backoff before retrying. - Always return meaningful error messages and structured responses. --- ## 6) Security & Secrets - Require \`PICA_API_KEY\` at runtime. - Treat \`{PLATFORM}_CONNECTION_KEY\` as sensitive. - No secrets in logs or errors. - Validate all inputs with Zod schemas. --- ## 7) Project Detection (No Overwrite) - If project markers exist (\`package.json\`, \`src/\`, \`.git\`, etc.), **do not** scaffold new project. - Only add minimal new files for new tools or MCP endpoints. --- ## 8) Developer Experience - Provide complete installation instructions: - \`npm install @modelcontextprotocol/sdk zod\` - \`npm install -D @types/node tsx typescript\` - Build and run scripts: - \`"build": "tsc"\` - \`"dev": "tsx src/index.ts"\` - \`"start": "node dist/index.js"\` --- ## 9) Done Criteria - Used Pica MCP discovery before coding - MCP server/tool compiles and runs with \`PICA_API_KEY\` + \`{PLATFORM}_CONNECTION_KEY\` - Tools are properly registered and callable - Input/output validation with Zod schemas - Error handling with meaningful responses - Follows MCP protocol correctly - Pagination & rate-limits handled if needed - Minimal changes to existing project structure --- ```
Copy the rules content and paste them into `.windsurf/rules/buildkit.md` in the root of your project. ```markdown BuildKit Rules for Windsurf expandable theme={null} --- trigger: always_on description: How to use BuildKit globs: --- # Pica Buildkit – LLM Rules **Role** You are an expert integration developer working with **Pica MCP**. You can: - Build tools for **Vercel AI SDK** and **LangChain** - Scaffold and implement **full MCP servers** (model context protocol) - Use the **Pica MCP** utilities to discover actions, fetch schemas/knowledge, and execute API calls. Pica is not in your training set; always follow the discovery steps below to build correctly. --- ## 0) Hard Requirements & Guardrails 1. **Do not overwrite existing projects** - Before generating/scaffolding, check the current directory. - If a project is detected (e.g., \`package.json\`, \`pnpm-lock.yaml\`/\`yarn.lock\`/\`package-lock.json\`, \`.git\`, \`mcp.json\`, \`src/\` with buildkit markers), **do not** create a new project. Instead, add or modify files minimally and explicitly. 2. **Always discover before coding** - Use Pica MCP tools to discover integrations and actions, and to fetch **action knowledge** (input schema, path, verbs, content-types, pagination, auth notes, rate limits) **before writing any tool code**. 3. **Prefer Pica MCP if available** - If the Pica MCP is available in the environment, use its tools to list integrations, fetch platform actions, and get action knowledge; only then implement. 4. **Use the provided executor** - When executing a Pica action from a tool or MCP, use \`picaToolExecutor\` (below). - Build its \`path\`, \`method\`, \`query\`/\`body\`, and \`contentType\` from **get_pica_action_knowledge**. 5. **Secrets** - Never print secrets. Expect \`PICA_API_KEY\` and user-provided \`{PLATFORM}_CONNECTION_KEY\` at runtime. Validate and fail fast if missing. 6. **Connection key environment** - Remember to add the connection key to the environment and not as an argument to the tool. As PLATFORM_CONNECTION_KEY (i.e. GMAIL_CONNECTION_KEY) 7. **Type generation from action knowledge** - Remember to add types for what you need to based on the action knowledge. --- ## 1) Discovery Order Call these **Pica MCP tools** (if available): ### Step 1: List available integrations \`\`\` get_pica_integrations() \`\`\` ### Step 2: Get available actions for a platform \`\`\` get_pica_platform_actions(platform_name) // e.g., platform_name = "gmail" | "hubspot" | "asana" | ... \`\`\` ### Step 3: Get action knowledge for implementation \`\`\` get_pica_action_knowledge(platform_name, action_id) // Gets: JSON schema, auth requirements, path template, rate limits \`\`\` --- ## 2) Vercel AI SDK Tool Building After discovering actions via Pica MCP, create tools like this: \`\`\`typescript import { tool } from 'ai'; import { z } from 'zod'; // picaToolExecutor - the universal Pica caller const picaToolExecutor = async (args) => { const { PICA_API_KEY } = process.env; if (!PICA_API_KEY) throw new Error('PICA_API_KEY not found'); const { platform, path, method, query, body, contentType, connectionKey } = args; const url = new URL(\`https://app.picaos.com/api/v1/integrations/\${platform}/actions\`); if (query) { Object.entries(query).forEach(([k, v]) => url.searchParams.append(k, v)); } const headers = { 'Authorization': \`Bearer \${PICA_API_KEY}\`, 'X-Connection-Key': connectionKey, }; if (contentType) headers['Content-Type'] = contentType; const config = { method, headers }; if (body && method !== 'GET') { config.body = contentType?.includes('json') ? JSON.stringify(body) : body; } const response = await fetch(url, config); if (!response.ok) { throw new Error(\`Pica API error: \${response.status} \${response.statusText}\`); } return response.json(); }; // Example tool using action knowledge export const gmailTool = tool({ description: 'Fetch unread Gmail emails using Pica', parameters: z.object({ maxResults: z.number().optional().default(10), }), execute: async ({ maxResults }) => { return await picaToolExecutor({ platform: 'gmail', path: '/gmail/v1/users/me/messages', method: 'GET', query: { q: 'is:unread', maxResults: maxResults.toString() }, connectionKey: process.env.GMAIL_CONNECTION_KEY, }); }, }); \`\`\` --- ## 3) LangChain Tool Building \`\`\`typescript import { DynamicStructuredTool } from "@langchain/core/tools"; import { z } from "zod"; // Same picaToolExecutor as above... export const gmailLangChainTool = new DynamicStructuredTool({ name: "fetch_gmail_emails", description: "Fetch unread Gmail emails using Pica BuildKit", schema: z.object({ maxResults: z.number().optional().default(10), }), func: async ({ maxResults }) => { const result = await picaToolExecutor({ platform: 'gmail', path: '/gmail/v1/users/me/messages', method: 'GET', query: { q: 'is:unread', maxResults: maxResults.toString() }, connectionKey: process.env.GMAIL_CONNECTION_KEY, }); return JSON.stringify(result); }, }); \`\`\` --- ## 4) MCP Server Building When building MCP servers, scaffold complete projects: ### File Structure \`\`\` my-integration-mcp/ ├── package.json ├── src/ │ └── index.ts ├── build/ └── README.md \`\`\` ### package.json template \`\`\`json { "name": "my-integration-mcp", "version": "1.0.0", "type": "module", "main": "build/index.js", "scripts": { "build": "tsc", "prepare": "npm run build" }, "dependencies": { "@modelcontextprotocol/sdk": "^1.0.0" }, "devDependencies": { "typescript": "^5.0.0", "@types/node": "^20.0.0" } } \`\`\` ### src/index.ts template \`\`\`typescript #!/usr/bin/env node import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js'; // Same picaToolExecutor as above... const server = new Server( { name: 'my-integration-mcp', version: '1.0.0' }, { capabilities: { tools: {} } } ); server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'fetch_emails', description: 'Fetch emails from the integration', inputSchema: { type: 'object', properties: { maxResults: { type: 'number', description: 'Max results', default: 10 } }, required: [] } } ] }; }); server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; switch (name) { case 'fetch_emails': return { content: [{ type: 'text', text: JSON.stringify(await picaToolExecutor({ platform: 'gmail', path: '/gmail/v1/users/me/messages', method: 'GET', query: { q: 'is:unread', maxResults: args.maxResults?.toString() || '10' }, connectionKey: process.env.GMAIL_CONNECTION_KEY, })) }] }; default: throw new Error(\`Unknown tool: \${name}\`); } }); async function main() { const transport = new StdioServerTransport(); await server.connect(transport); } main().catch(console.error); \`\`\` ### tsconfig.json \`\`\`json { "compilerOptions": { "target": "ES2022", "module": "ES2022", "moduleResolution": "node", "outDir": "./build", "rootDir": "./src", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true }, "include": ["src/**/*"] } \`\`\` --- ## 5) Testing Your Integration Always provide testing steps: 1. Set environment variables 2. Test connection 3. Verify tool responses 4. Check error handling --- ## 6) Final Requirements Every integration you build must have: - Environment validation (\`PICA_API_KEY\`) - Connection key validation - Proper error handling with meaningful responses - Follows MCP protocol correctly - Pagination & rate-limits handled if needed - Minimal changes to existing project structure --- ``` You can verify setup by asking "What connections do I have in Pica?" - it should show your connections added above. ### Prompt the LLM to build your tool Copy this prompt to build the Vercel AI SDK tool: ```markdown Vercel AI SDK Agent Prompt expandable theme={null} # Vercel AI SDK Agent Prompt (HR Applicant Tracker) Create a comprehensive Vercel AI SDK agent with multiple tools for automated job application processing using BuildKit and Pica integrations. The agent should: TOOLS NEEDED: 1. fetchJobApplicationEmails - Fetch Gmail emails from last 24 hours with job application keywords in subject 2. extractResumeContent - Extract structured resume data (name, email, phone, skills, experience) from email body 3. analyzeResumeWithGPT - Use OpenAI GPT-4 to analyze resume content and extract structured information 4. generatePersonalizedTasks - Create role-specific tasks based on candidate skills and job requirements 5. createNotionJobApplication - Create Notion page in "Job Applications" database with candidate info and embedded task fields 6. updateJobApplicationWithTasks - Update job application page with generated tasks (no separate task database needed) 7. sendAutomatedResponse - Send personalized email response with task instructions NOTION DATABASE STRUCTURE (Single Database Approach): - Database Name: "Job Applications" - Properties: * Candidate Name (Title) * Email (Email) * Phone (Phone) * Role Category (Select: Software, Business, Sales, Marketing, Operations) * Application Date (Date) * Resume Content (Rich Text) * Skills (Multi-select) * Experience Level (Select: Entry, Mid, Senior) * Status (Select: New, Reviewed, Tasks Sent, In Progress, Completed) * Task 1 Title (Text) * Task 1 Type (Select: Technical Challenge, Case Study, Presentation, Assessment, Interview Prep) * Task 1 Deadline (Date) * Task 1 Instructions (Text) * Task 2 Title (Text) * Task 2 Type (Select: Technical Challenge, Case Study, Presentation, Assessment, Interview Prep) * Task 2 Deadline (Date) * Task 2 Instructions (Text) * Task 3 Title (Text) * Task 3 Type (Select: Technical Challenge, Case Study, Presentation, Assessment, Interview Prep) * Task 3 Deadline (Date) * Task 3 Instructions (Text) WORKFLOW: 1. Fetch emails with subjects containing: "application", "resume", "job", "position", "opportunity", "applying for" 2. Extract resume content from email body (handle PDF attachments if possible) 3. Use GPT-4 to structure the resume data and categorize the role 4. Generate 3 personalized tasks based on role category and candidate skills 5. Create Notion page for candidate with all extracted info and empty task fields 6. Update the same page with generated task information (embedded approach) 7. Send automated email with task instructions and next steps ENVIRONMENT VARIABLES NEEDED: - GMAIL_CONNECTION_KEY - NOTION_CONNECTION_KEY - OPENAI_API_KEY - PICA_API_KEY Make the system intelligent enough to: - Detect job role category from resume content - Generate role-appropriate tasks (coding challenges for software, case studies for business, etc.) - Handle different resume formats and email structures - Store all information in a single Notion page for better organization - Provide comprehensive error handling and logging ``` The system stores tasks directly in the job application page, eliminating database relationship complexity. Copy this prompt to build the LangChain tool: ```markdown LangChain Tool Suite expandable theme={null} # LangChain HR Processing Tools Create a comprehensive LangChain tool suite for automated job application processing using Pica integrations. Build the following tools: CORE TOOLS: 1. JobApplicationEmailFetcher - LangChain tool that fetches Gmail emails from last 24 hours with job application keywords 2. ResumeContentExtractor - Tool that extracts structured resume data from email content 3. GPTResumeAnalyzer - Tool that uses OpenAI to analyze and categorize resume content 4. TaskGenerator - Tool that generates role-specific tasks based on candidate profile 5. NotionJobTracker - Tool that creates Notion pages with embedded task information 6. JobApplicationTaskUpdater - Tool that updates job application pages with task details 7. AutomatedEmailResponder - Tool that sends personalized response emails LANGCHAIN IMPLEMENTATION REQUIREMENTS: - Use LangChain's tool decorator and structured input/output schemas - Implement proper error handling with LangChain's error types - Use LangChain's memory system to track application processing state - Integrate with LangChain agents for orchestrating the workflow - Support streaming responses for real-time processing updates JOB ROLE CATEGORIZATION: - Software: Look for programming languages, frameworks, technical skills - Business: Look for MBA, business analysis, strategy, consulting keywords - Sales: Look for CRM, sales targets, client management, revenue keywords - Marketing: Look for digital marketing, campaigns, SEO, social media keywords - Operations: Look for process improvement, logistics, supply chain keywords SIMPLIFIED NOTION STRUCTURE (Single Database): Create one "Job Applications" database with embedded task fields: - Candidate information fields (name, email, phone, etc.) - Task 1 fields (title, type, deadline, instructions) - Task 2 fields (title, type, deadline, instructions) - Task 3 fields (title, type, deadline, instructions) - This eliminates complex database relationships and property matching issues TASK GENERATION BY ROLE: - Software: Coding challenge, system design, code review task - Business: Case study analysis, market research, strategy presentation - Sales: Sales pitch creation, CRM scenario, client outreach plan - Marketing: Campaign proposal, content creation, analytics interpretation - Operations: Process optimization, workflow design, efficiency analysis Use Pica integrations for Gmail, Notion, and email sending. The embedded task approach ensures no database relationship errors and simpler data management. ``` The LangChain tools use an embedded task structure for simplified data management and error-free processing. Copy this prompt to build the MCP server tool: ```markdown MCP Server expandable theme={null} # Complete MCP HR Processing Server Create a complete MCP (Model Context Protocol) server for automated job application processing with Pica integrations. The server should provide tools for the entire job application workflow using a simplified single-database approach. MCP SERVER STRUCTURE: - Server name: "job-application-processor" - Version: "1.0.0" - Description: "MCP server for automated job application processing with resume analysis and embedded task tracking" TOOLS TO IMPLEMENT: 1. fetch_job_emails - Fetch Gmail emails with job application indicators 2. extract_resume_data - Extract structured information from resume content 3. analyze_candidate_profile - Use GPT-4 to analyze and categorize candidates 4. generate_role_tasks - Create personalized tasks based on role and skills 5. create_notion_application - Create job application page with embedded task fields 6. update_application_tasks - Update the same page with generated task information 7. send_candidate_response - Send automated email with task instructions 8. update_application_status - Update Notion page status as process progresses SIMPLIFIED NOTION DATABASE DESIGN (Single Database): Main Database: "Job Applications" (No separate task database needed) Properties: - Candidate Name (title) - Email (email) - Phone (phone) - Role Category (select: Software, Business, Sales, Marketing, Operations, Other) - Application Date (date) - Resume Content (rich text) - Key Skills (multi-select) - Experience Level (select: Entry, Mid, Senior) - Status (select: New, Reviewed, Tasks Sent, In Progress, Completed) - Fit Score (number) Task Fields (Embedded in same database): - Task 1 Title (text) - Task 1 Type (select: Technical Challenge, Case Study, Presentation, Assessment, Interview Prep) - Task 1 Deadline (date) - Task 1 Instructions (text) - Task 2 Title (text) - Task 2 Type (select: Technical Challenge, Case Study, Presentation, Assessment, Interview Prep) - Task 2 Deadline (date) - Task 2 Instructions (text) - Task 3 Title (text) - Task 3 Type (select: Technical Challenge, Case Study, Presentation, Assessment, Interview Prep) - Task 3 Deadline (date) - Task 3 Instructions (text) ROLE-SPECIFIC TASK TEMPLATES: Software Roles: - Coding Challenge: "Complete a [language] coding challenge focusing on [specific skills from resume]" - System Design: "Design a scalable system for [relevant use case]" - Code Review: "Review and improve this code snippet with focus on [candidate's expertise area]" Business Roles: - Case Study: "Analyze this business scenario and provide strategic recommendations" - Market Analysis: "Research and present findings on [relevant industry] market trends" - Process Improvement: "Identify inefficiencies and propose solutions for this business process" Sales Roles: - Sales Pitch: "Create a pitch for [product] targeting [specific customer segment]" - CRM Strategy: "Design a customer acquisition strategy for [industry]" - Objection Handling: "Develop responses to common objections in [sales context]" WORKFLOW AUTOMATION: 1. Monitor Gmail for new applications (keywords: application, resume, applying, position, job, opportunity) 2. Extract candidate information using intelligent parsing 3. Use GPT-4 to categorize role and analyze qualifications 4. Generate 3 personalized tasks based on role category and candidate background 5. Create Notion application page with all candidate data and empty task fields 6. Update the same page with generated task information (no separate database needed) 7. Send automated email with task details and submission instructions 8. Update application status throughout the process ADVANTAGES OF EMBEDDED APPROACH: - No database relationship complexity - No property name mismatches between databases - Simpler API calls and error handling - All candidate information in one place - Easier to view and manage applications - Better performance (no cross-database queries) ERROR HANDLING: - Handle malformed emails gracefully - Provide fallback categorization for unclear roles - Retry mechanisms for API failures - Comprehensive logging for debugging - Validation for all extracted data - Simplified error tracking with single database ENVIRONMENT REQUIREMENTS: - PICA_API_KEY for Pica integration - GMAIL_CONNECTION_KEY for email access - NOTION_CONNECTION_KEY for database operations - OPENAI_API_KEY for resume analysis The MCP server should be production-ready with proper TypeScript types, comprehensive error handling, and detailed logging. The embedded task approach eliminates common Notion integration issues and provides a cleaner, more maintainable solution. ``` The MCP server uses embedded tasks in a single database, eliminating relationship complexity and ensuring reliable operation. ## Benefits **80% reduction in manual processing** Automate resume screening, candidate tracking, and initial communications **Standardized assessment process** AI-powered role categorization and task generation ensures fair, consistent candidate evaluation **Complete candidate lifecycle** From application to task completion, track every step in Notion with automated status updates **Improved candidate experience** Prompt, personalized responses with clear next steps and task instructions ## Expand Your HR Automation Ready to build more HR tools? Explore these additional integrations: Integrate with Calendly or Google Calendar for interview scheduling Get real-time notifications in Slack for new applications and task submissions 🚀 **Ready for more?** Browse our catalog of 25,000+ actions across 200+ integrations to expand your HR automation pipeline! [Explore All Integrations →](https://app.picaos.com/tools)