cdp-toolkit 1.10.0 → 2.0.0

package/src/mcp.ts

@@ -15,9 +15,9 @@
  *
  * stdout is the JSON-RPC channel, all diagnostics go to stderr only.
  */
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { Server } from "@modelcontextprotocol/server";
+import type { Tool } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { TOOLS, TOOL_NAMES, BASE } from "./index.ts";
 import { MANIFEST } from "./manifest.ts";
 import { resolveBackend, getOrCreateFirefoxSession, disposeFirefoxSession } from "./backend.ts";
@@ -25,8 +25,10 @@ import { disposeBrowserSession } from "./tools/browser-session.ts";
 import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, markLongLivedProcess, withLeaseScope } from "./leases.ts";
+import { TOOL_GROUP, TOOL_GROUPS, GROUP_TOOLS, PROFILES, type ProfileName } from "./toolGroups.ts";
+import { TOOL_DOCS } from "./toolDocs.ts";
 
-const VERSION = "1.10.0";
+const VERSION = "2.0.0";
 
 // Backend + (Firefox only) attach endpoint are read once at startup (MCP has no per-call notion
 // of backend): --browser flag / CDP_BROWSER env, else "chrome" (zero behavior change for existing
@@ -59,24 +61,134 @@ function auditCoverage(): void {
 // cap and front-loaded (grammar + leases before origin) so nothing critical is clipped.
 const INSTRUCTIONS = [
   "cdp-toolkit drives a real browser over Chrome DevTools Protocol (or Firefox WebDriver-BiDi): open and drive pages, click/fill/type, screenshot and accessibility-snapshot, read console + network, set cookies, emulate devices, run Lighthouse and performance traces, record screencasts. Conventions shared across its tools:",
+  "TOOL AVAILABILITY: the server starts on the core profile (12 everyday tools); the rest are organized into groups you can discover and activate with `browser_tools` (or start with CDP_TOOL_PROFILE=full for everything at once). `describe_tool` returns full docs for any tool by name, including hidden ones. Hidden tools are still callable by name even while unlisted.",
   "TARGET SELECTOR (the `target` param, unless a tool says otherwise): 'active' (default = first page) | 'index:N' (0-based) | 'url:<substr>' | 'title:<substr>' | 'label:<name>' (exact, from the origin ledger or a live lease) | a 32-hex '<targetId>'. Four Chrome-only tools (evaluate_script, list_network_requests, get_network_request, list_console_messages) also accept 'worker:<substr>' to reach a service/shared worker — e.g. an MV3 extension's background worker (worker:<extension-id> or worker:background.js); an idle-evicted worker is started first (see each tool's `wake`).",
   "LEASES (the `lease` param): claim_page, and new_page{claim:true}, mint an opaque token. Omit it for a tab THIS process already holds. It is required for a tab held by ANOTHER process, or one claimed explicitly. Under CDP_REQUIRE_LEASE the gate auto-acquires a lease for any tab this process drives — no token is surfaced, so pass `target`, not `lease` — while an explicit claim:true still demands its token on every later call. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all.",
   "ORIGIN: list_pages and list_leases tag each tab's `origin` as 'agent' (this toolkit created it) or 'unknown' — never 'human', because the toolkit cannot prove a person opened a tab. An 'agent' tab stays findable after its creator releases the lease or dies.",
 ].join("\n\n");
 
-const server = new Server({ name: "cdp-toolkit", version: VERSION }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+// Progressive disclosure: start with a lean profile (default "core") and reveal
+// further tool groups on demand via the browser_tools meta-tool, which fires
+// notifications/tools/list_changed so the client re-fetches tools/list. This keeps
+// the baseline tools/list payload — and thus the context tokens the toolkit costs —
+// a fraction of the full 45-tool surface until a group is actually needed. Set
+// CDP_TOOL_PROFILE=full to advertise everything at startup (prior behavior).
+const START_PROFILE: ProfileName = process.env.CDP_TOOL_PROFILE === "full" ? "full" : "core";
+const activeGroups = new Set<string>(PROFILES[START_PROFILE]);
 
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-  // Filtered to whatever the selected backend can actually run, per REQUIRED_CAPABILITIES:
-  // under Chrome this is byte-identical to the unfiltered MANIFEST (every capability CDP needs
-  // is declared); under Firefox the performance/heap/lighthouse tools are simply absent.
-  tools: MANIFEST.filter((s) => AVAILABLE_NAMES.has(s.name)).map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema })),
+/** Always-listed meta-tools that drive disclosure; never part of a group. */
+const META_TOOLS: ReadonlyArray<{ name: string; description: string; inputSchema: Tool["inputSchema"] }> = [
+  {
+    name: "browser_tools",
+    description:
+      "Manage which cdp-toolkit tool groups are exposed (progressive disclosure). Most tools are hidden until their group is activated; activating one reveals its tools via tools/list_changed. Use action:list_groups first to see what exists.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["list_groups", "activate", "deactivate", "set_profile"],
+          description: "list_groups: show every group, its tools, and active state; activate/deactivate: toggle one group; set_profile: switch wholesale.",
+        },
+        group: { type: "string", enum: [...TOOL_GROUPS], description: "Group for activate/deactivate." },
+        profile: { type: "string", enum: ["core", "full"], description: "Profile for set_profile (core=lean, full=all groups)." },
+      },
+      required: ["action"],
+      additionalProperties: false,
+    } as Tool["inputSchema"],
+  },
+  {
+    name: "describe_tool",
+    description: "Return the full description and per-parameter docs for any cdp-toolkit tool by name — including tools not currently listed. Call this before using an unfamiliar tool; the live tools/list carries only terse summaries.",
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string", description: "Tool name, e.g. take_screenshot." } },
+      required: ["name"],
+      additionalProperties: false,
+    } as Tool["inputSchema"],
+  },
+];
+
+/** Human-readable dump of every group, its tools, and whether it's currently active. */
+function renderGroups(): string {
+  const lines = [`profile start=${START_PROFILE}; active groups: ${[...activeGroups].join(", ") || "(none)"}`];
+  for (const g of TOOL_GROUPS) {
+    const shown = GROUP_TOOLS[g].filter((n) => AVAILABLE_NAMES.has(n));
+    lines.push(`${activeGroups.has(g) ? "[on] " : "[off]"} ${g} (${shown.length}): ${shown.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+/** describe_tool body: full prose for one tool from the on-demand docs map. */
+function renderToolDoc(toolName: string): string {
+  const doc = TOOL_DOCS[toolName];
+  if (!doc) return `unknown tool: ${toolName}`;
+  const group = TOOL_GROUP[toolName];
+  const params = Object.entries(doc.params);
+  const body = params.length ? params.map(([p, d]) => `- ${p}: ${d || "(no description)"}`).join("\n") : "(no parameters)";
+  return `${toolName}${group ? ` [group: ${group}]` : ""}\n\n${doc.description}\n\nParameters:\n${body}`;
+}
+
+const server = new Server({ name: "cdp-toolkit", version: VERSION }, { capabilities: { tools: { listChanged: true } }, instructions: INSTRUCTIONS });
+
+server.setRequestHandler('tools/list', async () => ({
+  // Two-axis disclosure: (1) the always-present meta-tools; (2) manifest tools the
+  // selected backend can run AND whose group is currently active. Descriptions/schemas
+  // here are the compressed form — full prose is served on demand by describe_tool.
+  tools: [
+    ...META_TOOLS,
+    ...MANIFEST
+      .filter((s) => AVAILABLE_NAMES.has(s.name) && activeGroups.has(TOOL_GROUP[s.name] ?? ""))
+      .map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema as Tool["inputSchema"] })),
+  ],
 }));
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+server.setRequestHandler('tools/call', async (request) => {
   const { name } = request.params;
   const args = (request.params.arguments ?? {}) as unknown;
 
+  // Meta-tools are handled at the MCP layer (they mutate what tools/list advertises)
+  // and never enter the browser dispatch or a lease scope.
+  if (name === "describe_tool") {
+    const toolName = typeof (args as { name?: unknown }).name === "string" ? (args as { name: string }).name : "";
+    const known = Boolean(TOOL_DOCS[toolName]);
+    return { content: [{ type: "text" as const, text: renderToolDoc(toolName) }], isError: !known };
+  }
+
+  if (name === "browser_tools") {
+    const a = args as { action?: unknown; group?: unknown; profile?: unknown };
+    const action = typeof a.action === "string" ? a.action : "";
+    const before = [...activeGroups].sort().join(",");
+
+    if (action === "list_groups") {
+      return { content: [{ type: "text" as const, text: renderGroups() }] };
+    }
+    if (action === "activate" || action === "deactivate") {
+      const group = typeof a.group === "string" ? a.group : "";
+      if (!(TOOL_GROUPS as readonly string[]).includes(group)) {
+        return { content: [{ type: "text" as const, text: `unknown group: ${group}. Known: ${TOOL_GROUPS.join(", ")}` }], isError: true };
+      }
+      if (action === "activate") activeGroups.add(group);
+      else activeGroups.delete(group);
+    } else if (action === "set_profile") {
+      const profile = a.profile === "full" ? "full" : a.profile === "core" ? "core" : "";
+      if (!profile) return { content: [{ type: "text" as const, text: `unknown profile: ${String(a.profile)}. Known: core, full` }], isError: true };
+      activeGroups.clear();
+      for (const g of PROFILES[profile]) activeGroups.add(g);
+    } else {
+      return { content: [{ type: "text" as const, text: `unknown action: ${action}. Use list_groups | activate | deactivate | set_profile.` }], isError: true };
+    }
+
+    if ([...activeGroups].sort().join(",") !== before) {
+      try {
+        await server.sendToolListChanged();
+      } catch (err) {
+        console.error(`[cdp-toolkit] WARN: sendToolListChanged failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    return { content: [{ type: "text" as const, text: renderGroups() }] };
+  }
+
   if (!AVAILABLE_NAMES.has(name)) {
     const gap = AVAILABILITY.unavailable.find((u) => u.name === name);
     return {