@withone/mcp 1.0.0

package/build/helpers.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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/helpers.js

@@ -0,0 +1,150 @@
+/**
+ * Utility Helper Functions
+ *
+ * This module contains reusable utility functions used throughout the One MCP server.
+ *
+ * @fileoverview Utility functions for data processing and API interactions
+ * @author One
+ */
+import axios from 'axios';
+/**
+ * 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 async function paginateResults(fetchFn, limit = 100) {
+    let page = 1;
+    let allResults = [];
+    let total = 0;
+    try {
+        do {
+            const response = await fetchFn(page, limit);
+            const { rows, total: totalCount } = response;
+            total = totalCount;
+            allResults = [...allResults, ...rows];
+            page++;
+        } while (allResults.length < total);
+        return allResults;
+    }
+    catch (error) {
+        console.error("Error in pagination:", error);
+        throw error;
+    }
+}
+/**
+ * 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 async function fetchPaginatedData(baseUrl, headers, additionalParams) {
+    const fetchFn = async (page, limit) => {
+        const params = {
+            page,
+            limit,
+            ...additionalParams
+        };
+        try {
+            const response = await axios.get(baseUrl, {
+                headers,
+                params
+            });
+            return response.data;
+        }
+        catch (error) {
+            console.error(`Failed to fetch from ${baseUrl}:`, error);
+            throw error;
+        }
+    };
+    return paginateResults(fetchFn);
+}
+/**
+ * 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 One API
+ * @param platform - The platform name (used for connection key)
+ * @param actionId - The action ID
+ * @returns Complete formatted knowledge with API guidance
+ */
+export function buildActionKnowledgeWithGuidance(knowledge, method, baseUrl, platform, actionId) {
+    const cleanBaseUrl = baseUrl.replace(/\/$/, '');
+    return `${knowledge}
+
+API REQUEST STRUCTURE
+======================
+URL: ${cleanBaseUrl}/v1/passthrough/{{PATH}}
+
+IMPORTANT: When constructing the URL, only include the API endpoint path after the base URL.
+Do NOT include the full third-party API URL.
+
+Examples:
+✅ Correct: ${cleanBaseUrl}/v1/passthrough/crm/v3/objects/contacts/search
+❌ Incorrect: ${cleanBaseUrl}/v1/passthrough/https://api.hubapi.com/crm/v3/objects/contacts/search
+
+METHOD: ${method}
+
+HEADERS:
+- x-one-secret: {{process.env.ONE_SECRET}}
+- x-one-connection-key: {{process.env.ONE_${platform.toUpperCase()}_CONNECTION_KEY}}
+- x-one-action-id: ${actionId}
+- ... (other headers)
+
+BODY: {{BODY}}
+
+QUERY PARAMS: {{QUERY_PARAMS}}`;
+}
+/**
+ * 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 function replacePathVariables(path, variables) {
+    if (!path)
+        return path;
+    let result = path;
+    // First, replace double bracket variables {{variableName}}
+    result = result.replace(/\{\{([^}]+)\}\}/g, (match, variable) => {
+        const trimmedVariable = variable.trim();
+        const value = variables[trimmedVariable];
+        if (value === undefined || value === null || value === '') {
+            throw new Error(`Missing value for path variable: ${trimmedVariable}`);
+        }
+        return encodeURIComponent(value.toString());
+    });
+    // Then, replace single bracket variables {variableName}
+    result = result.replace(/\{([^}]+)\}/g, (match, variable) => {
+        const trimmedVariable = variable.trim();
+        const value = variables[trimmedVariable];
+        if (value === undefined || value === null || value === '') {
+            throw new Error(`Missing value for path variable: ${trimmedVariable}`);
+        }
+        return encodeURIComponent(value.toString());
+    });
+    return result;
+}
+const PERMISSION_METHODS = {
+    read: ["GET"],
+    write: ["GET", "POST", "PUT", "PATCH"],
+    admin: null,
+};
+export function filterByPermissions(actions, permissions) {
+    const allowed = PERMISSION_METHODS[permissions];
+    if (allowed === null)
+        return actions;
+    return actions.filter((a) => allowed.includes(a.method.toUpperCase()));
+}
+export function isMethodAllowed(method, permissions) {
+    const allowed = PERMISSION_METHODS[permissions];
+    if (allowed === null)
+        return true;
+    return allowed.includes(method.toUpperCase());
+}
+export function isActionAllowed(actionId, allowedActionIds) {
+    return allowedActionIds.includes("*") || allowedActionIds.includes(actionId);
+}

package/build/index.d.ts

@@ -0,0 +1,10 @@
+#!/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/index.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * One MCP Server - Main Entry Point
+ *
+ * This is the main MCP (Model Context Protocol) server implementation for One.
+ *
+ * @fileoverview Main MCP server implementation with One API integration
+ * @author One
+ */
+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 { listOneIntegrationsToolConfig, searchOnePlatformActionsToolConfig, getOneActionKnowledgeToolConfig, executeOneActionToolConfig } from './schemas.js';
+const SERVER_NAME = "one-mcp-server";
+const SERVER_VERSION = "1.0.0";
+const ONE_SECRET = process.env.ONE_SECRET;
+if (!ONE_SECRET) {
+    console.error("ONE_SECRET environment variable is required");
+    process.exit(1);
+}
+const ONE_BASE_URL = process.env.ONE_BASE_URL || "https://api.withone.ai";
+const ONE_IDENTITY = process.env.ONE_IDENTITY;
+const ONE_IDENTITY_TYPE = process.env.ONE_IDENTITY_TYPE;
+const ONE_PERMISSIONS = process.env.ONE_PERMISSIONS || "admin";
+if (!["read", "write", "admin"].includes(ONE_PERMISSIONS)) {
+    console.error(`Invalid ONE_PERMISSIONS value: "${ONE_PERMISSIONS}". Must be one of: read, write, admin`);
+    process.exit(1);
+}
+const ONE_CONNECTION_KEYS = process.env.ONE_CONNECTION_KEYS
+    ? process.env.ONE_CONNECTION_KEYS.split(",").map(s => s.trim()).filter(Boolean)
+    : ["*"];
+const ONE_ACTION_IDS = process.env.ONE_ACTION_IDS
+    ? process.env.ONE_ACTION_IDS.split(",").map(s => s.trim()).filter(Boolean)
+    : ["*"];
+const ONE_KNOWLEDGE_AGENT = process.env.ONE_KNOWLEDGE_AGENT === "true";
+const oneClient = new OneClient({
+    secret: ONE_SECRET,
+    baseUrl: ONE_BASE_URL,
+    identity: ONE_IDENTITY,
+    identityType: ONE_IDENTITY_TYPE,
+    connectionKeys: ONE_CONNECTION_KEYS,
+});
+let oneInitialized = false;
+let initializationPromise = null;
+const initializeOne = async () => {
+    if (oneInitialized) {
+        return;
+    }
+    if (initializationPromise) {
+        return initializationPromise;
+    }
+    initializationPromise = (async () => {
+        try {
+            await oneClient.initialize();
+            oneInitialized = true;
+        }
+        catch (error) {
+            console.error("Failed to initialize One client:", error);
+            initializationPromise = null;
+            throw error;
+        }
+    })();
+    return initializationPromise;
+};
+const server = new McpServer({
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+});
+server.registerTool("list_one_integrations", listOneIntegrationsToolConfig, async (args) => {
+    await initializeOne();
+    return await handleGetIntegrations(args);
+});
+server.registerTool("search_one_platform_actions", searchOnePlatformActionsToolConfig, async (args) => {
+    await initializeOne();
+    return await handleSearchPlatformActions(args);
+});
+server.registerTool("get_one_action_knowledge", getOneActionKnowledgeToolConfig, async (args) => {
+    await initializeOne();
+    return await handleGetActionKnowledge(args);
+});
+if (!ONE_KNOWLEDGE_AGENT) {
+    server.registerTool("execute_one_action", executeOneActionToolConfig, async (args) => {
+        await initializeOne();
+        return await handleExecuteOneAction(args);
+    });
+}
+async function handleGetIntegrations(args) {
+    try {
+        const connectedIntegrations = oneClient.getUserConnections();
+        const availableIntegrations = oneClient.getAvailableConnectors();
+        const activeConnections = connectedIntegrations.filter(conn => conn.active);
+        let activePlatforms = availableIntegrations.filter(def => def.active && !def.deprecated);
+        // When connection keys are scoped, only show platforms that match active connections
+        if (!ONE_CONNECTION_KEYS.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 {
+        // Force knowledge mode when ONE_KNOWLEDGE_AGENT is enabled
+        const agentType = ONE_KNOWLEDGE_AGENT ? "knowledge" : args.agentType;
+        let actions = await oneClient.searchAvailableActions(args.platform, args.query, agentType);
+        // Apply permission-level filtering
+        actions = filterByPermissions(actions, ONE_PERMISSIONS);
+        // Apply action allowlist filtering
+        actions = actions.filter(a => isActionAllowed(a.systemId, ONE_ACTION_IDS));
+        const cleanedActions = actions.map(action => ({
+            actionId: action.systemId,
+            title: action.title,
+            method: action.method,
+            path: action.path
+        }));
+        // Handle empty results with helpful suggestions
+        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_one_integrations
+
+EXAMPLES OF GOOD QUERIES:
+- "search contacts"
+- "send email"
+- "create customer"
+- "list orders"`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: suggestionsText,
+                    },
+                ],
+            };
+        }
+        // Build structured response
+        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_one_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, ONE_ACTION_IDS)) {
+            throw new McpError(ErrorCode.InvalidRequest, `Action "${actionId}" is not in the allowed action list`);
+        }
+        if (!ONE_CONNECTION_KEYS.includes("*")) {
+            const connectedPlatforms = oneClient.getUserConnections().map(c => c.platform);
+            if (!connectedPlatforms.includes(args.platform)) {
+                throw new McpError(ErrorCode.InvalidRequest, `Platform "${args.platform}" has no allowed connections`);
+            }
+        }
+        const { knowledge, method } = await oneClient.getActionKnowledge(actionId);
+        const knowledgeWithGuidance = buildActionKnowledgeWithGuidance(knowledge, method, oneClient.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 handleExecuteOneAction(args) {
+    try {
+        if (!isActionAllowed(args.actionId, ONE_ACTION_IDS)) {
+            throw new McpError(ErrorCode.InvalidRequest, `Action "${args.actionId}" is not in the allowed action list`);
+        }
+        if (!ONE_CONNECTION_KEYS.includes("*")) {
+            const allowedKeys = oneClient.getUserConnections().map(c => c.key);
+            if (!allowedKeys.includes(args.connectionKey)) {
+                throw new McpError(ErrorCode.InvalidRequest, `Connection key "${args.connectionKey}" is not allowed`);
+            }
+        }
+        const actionDetails = await oneClient.getActionDetails(args.actionId);
+        if (!isMethodAllowed(actionDetails.method, ONE_PERMISSIONS)) {
+            throw new McpError(ErrorCode.InvalidRequest, `Method "${actionDetails.method}" is not allowed under "${ONE_PERMISSIONS}" permission level`);
+        }
+        const result = await oneClient.executePassthroughRequest(args, actionDetails);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new McpError(ErrorCode.InternalError, `Failed to execute One action: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+async function main() {
+    try {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    }
+    catch (error) {
+        console.error("Failed to start server:", error);
+        process.exit(1);
+    }
+}
+process.on('SIGINT', async () => {
+    console.error('Shutting down server...');
+    process.exit(0);
+});
+process.on('SIGTERM', async () => {
+    console.error('Shutting down server...');
+    process.exit(0);
+});
+process.on('uncaughtException', (error) => {
+    console.error('Uncaught exception:', error);
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason, promise) => {
+    console.error('Unhandled rejection at:', promise, 'reason:', reason);
+    process.exit(1);
+});
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});