@toolplex/client 0.1.33 → 0.1.35

package/README.md

@@ -1,15 +1,18 @@
 # ToolPlex Client
 
-[![Visit ToolPlex](https://img.shields.io/badge/ToolPlex.ai-%F0%9F%9A%80-blue?style=flat)](https://toolplex.ai)  
+[![npm version](https://img.shields.io/npm/v/@toolplex/client)](https://www.npmjs.com/package/@toolplex/client)
+[![npm downloads](https://img.shields.io/npm/dw/@toolplex/client)](https://www.npmjs.com/package/@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.
+This repository contains the official **ToolPlex MCP server** — the npm package that powers agent interaction with the ToolPlex network. It's the core of [ToolPlex Desktop](https://toolplex.ai) and works with any MCP-compatible client.
 
 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
+- Discover 4,000+ high quality, open-source MCP tools (and growing)
+- Automatically install and debug complex MCP servers — including fetching READMEs and resolving dependencies
+- Call any tool across any installed MCP server without loading every schema into context
+- Create and run playbooks (multi-step AI workflows) just by chatting
+- Learn from collective agent feedback to improve over time
 
 No complex setup. Just add ToolPlex to your AI client and start automating.
 
@@ -17,20 +20,22 @@ No complex setup. Just add ToolPlex to your AI client and start automating.
 
 - **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)**  
+**ToolPlex Desktop (recommended)**
+
+Download [ToolPlex Desktop](https://toolplex.ai) — a native app with the ToolPlex client built-in. No configuration needed.
+
+**Claude Desktop or other MCP clients**
+
 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`:
+2. Add this to your MCP client config (e.g. `claude_desktop_config.json`):
 
 ```json
 {
@@ -46,7 +51,7 @@ No complex setup. Just add ToolPlex to your AI client and start automating.
 }
 ```
 
-Or use any AI chat client that [supports MCP](https://github.com/punkpeye/awesome-mcp-clients).
+Works with any AI 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.
 
@@ -102,11 +107,12 @@ After initializing ToolPlex, just talk to your agent naturally:
 > 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`
+## LLM Compatibility
+ToolPlex works best with high-context LLMs that support tool-calling:
+* Claude Sonnet 4.5, Opus 4.5, Haiku 4.5
+* GPT-5, GPT-5 Mini
+* Gemini 2.5 Pro, Gemini 3 Pro
+* Kimi K2, Kimi K2 Thinking
+* Grok 4
 
-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.
+Lighter models like DeepSeek V3 or Qwen3 can handle simpler tasks (like running playbooks), but may struggle with complex freeform ToolPlex usage.

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

@@ -46,6 +46,15 @@ export declare class PolicyEnforcer {
      * @returns Filtered list with blocked servers removed
      */
     filterBlockedMcpServers<T>(servers: T[], getServerId: (item: T) => string): T[];
+    /**
+     * Applies both blocked and allowed server filtering.
+     * First removes blocked servers, then filters to allowed servers (if set).
+     *
+     * @param servers List of objects containing server IDs
+     * @param getServerId Function that extracts the server ID from an object
+     * @returns Filtered list with policy applied
+     */
+    filterServersByPolicy<T>(servers: T[], getServerId: (item: T) => string): T[];
     /**
      * Get a reference to the CallToolObserver instance.
      */

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

@@ -84,6 +84,20 @@ export class PolicyEnforcer {
         }
         return this.serverPolicy.filterBlockedMcpServers(servers, getServerId);
     }
+    /**
+     * Applies both blocked and allowed server filtering.
+     * First removes blocked servers, then filters to allowed servers (if set).
+     *
+     * @param servers List of objects containing server IDs
+     * @param getServerId Function that extracts the server ID from an object
+     * @returns Filtered list with policy applied
+     */
+    filterServersByPolicy(servers, getServerId) {
+        if (!this.serverPolicy) {
+            throw new Error("PolicyEnforcer not initialized");
+        }
+        return this.serverPolicy.filterServersByPolicy(servers, getServerId);
+    }
     /**
      * Get a reference to the CallToolObserver instance.
      */

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

@@ -11,6 +11,8 @@ export declare class ServerPolicy {
     enforceBlockedServerPolicy(serverId: string): void;
     /**
      * Validates that a server is allowed.
+     * - For org users: if allowlist is empty/null, NO servers are allowed
+     * - For non-org users: if allowlist is empty/null, all servers are allowed
      *
      * @throws Error if attempting to use a server not in the allowed list
      */
@@ -36,4 +38,23 @@ export declare class ServerPolicy {
      * @returns Filtered list with blocked servers removed
      */
     filterBlockedMcpServers<T>(servers: T[], getServerId: (item: T) => string): T[];
+    /**
+     * Filters servers to only include allowed servers (if allowlist is set).
+     * - For org users: if allowlist is empty/null, return NO servers (admin hasn't approved any)
+     * - For non-org users: if allowlist is empty/null, return all servers (no restrictions)
+     *
+     * @param servers List of objects containing server IDs
+     * @param getServerId Function that extracts the server ID from an object
+     * @returns Filtered list with only allowed servers
+     */
+    filterToAllowedServers<T>(servers: T[], getServerId: (item: T) => string): T[];
+    /**
+     * Applies both blocked and allowed server filtering.
+     * First removes blocked servers, then filters to allowed servers (if set).
+     *
+     * @param servers List of objects containing server IDs
+     * @param getServerId Function that extracts the server ID from an object
+     * @returns Filtered list with policy applied
+     */
+    filterServersByPolicy<T>(servers: T[], getServerId: (item: T) => string): T[];
 }

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

@@ -15,14 +15,24 @@ export class ServerPolicy {
     }
     /**
      * Validates that a server is allowed.
+     * - For org users: if allowlist is empty/null, NO servers are allowed
+     * - For non-org users: if allowlist is empty/null, all servers are allowed
      *
      * @throws Error if attempting to use a server not in the allowed list
      */
     enforceAllowedServerPolicy(serverId) {
         const allowedServers = this.clientContext.permissions.allowed_mcp_servers;
-        if (allowedServers &&
-            allowedServers.length > 0 &&
-            !allowedServers.includes(serverId)) {
+        // If allowlist is empty/null
+        if (!allowedServers || allowedServers.length === 0) {
+            // For org users: empty allowlist means NO servers approved
+            if (this.clientContext.isOrgUser) {
+                throw new Error(`No tools have been approved for your organization yet. Please contact your admin to approve tools on the ToolPlex Dashboard.`);
+            }
+            // For non-org users: no restrictions
+            return;
+        }
+        // Check if server is in the allowlist
+        if (!allowedServers.includes(serverId)) {
             throw new Error(`Server "${serverId}" is not allowed for your account. Please adjust the Allowed MCP Servers permissions on the ToolPlex Dashboard if this is a mistake.`);
         }
     }
@@ -60,4 +70,39 @@ export class ServerPolicy {
     filterBlockedMcpServers(servers, getServerId) {
         return servers.filter((server) => !this.blockedMcpServersSet.has(getServerId(server)));
     }
+    /**
+     * Filters servers to only include allowed servers (if allowlist is set).
+     * - For org users: if allowlist is empty/null, return NO servers (admin hasn't approved any)
+     * - For non-org users: if allowlist is empty/null, return all servers (no restrictions)
+     *
+     * @param servers List of objects containing server IDs
+     * @param getServerId Function that extracts the server ID from an object
+     * @returns Filtered list with only allowed servers
+     */
+    filterToAllowedServers(servers, getServerId) {
+        const allowedServers = this.clientContext.permissions.allowed_mcp_servers;
+        // If no allowlist configured
+        if (!allowedServers || allowedServers.length === 0) {
+            // For org users: empty allowlist means NO servers approved yet
+            if (this.clientContext.isOrgUser) {
+                return [];
+            }
+            // For non-org users: no restrictions, return all
+            return servers;
+        }
+        const allowedSet = new Set(allowedServers);
+        return servers.filter((server) => allowedSet.has(getServerId(server)));
+    }
+    /**
+     * Applies both blocked and allowed server filtering.
+     * First removes blocked servers, then filters to allowed servers (if set).
+     *
+     * @param servers List of objects containing server IDs
+     * @param getServerId Function that extracts the server ID from an object
+     * @returns Filtered list with policy applied
+     */
+    filterServersByPolicy(servers, getServerId) {
+        const withoutBlocked = this.filterBlockedMcpServers(servers, getServerId);
+        return this.filterToAllowedServers(withoutBlocked, getServerId);
+    }
 }

package/dist/mcp-server/toolHandlers/initHandler.js

@@ -115,8 +115,13 @@ export async function handleInitialize(params) {
     else {
         await logger.debug("No session resume history provided (new session)");
     }
-    const allSucceeded = serverManagerInitResults.succeeded;
-    const allFailures = serverManagerInitResults.failures;
+    // Filter servers by policy (blocked + allowed)
+    const allSucceeded = policyEnforcer.filterServersByPolicy(serverManagerInitResults.succeeded, (s) => s.server_id);
+    // Also filter failures by policy
+    const failureEntries = Object.entries(serverManagerInitResults.failures);
+    const filteredFailureEntries = policyEnforcer.filterServersByPolicy(failureEntries, ([serverId]) => serverId);
+    const allFailures = Object.fromEntries(filteredFailureEntries);
+    await logger.info(`Filtered to ${allSucceeded.length} servers (policy enforced)`);
     // Initialize the serversCache with the succeeded servers
     serversCache.init(allSucceeded);
     await logger.debug(`Total successes: ${allSucceeded.length}, Total failures: ${Object.keys(allFailures).length}`);

package/dist/mcp-server/toolHandlers/listServersHandler.js

@@ -24,8 +24,8 @@ export async function handleListServers() {
                 continue;
             }
             if (parsed.data.servers && parsed.data.servers.length > 0) {
-                // Filter out blocked servers
-                const filteredServers = policyEnforcer.filterBlockedMcpServers(parsed.data.servers, (server) => server.server_id);
+                // Filter servers by policy (blocked + allowed)
+                const filteredServers = policyEnforcer.filterServersByPolicy(parsed.data.servers, (server) => server.server_id);
                 filteredServers.forEach((server) => {
                     // Add to allServers for cache update and structured response
                     allServers.push({

package/dist/mcp-server/toolHandlers/listToolsHandler.js

@@ -68,9 +68,9 @@ export async function handleListTools(params) {
                     await logger.error(`Invalid response from server manager: ${parsed.error}, runtime: ${runtime}`);
                     continue;
                 }
-                // Filter out blocked servers
+                // Filter servers by policy (blocked + allowed)
                 const serverEntries = Object.entries(parsed.data.tools);
-                const filteredEntries = policyEnforcer.filterBlockedMcpServers(serverEntries, ([serverId]) => serverId);
+                const filteredEntries = policyEnforcer.filterServersByPolicy(serverEntries, ([serverId]) => serverId);
                 for (const [serverId, serverTools] of filteredEntries) {
                     if (serverTools && serverTools.length > 0) {
                         allServerTools.push({

package/dist/server-manager/serverManager.js

@@ -23,6 +23,58 @@ class PermissiveJsonSchemaValidator {
     }
 }
 const logger = FileLogger;
+// Private registry constants
+const PRIVATE_REGISTRY_URL = "https://registry.toolplex.ai";
+const PRIVATE_SCOPE_PATTERN = /^@(tp-(user|org)-[a-f0-9]{11})\//;
+/**
+ * Extract the private registry scope from args if present.
+ * Returns the scope without @ (e.g., "tp-user-abc123def45") or null if not found.
+ */
+function extractPrivateRegistryScope(args) {
+    for (const arg of args) {
+        const match = arg.match(PRIVATE_SCOPE_PATTERN);
+        if (match) {
+            return match[1]; // e.g., "tp-user-abc123def45"
+        }
+    }
+    return null;
+}
+/**
+ * Build npm config env vars for private registry authentication.
+ *
+ * Uses Basic auth (_auth) instead of _authToken because:
+ * - _authToken expects a token issued by Verdaccio (JWT)
+ * - _auth sends username:password on every request, triggering authenticate()
+ *
+ * The Verdaccio auth plugin expects:
+ * - username: the scope without @ (e.g., "tp-user-abc123def45")
+ * - password: the ToolPlex API key (tp_live_xxx or tp_test_xxx)
+ *
+ * @param scope - The scope without @ (e.g., "tp-user-abc123def45")
+ * @param apiKey - The ToolPlex API key
+ */
+function getPrivateRegistryEnv(scope, apiKey) {
+    // Create base64-encoded "username:password" for Basic auth
+    // Username is the scope (e.g., "tp-user-abc123def45")
+    // Password is the API key
+    const auth = Buffer.from(`${scope}:${apiKey}`).toString("base64");
+    return {
+        // Set the registry for @tp-user-* and @tp-org-* scopes
+        // Note: Using npm_config_ prefix with special chars may not work on all systems
+        "npm_config_@tp-user:registry": PRIVATE_REGISTRY_URL,
+        "npm_config_@tp-org:registry": PRIVATE_REGISTRY_URL,
+        // Set Basic auth for the registry
+        // npm_config_//host/:_auth maps to //host/:_auth in .npmrc
+        "npm_config_//registry.toolplex.ai/:_auth": auth,
+    };
+}
+/**
+ * Get additional args to prepend for private registry packages.
+ * Uses --registry flag which is more reliable than env vars with special chars.
+ */
+function getPrivateRegistryArgs() {
+    return [`--registry=${PRIVATE_REGISTRY_URL}`];
+}
 export class ServerManager {
     constructor() {
         this.config = {};
@@ -287,16 +339,38 @@ export class ServerManager {
                 resolvedCommand = resolved.command;
                 prependArgs = resolved.prependArgs;
             }
+            // Check if this is a private registry package and inject auth if needed
+            // Private packages have scopes like @tp-user-xxx/ or @tp-org-xxx/
+            let privateRegistryEnv = {};
+            let privateRegistryArgs = [];
+            const privateScope = extractPrivateRegistryScope(config.args || []);
+            if (privateScope) {
+                const apiKey = process.env.TOOLPLEX_API_KEY;
+                if (apiKey) {
+                    privateRegistryEnv = getPrivateRegistryEnv(privateScope, apiKey);
+                    privateRegistryArgs = getPrivateRegistryArgs();
+                    await logger.debug(`Injecting private registry auth for ${serverId} (scope: ${privateScope})`);
+                }
+                else {
+                    await logger.warn(`Private registry package detected but no TOOLPLEX_API_KEY available`);
+                }
+            }
             // Combine prependArgs with config.args
             // e.g., if npx is a .js file: command="node", prependArgs=["/path/to/npx-cli.js"]
             // then args become ["/path/to/npx-cli.js", "-y", "@wonderwhy-er/desktop-commander"]
-            const finalArgs = [...prependArgs, ...(config.args || [])];
+            // For private registry packages, insert --registry flag after prependArgs but before package name
+            const finalArgs = [
+                ...prependArgs,
+                ...privateRegistryArgs,
+                ...(config.args || []),
+            ];
             const serverParams = {
                 command: resolvedCommand,
                 args: finalArgs,
                 env: {
                     ...process.env,
                     PATH: inheritedPath,
+                    ...privateRegistryEnv,
                     ...(config.env || {}),
                 },
                 stderr: "pipe",

package/dist/src/mcp-server/policy/policyEnforcer.js

@@ -84,6 +84,20 @@ export class PolicyEnforcer {
         }
         return this.serverPolicy.filterBlockedMcpServers(servers, getServerId);
     }
+    /**
+     * Applies both blocked and allowed server filtering.
+     * First removes blocked servers, then filters to allowed servers (if set).
+     *
+     * @param servers List of objects containing server IDs
+     * @param getServerId Function that extracts the server ID from an object
+     * @returns Filtered list with policy applied
+     */
+    filterServersByPolicy(servers, getServerId) {
+        if (!this.serverPolicy) {
+            throw new Error("PolicyEnforcer not initialized");
+        }
+        return this.serverPolicy.filterServersByPolicy(servers, getServerId);
+    }
     /**
      * Get a reference to the CallToolObserver instance.
      */

package/dist/src/mcp-server/policy/serverPolicy.js

@@ -15,14 +15,24 @@ export class ServerPolicy {
     }
     /**
      * Validates that a server is allowed.
+     * - For org users: if allowlist is empty/null, NO servers are allowed
+     * - For non-org users: if allowlist is empty/null, all servers are allowed
      *
      * @throws Error if attempting to use a server not in the allowed list
      */
     enforceAllowedServerPolicy(serverId) {
         const allowedServers = this.clientContext.permissions.allowed_mcp_servers;
-        if (allowedServers &&
-            allowedServers.length > 0 &&
-            !allowedServers.includes(serverId)) {
+        // If allowlist is empty/null
+        if (!allowedServers || allowedServers.length === 0) {
+            // For org users: empty allowlist means NO servers approved
+            if (this.clientContext.isOrgUser) {
+                throw new Error(`No tools have been approved for your organization yet. Please contact your admin to approve tools on the ToolPlex Dashboard.`);
+            }
+            // For non-org users: no restrictions
+            return;
+        }
+        // Check if server is in the allowlist
+        if (!allowedServers.includes(serverId)) {
             throw new Error(`Server "${serverId}" is not allowed for your account. Please adjust the Allowed MCP Servers permissions on the ToolPlex Dashboard if this is a mistake.`);
         }
     }
@@ -60,4 +70,39 @@ export class ServerPolicy {
     filterBlockedMcpServers(servers, getServerId) {
         return servers.filter((server) => !this.blockedMcpServersSet.has(getServerId(server)));
     }
+    /**
+     * Filters servers to only include allowed servers (if allowlist is set).
+     * - For org users: if allowlist is empty/null, return NO servers (admin hasn't approved any)
+     * - For non-org users: if allowlist is empty/null, return all servers (no restrictions)
+     *
+     * @param servers List of objects containing server IDs
+     * @param getServerId Function that extracts the server ID from an object
+     * @returns Filtered list with only allowed servers
+     */
+    filterToAllowedServers(servers, getServerId) {
+        const allowedServers = this.clientContext.permissions.allowed_mcp_servers;
+        // If no allowlist configured
+        if (!allowedServers || allowedServers.length === 0) {
+            // For org users: empty allowlist means NO servers approved yet
+            if (this.clientContext.isOrgUser) {
+                return [];
+            }
+            // For non-org users: no restrictions, return all
+            return servers;
+        }
+        const allowedSet = new Set(allowedServers);
+        return servers.filter((server) => allowedSet.has(getServerId(server)));
+    }
+    /**
+     * Applies both blocked and allowed server filtering.
+     * First removes blocked servers, then filters to allowed servers (if set).
+     *
+     * @param servers List of objects containing server IDs
+     * @param getServerId Function that extracts the server ID from an object
+     * @returns Filtered list with policy applied
+     */
+    filterServersByPolicy(servers, getServerId) {
+        const withoutBlocked = this.filterBlockedMcpServers(servers, getServerId);
+        return this.filterToAllowedServers(withoutBlocked, getServerId);
+    }
 }

package/dist/src/mcp-server/toolHandlers/initHandler.js

@@ -115,8 +115,13 @@ export async function handleInitialize(params) {
     else {
         await logger.debug("No session resume history provided (new session)");
     }
-    const allSucceeded = serverManagerInitResults.succeeded;
-    const allFailures = serverManagerInitResults.failures;
+    // Filter servers by policy (blocked + allowed)
+    const allSucceeded = policyEnforcer.filterServersByPolicy(serverManagerInitResults.succeeded, (s) => s.server_id);
+    // Also filter failures by policy
+    const failureEntries = Object.entries(serverManagerInitResults.failures);
+    const filteredFailureEntries = policyEnforcer.filterServersByPolicy(failureEntries, ([serverId]) => serverId);
+    const allFailures = Object.fromEntries(filteredFailureEntries);
+    await logger.info(`Filtered to ${allSucceeded.length} servers (policy enforced)`);
     // Initialize the serversCache with the succeeded servers
     serversCache.init(allSucceeded);
     await logger.debug(`Total successes: ${allSucceeded.length}, Total failures: ${Object.keys(allFailures).length}`);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "0.1.33";
+export declare const version = "0.1.35";

package/dist/version.js

@@ -1 +1 @@
-export const version = '0.1.33';
+export const version = '0.1.35';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolplex/client",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "author": "ToolPlex LLC",
   "license": "SEE LICENSE IN LICENSE",
   "description": "The official ToolPlex client for AI agent tool discovery and execution",