@yawlabs/mcp-connect 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,174 @@
+# @yawlabs/mcp-connect
+
+One install. All your MCP servers. Managed from the cloud.
+
+mcp-connect is an MCP server that orchestrates all your other MCP servers. Configure your servers once on [mcp.hosting](https://mcp.hosting), install mcp-connect in your client, and never hand-edit MCP JSON configs again.
+
+## How it works
+
+```
+Your MCP client (Claude Code, Cursor, etc.)
+    |
+    |  single stdio connection
+    v
+@yawlabs/mcp-connect
+    |         |         |
+    v         v         v
+  GitHub    Slack    Stripe     ← your MCP servers (local or remote)
+```
+
+1. You add servers on [mcp.hosting](https://mcp.hosting) (name, command, args, env vars)
+2. mcp-connect pulls your config on startup
+3. You use 3 meta-tools to control which servers are active:
+   - **`mcp_connect_discover`** — list all configured servers
+   - **`mcp_connect_activate`** — connect a server and load its tools
+   - **`mcp_connect_deactivate`** — disconnect and remove tools
+
+Only activated servers load tools into context. This keeps your context window clean.
+
+## Install
+
+### Claude Code
+
+```json
+{
+  "mcpServers": {
+    "mcp-connect": {
+      "command": "npx",
+      "args": ["-y", "@yawlabs/mcp-connect"],
+      "env": {
+        "MCP_HOSTING_TOKEN": "mcp_pat_your_token_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor / VS Code
+
+Add to your MCP settings:
+
+```json
+{
+  "mcp-connect": {
+    "command": "npx",
+    "args": ["-y", "@yawlabs/mcp-connect"],
+    "env": {
+      "MCP_HOSTING_TOKEN": "mcp_pat_your_token_here"
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-connect": {
+      "command": "npx",
+      "args": ["-y", "@yawlabs/mcp-connect"],
+      "env": {
+        "MCP_HOSTING_TOKEN": "mcp_pat_your_token_here"
+      }
+    }
+  }
+}
+```
+
+## Getting your token
+
+1. Sign up at [mcp.hosting](https://mcp.hosting)
+2. Go to **Settings > API Tokens**
+3. Create a token — it starts with `mcp_pat_`
+4. Add it to your MCP client config as shown above
+
+## Adding servers
+
+On [mcp.hosting](https://mcp.hosting), add each MCP server you want to orchestrate:
+
+| Field | Description |
+|-------|-------------|
+| **Name** | Display name (e.g., "GitHub") |
+| **Namespace** | Short prefix for tool names (e.g., "gh") |
+| **Type** | `local` (stdio) or `remote` (HTTP) |
+| **Command** | For local: the command to run (e.g., "npx") |
+| **Args** | For local: command arguments (e.g., ["-y", "@modelcontextprotocol/server-github"]) |
+| **Env** | Environment variables (API keys, tokens) |
+| **URL** | For remote: the server URL |
+
+## Usage
+
+Once configured, your LLM will see three tools. Here's the typical flow:
+
+### 1. Discover servers
+
+```
+> What MCP servers do I have?
+
+Available MCP servers:
+
+  gh — GitHub [available] (local)
+  slack — Slack [available] (local)
+  stripe — Stripe [available] (local)
+
+0 active, 0 tools loaded.
+```
+
+### 2. Activate what you need
+
+```
+> Activate my GitHub server
+
+Activated "gh" — 24 tools available: gh_create_issue, gh_list_prs, ...
+```
+
+The tool list updates automatically via `tools/list_changed`. Your client will see the new tools immediately.
+
+### 3. Use the tools
+
+```
+> List my open PRs
+
+[gh_list_prs is called, returns results]
+```
+
+Tools are namespaced: `{namespace}_{original_tool_name}`. This prevents collisions between servers.
+
+### 4. Deactivate when done
+
+```
+> Deactivate GitHub
+
+Deactivated "gh". Tools removed.
+```
+
+This frees up context for other tools.
+
+## Config sync
+
+mcp-connect polls [mcp.hosting](https://mcp.hosting) every 60 seconds for config changes. When you add, remove, or modify a server on the dashboard, mcp-connect picks it up automatically — no restart needed.
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MCP_HOSTING_TOKEN` | Yes | Your personal access token from mcp.hosting |
+| `MCP_HOSTING_URL` | No | API URL (default: `https://mcp.hosting`) |
+
+## Requirements
+
+- Node.js 18+
+- An [mcp.hosting](https://mcp.hosting) account
+
+## License
+
+MIT
+
+## Links
+
+- [mcp.hosting](https://mcp.hosting) — Dashboard and server management
+- [@yawlabs/mcp-compliance](https://www.npmjs.com/package/@yawlabs/mcp-compliance) — Test your MCP servers for spec compliance
+- [GitHub](https://github.com/YawLabs/mcp-connect) — Source code and issues

package/dist/index.js

@@ -56,7 +56,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 var META_TOOLS = {
   discover: {
     name: "mcp_connect_discover",
-    description: "List all available MCP servers configured in your mcp.hosting account. Shows server names, namespaces, types, and whether they are currently active. Call this first to see what servers are available before activating them.",
+    description: "List all available MCP servers. Call this FIRST before activating anything. Only activate servers you need for the CURRENT task \u2014 each one adds tools to your context. Shows server names, namespaces, tool counts, and activation status.",
     inputSchema: {
       type: "object",
       properties: {}
@@ -71,7 +71,7 @@ var META_TOOLS = {
   },
   activate: {
     name: "mcp_connect_activate",
-    description: 'Activate an MCP server by its namespace. This connects to the server and makes its tools available. After activation, the tool list will update with the new tools prefixed by the namespace (e.g., "gh_create_issue" for namespace "gh").',
+    description: 'Activate an MCP server by namespace to load its tools. Each server adds tools to context, so only activate what you need right now. Good practice: deactivate servers you are done with before activating new ones. Tools are prefixed by namespace (e.g., "gh_create_issue").',
     inputSchema: {
       type: "object",
       properties: {
@@ -92,7 +92,7 @@ var META_TOOLS = {
   },
   deactivate: {
     name: "mcp_connect_deactivate",
-    description: "Deactivate an MCP server by its namespace. This disconnects from the server and removes its tools from the available tool list. Use this to free up context when you no longer need a server.",
+    description: "Deactivate an MCP server to remove its tools and free context. Always deactivate servers you are finished with. Servers idle for 10+ tool calls to other servers are auto-deactivated.",
     inputSchema: {
       type: "object",
       properties: {
@@ -257,7 +257,7 @@ async function fetchToolsFromUpstream(client, namespace) {
 
 // src/server.ts
 var POLL_INTERVAL = 6e4;
-var ConnectServer = class {
+var ConnectServer = class _ConnectServer {
   constructor(apiUrl2, token2) {
     this.apiUrl = apiUrl2;
     this.token = token2;
@@ -275,6 +275,8 @@ var ConnectServer = class {
   configVersion = null;
   pollTimer = null;
   toolRoutes = /* @__PURE__ */ new Map();
+  idleCallCounts = /* @__PURE__ */ new Map();
+  static IDLE_CALL_THRESHOLD = 10;
   setupHandlers() {
     this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
       tools: buildToolList(this.connections)
@@ -312,7 +314,12 @@ var ConnectServer = class {
     if (name === META_TOOLS.deactivate.name) {
       return this.handleDeactivate(args.server);
     }
-    return routeToolCall(name, args, this.toolRoutes, this.connections);
+    const route = this.toolRoutes.get(name);
+    const result = await routeToolCall(name, args, this.toolRoutes, this.connections);
+    if (route) {
+      await this.trackUsageAndAutoDeactivate(route.namespace);
+    }
+    return result;
   }
   handleDiscover() {
     if (!this.config || this.config.servers.length === 0) {
@@ -381,6 +388,7 @@ var ConnectServer = class {
     try {
       const connection = await connectToUpstream(serverConfig);
       this.connections.set(namespace, connection);
+      this.idleCallCounts.set(namespace, 0);
       this.toolRoutes = buildToolRoutes(this.connections);
       await this.server.sendToolListChanged();
       const toolNames = connection.tools.map((t) => t.namespacedName).join(", ");
@@ -416,12 +424,40 @@ var ConnectServer = class {
     }
     await disconnectFromUpstream(connection);
     this.connections.delete(namespace);
+    this.idleCallCounts.delete(namespace);
     this.toolRoutes = buildToolRoutes(this.connections);
     await this.server.sendToolListChanged();
     return {
       content: [{ type: "text", text: 'Deactivated "' + namespace + '". Tools removed.' }]
     };
   }
+  async trackUsageAndAutoDeactivate(calledNamespace) {
+    this.idleCallCounts.set(calledNamespace, 0);
+    for (const ns of this.connections.keys()) {
+      if (ns !== calledNamespace) {
+        this.idleCallCounts.set(ns, (this.idleCallCounts.get(ns) ?? 0) + 1);
+      }
+    }
+    const toDeactivate = [];
+    for (const [ns, idleCount] of this.idleCallCounts) {
+      if (idleCount >= _ConnectServer.IDLE_CALL_THRESHOLD && this.connections.has(ns)) {
+        toDeactivate.push(ns);
+      }
+    }
+    for (const ns of toDeactivate) {
+      log("info", "Auto-deactivating idle server", { namespace: ns, idleCalls: this.idleCallCounts.get(ns) });
+      const connection = this.connections.get(ns);
+      if (connection) {
+        await disconnectFromUpstream(connection);
+        this.connections.delete(ns);
+        this.idleCallCounts.delete(ns);
+      }
+    }
+    if (toDeactivate.length > 0) {
+      this.toolRoutes = buildToolRoutes(this.connections);
+      await this.server.sendToolListChanged();
+    }
+  }
   async fetchAndApplyConfig() {
     const newConfig = await fetchConfig(this.apiUrl, this.token);
     if (newConfig.configVersion === this.configVersion) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/mcp-connect",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "MCP orchestrator — one install, all your MCP servers, managed from the cloud",
   "license": "MIT",
   "author": "Yaw Labs <contact@yaw.sh> (https://yaw.sh)",