saasfunnels 0.2.1 → 0.2.3

package/README.md

@@ -73,6 +73,12 @@ Hosted interactive MCP uses Clerk OAuth at the application `/mcp` URL and does n
 
 The application imports the exact versioned MCP registry through the server-side `saasfunnels/library` export. This keeps hosted Streamable HTTP and local stdio MCP on one package owner; it is not a browser API.
 
+In hosted OAuth, `list_workspaces` discovers accessible workspace names and IDs. Live read, inspect, and plan tools accept an optional `workspace_id`. The hosted application must select the sole accessible workspace automatically, require an explicit ID when several are accessible, recheck authorization for every call, and include the selected workspace name and ID in each live response. The application passes the selection through to its developer API as the `workspace_id` query parameter. Local stdio API-key tools do not expose workspace selection; their key stays pinned to its workspace.
+
+For Funnel discovery, hosted MCP offers `list_funnels` and `get_funnel_state`. `list_funnels` returns at most 50 summaries per page; follow `page.hasMore` with the next `offset` to cover the workspace. The app returns the selected workspace and evaluation time with each read. `get_funnel_state` reports the current lifecycle and publication readiness for one Funnel. These reads do not include Funnel definitions, customer data, or Results. Signals remain supporting evidence and enrollment inputs.
+
+For performance, `get_portfolio_results` and `get_funnel_results` use a 7d, 30d, 90d, or 12m reporting window (30d by default). Portfolio rows are paged at 50 Funnels and cover at most the first 100; check `page.has_more` and `funnels_truncated` before claiming complete coverage. Stage counts and revenue rows retain their distinct attribution, value basis, and currency. `list_opportunities` and `list_leads` return at most 50 records per page with `page.total_count` and `page.has_more`; `get_opportunity` and `get_lead` return one bounded record. Opportunity reads omit private evidence and money; Lead reads omit personal identity and raw responses. These six reads require hosted OAuth, an accessible selected workspace, and the app's `funnels.view` role check.
+
 ## Development
 
 ```bash

package/dist/library.js

@@ -24151,6 +24151,10 @@ var registry2 = Object.freeze({
     "local_mcp",
     "api_key"
   ]),
+  "funnel.workspace.read": capability("funnel.workspace.read", "read", [
+    "in_app",
+    "hosted_mcp"
+  ]),
   "setup.test_event.send": capability("setup.test_event.send", "external_write", [
     "local_cli",
     "local_mcp",
@@ -24260,7 +24264,7 @@ function validateFeatureCatalogManifest(value) {
 
 // src/identity.ts
 var SAASFUNNELS_CLI_NAME = "saasfunnels";
-var SAASFUNNELS_CLI_VERSION = "0.2.1";
+var SAASFUNNELS_CLI_VERSION = "0.2.3";
 var SAASFUNNELS_PRODUCT_NAME = "SaaSFunnels";
 var SAASFUNNELS_DEFAULT_API_BASE_URL = "https://app.saasfunnels.ai";
 var SAASFUNNELS_ENV = Object.freeze({
@@ -24297,10 +24301,19 @@ var saasFunnelsMcpToolCapabilityIds = {
   apply_funnel_entry: "funnel.entry.apply",
   generate_direct_api_handoff: "developer.handoff.generate",
   get_integration_health: "developer.workspace.read",
+  get_funnel_results: "funnel.workspace.read",
+  get_funnel_state: "funnel.workspace.read",
+  get_lead: "funnel.workspace.read",
+  get_opportunity: "funnel.workspace.read",
+  get_portfolio_results: "funnel.workspace.read",
   get_signal_payload_preview: "developer.workspace.read",
   get_workspace_readiness: "developer.workspace.read",
+  list_workspaces: "developer.workspace.read",
   inspect_funnel_entry: "funnel.entry.inspect",
+  list_funnels: "funnel.workspace.read",
+  list_leads: "funnel.workspace.read",
   list_mapping_gaps: "developer.workspace.read",
+  list_opportunities: "funnel.workspace.read",
   list_recent_signals: "developer.workspace.read",
   simulate_account_funnel_fit: "account.funnel_fit.simulate",
   propose_funnel_entry_installation: "funnel.entry.plan",
@@ -24379,6 +24392,42 @@ function stringArg(args, name) {
   const value = args[name];
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
+var uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var resultsWindows = ["7d", "30d", "90d", "12m"];
+var attributionRoles = ["direct", "influenced", "observed"];
+var opportunityStates = ["detected", "open", "eligible", "queued", "presented", "engaged", "action_pending", "converted", "dismissed", "suppressed", "expired", "failed"];
+var leadStates = ["new", "working", "qualified", "converted", "disqualified", "withdrawn", "deleted"];
+function uuidArg(args, name, required2 = false) {
+  const value = args[name];
+  if (value === void 0 && !required2) return void 0;
+  const parsed = stringArg(args, name);
+  if (!parsed || !uuidPattern.test(parsed)) {
+    throw new McpProtocolError(-32602, `${name} must be a UUID.`);
+  }
+  return parsed;
+}
+function integerArg(args, name, fallback, max) {
+  const value = args[name] ?? fallback;
+  if (!Number.isInteger(value) || Number(value) < (name === "limit" ? 1 : 0) || Number(value) > max) {
+    throw new McpProtocolError(-32602, `${name} must be an integer from ${name === "limit" ? 1 : 0} to ${max}.`);
+  }
+  return Number(value);
+}
+function optionalFilterArg(args, name) {
+  if (args[name] === void 0) return void 0;
+  const value = stringArg(args, name);
+  if (!value || value.length > 80) {
+    throw new McpProtocolError(-32602, `${name} must be a non-empty string of at most 80 characters.`);
+  }
+  return value;
+}
+function resultsWindowArg(args) {
+  const value = args.window ?? "30d";
+  if (typeof value !== "string" || !resultsWindows.includes(value)) {
+    throw new McpProtocolError(-32602, "window must be 7d, 30d, 90d, or 12m.");
+  }
+  return value;
+}
 function sourceArg(args) {
   const source = stringArg(args, "source") ?? "direct";
   if (!sourceNames.has(source)) {
@@ -24399,7 +24448,7 @@ function objectArg(args, name) {
 function sanitizeString(value) {
   const withoutSecrets = value.replace(
     tokenPattern,
-    (candidate) => /^[A-Z0-9_]+$/.test(candidate) ? candidate : "[redacted-token]"
+    (candidate) => /^[A-Z0-9_]+$/.test(candidate) || /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(candidate) ? candidate : "[redacted-token]"
   ).replace(emailPattern3, "[redacted-email]");
   try {
     const parsed = new URL(
@@ -24668,6 +24717,33 @@ function emptyLiveInputSchema() {
     type: "object"
   };
 }
+var hostedWorkspaceToolNames = /* @__PURE__ */ new Set([
+  "get_integration_health",
+  "get_funnel_results",
+  "get_funnel_state",
+  "get_lead",
+  "get_opportunity",
+  "get_portfolio_results",
+  "get_workspace_readiness",
+  "list_mapping_gaps",
+  "list_recent_signals",
+  "get_signal_payload_preview",
+  "inspect_funnel_entry",
+  "list_funnels",
+  "list_leads",
+  "list_opportunities",
+  "propose_funnel_entry_installation",
+  "get_account_strategy",
+  "simulate_account_funnel_fit"
+]);
+function developerPathForWorkspace(path, args, options) {
+  if (!options.hostedMode) return path;
+  if ("workspace_id" in args && !stringArg(args, "workspace_id")) {
+    throw new McpProtocolError(-32602, "workspace_id must be a non-empty string.");
+  }
+  const workspaceId = stringArg(args, "workspace_id");
+  return workspaceId ? `${path}${path.includes("?") ? "&" : "?"}workspace_id=${encodeURIComponent(workspaceId)}` : path;
+}
 function saasFunnelsMcpToolDefinitions({
   allowFunnelTests = false,
   allowFunnelWrites = false,
@@ -24859,6 +24935,136 @@ function saasFunnelsMcpToolDefinitions({
     }
   ];
   if (includeHostedAccountTools) {
+    const readAnnotations = {
+      idempotentHint: true,
+      openWorldHint: true,
+      readOnlyHint: true
+    };
+    const windowSchema = { default: "30d", enum: resultsWindows, type: "string" };
+    const uuidSchema = { format: "uuid", type: "string" };
+    tools.push({
+      annotations: readAnnotations,
+      description: "Read bounded portfolio Results for one workspace and reporting window (30d by default). Funnel rows are paged within the first 100; stage counts, acquisition aggregates, and revenue value bases stay distinct. Check page.has_more and funnels_truncated for coverage.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          attribution_role: { enum: attributionRoles, type: "string" },
+          funnel_id: uuidSchema,
+          limit: { type: "integer", minimum: 1, maximum: 50 },
+          objective: { enum: ["convert", "grow", "save"], type: "string" },
+          offset: { type: "integer", minimum: 0, maximum: 100 },
+          window: windowSchema
+        },
+        type: "object"
+      },
+      name: "get_portfolio_results",
+      title: "Get Portfolio Results"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "Read one Funnel's Results for a reporting window, including stage counts, configured acquisition aggregates, maturity, warnings, and separate revenue rows. Bounded arrays carry truncation flags.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: { funnel_id: uuidSchema, window: windowSchema },
+        required: ["funnel_id"],
+        type: "object"
+      },
+      name: "get_funnel_results",
+      title: "Get Funnel Results"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "List up to 50 Opportunities in one workspace, optionally filtered by Funnel or lifecycle state. Returns exact total count and page.has_more; no raw evidence or monetary values.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          funnel_id: uuidSchema,
+          limit: { type: "integer", minimum: 1, maximum: 50 },
+          offset: { type: "integer", minimum: 0, maximum: 25e4 },
+          state: { enum: opportunityStates, type: "string" }
+        },
+        type: "object"
+      },
+      name: "list_opportunities",
+      title: "List Opportunities"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "Read one Opportunity's bounded Funnel, account, lifecycle, delivery, and outcome summary in the selected workspace. No private evidence or monetary values.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: { opportunity_id: uuidSchema },
+        required: ["opportunity_id"],
+        type: "object"
+      },
+      name: "get_opportunity",
+      title: "Get Opportunity"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "List up to 50 generated Leads in one workspace with source Funnel, lifecycle, delivery, and capture counts. Returns exact total count and page.has_more; no personal identity or raw responses.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          funnel_id: uuidSchema,
+          limit: { type: "integer", minimum: 1, maximum: 50 },
+          offset: { type: "integer", minimum: 0, maximum: 25e4 },
+          state: { enum: leadStates, type: "string" }
+        },
+        type: "object"
+      },
+      name: "list_leads",
+      title: "List Leads"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "Read one generated Lead's bounded source, lifecycle, delivery, capture, and verified outcome summary in the selected workspace. No personal identity or raw responses.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: { lead_id: uuidSchema },
+        required: ["lead_id"],
+        type: "object"
+      },
+      name: "get_lead",
+      title: "Get Lead"
+    });
+    tools.push({
+      annotations: {
+        idempotentHint: true,
+        openWorldHint: true,
+        readOnlyHint: true
+      },
+      description: "List one selected workspace's Funnels with lifecycle, draft, and publication state. Results include evaluation time, total count, and pagination; use offset to read more pages. No Funnel definitions or customer data.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          include_archived: { type: "boolean" },
+          limit: { type: "integer", minimum: 1, maximum: 50 },
+          offset: { type: "integer", minimum: 0 }
+        },
+        type: "object"
+      },
+      name: "list_funnels",
+      title: "List Funnels"
+    });
+    tools.push({
+      annotations: {
+        idempotentHint: true,
+        openWorldHint: true,
+        readOnlyHint: true
+      },
+      description: "Read one Funnel's current lifecycle, draft and published revisions, and server-derived publication readiness in the selected workspace. No definitions or private evidence.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          funnel_id: { type: "string", format: "uuid" }
+        },
+        required: ["funnel_id"],
+        type: "object"
+      },
+      name: "get_funnel_state",
+      title: "Get Funnel State"
+    });
     tools.push({
       annotations: {
         idempotentHint: true,
@@ -25030,6 +25236,29 @@ function hostedSaaSFunnelsMcpToolDefinitions() {
       capability2 && agentCapabilityAllowedAtBoundary(capability2.id, "hosted_mcp")
     );
   });
+  for (const tool of tools) {
+    if (!hostedWorkspaceToolNames.has(tool.name)) continue;
+    const properties = tool.inputSchema.properties;
+    properties.workspace_id = {
+      description: "Workspace ID from list_workspaces. Required when your OAuth identity can access multiple workspaces; optional when it can access one. The server verifies access for every call.",
+      type: "string"
+    };
+  }
+  tools.push({
+    annotations: {
+      idempotentHint: true,
+      openWorldHint: true,
+      readOnlyHint: true
+    },
+    description: "List the names and IDs of workspaces accessible to the OAuth user. Use a workspace ID from this list to target live tools when more than one workspace is accessible.",
+    inputSchema: {
+      additionalProperties: false,
+      properties: {},
+      type: "object"
+    },
+    name: "list_workspaces",
+    title: "List Workspaces"
+  });
   assertMcpToolCapabilityContract(tools, "hosted_mcp");
   return tools;
 }
@@ -25055,7 +25284,7 @@ async function developerGet(path, args, options) {
     });
   }
   const response = await (options.fetch ?? fetch)(
-    `${apiBaseUrl(options, args)}${path}`,
+    `${apiBaseUrl(options, args)}${developerPathForWorkspace(path, args, options)}`,
     {
       headers: {
         authorization
@@ -25091,7 +25320,7 @@ async function developerPost(path, args, body, options, requiredScope) {
     });
   }
   const response = await (options.fetch ?? fetch)(
-    `${apiBaseUrl(options, args)}${path}`,
+    `${apiBaseUrl(options, args)}${developerPathForWorkspace(path, args, options)}`,
     {
       body: JSON.stringify(body),
       headers: {
@@ -25161,11 +25390,17 @@ async function sendTestEvent(args, options) {
 }
 async function callSaaSFunnelsMcpTool(name, args, options = {}) {
   try {
-    if ((name === "get_account_strategy" || name === "simulate_account_funnel_fit") && !options.hostedMode) {
+    if (!options.hostedMode && "workspace_id" in args && hostedWorkspaceToolNames.has(name)) {
+      throw new McpProtocolError(
+        -32602,
+        "workspace_id is available only with hosted OAuth; an API key is pinned to its workspace."
+      );
+    }
+    if ((name === "get_account_strategy" || name === "get_funnel_results" || name === "get_funnel_state" || name === "get_lead" || name === "get_opportunity" || name === "get_portfolio_results" || name === "list_funnels" || name === "list_leads" || name === "list_opportunities" || name === "simulate_account_funnel_fit" || name === "list_workspaces") && !options.hostedMode) {
       throw new McpToolExecutionError(
-        "This account tool requires hosted OAuth.",
+        "This tool requires hosted OAuth.",
         {
-          error: "This account tool requires hosted OAuth.",
+          error: "This tool requires hosted OAuth.",
           ok: false,
           required_boundary: "hosted_mcp"
         }
@@ -25208,6 +25443,106 @@ async function callSaaSFunnelsMcpTool(name, args, options = {}) {
           options
         )
       );
+    if (name === "list_workspaces")
+      return structuredToolResult(
+        await developerGet("/api/developer-tools/workspaces", {}, options)
+      );
+    if (name === "list_funnels") {
+      const limit = args.limit ?? 25;
+      const offset = args.offset ?? 0;
+      if (!Number.isInteger(limit) || Number(limit) < 1 || Number(limit) > 50 || !Number.isInteger(offset) || Number(offset) < 0 || Number(offset) > 25e4 || args.include_archived !== void 0 && typeof args.include_archived !== "boolean") {
+        throw new McpProtocolError(
+          -32602,
+          "limit must be 1\u201350, offset must be 0\u2013250000, and include_archived must be boolean."
+        );
+      }
+      const query = new URLSearchParams({
+        include_archived: String(args.include_archived === true),
+        limit: String(limit),
+        offset: String(offset)
+      });
+      return structuredToolResult(
+        await developerGet(`/api/developer-tools/funnels?${query}`, args, options)
+      );
+    }
+    if (name === "get_funnel_state") {
+      const funnelId = uuidArg(args, "funnel_id", true);
+      return structuredToolResult(
+        await developerGet(
+          `/api/developer-tools/funnels/${encodeURIComponent(funnelId)}`,
+          args,
+          options
+        )
+      );
+    }
+    if (name === "get_portfolio_results") {
+      const query = new URLSearchParams({
+        window: resultsWindowArg(args),
+        limit: String(integerArg(args, "limit", 50, 50)),
+        offset: String(integerArg(args, "offset", 0, 100))
+      });
+      const funnelId = uuidArg(args, "funnel_id");
+      if (funnelId) query.set("funnel_id", funnelId);
+      const objective = optionalFilterArg(args, "objective");
+      if (objective) {
+        if (!["convert", "grow", "save"].includes(objective)) {
+          throw new McpProtocolError(-32602, "objective must be convert, grow, or save.");
+        }
+        query.set("objective", objective);
+      }
+      const attributionRole = optionalFilterArg(args, "attribution_role");
+      if (attributionRole) {
+        if (!attributionRoles.includes(attributionRole)) {
+          throw new McpProtocolError(-32602, "attribution_role must be direct, influenced, or observed.");
+        }
+        query.set("attribution_role", attributionRole);
+      }
+      return structuredToolResult(
+        await developerGet(`/api/developer-tools/results?${query}`, args, options)
+      );
+    }
+    if (name === "get_funnel_results") {
+      const funnelId = uuidArg(args, "funnel_id", true);
+      const query = new URLSearchParams({ window: resultsWindowArg(args) });
+      return structuredToolResult(
+        await developerGet(
+          `/api/developer-tools/funnels/${encodeURIComponent(funnelId)}/results?${query}`,
+          args,
+          options
+        )
+      );
+    }
+    if (name === "list_opportunities" || name === "list_leads") {
+      const query = new URLSearchParams({
+        limit: String(integerArg(args, "limit", 25, 50)),
+        offset: String(integerArg(args, "offset", 0, 25e4))
+      });
+      const funnelId = uuidArg(args, "funnel_id");
+      if (funnelId) query.set("funnel_id", funnelId);
+      const state = optionalFilterArg(args, "state");
+      if (state) {
+        const allowed = name === "list_leads" ? leadStates : opportunityStates;
+        if (!allowed.includes(state)) {
+          throw new McpProtocolError(-32602, `state is not a supported ${name === "list_leads" ? "Lead" : "Opportunity"} state.`);
+        }
+        query.set("state", state);
+      }
+      const resource = name === "list_leads" ? "leads" : "opportunities";
+      return structuredToolResult(
+        await developerGet(`/api/developer-tools/${resource}?${query}`, args, options)
+      );
+    }
+    if (name === "get_opportunity" || name === "get_lead") {
+      const resource = name === "get_lead" ? "leads" : "opportunities";
+      const id = uuidArg(args, name === "get_lead" ? "lead_id" : "opportunity_id", true);
+      return structuredToolResult(
+        await developerGet(
+          `/api/developer-tools/${resource}/${encodeURIComponent(id)}`,
+          args,
+          options
+        )
+      );
+    }
     if (name === "get_workspace_readiness")
       return structuredToolResult(
         await developerGet(

package/dist/saasfunnels.js

@@ -24802,7 +24802,7 @@ Applied reviewed edits. Change record: ${result3.changeRecordPath}` : result3.id
 
 // src/identity.ts
 var SAASFUNNELS_CLI_NAME = "saasfunnels";
-var SAASFUNNELS_CLI_VERSION = "0.2.1";
+var SAASFUNNELS_CLI_VERSION = "0.2.3";
 var SAASFUNNELS_PRODUCT_NAME = "SaaSFunnels";
 var SAASFUNNELS_DEFAULT_API_BASE_URL = "https://app.saasfunnels.ai";
 var SAASFUNNELS_ENV = Object.freeze({
@@ -25342,6 +25342,10 @@ var registry2 = Object.freeze({
     "local_mcp",
     "api_key"
   ]),
+  "funnel.workspace.read": capability("funnel.workspace.read", "read", [
+    "in_app",
+    "hosted_mcp"
+  ]),
   "setup.test_event.send": capability("setup.test_event.send", "external_write", [
     "local_cli",
     "local_mcp",
@@ -25380,10 +25384,19 @@ var saasFunnelsMcpToolCapabilityIds = {
   apply_funnel_entry: "funnel.entry.apply",
   generate_direct_api_handoff: "developer.handoff.generate",
   get_integration_health: "developer.workspace.read",
+  get_funnel_results: "funnel.workspace.read",
+  get_funnel_state: "funnel.workspace.read",
+  get_lead: "funnel.workspace.read",
+  get_opportunity: "funnel.workspace.read",
+  get_portfolio_results: "funnel.workspace.read",
   get_signal_payload_preview: "developer.workspace.read",
   get_workspace_readiness: "developer.workspace.read",
+  list_workspaces: "developer.workspace.read",
   inspect_funnel_entry: "funnel.entry.inspect",
+  list_funnels: "funnel.workspace.read",
+  list_leads: "funnel.workspace.read",
   list_mapping_gaps: "developer.workspace.read",
+  list_opportunities: "funnel.workspace.read",
   list_recent_signals: "developer.workspace.read",
   simulate_account_funnel_fit: "account.funnel_fit.simulate",
   propose_funnel_entry_installation: "funnel.entry.plan",
@@ -25462,6 +25475,42 @@ function stringArg(args, name) {
   const value = args[name];
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
+var uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var resultsWindows = ["7d", "30d", "90d", "12m"];
+var attributionRoles = ["direct", "influenced", "observed"];
+var opportunityStates = ["detected", "open", "eligible", "queued", "presented", "engaged", "action_pending", "converted", "dismissed", "suppressed", "expired", "failed"];
+var leadStates = ["new", "working", "qualified", "converted", "disqualified", "withdrawn", "deleted"];
+function uuidArg(args, name, required2 = false) {
+  const value = args[name];
+  if (value === void 0 && !required2) return void 0;
+  const parsed = stringArg(args, name);
+  if (!parsed || !uuidPattern.test(parsed)) {
+    throw new McpProtocolError(-32602, `${name} must be a UUID.`);
+  }
+  return parsed;
+}
+function integerArg(args, name, fallback, max) {
+  const value = args[name] ?? fallback;
+  if (!Number.isInteger(value) || Number(value) < (name === "limit" ? 1 : 0) || Number(value) > max) {
+    throw new McpProtocolError(-32602, `${name} must be an integer from ${name === "limit" ? 1 : 0} to ${max}.`);
+  }
+  return Number(value);
+}
+function optionalFilterArg(args, name) {
+  if (args[name] === void 0) return void 0;
+  const value = stringArg(args, name);
+  if (!value || value.length > 80) {
+    throw new McpProtocolError(-32602, `${name} must be a non-empty string of at most 80 characters.`);
+  }
+  return value;
+}
+function resultsWindowArg(args) {
+  const value = args.window ?? "30d";
+  if (typeof value !== "string" || !resultsWindows.includes(value)) {
+    throw new McpProtocolError(-32602, "window must be 7d, 30d, 90d, or 12m.");
+  }
+  return value;
+}
 function sourceArg(args) {
   const source = stringArg(args, "source") ?? "direct";
   if (!sourceNames.has(source)) {
@@ -25482,7 +25531,7 @@ function objectArg(args, name) {
 function sanitizeString(value) {
   const withoutSecrets = value.replace(
     tokenPattern,
-    (candidate) => /^[A-Z0-9_]+$/.test(candidate) ? candidate : "[redacted-token]"
+    (candidate) => /^[A-Z0-9_]+$/.test(candidate) || /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(candidate) ? candidate : "[redacted-token]"
   ).replace(emailPattern3, "[redacted-email]");
   try {
     const parsed = new URL(
@@ -25751,6 +25800,33 @@ function emptyLiveInputSchema() {
     type: "object"
   };
 }
+var hostedWorkspaceToolNames = /* @__PURE__ */ new Set([
+  "get_integration_health",
+  "get_funnel_results",
+  "get_funnel_state",
+  "get_lead",
+  "get_opportunity",
+  "get_portfolio_results",
+  "get_workspace_readiness",
+  "list_mapping_gaps",
+  "list_recent_signals",
+  "get_signal_payload_preview",
+  "inspect_funnel_entry",
+  "list_funnels",
+  "list_leads",
+  "list_opportunities",
+  "propose_funnel_entry_installation",
+  "get_account_strategy",
+  "simulate_account_funnel_fit"
+]);
+function developerPathForWorkspace(path, args, options) {
+  if (!options.hostedMode) return path;
+  if ("workspace_id" in args && !stringArg(args, "workspace_id")) {
+    throw new McpProtocolError(-32602, "workspace_id must be a non-empty string.");
+  }
+  const workspaceId = stringArg(args, "workspace_id");
+  return workspaceId ? `${path}${path.includes("?") ? "&" : "?"}workspace_id=${encodeURIComponent(workspaceId)}` : path;
+}
 function saasFunnelsMcpToolDefinitions({
   allowFunnelTests = false,
   allowFunnelWrites = false,
@@ -25942,6 +26018,136 @@ function saasFunnelsMcpToolDefinitions({
     }
   ];
   if (includeHostedAccountTools) {
+    const readAnnotations = {
+      idempotentHint: true,
+      openWorldHint: true,
+      readOnlyHint: true
+    };
+    const windowSchema = { default: "30d", enum: resultsWindows, type: "string" };
+    const uuidSchema = { format: "uuid", type: "string" };
+    tools.push({
+      annotations: readAnnotations,
+      description: "Read bounded portfolio Results for one workspace and reporting window (30d by default). Funnel rows are paged within the first 100; stage counts, acquisition aggregates, and revenue value bases stay distinct. Check page.has_more and funnels_truncated for coverage.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          attribution_role: { enum: attributionRoles, type: "string" },
+          funnel_id: uuidSchema,
+          limit: { type: "integer", minimum: 1, maximum: 50 },
+          objective: { enum: ["convert", "grow", "save"], type: "string" },
+          offset: { type: "integer", minimum: 0, maximum: 100 },
+          window: windowSchema
+        },
+        type: "object"
+      },
+      name: "get_portfolio_results",
+      title: "Get Portfolio Results"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "Read one Funnel's Results for a reporting window, including stage counts, configured acquisition aggregates, maturity, warnings, and separate revenue rows. Bounded arrays carry truncation flags.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: { funnel_id: uuidSchema, window: windowSchema },
+        required: ["funnel_id"],
+        type: "object"
+      },
+      name: "get_funnel_results",
+      title: "Get Funnel Results"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "List up to 50 Opportunities in one workspace, optionally filtered by Funnel or lifecycle state. Returns exact total count and page.has_more; no raw evidence or monetary values.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          funnel_id: uuidSchema,
+          limit: { type: "integer", minimum: 1, maximum: 50 },
+          offset: { type: "integer", minimum: 0, maximum: 25e4 },
+          state: { enum: opportunityStates, type: "string" }
+        },
+        type: "object"
+      },
+      name: "list_opportunities",
+      title: "List Opportunities"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "Read one Opportunity's bounded Funnel, account, lifecycle, delivery, and outcome summary in the selected workspace. No private evidence or monetary values.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: { opportunity_id: uuidSchema },
+        required: ["opportunity_id"],
+        type: "object"
+      },
+      name: "get_opportunity",
+      title: "Get Opportunity"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "List up to 50 generated Leads in one workspace with source Funnel, lifecycle, delivery, and capture counts. Returns exact total count and page.has_more; no personal identity or raw responses.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          funnel_id: uuidSchema,
+          limit: { type: "integer", minimum: 1, maximum: 50 },
+          offset: { type: "integer", minimum: 0, maximum: 25e4 },
+          state: { enum: leadStates, type: "string" }
+        },
+        type: "object"
+      },
+      name: "list_leads",
+      title: "List Leads"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "Read one generated Lead's bounded source, lifecycle, delivery, capture, and verified outcome summary in the selected workspace. No personal identity or raw responses.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: { lead_id: uuidSchema },
+        required: ["lead_id"],
+        type: "object"
+      },
+      name: "get_lead",
+      title: "Get Lead"
+    });
+    tools.push({
+      annotations: {
+        idempotentHint: true,
+        openWorldHint: true,
+        readOnlyHint: true
+      },
+      description: "List one selected workspace's Funnels with lifecycle, draft, and publication state. Results include evaluation time, total count, and pagination; use offset to read more pages. No Funnel definitions or customer data.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          include_archived: { type: "boolean" },
+          limit: { type: "integer", minimum: 1, maximum: 50 },
+          offset: { type: "integer", minimum: 0 }
+        },
+        type: "object"
+      },
+      name: "list_funnels",
+      title: "List Funnels"
+    });
+    tools.push({
+      annotations: {
+        idempotentHint: true,
+        openWorldHint: true,
+        readOnlyHint: true
+      },
+      description: "Read one Funnel's current lifecycle, draft and published revisions, and server-derived publication readiness in the selected workspace. No definitions or private evidence.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          funnel_id: { type: "string", format: "uuid" }
+        },
+        required: ["funnel_id"],
+        type: "object"
+      },
+      name: "get_funnel_state",
+      title: "Get Funnel State"
+    });
     tools.push({
       annotations: {
         idempotentHint: true,
@@ -26128,7 +26334,7 @@ async function developerGet(path, args, options) {
     });
   }
   const response = await (options.fetch ?? fetch)(
-    `${apiBaseUrl(options, args)}${path}`,
+    `${apiBaseUrl(options, args)}${developerPathForWorkspace(path, args, options)}`,
     {
       headers: {
         authorization
@@ -26164,7 +26370,7 @@ async function developerPost(path, args, body, options, requiredScope) {
     });
   }
   const response = await (options.fetch ?? fetch)(
-    `${apiBaseUrl(options, args)}${path}`,
+    `${apiBaseUrl(options, args)}${developerPathForWorkspace(path, args, options)}`,
     {
       body: JSON.stringify(body),
       headers: {
@@ -26234,11 +26440,17 @@ async function sendTestEvent(args, options) {
 }
 async function callSaaSFunnelsMcpTool(name, args, options = {}) {
   try {
-    if ((name === "get_account_strategy" || name === "simulate_account_funnel_fit") && !options.hostedMode) {
+    if (!options.hostedMode && "workspace_id" in args && hostedWorkspaceToolNames.has(name)) {
+      throw new McpProtocolError(
+        -32602,
+        "workspace_id is available only with hosted OAuth; an API key is pinned to its workspace."
+      );
+    }
+    if ((name === "get_account_strategy" || name === "get_funnel_results" || name === "get_funnel_state" || name === "get_lead" || name === "get_opportunity" || name === "get_portfolio_results" || name === "list_funnels" || name === "list_leads" || name === "list_opportunities" || name === "simulate_account_funnel_fit" || name === "list_workspaces") && !options.hostedMode) {
       throw new McpToolExecutionError(
-        "This account tool requires hosted OAuth.",
+        "This tool requires hosted OAuth.",
         {
-          error: "This account tool requires hosted OAuth.",
+          error: "This tool requires hosted OAuth.",
           ok: false,
           required_boundary: "hosted_mcp"
         }
@@ -26281,6 +26493,106 @@ async function callSaaSFunnelsMcpTool(name, args, options = {}) {
           options
         )
       );
+    if (name === "list_workspaces")
+      return structuredToolResult(
+        await developerGet("/api/developer-tools/workspaces", {}, options)
+      );
+    if (name === "list_funnels") {
+      const limit = args.limit ?? 25;
+      const offset = args.offset ?? 0;
+      if (!Number.isInteger(limit) || Number(limit) < 1 || Number(limit) > 50 || !Number.isInteger(offset) || Number(offset) < 0 || Number(offset) > 25e4 || args.include_archived !== void 0 && typeof args.include_archived !== "boolean") {
+        throw new McpProtocolError(
+          -32602,
+          "limit must be 1\u201350, offset must be 0\u2013250000, and include_archived must be boolean."
+        );
+      }
+      const query = new URLSearchParams({
+        include_archived: String(args.include_archived === true),
+        limit: String(limit),
+        offset: String(offset)
+      });
+      return structuredToolResult(
+        await developerGet(`/api/developer-tools/funnels?${query}`, args, options)
+      );
+    }
+    if (name === "get_funnel_state") {
+      const funnelId = uuidArg(args, "funnel_id", true);
+      return structuredToolResult(
+        await developerGet(
+          `/api/developer-tools/funnels/${encodeURIComponent(funnelId)}`,
+          args,
+          options
+        )
+      );
+    }
+    if (name === "get_portfolio_results") {
+      const query = new URLSearchParams({
+        window: resultsWindowArg(args),
+        limit: String(integerArg(args, "limit", 50, 50)),
+        offset: String(integerArg(args, "offset", 0, 100))
+      });
+      const funnelId = uuidArg(args, "funnel_id");
+      if (funnelId) query.set("funnel_id", funnelId);
+      const objective = optionalFilterArg(args, "objective");
+      if (objective) {
+        if (!["convert", "grow", "save"].includes(objective)) {
+          throw new McpProtocolError(-32602, "objective must be convert, grow, or save.");
+        }
+        query.set("objective", objective);
+      }
+      const attributionRole = optionalFilterArg(args, "attribution_role");
+      if (attributionRole) {
+        if (!attributionRoles.includes(attributionRole)) {
+          throw new McpProtocolError(-32602, "attribution_role must be direct, influenced, or observed.");
+        }
+        query.set("attribution_role", attributionRole);
+      }
+      return structuredToolResult(
+        await developerGet(`/api/developer-tools/results?${query}`, args, options)
+      );
+    }
+    if (name === "get_funnel_results") {
+      const funnelId = uuidArg(args, "funnel_id", true);
+      const query = new URLSearchParams({ window: resultsWindowArg(args) });
+      return structuredToolResult(
+        await developerGet(
+          `/api/developer-tools/funnels/${encodeURIComponent(funnelId)}/results?${query}`,
+          args,
+          options
+        )
+      );
+    }
+    if (name === "list_opportunities" || name === "list_leads") {
+      const query = new URLSearchParams({
+        limit: String(integerArg(args, "limit", 25, 50)),
+        offset: String(integerArg(args, "offset", 0, 25e4))
+      });
+      const funnelId = uuidArg(args, "funnel_id");
+      if (funnelId) query.set("funnel_id", funnelId);
+      const state = optionalFilterArg(args, "state");
+      if (state) {
+        const allowed3 = name === "list_leads" ? leadStates : opportunityStates;
+        if (!allowed3.includes(state)) {
+          throw new McpProtocolError(-32602, `state is not a supported ${name === "list_leads" ? "Lead" : "Opportunity"} state.`);
+        }
+        query.set("state", state);
+      }
+      const resource = name === "list_leads" ? "leads" : "opportunities";
+      return structuredToolResult(
+        await developerGet(`/api/developer-tools/${resource}?${query}`, args, options)
+      );
+    }
+    if (name === "get_opportunity" || name === "get_lead") {
+      const resource = name === "get_lead" ? "leads" : "opportunities";
+      const id = uuidArg(args, name === "get_lead" ? "lead_id" : "opportunity_id", true);
+      return structuredToolResult(
+        await developerGet(
+          `/api/developer-tools/${resource}/${encodeURIComponent(id)}`,
+          args,
+          options
+        )
+      );
+    }
     if (name === "get_workspace_readiness")
       return structuredToolResult(
         await developerGet(

package/dist/types/capabilities.d.ts

@@ -1,4 +1,4 @@
-export type AgentCapabilityId = "account.funnel_fit.simulate" | "account.strategy.read" | "developer.event.validate" | "developer.feature_manifest.validate" | "developer.handoff.generate" | "developer.workspace.read" | "funnel.entry.apply" | "funnel.entry.evidence.submit" | "funnel.entry.inspect" | "funnel.entry.plan" | "funnel.entry.test" | "setup.test_event.send";
+export type AgentCapabilityId = "account.funnel_fit.simulate" | "account.strategy.read" | "developer.event.validate" | "developer.feature_manifest.validate" | "developer.handoff.generate" | "developer.workspace.read" | "funnel.entry.apply" | "funnel.entry.evidence.submit" | "funnel.entry.inspect" | "funnel.entry.plan" | "funnel.entry.test" | "funnel.workspace.read" | "setup.test_event.send";
 type AgentExecutionBoundary = "api_key" | "hosted_mcp" | "in_app" | "local_cli" | "local_mcp" | "scheduled_agent";
 type AgentOperationClass = "external_write" | "plan" | "prepare" | "read" | "reversible_write" | "simulate" | "validate";
 type Capability = {

package/dist/types/identity.d.ts

@@ -1,5 +1,5 @@
 export declare const SAASFUNNELS_CLI_NAME = "saasfunnels";
-export declare const SAASFUNNELS_CLI_VERSION = "0.2.1";
+export declare const SAASFUNNELS_CLI_VERSION = "0.2.3";
 export declare const SAASFUNNELS_PRODUCT_NAME = "SaaSFunnels";
 export declare const SAASFUNNELS_DEFAULT_API_BASE_URL = "https://app.saasfunnels.ai";
 export declare const SAASFUNNELS_ENV: Readonly<{

package/dist/types/mcp.d.ts

@@ -35,10 +35,19 @@ export declare const saasFunnelsMcpToolCapabilityIds: {
     readonly apply_funnel_entry: "funnel.entry.apply";
     readonly generate_direct_api_handoff: "developer.handoff.generate";
     readonly get_integration_health: "developer.workspace.read";
+    readonly get_funnel_results: "funnel.workspace.read";
+    readonly get_funnel_state: "funnel.workspace.read";
+    readonly get_lead: "funnel.workspace.read";
+    readonly get_opportunity: "funnel.workspace.read";
+    readonly get_portfolio_results: "funnel.workspace.read";
     readonly get_signal_payload_preview: "developer.workspace.read";
     readonly get_workspace_readiness: "developer.workspace.read";
+    readonly list_workspaces: "developer.workspace.read";
     readonly inspect_funnel_entry: "funnel.entry.inspect";
+    readonly list_funnels: "funnel.workspace.read";
+    readonly list_leads: "funnel.workspace.read";
     readonly list_mapping_gaps: "developer.workspace.read";
+    readonly list_opportunities: "funnel.workspace.read";
     readonly list_recent_signals: "developer.workspace.read";
     readonly simulate_account_funnel_fit: "account.funnel_fit.simulate";
     readonly propose_funnel_entry_installation: "funnel.entry.plan";
@@ -68,7 +77,7 @@ export type SaaSFunnelsMcpOptions = {
     output?: Pick<NodeJS.WritableStream, "write">;
 };
 declare const mcpProtocolVersion = "2025-06-18";
-declare const mcpServerVersion = "0.2.1";
+declare const mcpServerVersion = "0.2.3";
 export declare function saasFunnelsMcpResources(): McpResourceDefinition[];
 export declare function readSaaSFunnelsMcpResource(uri: string, options?: SaaSFunnelsMcpOptions): string;
 export declare function saasFunnelsMcpToolDefinitions({ allowFunnelTests, allowFunnelWrites, allowTestWrites, includeHostedAccountTools, }?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saasfunnels",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "private": false,
   "description": "SaaSFunnels CLI and local stdio MCP server",
   "author": "SaaSFunnels",