@withone/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 One Systems, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+<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;">
+
+<h3 align="center">One MCP Server</h3>
+
+<p align="center">
+  <a href="https://withone.ai"><strong>Website</strong></a>
+  &nbsp;·&nbsp;
+  <a href="https://withone.ai/docs"><strong>Docs</strong></a>
+  &nbsp;·&nbsp;
+  <a href="https://app.withone.ai"><strong>Dashboard</strong></a>
+  &nbsp;·&nbsp;
+  <a href="https://withone.ai/changelog"><strong>Changelog</strong></a>
+  &nbsp;·&nbsp;
+  <a href="https://x.com/withoneai"><strong>X</strong></a>
+  &nbsp;·&nbsp;
+  <a href="https://linkedin.com/company/withoneai"><strong>LinkedIn</strong></a>
+</p>
+
+<p align="center">
+  <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.
+
+```bash
+npm install -g @withone/cli
+one init
+```
+
+That's it. The [One CLI](https://www.npmjs.com/package/@withone/cli) will prompt you for your API key (get one from the [One dashboard](https://app.withone.ai/settings/api-keys)) and configure the MCP server for your environment: Claude Desktop, Cursor, Claude Code, Windsurf, or any MCP-compatible agent.
+
+## Capabilities
+
+- **250+ 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.
+- **Fine-grained access control.** Restrict which actions, connections, and permission levels (read, write, admin) your agent has access to.
+- **Secure by default.** All requests proxied through One, secrets automatically redacted, no platform API keys to manage.
+
+## Examples
+
+**Execute actions directly:**
+> "Get my last 5 emails from Gmail"
+
+> "Send a Slack message to #general: 'Meeting in 10 minutes'"
+
+> "Get all products from my Shopify store"
+
+**Generate integration code:**
+> "Create a React form component that sends emails using Gmail"
+
+> "Build a dashboard that displays Linear users and their assigned projects with filtering"
+
+> "Create a paginatable table that fetches and displays QuickBooks invoices with search and sort"
+
+## Tools
+
+The server exposes four MCP tools:
+
+| Tool | Description |
+|------|-------------|
+| `list_one_integrations` | List available platforms and active connections |
+| `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 |
+
+## Manual Installation
+
+If you prefer to configure the server manually instead of using `one init`, install the package directly:
+
+```bash
+npm install @withone/mcp
+```
+
+Then set the required environment variable:
+
+```bash
+ONE_SECRET=your-one-secret-key
+```
+
+### Identity Scoping
+
+Scope connections to a specific identity (e.g., a user, team, or organization):
+
+```bash
+ONE_IDENTITY=user_123
+ONE_IDENTITY_TYPE=user
+```
+
+| Variable | Description | Values |
+|----------|-------------|--------|
+| `ONE_IDENTITY` | The identifier for the entity (e.g., user ID, team ID) | Any string |
+| `ONE_IDENTITY_TYPE` | The type of identity | `user`, `team`, `organization`, `project` |
+
+When set, the MCP server will only return connections associated with the specified identity. This is useful for multi-tenant applications where you want to scope integrations to specific users or entities.
+
+### Access Control
+
+Fine-tune what the MCP server can see and do:
+
+```bash
+ONE_PERMISSIONS=read
+ONE_CONNECTION_KEYS=conn_key_1,conn_key_2
+ONE_ACTION_IDS=action_id_1,action_id_2
+ONE_KNOWLEDGE_AGENT=true
+```
+
+| Variable | Type | Default | Description |
+|---|---|---|---|
+| `ONE_PERMISSIONS` | `read` \| `write` \| `admin` | `admin` | Filter actions by HTTP method. `read` = GET only, `write` = GET/POST/PUT/PATCH, `admin` = all methods |
+| `ONE_CONNECTION_KEYS` | `*` or comma-separated keys | `*` | Restrict visible connections and platforms to specific connection keys |
+| `ONE_ACTION_IDS` | `*` or comma-separated IDs | `*` | Restrict visible and executable actions to specific action IDs |
+| `ONE_KNOWLEDGE_AGENT` | `true` \| `false` | `false` | Remove the `execute_one_action` tool entirely, forcing knowledge-only mode |
+
+All defaults preserve current behavior. If no access control env vars are set, the server starts with full access and all tools available.
+
+## Manual Configuration
+
+If you used `one init`, the configuration below is already done for you. These examples are for reference or manual setups.
+
+### Standalone
+
+```bash
+npx @withone/mcp
+```
+
+### Claude Desktop / Cursor
+
+Add the following to your MCP config:
+
+- **Claude Desktop:** MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%/Claude/claude_desktop_config.json`
+- **Cursor:** Open the Cursor menu and select "MCP Settings"
+
+```json
+{
+  "mcpServers": {
+    "one": {
+      "command": "npx",
+      "args": ["@withone/mcp"],
+      "env": {
+        "ONE_SECRET": "your-one-secret-key"
+      }
+    }
+  }
+}
+```
+
+### Remote MCP Server
+
+The remote MCP server is available at [https://mcp.withone.ai](https://mcp.withone.ai).
+
+### Docker
+
+```bash
+docker build -t one-mcp-server .
+docker run -e ONE_SECRET=your_one_secret_key one-mcp-server
+```
+
+All environment variables listed above can be passed as `-e` flags.
+
+## Security
+
+All requests to third-party platforms are authenticated and proxied through One's API. The MCP server never handles OAuth tokens or platform API keys directly. The `ONE_SECRET` key is the sole credential required, and it is automatically redacted from all response payloads returned to clients. Sensitive headers are stripped from logged and returned request configurations.
+
+## License
+
+MIT
+
+## Support
+
+For support, please contact support@withone.ai or visit https://withone.ai

package/build/client.d.ts

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

@@ -0,0 +1,362 @@
+/**
+ * One API Client
+ *
+ * This module provides a TypeScript client for interacting with the One API.
+ *
+ * @fileoverview One API client with authentication and data management
+ * @author One
+ */
+import axios from 'axios';
+import FormData from 'form-data';
+import { fetchPaginatedData, replacePathVariables } from './helpers.js';
+/**
+ * Client for interacting with the One API
+ */
+export class OneClient {
+    secret;
+    baseUrl;
+    identity;
+    identityType;
+    connectionKeys;
+    connections = [];
+    connectors = [];
+    isInitialized = false;
+    constructor(optionsOrSecret, baseUrl = "https://api.withone.ai") {
+        if (typeof optionsOrSecret === 'string') {
+            // Legacy constructor: (secret, baseUrl)
+            if (!optionsOrSecret?.trim()) {
+                throw new Error("One secret is required and cannot be empty");
+            }
+            this.secret = optionsOrSecret;
+            this.baseUrl = baseUrl.replace(/\/$/, '');
+        }
+        else {
+            // New constructor: (options)
+            if (!optionsOrSecret.secret?.trim()) {
+                throw new Error("One secret is required and cannot be empty");
+            }
+            this.secret = optionsOrSecret.secret;
+            this.baseUrl = (optionsOrSecret.baseUrl || "https://api.withone.ai").replace(/\/$/, '');
+            this.identity = optionsOrSecret.identity;
+            this.identityType = optionsOrSecret.identityType;
+            this.connectionKeys = optionsOrSecret.connectionKeys;
+        }
+    }
+    /**
+     * Initializes the client by fetching connections and available connectors
+     * @throws {Error} If initialization fails completely
+     */
+    async initialize() {
+        if (this.isInitialized) {
+            return;
+        }
+        const results = await Promise.allSettled([
+            this.fetchConnections(),
+            this.fetchConnectionDefinitions(),
+        ]);
+        const [connectionsResult, connectorsResult] = results;
+        if (connectionsResult.status === 'rejected') {
+            console.error("Failed to fetch connections:", connectionsResult.reason);
+            this.connections = [];
+        }
+        if (connectorsResult.status === 'rejected') {
+            console.error("Failed to fetch connectors:", connectorsResult.reason);
+            this.connectors = [];
+        }
+        this.isInitialized = true;
+    }
+    /**
+     * Generates standard headers for API requests
+     */
+    generateHeaders() {
+        return {
+            "Content-Type": "application/json",
+            "x-one-secret": this.secret,
+        };
+    }
+    /**
+     * Fetches user connections from the API
+     */
+    async fetchConnections() {
+        try {
+            // If connectionKeys is set, not ["*"], and empty → no connections
+            if (this.connectionKeys && !this.connectionKeys.includes("*") && this.connectionKeys.length === 0) {
+                this.connections = [];
+                return;
+            }
+            const headers = this.generateHeaders();
+            const url = `${this.baseUrl}/v1/vault/connections`;
+            const additionalParams = {};
+            if (this.identity) {
+                additionalParams.identity = this.identity;
+            }
+            if (this.identityType) {
+                additionalParams.identityType = this.identityType;
+            }
+            if (this.connectionKeys && !this.connectionKeys.includes("*")) {
+                additionalParams.key = this.connectionKeys.join(",");
+            }
+            this.connections = await fetchPaginatedData(url, headers, Object.keys(additionalParams).length > 0 ? additionalParams : undefined);
+        }
+        catch (error) {
+            console.error("Failed to fetch connections:", error);
+            this.connections = [];
+            throw error;
+        }
+    }
+    /**
+     * Fetches available connection definitions from the API
+     */
+    async fetchConnectionDefinitions() {
+        try {
+            const headers = this.generateHeaders();
+            const url = `${this.baseUrl}/v1/available-connectors`;
+            this.connectors = await fetchPaginatedData(url, headers);
+        }
+        catch (error) {
+            console.error("Failed to fetch connection definitions:", error);
+            this.connectors = [];
+            throw error;
+        }
+    }
+    /**
+     * 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
+     */
+    async searchAvailableActions(platform, query, agentType) {
+        if (!platform?.trim()) {
+            throw new Error("Platform name is required");
+        }
+        if (!query?.trim()) {
+            throw new Error("Search query is required");
+        }
+        try {
+            const headers = this.generateHeaders();
+            const url = `${this.baseUrl}/v1/available-actions/search/${platform}`;
+            // Default to knowledgeAgent if not specified
+            const isKnowledgeAgent = !agentType || agentType === "knowledge";
+            const params = {
+                query,
+                limit: '5'
+            };
+            if (isKnowledgeAgent) {
+                params.knowledgeAgent = 'true';
+            }
+            else {
+                params.executeAgent = 'true';
+            }
+            const response = await axios.get(url, {
+                headers,
+                params
+            });
+            return response.data || [];
+        }
+        catch (error) {
+            console.error("Error searching available actions:", error);
+            if (axios.isAxiosError(error)) {
+                throw new Error(`Failed to search available actions: ${error.response?.status} ${error.response?.statusText}`);
+            }
+            throw new Error("Failed to search available actions");
+        }
+    }
+    /**
+     * 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
+     */
+    async getActionDetails(actionId) {
+        if (!actionId?.trim()) {
+            throw new Error("Action ID is required");
+        }
+        try {
+            const headers = this.generateHeaders();
+            const url = `${this.baseUrl}/v1/knowledge`;
+            const params = {
+                _id: actionId
+            };
+            const response = await axios.get(url, {
+                headers,
+                params
+            });
+            const actions = response.data?.rows || [];
+            if (actions.length === 0) {
+                throw new Error(`Action with ID ${actionId} not found`);
+            }
+            return actions[0];
+        }
+        catch (error) {
+            console.error("Error fetching action details:", error);
+            if (axios.isAxiosError(error)) {
+                throw new Error(`Failed to fetch action details: ${error.response?.status} ${error.response?.statusText}`);
+            }
+            throw new Error("Failed to fetch action details");
+        }
+    }
+    /**
+     * 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
+     */
+    async getActionKnowledge(actionId) {
+        try {
+            const action = await this.getActionDetails(actionId);
+            if (!action.knowledge || !action.method) {
+                return {
+                    knowledge: "No knowledge was found",
+                    method: "No method was found"
+                };
+            }
+            return {
+                knowledge: action.knowledge,
+                method: action.method
+            };
+        }
+        catch (error) {
+            console.error("Error fetching action knowledge:", error);
+            throw error;
+        }
+    }
+    /**
+     * Executes a passthrough request to a third-party API through One
+     * @param args - The execution arguments containing all request details
+     * @returns Object containing sanitized request config and response data
+     * @throws {Error} If the request fails
+     */
+    async executePassthroughRequest(args, preloadedAction) {
+        const { actionId, connectionKey, data, pathVariables, queryParams, headers, isFormData, isFormUrlEncoded, } = args;
+        // Use preloaded action or fetch action details
+        const action = preloadedAction ?? await this.getActionDetails(actionId);
+        const method = action.method;
+        const contentType = isFormData ? 'multipart/form-data' : isFormUrlEncoded ? 'application/x-www-form-urlencoded' : 'application/json';
+        const requestHeaders = {
+            ...this.generateHeaders(),
+            'x-one-connection-key': connectionKey,
+            'x-one-action-id': action._id,
+            'Content-Type': contentType,
+            ...headers
+        };
+        const finalActionPath = pathVariables
+            ? replacePathVariables(action.path, pathVariables)
+            : action.path;
+        const normalizedPath = finalActionPath.startsWith('/') ? finalActionPath : `/${finalActionPath}`;
+        const url = `${this.baseUrl}/v1/passthrough${normalizedPath}`;
+        let requestData = data;
+        if (typeof requestData === 'string') {
+            try {
+                requestData = JSON.parse(requestData);
+            }
+            catch { }
+        }
+        // Check if action has "custom" tag and add connectionKey to body if needed
+        const isCustomAction = action.tags?.includes('custom');
+        if (isCustomAction && method?.toLowerCase() !== 'get') {
+            requestData = {
+                ...requestData,
+                connectionKey
+            };
+        }
+        const requestConfig = {
+            url,
+            method,
+            headers: requestHeaders,
+            params: queryParams
+        };
+        if (method?.toLowerCase() !== 'get') {
+            if (isFormData) {
+                const formData = new FormData();
+                if (requestData && typeof requestData === 'object' && !Array.isArray(requestData)) {
+                    Object.entries(requestData).forEach(([key, value]) => {
+                        if (typeof value === 'object') {
+                            formData.append(key, JSON.stringify(value));
+                        }
+                        else {
+                            formData.append(key, String(value));
+                        }
+                    });
+                }
+                requestConfig.data = formData;
+                Object.assign(requestConfig.headers, formData.getHeaders());
+            }
+            else if (isFormUrlEncoded) {
+                const params = new URLSearchParams();
+                if (requestData && typeof requestData === 'object' && !Array.isArray(requestData)) {
+                    Object.entries(requestData).forEach(([key, value]) => {
+                        if (typeof value === 'object') {
+                            params.append(key, JSON.stringify(value));
+                        }
+                        else {
+                            params.append(key, String(value));
+                        }
+                    });
+                }
+                requestConfig.data = params;
+            }
+            else {
+                requestConfig.data = requestData;
+            }
+        }
+        const sanitizedConfig = {
+            ...requestConfig,
+            headers: {
+                ...requestConfig.headers,
+                'x-one-secret': '***REDACTED***'
+            }
+        };
+        try {
+            const response = await axios(requestConfig);
+            return {
+                requestConfig: sanitizedConfig,
+                responseData: response.data
+            };
+        }
+        catch (error) {
+            console.error("Error executing passthrough request:", error);
+            if (axios.isAxiosError(error)) {
+                throw new Error(`Failed to execute passthrough request: ${error.response?.status} ${error.response?.statusText}`);
+            }
+            throw new Error("Failed to execute passthrough request");
+        }
+    }
+    /**
+     * Gets the base URL for the One API
+     * @returns The base URL for the One API
+     */
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    /**
+     * Gets the current user's connections
+     * @returns Array of user connections
+     */
+    getUserConnections() {
+        return [...this.connections];
+    }
+    /**
+     * Gets available connectors/platforms
+     * @returns Array of available connection definitions
+     */
+    getAvailableConnectors() {
+        return [...this.connectors];
+    }
+    /**
+     * Checks if the client has been initialized
+     */
+    isClientInitialized() {
+        return this.isInitialized;
+    }
+    /**
+     * Refreshes connections and connectors data
+     */
+    async refresh() {
+        await Promise.allSettled([
+            this.fetchConnections(),
+            this.fetchConnectionDefinitions(),
+        ]);
+    }
+}