@shawnowen/comet-mcp 2.3.1 → 2.4.1

package/dist/discovery/tool-meta.js

@@ -0,0 +1,229 @@
+/**
+ * tool-meta.ts
+ * Discovery metadata catalog for the 25 native Comet MCP tools (Spec 042, T024).
+ *
+ * Each entry provides the discovery-layer fields that are NOT present in the
+ * existing TOOLS array in index.ts: canonicalId, safety, preconditions,
+ * intentKeywords, and a description following the R10 template.
+ *
+ * AUTHORITATIVE SOURCES:
+ *   - Safety classes: docs/TOOL-SAFETY-REFERENCE.md
+ *   - Preconditions: same doc, safety class descriptions
+ *
+ * This file is the single source of truth for native-tool discovery metadata.
+ * When a new tool is added to TOOLS in index.ts, add a matching entry here.
+ */
+// CDP session precondition (reused across SESSION tools)
+const CDP_SESSION = {
+    kind: "cdp_session",
+    note: "Requires an active Comet CDP session — call comet_connect first",
+};
+/**
+ * Discovery metadata for the 25 native MCP tools.
+ * Order matches the TOOLS array in index.ts for readability.
+ */
+export const TOOL_META = [
+    {
+        toolName: "comet_connect",
+        canonicalId: "comet-connect",
+        safety: "SESSION",
+        preconditions: [],
+        intentKeywords: ["connect", "start session", "browser", "tab group", "agent session", "open browser"],
+        description: "Connect to the Comet browser and create a new tab group for this agent session. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_ask",
+        canonicalId: "comet-ask",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["ask", "prompt", "perplexity", "research", "ai", "question", "sidecar"],
+        description: "Send a prompt to Comet/Perplexity AI and wait for the complete response. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_poll",
+        canonicalId: "comet-poll",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["poll", "status", "progress", "monitor", "check", "agentic task"],
+        description: "Check agent status and progress in the current session. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_stop",
+        canonicalId: "comet-stop",
+        safety: "CAUTION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["stop", "cancel", "abort", "terminate", "halt"],
+        description: "Stop the current agent task if it is going off track. CAUTION: terminates the running task — only use on YOUR OWN session. Source: mcp. Safety: CAUTION.",
+    },
+    {
+        toolName: "comet_screenshot",
+        canonicalId: "comet-screenshot",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["screenshot", "capture", "image", "png", "visual", "photo"],
+        description: "Capture a screenshot of the current page in this agent's tab. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_mode",
+        canonicalId: "comet-mode",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["mode", "perplexity mode", "search mode", "focus", "writing", "coding"],
+        description: "Get or set the Perplexity search mode in this agent's tab. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_tab_groups",
+        canonicalId: "comet-tab-groups",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["tab group", "tabs", "list groups", "create group", "archive", "restore", "save group"],
+        description: "Manage Chrome tab groups — list, create, update, archive, restore, and delete groups. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_shortcut",
+        canonicalId: "comet-shortcut",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["shortcut", "query shortcut", "quick command", "template", "macro"],
+        description: "Trigger a query shortcut in this agent's Perplexity tab. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_read_page",
+        canonicalId: "comet-read-page",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["read page", "extract text", "page content", "dom tree", "accessibility tree", "markdown"],
+        description: "Extract text, links, or DOM tree from the current page in this agent's tab. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_interact",
+        canonicalId: "comet-interact",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["interact", "click", "type", "fill form", "input", "button", "element", "action"],
+        description: "Execute click, type, scroll, and fill-form actions on the current page. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_navigate",
+        canonicalId: "comet-navigate",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["navigate", "go to", "open url", "browse", "load page", "visit"],
+        description: "Navigate this agent's tab to a specified URL. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_wait_for_idle",
+        canonicalId: "comet-wait-for-idle",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["wait", "idle", "network idle", "page load", "settle", "ready"],
+        description: "Wait for this agent's tab to finish loading and reach a network-idle state. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_lifecycle_start",
+        canonicalId: "comet-lifecycle-start",
+        safety: "SESSION",
+        preconditions: [{ kind: "task_thread", note: "A task thread ID must be registered before calling" }],
+        intentKeywords: ["lifecycle start", "start task", "begin run", "dispatch agent", "register lifecycle"],
+        description: "Register the start of a lifecycle run for a task thread with the Command Center. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_lifecycle_complete",
+        canonicalId: "comet-lifecycle-complete",
+        safety: "SESSION",
+        preconditions: [{ kind: "task_thread", note: "A started lifecycle run must exist for the task thread" }],
+        intentKeywords: ["lifecycle complete", "finish task", "complete run", "mark done", "task success"],
+        description: "Mark a lifecycle run as successfully completed with the Command Center. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_lifecycle_abort",
+        canonicalId: "comet-lifecycle-abort",
+        safety: "SESSION",
+        preconditions: [{ kind: "task_thread", note: "A started lifecycle run must exist for the task thread" }],
+        intentKeywords: ["lifecycle abort", "abort task", "cancel run", "task failed", "terminate lifecycle"],
+        description: "Abort a lifecycle run and record the reason with the Command Center. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_lifecycle_update",
+        canonicalId: "comet-lifecycle-update",
+        safety: "SESSION",
+        preconditions: [{ kind: "task_thread", note: "A started lifecycle run must exist for the task thread" }],
+        intentKeywords: ["lifecycle update", "update status", "progress update", "task status update"],
+        description: "Send a status update or progress event for an active lifecycle run. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_task_status",
+        canonicalId: "comet-task-status",
+        safety: "SAFE",
+        preconditions: [],
+        intentKeywords: ["task status", "task thread", "orchestrator", "equabot", "agent status", "running tasks"],
+        description: "Get the current status of Equabot task threads and orchestrator agents. Source: mcp. Safety: SAFE.",
+    },
+    {
+        toolName: "comet_delegate",
+        canonicalId: "comet-delegate",
+        safety: "CAUTION",
+        preconditions: [{ kind: "task_group", note: "COMET_TASK_GROUP must be set for the calling agent" }],
+        intentKeywords: ["delegate", "spawn agent", "sub-agent", "dispatch task", "equabot", "multi-agent"],
+        description: "Delegate a task to an Equabot sub-agent. CAUTION: spawns a new agent process — ensure you own the task thread before delegating. Source: mcp. Safety: CAUTION.",
+    },
+    {
+        toolName: "comet_observe",
+        canonicalId: "comet-observe",
+        safety: "SAFE",
+        preconditions: [],
+        intentKeywords: ["observe", "snapshot", "health check", "agents", "tab groups", "browser status", "overview"],
+        description: "Observe the browser environment — health, snapshot, status, or detail view of tab groups and agents. Source: mcp. Safety: SAFE.",
+    },
+    {
+        toolName: "comet_peek",
+        canonicalId: "comet-peek",
+        safety: "SAFE",
+        preconditions: [],
+        intentKeywords: ["peek", "inspect tab", "tab info", "read other tab", "screenshot other", "cross-agent observe"],
+        description: "Peek at any browser tab — get info, screenshot, or page text without affecting the tab. Source: mcp. Safety: SAFE.",
+    },
+    {
+        toolName: "comet_pdf",
+        canonicalId: "comet-pdf",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["pdf", "print", "save page", "generate pdf", "document", "export"],
+        description: "Generate a PDF of the current page in this agent's tab. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_scrape",
+        canonicalId: "comet-scrape",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["scrape", "extract", "structured data", "table", "list", "parse page", "data extraction"],
+        description: "Extract structured data (tables, lists, forms) from the current page. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_network",
+        canonicalId: "comet-network",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["network", "requests", "api calls", "xhr", "fetch", "capture traffic", "network log"],
+        description: "Capture and inspect network requests from the current page. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_automate",
+        canonicalId: "comet-automate",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["automate", "workflow", "multi-step", "automation", "sequence", "playbook"],
+        description: "Run a multi-step automation workflow in this agent's tab following a defined playbook. Source: mcp. Safety: SESSION.",
+    },
+    {
+        toolName: "comet_domain",
+        canonicalId: "comet-domain",
+        safety: "SESSION",
+        preconditions: [CDP_SESSION],
+        intentKeywords: ["domain", "quickbooks", "mercury", "github", "google", "salt", "auth", "login"],
+        description: "Route to a domain-specific playbook for authenticated sites (QBO, Mercury, GitHub, Google, SALT). Source: mcp. Safety: SESSION.",
+    },
+];
+/** Lookup map: toolName → ToolMeta */
+export const TOOL_META_MAP = new Map(TOOL_META.map((m) => [m.toolName, m]));
+//# sourceMappingURL=tool-meta.js.map

package/dist/discovery/virtual-tools.d.ts

@@ -0,0 +1,20 @@
+/**
+ * virtual-tools.ts
+ * Virtual MCP tool emitter for the Comet Discovery Layer (Spec 042, T011/T022/T034/T035/T045).
+ *
+ * T011: Stub (proved the integration point compiled).
+ * T022: Emit pass-through McpToolDefinition for recommended native entries.
+ * T034: Inject description-template output into the description field.
+ * T035: Append preconditions block to each tool description.
+ * T045: Handle plugin guide + extension dispatch (US3, future).
+ */
+import type { CapabilityEntry, McpToolDefinition } from "./capability-entry.js";
+/**
+ * Emit McpToolDefinition objects for every non-humanOnly recommended entry.
+ *
+ * T022: native pass-through — uses the original argsSchema so the tool
+ *   contract is byte-identical to the pre-discovery registration (FR-009).
+ * T045: plugin guide and extension dispatch (not yet implemented).
+ */
+export declare function emitVirtualTools(entries: CapabilityEntry[]): McpToolDefinition[];
+//# sourceMappingURL=virtual-tools.d.ts.map

package/dist/discovery/virtual-tools.js

@@ -0,0 +1,69 @@
+/**
+ * virtual-tools.ts
+ * Virtual MCP tool emitter for the Comet Discovery Layer (Spec 042, T011/T022/T034/T035/T045).
+ *
+ * T011: Stub (proved the integration point compiled).
+ * T022: Emit pass-through McpToolDefinition for recommended native entries.
+ * T034: Inject description-template output into the description field.
+ * T035: Append preconditions block to each tool description.
+ * T045: Handle plugin guide + extension dispatch (US3, future).
+ */
+import { CAUTION_MULTI_AGENT_CLAUSE } from "./description-template.js";
+// ── Precondition → human-readable bullet ─────────────────────────────────────
+function preconditionText(p) {
+    switch (p.kind) {
+        case "cdp_session": return p.note;
+        case "profile": return `Requires --profile ${p.value}`;
+        case "task_group": return p.note;
+        case "task_thread": return p.note;
+        case "free": return p.note;
+    }
+}
+function buildPreconditionsBlock(preconditions) {
+    if (preconditions.length === 0)
+        return "";
+    const bullets = preconditions.map((p) => `- ${preconditionText(p)}`).join("\n");
+    return `\n\nPreconditions:\n${bullets}`;
+}
+// ── Description builder ───────────────────────────────────────────────────────
+function buildDescription(entry) {
+    let desc = entry.description;
+    // For CAUTION tools, ensure the canonical multi-agent clause is present.
+    // (It should already be in tool-meta.ts descriptions, but this is a safety net.)
+    if (entry.safety === "CAUTION" && !desc.includes("CAUTION:")) {
+        desc += " " + CAUTION_MULTI_AGENT_CLAUSE;
+    }
+    // T035: append preconditions block
+    desc += buildPreconditionsBlock(entry.preconditions);
+    return desc.slice(0, 1000); // hard cap for MCP clients
+}
+// ── Main emitter ──────────────────────────────────────────────────────────────
+/**
+ * Emit McpToolDefinition objects for every non-humanOnly recommended entry.
+ *
+ * T022: native pass-through — uses the original argsSchema so the tool
+ *   contract is byte-identical to the pre-discovery registration (FR-009).
+ * T045: plugin guide and extension dispatch (not yet implemented).
+ */
+export function emitVirtualTools(entries) {
+    const tools = [];
+    for (const entry of entries) {
+        // Skip human-only entries — they have no agent-reachable entry point
+        if (entry.humanOnly)
+            continue;
+        // Only emit the recommended entry per group (suppressed entries are not tools)
+        if (!entry.recommended)
+            continue;
+        if (entry.invocation.kind === "native") {
+            // T022: pass-through — same name and args schema as the native tool (FR-009)
+            tools.push({
+                name: entry.name,
+                description: buildDescription(entry),
+                inputSchema: entry.argsSchema,
+            });
+        }
+        // TODO T045: "guide" and "cdp"/"filesystem"/"cli" invocation kinds
+    }
+    return tools;
+}
+//# sourceMappingURL=virtual-tools.js.map