Build a LangChain QuickBooks Invoice Agent

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.

---
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<string, string> = {
'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<string, string> = {
'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

---

---
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

---