@toolplex/client 0.1.1

package/LICENSE

@@ -0,0 +1,98 @@
+License text copyright (c) 2025 ToolPlex LLC. All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             ToolPlex LLC
+Licensed Work:        ToolPlex Client, as published in this repository. The Licensed Work is (c) 2025
+                      ToolPlex LLC.
+Additional Use Grant: You may make production use of the Licensed Work, provided
+                      your use does not involve offering it or derivative works on a 
+                      hosted or embedded basis to compete with ToolPlex's paid platform 
+                      or services. For purposes of this license:
+
+                      A "competitive offering" is a product or service that is offered 
+                      to third parties on a paid basis (including through paid support), 
+                      and that significantly overlaps with ToolPlex's platform, including: 
+                      tool discovery, tool execution, agent control, or workflow/playbook 
+                      reuse.
+
+                      "Product" means software made available to end users or used to 
+                      operate hosted services.
+
+                      "Embedded" includes incorporating source or binary components of 
+                      the Licensed Work into another product or requiring the Licensed 
+                      Work for that product to function.
+
+                      "Internal use" within your organization is permitted, even for 
+                      commercial purposes, as long as it is not redistributed or offered 
+                      to others.
+
+                      "API Integration Restrictions": Use of the ToolPlex API or services 
+                      to build, enhance, or operate a competitive offering is prohibited, 
+                      regardless of whether the Licensed Work is directly incorporated.
+
+                      "Derivative Works": Includes any modification, adaptation, or custom 
+                      implementation based on the Licensed Work, including but not limited 
+                      to custom clients for ToolPlex API interaction. While permitted under 
+                      this license, such derivatives may present technical challenges and 
+                      are not officially supported.
+
+                      "Research and Academic Use": Non-commercial research, educational, 
+                      and academic use is permitted regardless of competitive overlap, 
+                      provided results are not used to develop commercial competitive 
+                      offerings.
+
+                      "Official Client Recommendation": While custom clients are permitted 
+                      under this license, ToolPlex strongly recommends using the official 
+                      client to ensure compatibility, security, and optimal performance.
+
+                      Hosting or using the Licensed Work for internal purposes within an 
+                      organization is not considered a competitive offering. ToolPlex 
+                      considers your organization to include all of your affiliates under 
+                      common control.
+
+Change Date:          None
+Change License:       MPL 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact support@toolplex.ai.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production use.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

package/README.md

@@ -0,0 +1,112 @@
+# ToolPlex Client
+
+[![Visit ToolPlex](https://img.shields.io/badge/ToolPlex.ai-%F0%9F%9A%80-blue?style=flat)](https://toolplex.ai)  
+[![Discord](https://img.shields.io/badge/Join%20Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/KpCjj8ay)
+
+This repository contains the official **ToolPlex MCP server** — the npm package that enables AI agents to connect to the ToolPlex platform.
+
+ToolPlex is a curated tool ecosystem built for AI agents. With ToolPlex, your agent can:
+- 🔍 Discover 2,000+ high quality, open-source MCP tools
+- 🛠️ Install and run tools with your permission
+- 📚 Save workflows as reusable playbooks
+- 🔁 Learn from success — your agent evolves from collective agent feedback
+
+No complex setup. Just add ToolPlex to your AI client and start automating.
+
+## Features
+
+- **Agent Tool Discovery** — Your agent can search a curated index of MCP servers, filtered by code analysis and popularity signals to find tools that actually work  
+- **Smooth Install Experience** — Automatically installs even complex tools, with the agent handling tricky build steps, dependencies, and setup flows behind the scenes  
+- **Secure Config Handling** — Injects API keys, secrets, and file paths only when needed — always under your control  
+- **Seamless Server Activation** — Install and uninstall MCP servers at any time without restarting your LLM or resetting the session  
+- **Workflow Memory** — Successful tasks are saved as playbooks your agent can search, reuse, and adapt later  
+- **Quality Signals Built-In** — Agents report tool usage and failure rates to help down-rank unreliable or broken servers automatically  
+- **Team-Ready** — Share tools, playbooks, and permission sets across your org for faster onboarding and coordinated automation  
+- **Full Agent Control** — Use the ToolPlex dashboard to manage server access, shell permissions, file visibility, feedback settings, and more  
+- **Local-First Execution** — By default, ToolPlex installs and runs tools on your machine for full speed, privacy, and control  
+
+## Quick Setup
+
+**Claude Desktop (recommended)**  
+1. Sign up for a [ToolPlex AI](https://toolplex.ai) account and create your first API key.
+2. Install [Claude Desktop](https://claude.ai/download).
+3. Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "toolplex-mcp": {
+      "command": "npx",
+      "args": ["@toolplex/client"],
+      "env": {
+        "TOOLPLEX_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+Or use any AI chat client that [supports MCP](https://github.com/punkpeye/awesome-mcp-clients).
+
+ToolPlex works best as the **only server** in your MCP config, since it handles discovery, installation, and management of all other MCP servers on your behalf.
+
+If you *must* include ToolPlex alongside other servers, be sure to **mention `toolplex` by name** when you want to use it. This helps your agent avoid ambiguity when multiple servers are present.
+
+## ToolPlex Usage Guide
+
+ToolPlex API users aren't humans — they're AI agents.
+
+**You talk to your agent.** Your agent talks to ToolPlex. This allows agents to handle the full lifecycle of tool usage — from discovery and installation to configuration, execution, and playbook use — all without human micromanagement.
+
+Ask your AI to activate ToolPlex:
+```
+> init toolplex
+> start toolplex
+> open toolplex
+```
+
+After initializing ToolPlex, just talk to your agent naturally:
+
+### Discover Available Tools
+```
+> what tools are currently installed?
+> show me what ToolPlex servers I can use
+```
+
+### Run Installed Tools
+```
+> merge these PDFs using the File Merger tool
+> fetch the latest bitcoin price from Yahoo Finance
+> find some tools to generate my weekly dinner menu
+> extract tables from this Excel file using the Excel MCP
+> query our BigQuery sales data for Q2 totals
+```
+
+### Install New Tools (via search)
+```
+> find a tool that can automate browser tests
+> is there a server that can visualize data with charts?
+> search for a tool that can read and organize research PDFs
+```
+
+### Manage Tools
+```
+> install the google news server
+> uninstall the ffmpeg server
+> reinstall the Playwright automation server
+```
+
+### Use Playbooks
+```
+> run my weekly KPI dashboard playbook
+> save this as a playbook
+```
+
+## LLM Compatability
+ToolPlex works better with generalist, high-context LLMs that support tool-calling, like:
+* `claude-sonnet-3.7`
+* `claude-sonnet-4`
+* `gpt-4o`
+* `gpt-4.1`
+
+Weaker reasoning models like `deepseek-chat` or `claude-haiku-3.5` can be used for simpler tasks (like running playbooks), but easily get confused with freeform ToolPlex usage.

package/dist/mcp-server/clientContext.d.ts

@@ -0,0 +1,35 @@
+import { LLMContext } from '../shared/mcpServerTypes.js';
+import { ClientPermissions, ClientFlags } from './toolplexApi/types.js';
+/**
+ * Maintains client context for the ToolPlex server
+ */
+export declare class ClientContext {
+    private _sessionId;
+    private _dev;
+    private _apiKey;
+    private _clientMode;
+    private _llmContext;
+    private _clientVersion;
+    private _permissions;
+    private _flags;
+    private _isOrgUser;
+    get sessionId(): string;
+    set sessionId(id: string);
+    get dev(): boolean;
+    set dev(isDev: boolean);
+    get apiKey(): string;
+    set apiKey(key: string);
+    get clientMode(): 'standard' | 'restricted';
+    set clientMode(mode: 'standard' | 'restricted');
+    get llmContext(): LLMContext;
+    set llmContext(context: LLMContext);
+    get clientVersion(): string;
+    set clientVersion(version: string);
+    get permissions(): ClientPermissions;
+    set permissions(perms: ClientPermissions);
+    get flags(): ClientFlags;
+    set flags(consts: ClientFlags);
+    get isOrgUser(): boolean;
+    set isOrgUser(isOrgUser: boolean);
+    isInitialized(): boolean;
+}

package/dist/mcp-server/clientContext.js

@@ -0,0 +1,107 @@
+/**
+ * Maintains client context for the ToolPlex server
+ */
+export class ClientContext {
+    constructor() {
+        this._sessionId = null;
+        this._dev = null;
+        this._apiKey = null;
+        this._clientMode = null;
+        this._llmContext = null;
+        this._clientVersion = null;
+        this._permissions = null;
+        this._flags = null;
+        this._isOrgUser = null;
+    }
+    get sessionId() {
+        if (!this._sessionId) {
+            throw new Error('Session ID not set - ToolPlex not initialized');
+        }
+        return this._sessionId;
+    }
+    set sessionId(id) {
+        this._sessionId = id;
+    }
+    get dev() {
+        if (this._dev === null) {
+            throw new Error('Dev mode not set - ToolPlex not initialized');
+        }
+        return this._dev;
+    }
+    set dev(isDev) {
+        this._dev = isDev;
+    }
+    get apiKey() {
+        if (!this._apiKey) {
+            throw new Error('API key not set - ToolPlex not initialized');
+        }
+        return this._apiKey;
+    }
+    set apiKey(key) {
+        this._apiKey = key;
+    }
+    get clientMode() {
+        if (!this._clientMode) {
+            throw new Error('Client mode not set - ToolPlex not initialized');
+        }
+        return this._clientMode;
+    }
+    set clientMode(mode) {
+        this._clientMode = mode;
+    }
+    get llmContext() {
+        if (!this._llmContext) {
+            throw new Error('LLM context not set - ToolPlex not initialized');
+        }
+        return this._llmContext;
+    }
+    set llmContext(context) {
+        this._llmContext = context;
+    }
+    get clientVersion() {
+        if (!this._clientVersion) {
+            throw new Error('Client version not set - ToolPlex not initialized');
+        }
+        return this._clientVersion;
+    }
+    set clientVersion(version) {
+        this._clientVersion = version;
+    }
+    get permissions() {
+        if (!this._permissions) {
+            throw new Error('Permissions not set - ToolPlex not initialized');
+        }
+        return this._permissions;
+    }
+    set permissions(perms) {
+        this._permissions = perms;
+    }
+    get flags() {
+        if (!this._flags) {
+            throw new Error('Consts not set - ToolPlex not initialized');
+        }
+        return this._flags;
+    }
+    set flags(consts) {
+        this._flags = consts;
+    }
+    get isOrgUser() {
+        if (this._isOrgUser === null) {
+            throw new Error('Organization user status not set - ToolPlex not initialized');
+        }
+        return this._isOrgUser;
+    }
+    set isOrgUser(isOrgUser) {
+        this._isOrgUser = isOrgUser;
+    }
+    isInitialized() {
+        return !!(this._sessionId &&
+            this._apiKey &&
+            this._clientMode &&
+            this._llmContext &&
+            this._clientVersion &&
+            this._permissions &&
+            this._flags &&
+            this._isOrgUser !== null);
+    }
+}

package/dist/mcp-server/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp-server/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { serve } from './toolplexServer.js';
+import dotenv from 'dotenv';
+import { FileLogger } from '../shared/fileLogger.js';
+dotenv.config();
+FileLogger.initialize('mcp-server');
+const isDev = process.env.DEV === 'true';
+const apiKey = process.env.TOOLPLEX_API_KEY;
+const clientMode = process.env.TOOLPLEX_CLIENT_MODE || 'standard';
+const logLevel = process.env.LOG_LEVEL || 'info';
+if (!apiKey) {
+    process.exit(1);
+}
+const config = {
+    dev: isDev,
+    apiKey,
+    clientMode,
+    logLevel,
+};
+serve(config).catch(() => {
+    process.exit(1);
+});

package/dist/mcp-server/logging/telemetryLogger.d.ts

@@ -0,0 +1,18 @@
+import { LogTelemetryRequest } from '../toolplexApi/types.js';
+export declare class TelemetryLogger {
+    private eventQueue;
+    private flushTimeout;
+    private readonly BATCH_SIZE;
+    private readonly FLUSH_INTERVAL;
+    constructor();
+    /**
+     * Log a telemetry event
+     */
+    log(eventType: LogTelemetryRequest['event_type'], data: Partial<Omit<LogTelemetryRequest, 'event_type'>>): Promise<void>;
+    private flush;
+    private scheduleFlush;
+    /**
+     * Clean up resources - should be called when shutting down
+     */
+    dispose(): Promise<void>;
+}

package/dist/mcp-server/logging/telemetryLogger.js

@@ -0,0 +1,54 @@
+import Registry from '../registry.js';
+import { FileLogger } from '../../shared/fileLogger.js';
+const logger = FileLogger;
+export class TelemetryLogger {
+    constructor() {
+        this.eventQueue = [];
+        this.flushTimeout = null;
+        this.BATCH_SIZE = 10;
+        this.FLUSH_INTERVAL = 30000;
+        this.scheduleFlush();
+    }
+    /**
+     * Log a telemetry event
+     */
+    async log(eventType, data) {
+        this.eventQueue.push({ eventType, data });
+        if (this.eventQueue.length >= this.BATCH_SIZE) {
+            await this.flush();
+        }
+    }
+    async flush() {
+        if (this.eventQueue.length === 0)
+            return;
+        try {
+            const apiService = Registry.getToolplexApiService();
+            const events = [...this.eventQueue];
+            this.eventQueue = [];
+            await logger.debug(`Flushing ${events.length} telemetry events`);
+            await apiService.logTelemetryEvents(events);
+        }
+        catch (err) {
+            await logger.error(`Error flushing telemetry events: ${err}`);
+            this.eventQueue.unshift(...this.eventQueue);
+        }
+    }
+    scheduleFlush() {
+        if (this.flushTimeout) {
+            clearTimeout(this.flushTimeout);
+        }
+        this.flushTimeout = setTimeout(async () => {
+            await this.flush();
+            this.scheduleFlush();
+        }, this.FLUSH_INTERVAL);
+    }
+    /**
+     * Clean up resources - should be called when shutting down
+     */
+    async dispose() {
+        if (this.flushTimeout) {
+            clearTimeout(this.flushTimeout);
+        }
+        await this.flush();
+    }
+}

package/dist/mcp-server/policy/callToolObserver.d.ts

@@ -0,0 +1,9 @@
+declare class CallToolObserver {
+    private serverToolCalls;
+    constructor();
+    recordCall(serverId: string, toolName: string): void;
+    wasServerCalled(serverId: string): boolean;
+    wasToolCalled(serverId: string, toolName: string): boolean;
+    clear(): void;
+}
+export default CallToolObserver;

package/dist/mcp-server/policy/callToolObserver.js

@@ -0,0 +1,25 @@
+class CallToolObserver {
+    constructor() {
+        this.serverToolCalls = new Map();
+    }
+    // Record a call to a tool on a server
+    recordCall(serverId, toolName) {
+        if (!this.serverToolCalls.has(serverId)) {
+            this.serverToolCalls.set(serverId, new Set());
+        }
+        this.serverToolCalls.get(serverId).add(toolName);
+    }
+    // Check if a server was called at all
+    wasServerCalled(serverId) {
+        return this.serverToolCalls.has(serverId) && this.serverToolCalls.get(serverId).size > 0;
+    }
+    // Check if a specific tool was called on a server
+    wasToolCalled(serverId, toolName) {
+        return this.serverToolCalls.has(serverId) && this.serverToolCalls.get(serverId).has(toolName);
+    }
+    // Optionally, clear all records (for testing or reset)
+    clear() {
+        this.serverToolCalls.clear();
+    }
+}
+export default CallToolObserver;

package/dist/mcp-server/policy/feedbackPolicy.d.ts

@@ -0,0 +1,27 @@
+import CallToolObserver from './callToolObserver.js';
+import InstallObserver from './installObserver.js';
+import { ClientContext } from '../clientContext.js';
+import { SubmitFeedbackParams } from '../../shared/mcpServerTypes.js';
+export declare class FeedbackPolicy {
+    private callToolObserver;
+    private installObserver;
+    private clientContext;
+    private blockedMcpServersSet;
+    constructor(clientContext: ClientContext, callToolObserver: CallToolObserver, installObserver: InstallObserver);
+    /**
+     * Validates feedback by checking that:
+     * - The referenced server has been used or had an install/uninstall action
+     * - The server is not in the blocked servers list
+     *
+     * For server feedback, verifies that:
+     * - The referenced server has been connected to and used or had an install/uninstall action
+     * - The server is not blocked
+     *
+     * For playbook feedback, no validation is currently performed
+     * since playbooks can reference other playbooks.
+     *
+     * @throws Error if feedback references a server that hasn't been used or had an install/uninstall action
+     * in the current session or if the server is blocked
+     */
+    enforceFeedbackPolicy(feedback: SubmitFeedbackParams): void;
+}

package/dist/mcp-server/policy/feedbackPolicy.js

@@ -0,0 +1,39 @@
+export class FeedbackPolicy {
+    constructor(clientContext, callToolObserver, installObserver) {
+        this.callToolObserver = callToolObserver;
+        this.installObserver = installObserver;
+        this.clientContext = clientContext;
+        this.blockedMcpServersSet = new Set(clientContext.flags.blocked_mcp_servers || []);
+    }
+    /**
+     * Validates feedback by checking that:
+     * - The referenced server has been used or had an install/uninstall action
+     * - The server is not in the blocked servers list
+     *
+     * For server feedback, verifies that:
+     * - The referenced server has been connected to and used or had an install/uninstall action
+     * - The server is not blocked
+     *
+     * For playbook feedback, no validation is currently performed
+     * since playbooks can reference other playbooks.
+     *
+     * @throws Error if feedback references a server that hasn't been used or had an install/uninstall action
+     * in the current session or if the server is blocked
+     */
+    enforceFeedbackPolicy(feedback) {
+        const { target_type, target_id } = feedback;
+        if (target_type === 'server') {
+            // Check if server is blocked
+            if (this.blockedMcpServersSet.has(target_id)) {
+                throw new Error(`Cannot submit feedback for blocked server "${target_id}"`);
+            }
+            // For server feedback, verify the server was actually used or had an install/uninstall action
+            if (!this.callToolObserver.wasServerCalled(target_id) &&
+                !this.installObserver.wasServerInstalled(target_id) &&
+                !this.installObserver.wasServerUninstalled(target_id)) {
+                throw new Error(`Cannot submit feedback for server "${target_id}" which has not been used or had an install/uninstall action in this session.`);
+            }
+        }
+        // For playbook feedback, we don't validate usage since playbooks can reference other playbooks
+    }
+}

package/dist/mcp-server/policy/installObserver.d.ts

@@ -0,0 +1,11 @@
+declare class InstallObserver {
+    private serverInstallActions;
+    constructor();
+    recordInstall(serverId: string): void;
+    recordUninstall(serverId: string): void;
+    wasServerInstalled(serverId: string): boolean;
+    wasServerUninstalled(serverId: string): boolean;
+    clear(): void;
+    private recordAction;
+}
+export default InstallObserver;

package/dist/mcp-server/policy/installObserver.js

@@ -0,0 +1,35 @@
+class InstallObserver {
+    constructor() {
+        this.serverInstallActions = new Map();
+    }
+    // Record an install action on a server
+    recordInstall(serverId) {
+        this.recordAction(serverId, 'install');
+    }
+    // Record an uninstall action on a server
+    recordUninstall(serverId) {
+        this.recordAction(serverId, 'uninstall');
+    }
+    // Check if a server has been installed
+    wasServerInstalled(serverId) {
+        return (this.serverInstallActions.has(serverId) &&
+            this.serverInstallActions.get(serverId).has('install'));
+    }
+    // Check if a server has been uninstalled
+    wasServerUninstalled(serverId) {
+        return (this.serverInstallActions.has(serverId) &&
+            this.serverInstallActions.get(serverId).has('uninstall'));
+    }
+    // Optionally, clear all records (for testing or reset)
+    clear() {
+        this.serverInstallActions.clear();
+    }
+    // Private method to record an action
+    recordAction(serverId, action) {
+        if (!this.serverInstallActions.has(serverId)) {
+            this.serverInstallActions.set(serverId, new Set());
+        }
+        this.serverInstallActions.get(serverId).add(action);
+    }
+}
+export default InstallObserver;

package/dist/mcp-server/policy/playbookPolicy.d.ts

@@ -0,0 +1,29 @@
+import CallToolObserver from './callToolObserver.js';
+import { ClientContext } from '../clientContext.js';
+import { SavePlaybookParams } from '../../shared/mcpServerTypes.js';
+export declare class PlaybookPolicy {
+    private callToolObserver;
+    private clientContext;
+    private blockedMcpServersSet;
+    constructor(clientContext: ClientContext, callToolObserver: CallToolObserver);
+    /**
+     * Validates a playbook before saving by checking that:
+     * - Referenced servers and tools have been used
+     * - No blocked servers are referenced
+     * - Private playbooks are only created when enabled
+     *
+     * For each action with a 'call' property, verifies that:
+     * - Any referenced server has been connected to
+     * - Any referenced server/tool combination has been executed
+     * - The server is not in the blocked servers list
+     *
+     * @throws Error if a referenced server or tool has not been used in the current session,
+     * if a blocked server is referenced, or if trying to create a private playbook when disabled
+     */
+    enforceSavePlaybookPolicy(playbook: SavePlaybookParams): void;
+    /**
+     * Validates if playbook usage logging is allowed based on read-only mode
+     * @throws Error if read-only mode is enabled
+     */
+    enforceLogPlaybookUsagePolicy(): void;
+}