@withone/mcp 1.0.0 → 1.1.0

package/README.md

@@ -1,4 +1,4 @@
-<img src="https://assets.withone.ai/banners/mcp.png?v=1" alt="One MCP — Connect your agents to every app through a single MCP." style="border-radius: 5px;">
+<img src="https://assets.withone.ai/banners/mcp.png?v=3" alt="One MCP — Connect your agents to every app through a single MCP." style="border-radius: 5px;">
 
 <h3 align="center">One MCP Server</h3>
 
@@ -20,7 +20,7 @@
   <a href="https://npmjs.com/package/@withone/mcp"><img src="https://img.shields.io/npm/v/%40withone%2Fmcp" alt="npm version"></a>
 </p>
 
-Connect your AI agents to 250+ apps through a single [MCP](https://modelcontextprotocol.io) server. Search for actions, read documentation, and execute API calls across platforms, without having to manage OAuth tokens or API keys.
+Connect your AI agents to 500+ apps through a single [MCP](https://modelcontextprotocol.io) server. Search for actions, read documentation, and execute API calls across platforms, without having to manage OAuth tokens or API keys.
 
 ```bash
 npm install -g @withone/cli
@@ -31,7 +31,7 @@ That's it. The [One CLI](https://www.npmjs.com/package/@withone/cli) will prompt
 
 ## Capabilities
 
-- **250+ platforms.** Gmail, Slack, Shopify, HubSpot, Stripe, Linear, QuickBooks, and [more](https://app.withone.ai/tools).
+- **500+ platforms.** Gmail, Slack, Shopify, HubSpot, Stripe, Linear, QuickBooks, and [more](https://app.withone.ai/tools).
 - **Natural language execution.** "read my last gmail email", "send a message to #general on Slack"
 - **Code generation.** "build a form to send emails using Gmail", "create a dashboard that lists my Linear projects"
 - **No tool bloat.** Only 4 tools exposed regardless of how many platforms or actions you connect. Actions are search-based, so your agent's context window stays clean.
@@ -60,11 +60,36 @@ The server exposes four MCP tools:
 
 | Tool | Description |
 |------|-------------|
-| `list_one_integrations` | List available platforms and active connections |
+| `list_one_integrations` | List available platforms and active connections, each with the `access` it confers (full, methods, or specific actions) |
 | `search_one_platform_actions` | Search for actions on a specific platform |
 | `get_one_action_knowledge` | Get detailed documentation for an action |
 | `execute_one_action` | Execute an API action on a connected platform |
 
+## Remote MCP Server
+
+Prefer not to run anything locally? One hosts a remote MCP server at **`https://mcp.withone.ai/mcp`**. Point any MCP client that supports remote (HTTP) servers at that URL and authenticate with One via OAuth. There's no `npm install` and no `ONE_SECRET` to manage. You approve access in One's consent screen, where you can scope exactly which connections, actions, and permission levels the agent gets. Those choices are surfaced back to the agent through each connection's `access` field, so it knows what it can run without searching.
+
+### Clients with native remote support
+
+Add `https://mcp.withone.ai/mcp` as a remote (custom) MCP server and complete the OAuth prompt.
+
+### Clients without native remote support (Claude Desktop, etc.)
+
+Bridge to the remote server with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):
+
+```json
+{
+  "mcpServers": {
+    "one": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://mcp.withone.ai/mcp"]
+    }
+  }
+}
+```
+
+The first run opens a browser to authenticate and authorize. After that, the same four tools are available.
+
 ## Manual Installation
 
 If you prefer to configure the server manually instead of using `one init`, install the package directly:
@@ -115,6 +140,14 @@ ONE_KNOWLEDGE_AGENT=true
 
 All defaults preserve current behavior. If no access control env vars are set, the server starts with full access and all tools available.
 
+Whatever you configure here is surfaced back to the agent: `list_one_integrations` stamps each connection with an `access` field so the agent knows up front what it can run there, without spending a turn searching. It is one of:
+
+| `access` | When |
+|---|---|
+| `{ "policy": "full" }` | No action allowlist and `ONE_PERMISSIONS=admin` — every action is runnable. |
+| `{ "policy": "methods", "methods": ["GET", ...] }` | No action allowlist, but `ONE_PERMISSIONS` is `read`/`write` — only these HTTP methods are runnable. |
+| `{ "policy": "actions", "actions": [{ "actionId", "title", "method" }] }` | `ONE_ACTION_IDS` is set — exactly these actions (the ones on that connection's platform) are runnable, so no search is needed. |
+
 ## Manual Configuration
 
 If you used `one init`, the configuration below is already done for you. These examples are for reference or manual setups.
@@ -146,10 +179,6 @@ Add the following to your MCP config:
 }
 ```
 
-### Remote MCP Server
-
-The remote MCP server is available at [https://mcp.withone.ai](https://mcp.withone.ai).
-
 ### Docker
 
 ```bash

package/build/client.js

@@ -21,6 +21,7 @@ export class OneClient {
     connections = [];
     connectors = [];
     isInitialized = false;
+    allowedActionsCache = null;
     constructor(optionsOrSecret, baseUrl = "https://api.withone.ai") {
         if (typeof optionsOrSecret === 'string') {
             // Legacy constructor: (secret, baseUrl)
@@ -222,6 +223,44 @@ export class OneClient {
             throw error;
         }
     }
+    /**
+     * Resolves an allowlist of action ids to their metadata (title, method, and
+     * owning platform), so `list_one_integrations` can report each connection's
+     * enumerated actions. `"*"` (unrestricted) resolves to an empty list — there
+     * is no allowlist to enumerate. Ids that fail to resolve or carry no platform
+     * are skipped rather than failing the whole call. The result is cached: the
+     * allowlist is fixed for the process lifetime.
+     * @param actionIds - The configured `ONE_ACTION_IDS` allowlist
+     * @returns Resolved metadata for every enumerable allowed action
+     */
+    async resolveAllowedActions(actionIds) {
+        if (actionIds.includes("*")) {
+            return [];
+        }
+        if (this.allowedActionsCache) {
+            return this.allowedActionsCache;
+        }
+        const resolved = await Promise.all(actionIds.map(async (actionId) => {
+            try {
+                const action = await this.getActionDetails(actionId);
+                if (!action.connectionPlatform) {
+                    return null;
+                }
+                return {
+                    actionId,
+                    title: action.title,
+                    method: action.method,
+                    platform: action.connectionPlatform
+                };
+            }
+            catch (error) {
+                console.error(`Failed to resolve allowed action ${actionId}:`, error);
+                return null;
+            }
+        }));
+        this.allowedActionsCache = resolved.filter((a) => a !== null);
+        return this.allowedActionsCache;
+    }
     /**
      * Executes a passthrough request to a third-party API through One
      * @param args - The execution arguments containing all request details

package/build/helpers.js

@@ -148,3 +148,25 @@ export function isMethodAllowed(method, permissions) {
 export function isActionAllowed(actionId, allowedActionIds) {
     return allowedActionIds.includes("*") || allowedActionIds.includes(actionId);
 }
+/**
+ * What the current access config lets the agent run on a connection of
+ * `platform`, so `list_one_integrations` can surface it without a search.
+ * Mirrors the One core `resolve_connection_access` precedence:
+ * an action allowlist wins (report the enumerated actions on this platform),
+ * else a non-`admin` permission level reports its method set, else full.
+ * `resolvedAllowed` is the allowlisted actions already resolved to their
+ * metadata and method-filtered by the permission level.
+ */
+export function computeConnectionAccess(platform, permissions, allowedActionIds, resolvedAllowed) {
+    if (!allowedActionIds.includes("*")) {
+        const actions = resolvedAllowed
+            .filter(a => a.platform === platform)
+            .map(({ actionId, title, method }) => ({ actionId, title, method }));
+        return { policy: "actions", actions };
+    }
+    const methods = PERMISSION_METHODS[permissions];
+    if (methods !== null) {
+        return { policy: "methods", methods };
+    }
+    return { policy: "full" };
+}

package/build/index.js

@@ -11,7 +11,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { OneClient } from './client.js';
-import { buildActionKnowledgeWithGuidance, filterByPermissions, isMethodAllowed, isActionAllowed, } from './helpers.js';
+import { buildActionKnowledgeWithGuidance, filterByPermissions, isMethodAllowed, isActionAllowed, computeConnectionAccess, } from './helpers.js';
 import { listOneIntegrationsToolConfig, searchOnePlatformActionsToolConfig, getOneActionKnowledgeToolConfig, executeOneActionToolConfig } from './schemas.js';
 const SERVER_NAME = "one-mcp-server";
 const SERVER_VERSION = "1.0.0";
@@ -97,11 +97,17 @@ async function handleGetIntegrations(args) {
             const connectedPlatforms = new Set(activeConnections.map(conn => conn.platform));
             activePlatforms = activePlatforms.filter(def => connectedPlatforms.has(def.platform));
         }
+        // Resolve the action allowlist to per-platform metadata (method-filtered by
+        // the permission level) once, so each connection can report the exact
+        // actions it may run. Only needed when an action allowlist is set.
+        const resolvedAllowed = (await oneClient.resolveAllowedActions(ONE_ACTION_IDS))
+            .filter(action => isMethodAllowed(action.method, ONE_PERMISSIONS));
         const structuredResponse = {
             connections: activeConnections.map(conn => ({
                 platform: conn.platform,
                 key: conn.key,
-                tags: conn.tags ?? []
+                tags: conn.tags ?? [],
+                access: computeConnectionAccess(conn.platform, ONE_PERMISSIONS, ONE_ACTION_IDS, resolvedAllowed)
             })),
             availablePlatforms: activePlatforms.map(def => ({
                 platform: def.platform,

package/build/schemas.js

@@ -44,12 +44,30 @@ export const executeOneActionInputSchema = {
 /**
  * Output schemas for list_one_integrations tool
  */
+const connectionAccessSchema = z.union([
+    z.object({
+        policy: z.literal("full")
+    }),
+    z.object({
+        policy: z.literal("methods"),
+        methods: z.array(z.string())
+    }),
+    z.object({
+        policy: z.literal("actions"),
+        actions: z.array(z.object({
+            actionId: z.string(),
+            title: z.string(),
+            method: z.string()
+        }))
+    })
+]).describe("What the access config lets you run on this connection: `full`, an allowed `methods` set, or a specific `actions` list. When `actions`, those are exactly what may run, so no search is needed.");
 export const listOneIntegrationsOutputSchema = {
     connections: z.array(z.object({
         platform: z.string(),
         key: z.string(),
-        tags: z.array(z.string())
-    })).describe("Array of user's active connections"),
+        tags: z.array(z.string()),
+        access: connectionAccessSchema
+    })).describe("Array of user's active connections, each with the access the current config confers"),
     availablePlatforms: z.array(z.object({
         platform: z.string(),
         name: z.string(),
@@ -81,7 +99,7 @@ export const searchOnePlatformActionsOutputSchema = {
  */
 export const listOneIntegrationsToolConfig = {
     title: "List One Integrations",
-    description: "List all available One integrations and platforms. ALWAYS call this tool first in any workflow to discover what platforms and connections are available. This returns the connections that the user has and all available One platforms in kebab-case format (e.g., 'ship-station', 'shopify') which you'll need for subsequent tool calls.",
+    description: "List all available One integrations and platforms. ALWAYS call this tool first in any workflow to discover what platforms and connections are available. This returns the connections that the user has and all available One platforms in kebab-case format (e.g., 'ship-station', 'shopify') which you'll need for subsequent tool calls. Each connection carries an `access` field describing what you may run on it: `full`, a set of allowed HTTP `methods`, or a specific list of `actions` (each with `actionId`, `title`, `method`). When a connection is action-scoped, its `actions` are exactly what may run, so you need not search.",
     inputSchema: listOneIntegrationsInputSchema,
     outputSchema: listOneIntegrationsOutputSchema
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A Model Context Protocol Server for One",
   "type": "module",
   "bin": {

package/build/client.d.ts

@@ -1,102 +0,0 @@
-/**
- * Pica API Client
- *
- * This module provides a TypeScript client for interacting with the Pica API.
- *
- * @fileoverview Pica API client with authentication and data management
- * @author Pica
- */
-import { Connection, ConnectionDefinition, AvailableAction, ActionDetails, GetPicaActionKnowledgeResponse, ExecutePicaActionArgs, ExecutePassthroughResponse } from './types.js';
-export type IdentityType = 'user' | 'team' | 'organization' | 'project';
-export interface PicaClientOptions {
-    secret: string;
-    baseUrl?: string;
-    identity?: string;
-    identityType?: IdentityType;
-    connectionKeys?: string[];
-}
-/**
- * Client for interacting with the Pica API
- */
-export declare class PicaClient {
-    private readonly secret;
-    private readonly baseUrl;
-    private readonly identity?;
-    private readonly identityType?;
-    private readonly connectionKeys?;
-    private connections;
-    private connectors;
-    private isInitialized;
-    constructor(options: PicaClientOptions);
-    constructor(secret: string, baseUrl?: string);
-    /**
-     * Initializes the client by fetching connections and available connectors
-     * @throws {Error} If initialization fails completely
-     */
-    initialize(): Promise<void>;
-    /**
-     * Generates standard headers for API requests
-     */
-    generateHeaders(): Record<string, string>;
-    /**
-     * Fetches user connections from the API
-     */
-    private fetchConnections;
-    /**
-     * Fetches available connection definitions from the API
-     */
-    private fetchConnectionDefinitions;
-    /**
-     * Searches for actions on a specific platform using a query
-     * @param platform - The platform name to search actions for
-     * @param query - The search query to find relevant actions
-     * @param agentType - The type of agent context (execute or knowledge)
-     * @returns Array of top 5 most relevant actions for the platform
-     * @throws {Error} If platform or query is not provided or API request fails
-     */
-    searchAvailableActions(platform: string, query: string, agentType?: "execute" | "knowledge"): Promise<AvailableAction[]>;
-    /**
-     * Gets full action details by ID
-     * @param actionId - The action ID to get details for
-     * @returns The full action object
-     * @throws {Error} If action ID is not provided or API request fails
-     */
-    getActionDetails(actionId: string): Promise<ActionDetails>;
-    /**
-     * Gets knowledge for a specific action by ID
-     * @param actionId - The action ID to get knowledge for
-     * @returns The knowledge string for the action
-     * @throws {Error} If action ID is not provided or API request fails
-     */
-    getActionKnowledge(actionId: string): Promise<GetPicaActionKnowledgeResponse>;
-    /**
-     * Executes a passthrough request to a third-party API through Pica
-     * @param args - The execution arguments containing all request details
-     * @returns Object containing sanitized request config and response data
-     * @throws {Error} If the request fails
-     */
-    executePassthroughRequest(args: ExecutePicaActionArgs, preloadedAction?: ActionDetails): Promise<ExecutePassthroughResponse>;
-    /**
-     * Gets the base URL for the Pica API
-     * @returns The base URL for the Pica API
-     */
-    getBaseUrl(): string;
-    /**
-     * Gets the current user's connections
-     * @returns Array of user connections
-     */
-    getUserConnections(): Connection[];
-    /**
-     * Gets available connectors/platforms
-     * @returns Array of available connection definitions
-     */
-    getAvailableConnectors(): ConnectionDefinition[];
-    /**
-     * Checks if the client has been initialized
-     */
-    isClientInitialized(): boolean;
-    /**
-     * Refreshes connections and connectors data
-     */
-    refresh(): Promise<void>;
-}

package/build/helpers.d.ts

@@ -1,53 +0,0 @@
-/**
- * Utility Helper Functions
- *
- * This module contains reusable utility functions used throughout the Pica MCP server.
- *
- * @fileoverview Utility functions for data processing and API interactions
- * @author Pica
- */
-import { PermissionLevel } from './types.js';
-/**
- * Paginates through API results by repeatedly calling a fetch function until all data is retrieved.
- * @param fetchFn - Function that fetches paginated data, takes skip and limit parameters
- * @param limit - Maximum number of items to fetch per request (default: 100)
- * @returns Promise that resolves to an array of all paginated results
- */
-export declare function paginateResults<T>(fetchFn: (skip: number, limit: number) => Promise<{
-    rows: T[];
-    total: number;
-    skip: number;
-    limit: number;
-}>, limit?: number): Promise<T[]>;
-/**
- * Generic function to fetch paginated data from any API endpoint
- * @param baseUrl - The base URL for the API endpoint (without query parameters)
- * @param headers - Headers to include in the request
- * @param additionalParams - Optional additional parameters to include in the request
- * @returns Promise that resolves to an array of all paginated results
- */
-export declare function fetchPaginatedData<T>(baseUrl: string, headers: Record<string, string>, additionalParams?: Record<string, string | number | boolean>): Promise<T[]>;
-/**
- * Builds action knowledge with API request structure guidance.
- * @param knowledge - The raw knowledge content for the action
- * @param method - The HTTP method for the action
- * @param baseUrl - The base URL for Pica API
- * @param platform - The platform name (used for connection key)
- * @param actionId - The action ID
- * @returns Complete formatted knowledge with API guidance
- */
-export declare function buildActionKnowledgeWithGuidance(knowledge: string, method: string, baseUrl: string, platform: string, actionId: string): string;
-/**
- * Replaces path variables in a template string with actual values.
- * Path variables can be in either format: {variableName} or {{variableName}} and will be replaced with corresponding values.
- * @param path - The template string containing path variables in {variableName} or {{variableName}} format
- * @param variables - Object containing variable names as keys and their replacement values
- * @returns The path string with all variables replaced by their encoded values
- * @throws Error if any required variable is missing, null, undefined, or empty string
- */
-export declare function replacePathVariables(path: string, variables: Record<string, string | number | boolean>): string;
-export declare function filterByPermissions<T extends {
-    method: string;
-}>(actions: T[], permissions: PermissionLevel): T[];
-export declare function isMethodAllowed(method: string, permissions: PermissionLevel): boolean;
-export declare function isActionAllowed(actionId: string, allowedActionIds: string[]): boolean;

package/build/index.d.ts

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-/**
- * Pica MCP Server - Main Entry Point
- *
- * This is the main MCP (Model Context Protocol) server implementation for Pica.
- *
- * @fileoverview Main MCP server implementation with Pica API integration
- * @author Pica
- */
-export { createPicaServer, type CreatePicaServerOptions } from './server.js';

package/build/schemas.d.ts

@@ -1,285 +0,0 @@
-/**
- * MCP Tool Schemas
- *
- * This file contains all tool schema definitions for MCP tools using zod.
- * Centralizing schemas here improves maintainability and reusability.
- *
- * @fileoverview Complete tool schema definitions for all MCP tools
- * @author Pica
- */
-import { z } from 'zod';
-/**
- * Schema for listing Pica integrations (no parameters required)
- */
-export declare const listPicaIntegrationsInputSchema: {};
-/**
- * Schema for searching platform actions
- */
-export declare const searchPicaPlatformActionsInputSchema: {
-    platform: z.ZodString;
-    query: z.ZodString;
-    agentType: z.ZodOptional<z.ZodEnum<["execute", "knowledge"]>>;
-};
-/**
- * Schema for getting action knowledge
- */
-export declare const getPicaActionKnowledgeInputSchema: {
-    actionId: z.ZodString;
-    platform: z.ZodString;
-};
-/**
- * Schema for executing Pica actions
- */
-export declare const executePicaActionInputSchema: {
-    platform: z.ZodString;
-    actionId: z.ZodString;
-    connectionKey: z.ZodString;
-    data: z.ZodOptional<z.ZodAny>;
-    pathVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
-    queryParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
-    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    isFormData: z.ZodOptional<z.ZodBoolean>;
-    isFormUrlEncoded: z.ZodOptional<z.ZodBoolean>;
-};
-/**
- * Output schemas for list_pica_integrations tool
- */
-export declare const listPicaIntegrationsOutputSchema: {
-    connections: z.ZodArray<z.ZodObject<{
-        platform: z.ZodString;
-        key: z.ZodString;
-        tags: z.ZodArray<z.ZodString, "many">;
-    }, "strip", z.ZodTypeAny, {
-        key: string;
-        platform: string;
-        tags: string[];
-    }, {
-        key: string;
-        platform: string;
-        tags: string[];
-    }>, "many">;
-    availablePlatforms: z.ZodArray<z.ZodObject<{
-        platform: z.ZodString;
-        name: z.ZodString;
-        category: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        platform: string;
-        name: string;
-        category: string;
-    }, {
-        platform: string;
-        name: string;
-        category: string;
-    }>, "many">;
-    summary: z.ZodObject<{
-        connectedCount: z.ZodNumber;
-        availableCount: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        connectedCount: number;
-        availableCount: number;
-    }, {
-        connectedCount: number;
-        availableCount: number;
-    }>;
-};
-/**
- * Output schemas for search_pica_platform_actions tool
- */
-export declare const searchPicaPlatformActionsOutputSchema: {
-    actions: z.ZodArray<z.ZodObject<{
-        actionId: z.ZodString;
-        title: z.ZodString;
-        method: z.ZodString;
-        path: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        method: string;
-        actionId: string;
-        path: string;
-        title: string;
-    }, {
-        method: string;
-        actionId: string;
-        path: string;
-        title: string;
-    }>, "many">;
-    metadata: z.ZodObject<{
-        platform: z.ZodString;
-        query: z.ZodString;
-        count: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        query: string;
-        platform: string;
-        count: number;
-    }, {
-        query: string;
-        platform: string;
-        count: number;
-    }>;
-};
-/**
- * Tool configuration objects for registerTool
- */
-export declare const listPicaIntegrationsToolConfig: {
-    title: string;
-    description: string;
-    inputSchema: {};
-    outputSchema: {
-        connections: z.ZodArray<z.ZodObject<{
-            platform: z.ZodString;
-            key: z.ZodString;
-            tags: z.ZodArray<z.ZodString, "many">;
-        }, "strip", z.ZodTypeAny, {
-            key: string;
-            platform: string;
-            tags: string[];
-        }, {
-            key: string;
-            platform: string;
-            tags: string[];
-        }>, "many">;
-        availablePlatforms: z.ZodArray<z.ZodObject<{
-            platform: z.ZodString;
-            name: z.ZodString;
-            category: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
-            platform: string;
-            name: string;
-            category: string;
-        }, {
-            platform: string;
-            name: string;
-            category: string;
-        }>, "many">;
-        summary: z.ZodObject<{
-            connectedCount: z.ZodNumber;
-            availableCount: z.ZodNumber;
-        }, "strip", z.ZodTypeAny, {
-            connectedCount: number;
-            availableCount: number;
-        }, {
-            connectedCount: number;
-            availableCount: number;
-        }>;
-    };
-};
-export declare const searchPicaPlatformActionsToolConfig: {
-    title: string;
-    description: string;
-    inputSchema: {
-        platform: z.ZodString;
-        query: z.ZodString;
-        agentType: z.ZodOptional<z.ZodEnum<["execute", "knowledge"]>>;
-    };
-    outputSchema: {
-        actions: z.ZodArray<z.ZodObject<{
-            actionId: z.ZodString;
-            title: z.ZodString;
-            method: z.ZodString;
-            path: z.ZodString;
-        }, "strip", z.ZodTypeAny, {
-            method: string;
-            actionId: string;
-            path: string;
-            title: string;
-        }, {
-            method: string;
-            actionId: string;
-            path: string;
-            title: string;
-        }>, "many">;
-        metadata: z.ZodObject<{
-            platform: z.ZodString;
-            query: z.ZodString;
-            count: z.ZodNumber;
-        }, "strip", z.ZodTypeAny, {
-            query: string;
-            platform: string;
-            count: number;
-        }, {
-            query: string;
-            platform: string;
-            count: number;
-        }>;
-    };
-};
-export declare const getPicaActionKnowledgeToolConfig: {
-    title: string;
-    description: string;
-    inputSchema: {
-        actionId: z.ZodString;
-        platform: z.ZodString;
-    };
-};
-export declare const executePicaActionToolConfig: {
-    title: string;
-    description: string;
-    inputSchema: {
-        platform: z.ZodString;
-        actionId: z.ZodString;
-        connectionKey: z.ZodString;
-        data: z.ZodOptional<z.ZodAny>;
-        pathVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
-        queryParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
-        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-        isFormData: z.ZodOptional<z.ZodBoolean>;
-        isFormUrlEncoded: z.ZodOptional<z.ZodBoolean>;
-    };
-};
-/**
- * Zod object schemas for type inference (for internal use)
- */
-export declare const listPicaIntegrationsZodSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
-export declare const searchPicaPlatformActionsZodSchema: z.ZodObject<{
-    platform: z.ZodString;
-    query: z.ZodString;
-    agentType: z.ZodOptional<z.ZodEnum<["execute", "knowledge"]>>;
-}, "strip", z.ZodTypeAny, {
-    query: string;
-    platform: string;
-    agentType?: "execute" | "knowledge" | undefined;
-}, {
-    query: string;
-    platform: string;
-    agentType?: "execute" | "knowledge" | undefined;
-}>;
-export declare const getPicaActionKnowledgeZodSchema: z.ZodObject<{
-    actionId: z.ZodString;
-    platform: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    actionId: string;
-    platform: string;
-}, {
-    actionId: string;
-    platform: string;
-}>;
-export declare const executePicaActionZodSchema: z.ZodObject<{
-    platform: z.ZodString;
-    actionId: z.ZodString;
-    connectionKey: z.ZodString;
-    data: z.ZodOptional<z.ZodAny>;
-    pathVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
-    queryParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
-    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    isFormData: z.ZodOptional<z.ZodBoolean>;
-    isFormUrlEncoded: z.ZodOptional<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    actionId: string;
-    connectionKey: string;
-    platform: string;
-    headers?: Record<string, string> | undefined;
-    data?: any;
-    pathVariables?: Record<string, string | number | boolean> | undefined;
-    queryParams?: Record<string, any> | undefined;
-    isFormData?: boolean | undefined;
-    isFormUrlEncoded?: boolean | undefined;
-}, {
-    actionId: string;
-    connectionKey: string;
-    platform: string;
-    headers?: Record<string, string> | undefined;
-    data?: any;
-    pathVariables?: Record<string, string | number | boolean> | undefined;
-    queryParams?: Record<string, any> | undefined;
-    isFormData?: boolean | undefined;
-    isFormUrlEncoded?: boolean | undefined;
-}>;

package/build/server.d.ts

@@ -1,27 +0,0 @@
-/**
- * Pica MCP Server Factory
- *
- * Exports a factory function that registers all Pica tools on a provided McpServer instance.
- *
- * @fileoverview createPicaServer() factory for reuse across stdio and HTTP transports
- * @author Pica
- */
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { PermissionLevel } from './types.js';
-export interface CreatePicaServerOptions {
-    secret: string;
-    baseUrl?: string;
-    identity?: string;
-    identityType?: 'user' | 'team' | 'organization' | 'project';
-    permissions?: PermissionLevel;
-    connectionKeys?: string[];
-    actionIds?: string[];
-    knowledgeAgent?: boolean;
-}
-/**
- * Registers all Pica MCP tools on the provided server instance.
- *
- * @param server - An McpServer instance to register tools on
- * @param options - Configuration options (secret is required, rest have sensible defaults)
- */
-export declare function createPicaServer(server: McpServer, options: CreatePicaServerOptions): Promise<void>;

package/build/server.js

@@ -1,215 +0,0 @@
-/**
- * Pica MCP Server Factory
- *
- * Exports a factory function that registers all Pica tools on a provided McpServer instance.
- *
- * @fileoverview createPicaServer() factory for reuse across stdio and HTTP transports
- * @author Pica
- */
-import { ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
-import { PicaClient } from './client.js';
-import { buildActionKnowledgeWithGuidance, filterByPermissions, isMethodAllowed, isActionAllowed, } from './helpers.js';
-import { listPicaIntegrationsToolConfig, searchPicaPlatformActionsToolConfig, getPicaActionKnowledgeToolConfig, executePicaActionToolConfig, } from './schemas.js';
-/**
- * Registers all Pica MCP tools on the provided server instance.
- *
- * @param server - An McpServer instance to register tools on
- * @param options - Configuration options (secret is required, rest have sensible defaults)
- */
-export async function createPicaServer(server, options) {
-    const { secret, baseUrl, identity, identityType, permissions = 'admin', connectionKeys = ['*'], actionIds = ['*'], knowledgeAgent = false, } = options;
-    const picaClient = new PicaClient({
-        secret,
-        baseUrl,
-        identity,
-        identityType,
-        connectionKeys,
-    });
-    let picaInitialized = false;
-    let initializationPromise = null;
-    const initializePica = async () => {
-        if (picaInitialized) {
-            return;
-        }
-        if (initializationPromise) {
-            return initializationPromise;
-        }
-        initializationPromise = (async () => {
-            try {
-                await picaClient.initialize();
-                picaInitialized = true;
-            }
-            catch (error) {
-                console.error("Failed to initialize Pica client:", error);
-                initializationPromise = null;
-                throw error;
-            }
-        })();
-        return initializationPromise;
-    };
-    // --- Tool handlers ---
-    async function handleGetIntegrations(_args) {
-        try {
-            const connectedIntegrations = picaClient.getUserConnections();
-            const availableIntegrations = picaClient.getAvailableConnectors();
-            const activeConnections = connectedIntegrations.filter(conn => conn.active);
-            let activePlatforms = availableIntegrations.filter(def => def.active && !def.deprecated);
-            if (!connectionKeys.includes("*")) {
-                const connectedPlatforms = new Set(activeConnections.map(conn => conn.platform));
-                activePlatforms = activePlatforms.filter(def => connectedPlatforms.has(def.platform));
-            }
-            const structuredResponse = {
-                connections: activeConnections.map(conn => ({
-                    platform: conn.platform,
-                    key: conn.key,
-                    tags: conn.tags ?? [],
-                })),
-                availablePlatforms: activePlatforms.map(def => ({
-                    platform: def.platform,
-                    name: def.name,
-                    category: def.category,
-                })),
-                summary: {
-                    connectedCount: activeConnections.length,
-                    availableCount: activePlatforms.length,
-                },
-            };
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(structuredResponse, null, 2),
-                    },
-                ],
-                structuredContent: structuredResponse,
-            };
-        }
-        catch (error) {
-            throw new McpError(ErrorCode.InternalError, `Failed to retrieve integrations: ${error instanceof Error ? error.message : 'Unknown error'}`);
-        }
-    }
-    async function handleSearchPlatformActions(args) {
-        try {
-            const agentType = knowledgeAgent ? "knowledge" : args.agentType;
-            let actions = await picaClient.searchAvailableActions(args.platform, args.query, agentType);
-            actions = filterByPermissions(actions, permissions);
-            actions = actions.filter(a => isActionAllowed(a.systemId, actionIds));
-            const cleanedActions = actions.map(action => ({
-                actionId: action.systemId,
-                title: action.title,
-                method: action.method,
-                path: action.path,
-            }));
-            if (cleanedActions.length === 0) {
-                const suggestionsText = `No actions found for platform '${args.platform}' matching query '${args.query}'.
-
-SUGGESTIONS:
-- Try a more general query (e.g., 'list', 'get', 'search', 'create')
-- Verify the platform name is correct
-- Check that actions exist for this platform using list_pica_integrations
-
-EXAMPLES OF GOOD QUERIES:
-- "search contacts"
-- "send email"
-- "create customer"
-- "list orders"`;
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: suggestionsText,
-                        },
-                    ],
-                };
-            }
-            const structuredResponse = {
-                actions: cleanedActions,
-                metadata: {
-                    platform: args.platform,
-                    query: args.query,
-                    count: cleanedActions.length,
-                },
-            };
-            const responseText = `Found ${cleanedActions.length} action(s) for platform '${args.platform}' matching query '${args.query}':
-
-${JSON.stringify(structuredResponse, null, 2)}
-
-NEXT STEP: Use get_pica_action_knowledge with an actionId to get detailed documentation before building requests or executing actions.`;
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: responseText,
-                    },
-                ],
-                structuredContent: structuredResponse,
-            };
-        }
-        catch (error) {
-            throw new McpError(ErrorCode.InternalError, `Failed to search platform actions: ${error instanceof Error ? error.message : 'Unknown error'}`);
-        }
-    }
-    async function handleGetActionKnowledge(args) {
-        try {
-            const actionId = args.actionId;
-            if (!isActionAllowed(actionId, actionIds)) {
-                throw new McpError(ErrorCode.InvalidRequest, `Action "${actionId}" is not in the allowed action list`);
-            }
-            const { knowledge, method } = await picaClient.getActionKnowledge(actionId);
-            const knowledgeWithGuidance = buildActionKnowledgeWithGuidance(knowledge, method, picaClient.getBaseUrl(), args.platform, actionId);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: knowledgeWithGuidance,
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            throw new McpError(ErrorCode.InternalError, `Failed to retrieve action knowledge: ${error instanceof Error ? error.message : 'Unknown error'}`);
-        }
-    }
-    async function handleExecutePicaAction(args) {
-        try {
-            if (!isActionAllowed(args.actionId, actionIds)) {
-                throw new McpError(ErrorCode.InvalidRequest, `Action "${args.actionId}" is not in the allowed action list`);
-            }
-            const actionDetails = await picaClient.getActionDetails(args.actionId);
-            if (!isMethodAllowed(actionDetails.method, permissions)) {
-                throw new McpError(ErrorCode.InvalidRequest, `Method "${actionDetails.method}" is not allowed under "${permissions}" permission level`);
-            }
-            const result = await picaClient.executePassthroughRequest(args, actionDetails);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(result, null, 2),
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            throw new McpError(ErrorCode.InternalError, `Failed to execute Pica action: ${error instanceof Error ? error.message : 'Unknown error'}`);
-        }
-    }
-    // --- Register tools ---
-    server.registerTool("list_pica_integrations", listPicaIntegrationsToolConfig, async (args) => {
-        await initializePica();
-        return await handleGetIntegrations(args);
-    });
-    server.registerTool("search_pica_platform_actions", searchPicaPlatformActionsToolConfig, async (args) => {
-        await initializePica();
-        return await handleSearchPlatformActions(args);
-    });
-    server.registerTool("get_pica_action_knowledge", getPicaActionKnowledgeToolConfig, async (args) => {
-        await initializePica();
-        return await handleGetActionKnowledge(args);
-    });
-    if (!knowledgeAgent) {
-        server.registerTool("execute_pica_action", executePicaActionToolConfig, async (args) => {
-            await initializePica();
-            return await handleExecutePicaAction(args);
-        });
-    }
-}

package/build/types.d.ts

@@ -1,182 +0,0 @@
-/**
- * Type definitions for the Pica MCP Server
- *
- * This file contains all TypeScript interfaces and types used throughout the application.
- *
- * @fileoverview Core type definitions for Pica API integration
- * @author Pica
- */
-/**
- * API response structure for paginated endpoints
- */
-export interface PaginatedResponse<T> {
-    rows: T[];
-    total: number;
-    skip: number;
-    limit: number;
-}
-/**
- * Definition of an available platform/connector that users can connect to
- */
-export interface ConnectionDefinition {
-    name: string;
-    key: string;
-    platform: string;
-    platformVersion: string;
-    description: string;
-    category: string;
-    image: string;
-    tags: string[];
-    oauth: boolean;
-    createdAt: number;
-    updatedAt: number;
-    version: string;
-    active: boolean;
-    deprecated: boolean;
-}
-/**
- * Represents an active user connection to a platform
- */
-export interface Connection {
-    key: string;
-    platform: string;
-    tags: string[];
-    active: boolean;
-}
-/**
- * Available action from search endpoint (uses systemId)
- */
-export interface AvailableAction {
-    systemId: string;
-    title: string;
-    tags?: string[];
-    knowledge?: string;
-    path: string;
-    method: string;
-}
-/**
- * Action details from knowledge endpoint (uses _id)
- */
-export interface ActionDetails {
-    _id: string;
-    title: string;
-    tags?: string[];
-    knowledge?: string;
-    path: string;
-    method: string;
-}
-/**
- * Arguments for list_pica_integrations tool
- */
-export interface ListPicaIntegrationsArgs {
-}
-/**
- * Arguments for search_pica_platform_actions tool
- */
-export interface SearchPicaPlatformActionsArgs {
-    platform: string;
-    query: string;
-    agentType?: "execute" | "knowledge";
-}
-/**
- * Arguments for get_pica_action_knowledge tool
- */
-export interface GetPicaActionKnowledgeArgs {
-    actionId: string;
-    platform: string;
-}
-/**
- * Response for get_pica_action_knowledge tool
- */
-export interface GetPicaActionKnowledgeResponse {
-    knowledge: string;
-    method: string;
-}
-/**
- * Action object structure for create_pica_request tool
- */
-export interface ActionObject {
-    _id: string;
-    path: string;
-    method: string;
-    tags?: string[];
-}
-/**
- * Arguments for create_pica_request tool
- */
-export interface ExecutePicaActionArgs {
-    platform: string;
-    actionId: string;
-    connectionKey: string;
-    data?: any;
-    pathVariables?: Record<string, string | number | boolean>;
-    queryParams?: Record<string, any>;
-    headers?: Record<string, any>;
-    isFormData?: boolean;
-    isFormUrlEncoded?: boolean;
-}
-/**
- * HTTP request configuration for axios
- */
-export interface RequestConfig {
-    url: string;
-    method: string;
-    headers: Record<string, string>;
-    params?: Record<string, string>;
-    data?: unknown;
-}
-/**
- * Sanitized version of request config with sensitive data redacted
- */
-export interface SanitizedRequestConfig {
-    url: string;
-    method: string;
-    headers: Record<string, string>;
-    params?: Record<string, string>;
-    data?: unknown;
-}
-/**
- * Response from executePassthroughRequest
- */
-export interface ExecutePassthroughResponse {
-    requestConfig: SanitizedRequestConfig;
-    responseData: unknown;
-}
-/**
- * Structured response for list_pica_integrations tool
- */
-export interface ListIntegrationsResponse {
-    [x: string]: unknown;
-    connections: Array<{
-        platform: string;
-        key: string;
-        tags: string[];
-    }>;
-    availablePlatforms: Array<{
-        platform: string;
-        name: string;
-        category: string;
-    }>;
-    summary: {
-        connectedCount: number;
-        availableCount: number;
-    };
-}
-/**
- * Structured response for search_pica_platform_actions tool
- */
-export interface SearchActionsResponse {
-    [x: string]: unknown;
-    actions: Array<{
-        actionId: string;
-        title: string;
-        method: string;
-        path: string;
-    }>;
-    metadata: {
-        platform: string;
-        query: string;
-        count: number;
-    };
-}
-export type PermissionLevel = "read" | "write" | "admin";