@myna-sh/mcp 0.16.1 → 0.17.0

package/README.md

@@ -1,6 +1,6 @@
 # @myna-sh/mcp
 
-Model Context Protocol server for operating [Myna](https://myna.sh) content and feedback from coding agents and MCP clients.
+Model Context Protocol server for operating [Myna](https://myna.sh) content, analytics, and feedback from coding agents and MCP clients.
 
 > **Connecting Claude, ChatGPT, or another remote agent?** You do not need this package. Myna hosts the same server at `https://api.myna.sh/mcp` — add it as a custom connector and authorize it with OAuth. See [connecting a remote agent](https://docs.myna.sh/mcp/hosted). This package is for local coding agents that run the server over stdio.
 

package/dist/main.d.ts

@@ -97,8 +97,8 @@ interface ToolOptions {
      * conservative default, and the one that matters: a customer's saved agent
      * configuration must not change shape because Myna shipped a second product.
      * There are already 45+ tools on this server, and every one added degrades
-     * selection for all of them, so a project that does not run Feedback should
-     * never be shown Feedback's.
+     * selection for all of them, so a project that does not run a product should
+     * never be shown that product's tools.
      */
     products?: readonly string[];
 }

package/dist/main.js

@@ -771,6 +771,110 @@ var ManagementClient = class {
     revokeForProject: (project, key) => this.mutate("DELETE", `/projects/${enc(project)}/api-keys/${enc(key)}`)
   };
   // --- Webhooks -------------------------------------------------------------
+  /**
+   * Myna Analytics.
+   *
+   * Shaped for a caller that has to *reason* about the numbers rather than draw
+   * them. Every read echoes the window it resolved, `overview` carries the
+   * previous period and the movement, and `releaseImpact` answers "what
+   * happened after we shipped this" in one call instead of six — which for an
+   * agent is one turn instead of six.
+   */
+  analytics = {
+    /**
+     * Headline numbers and how they moved.
+     *
+     * `period` is `24h`, `7d`, `30d`, `12w`; `from`/`to` is the exact form.
+     * Naming both is an error rather than a precedence rule, because a silent
+     * guess about which window produced a number is indistinguishable from a
+     * correct answer.
+     */
+    overview: (project, query = {}, signal) => this.get(`/projects/${enc(project)}/analytics/overview`, query, signal),
+    /** All four metrics over time, bucketed by hour, day, or week. */
+    series: (project, query = {}, signal) => this.get(`/projects/${enc(project)}/analytics/series`, query, signal),
+    /**
+     * Group by a dimension, or by a custom property as `property:<key>`.
+     *
+     * `entry`, `collection`, and `release` are the dimensions no general
+     * analytics product has, because they name things in the CMS on the other
+     * side of the same project.
+     */
+    breakdown: (project, query, signal) => this.get(`/projects/${enc(project)}/analytics/breakdown`, query, signal),
+    /**
+     * Conversion through ordered steps.
+     *
+     * A POST because a funnel definition does not fit in a query string, not
+     * because it writes anything. Order is enforced and `withinHours` is
+     * measured from the visitor's first step.
+     */
+    funnel: (project, body, signal) => this.http.request("POST", `/projects/${enc(project)}/analytics/funnel`, {
+      body,
+      signal
+    }),
+    /** Where people stop: exits, bounces, and pages that generate complaints. */
+    friction: (project, query = {}, signal) => this.get(`/projects/${enc(project)}/analytics/friction`, query, signal),
+    /**
+     * Every event name this project has recorded, and what each one means.
+     *
+     * Read this before writing a funnel: `description` is where somebody wrote
+     * down whether `checkout_started` fires on the click or on the page, which
+     * nothing in the data itself says.
+     */
+    events: (project, query = {}, signal) => this.get(`/projects/${enc(project)}/analytics/events`, query, signal),
+    event: (project, event, query = {}, signal) => this.get(
+      `/projects/${enc(project)}/analytics/events/${enc(event)}`,
+      query,
+      signal
+    ),
+    /** Write down what an event means. `null` clears it. */
+    describeEvent: (project, event, body) => this.mutate(
+      "PATCH",
+      `/projects/${enc(project)}/analytics/events/${enc(event)}`,
+      body
+    ),
+    /** Traffic and complaints per content entry. */
+    content: (project, query = {}, signal) => this.get(`/projects/${enc(project)}/analytics/content`, query, signal),
+    /** One entry: its numbers, every publication in the window, and their effect. */
+    entry: (project, entry, query = {}, signal) => this.get(
+      `/projects/${enc(project)}/analytics/content/${enc(entry)}`,
+      query,
+      signal
+    ),
+    /**
+     * What measurably happened after a release.
+     *
+     * Correlation, and it says so: a release is not the only thing that
+     * happened that day. What it removes is every reason not to look.
+     */
+    releaseImpact: (project, release, opts = {}, signal) => this.get(
+      `/projects/${enc(project)}/analytics/releases/${release}/impact`,
+      opts,
+      signal
+    ),
+    /** People the customer's own backend vouched for. Anonymous visitors are not here. */
+    profiles: (project, opts = {}) => {
+      const { q, ...rest } = opts;
+      return this.page(`/projects/${enc(project)}/analytics/profiles`, rest, { q });
+    },
+    /** By Myna id (`apr_…`) or by the customer's own user id. */
+    profile: (project, profile, signal) => this.get(
+      `/projects/${enc(project)}/analytics/profiles/${enc(profile)}`,
+      void 0,
+      signal
+    ),
+    sessions: (project, opts = {}) => {
+      const { profile, ...rest } = opts;
+      return this.page(`/projects/${enc(project)}/analytics/sessions`, rest, { profile });
+    },
+    session: (project, session, signal) => this.get(
+      `/projects/${enc(project)}/analytics/sessions/${enc(session)}`,
+      void 0,
+      signal
+    ),
+    settings: (project, signal) => this.get(`/projects/${enc(project)}/analytics/settings`, void 0, signal),
+    /** Retention and path exclusions. Shortening retention deletes data. */
+    updateSettings: (project, body) => this.mutate("PUT", `/projects/${enc(project)}/analytics/settings`, body)
+  };
   webhooks = {
     list: (project, signal) => this.get(`/projects/${enc(project)}/webhooks`, void 0, signal),
     create: (project, body) => this.mutate("POST", `/projects/${enc(project)}/webhooks`, body),
@@ -1087,7 +1191,17 @@ var TOOL_CAPABILITY = {
   myna_request_retest: "feedback:write",
   myna_merge_report: "feedback:write",
   myna_move_report: "feedback:write",
-  myna_block_reporter: "feedback:manage"
+  myna_block_reporter: "feedback:manage",
+  myna_analytics_overview: "analytics:read",
+  myna_analytics_breakdown: "analytics:read",
+  myna_analytics_events: "analytics:read",
+  myna_analytics_funnel: "analytics:read",
+  myna_analytics_friction: "analytics:read",
+  myna_analytics_content: "analytics:read",
+  myna_analytics_entry: "analytics:read",
+  myna_analytics_release_impact: "analytics:read",
+  myna_analytics_person: "analytics:read",
+  myna_describe_analytics_event: "analytics:write"
 };
 function registerTools(server, registry, options = { allowPathUploads: true }) {
   server.registerTool(
@@ -2160,6 +2274,7 @@ function registerTools(server, registry, options = { allowPathUploads: true }) {
     }
   );
   if (options.products?.includes("feedback")) registerFeedbackTools(server, registry);
+  if (options.products?.includes("analytics")) registerAnalyticsTools(server, registry);
 }
 var reportArg = {
   ...projectArg,
@@ -2545,6 +2660,290 @@ function registerFeedbackTools(server, registry) {
     }
   );
 }
+var analyticsFilterArgs = {
+  ...projectArg,
+  period: z.string().optional().describe("Window: 24h, 7d, 30d, 12w. Defaults to 7d. Do not combine with from/to."),
+  from: z.string().optional().describe("ISO start of an explicit window."),
+  to: z.string().optional().describe("ISO end of an explicit window."),
+  event: z.string().optional().describe("Only this event name."),
+  path: z.string().optional().describe("Only this page path."),
+  referrerDomain: z.string().optional().describe("Only traffic from this referrer host."),
+  utmSource: z.string().optional(),
+  utmMedium: z.string().optional(),
+  utmCampaign: z.string().optional(),
+  browser: z.string().optional(),
+  os: z.string().optional(),
+  deviceType: z.string().optional().describe("desktop, mobile, or tablet."),
+  locale: z.string().optional(),
+  environment: z.string().optional().describe("The application's own environment name."),
+  appVersion: z.string().optional().describe("The application's own build."),
+  entry: z.string().optional().describe("Only events on this content entry (ent_...)."),
+  collection: z.string().optional().describe("Only events on entries in this collection."),
+  release: z.number().optional().describe("Only events on this Myna release."),
+  property: z.string().optional().describe("`key:value` against an event's custom properties."),
+  identified: z.enum(["true", "false"]).optional().describe("true for people the customer's backend vouched for, false for everyone else.")
+};
+function analyticsQueryOf(args) {
+  const { project: _project, ...rest } = args;
+  return rest;
+}
+function registerAnalyticsTools(server, registry) {
+  server.registerTool(
+    "myna_analytics_overview",
+    {
+      title: "Analytics overview",
+      description: "Headline product usage for a window, with the previous period beside it and the percentage change: visitors, sessions, page views, events, bounce rate, session length, top pages, top events, top referrers, and what share of visitors are identified. Start here \u2014 it answers 'is anything different' in one call. Every filter narrows every number.",
+      inputSchema: { ...analyticsFilterArgs },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const result = await client.analytics.overview(project, analyticsQueryOf(args));
+        const summary = [
+          `${result.totals.visitors} visitors (${result.change.visitors ?? "\u2014"}%)`,
+          `${result.totals.sessions} sessions`,
+          `${result.totals.pageviews} page views (${result.change.pageviews ?? "\u2014"}%)`,
+          `bounce ${result.averages.bounceRate}%`
+        ].join(", ");
+        return ok(summary, result);
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_analytics_breakdown",
+    {
+      title: "Break analytics down by a dimension",
+      description: "Group events by a dimension and get visitors, sessions, page views, and events for each. Built-in dimensions: event, path, referrerDomain, utmSource, utmMedium, utmCampaign, browser, os, deviceType, locale, environment, appVersion, entry, collection, release. A custom event property is `property:<key>` \u2014 call myna_analytics_events first to see which keys exist. `entry`, `collection`, and `release` name Myna content, which is what makes 'which pages did this release change, and did their traffic move' answerable at all.",
+      inputSchema: {
+        ...analyticsFilterArgs,
+        dimension: z.string().describe("What to group by. See the description."),
+        metric: z.enum(["visitors", "sessions", "pageviews", "events"]).optional().describe("What to sort and compute shares by. Defaults to visitors."),
+        limit: z.number().optional().describe("Rows to return, up to 100. Defaults to 25.")
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const result = await client.analytics.breakdown(project, {
+          ...analyticsQueryOf(args),
+          dimension: args.dimension,
+          metric: args.metric,
+          limit: args.limit
+        });
+        return ok(`${result.rows.length} row(s) by ${result.dimension}.`, result);
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_analytics_events",
+    {
+      title: "What this project measures",
+      description: "Every event name this project records, how often each fired in the window, which custom properties it carries, and \u2014 crucially \u2014 what somebody wrote down that it *means*. Read this before writing a funnel or a breakdown: nothing in the data says whether checkout_started fires on the click or on the page, and guessing wrong makes every number after it wrong. An event with a count of zero is an integration that stopped sending.",
+      inputSchema: { ...analyticsFilterArgs },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const events = await client.analytics.events(project, analyticsQueryOf(args));
+        const undescribed = events.filter((e) => !e.description).length;
+        return ok(
+          `${events.length} event type(s)${undescribed > 0 ? `, ${undescribed} with no description` : ""}.`,
+          { events }
+        );
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_describe_analytics_event",
+    {
+      title: "Describe what an event means",
+      description: "Write down what an event actually measures, so the next reader \u2014 a teammate or another agent \u2014 does not have to infer it from the name. This is the analytics equivalent of a collection's guidance. Say when it fires and what its properties mean; do not restate the name. Pass null to clear.",
+      inputSchema: {
+        ...projectArg,
+        event: z.string().describe("The event name, exactly as it is recorded."),
+        description: z.string().nullable().describe("What it means, or null to clear.")
+      },
+      annotations: { openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const updated = await client.analytics.describeEvent(project, args.event, {
+          description: args.description
+        });
+        return ok(`Described ${updated.name}.`, updated);
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_analytics_funnel",
+    {
+      title: "Conversion through ordered steps",
+      description: "How many visitors got through a sequence of events, in order, within a time budget. Returns per step: visitors, conversion from the first and previous step, how many dropped, and the median seconds it took. Order is enforced \u2014 somebody who saw the confirmation page before starting checkout has not converted. Pin a step to a page with `path` when the same event fires in several places.",
+      inputSchema: {
+        ...projectArg,
+        steps: z.array(
+          z.object({
+            event: z.string(),
+            path: z.string().optional().describe("Narrow this step to one page."),
+            label: z.string().optional()
+          })
+        ).describe("Two to eight steps, in the order a visitor performs them."),
+        period: z.string().optional().describe("Window: 24h, 7d, 30d. Defaults to 7d."),
+        from: z.string().optional(),
+        to: z.string().optional(),
+        withinHours: z.number().optional().describe("How long a visitor has to finish, measured from their first step. Defaults to 168.")
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const result = await client.analytics.funnel(project, {
+          steps: args.steps,
+          period: args.period,
+          from: args.from,
+          to: args.to,
+          withinHours: args.withinHours
+        });
+        const worst = [...result.steps].slice(1).sort((a, b) => a.conversionFromPrevious - b.conversionFromPrevious)[0];
+        const summary = worst ? `${result.conversion}% end to end; the biggest drop is into "${worst.label}" at ${worst.conversionFromPrevious}%.` : `${result.conversion}% end to end.`;
+        return ok(summary, result);
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_analytics_friction",
+    {
+      title: "Where people stop",
+      description: "Three signals in one call: the pages visits most often end on with their exit rates, the pages people arrive at and leave without going anywhere else, and \u2014 the one no other analytics tool can compute \u2014 the pages that generate bug reports out of proportion to their traffic, with the reports themselves. Use this when asked why usage dropped and you do not yet know where to look. There are no rage clicks here: Myna does not read the DOM.",
+      inputSchema: { ...analyticsFilterArgs },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const result = await client.analytics.friction(project, analyticsQueryOf(args));
+        const hotspot = result.feedbackHotspots[0];
+        const summary = hotspot ? `Worst complaint rate: ${hotspot.path} at ${hotspot.reportsPerThousandSessions} reports per 1000 sessions.` : `${result.exits.length} exit page(s), ${result.bounces.length} bounce page(s).`;
+        return ok(summary, result);
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_analytics_content",
+    {
+      title: "Traffic and complaints per content entry",
+      description: "Which Myna content entries people actually reach, how much traffic each gets, and how many bug reports were filed from their pages. The report links behaviour to the entries you can edit \u2014 an entry with heavy traffic and a high complaint count is where a copy change pays. `unattributed` tells you what share of events carried no content context, which distinguishes 'this entry has no traffic' from 'this application never attaches content'.",
+      inputSchema: { ...analyticsFilterArgs },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const result = await client.analytics.content(project, analyticsQueryOf(args));
+        return ok(
+          `${result.entries.length} entr(ies) with traffic; ${result.unattributed.share}% of events carried no content context.`,
+          result
+        );
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_analytics_entry",
+    {
+      title: "One entry, its publications, and their effect",
+      description: "Everything measured about one content entry: totals against the previous period, a daily series, which pages served it, its top events, every time it was published inside the window with the metric movement either side of each publication, and the reports filed from its pages. This is the call for 'did that copy change help' \u2014 it puts the edit and the numbers in one response.",
+      inputSchema: { ...analyticsFilterArgs, entryId: z.string().describe("Entry id (ent_...).") },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const { entryId, ...rest } = args;
+        const result = await client.analytics.entry(project, entryId, analyticsQueryOf(rest));
+        return ok(
+          `${result.entry.title ?? entryId}: ${result.totals.visitors} visitors (${result.change.visitors ?? "\u2014"}%), ${result.publications.length} publication(s), ${result.relatedReports.length} related report(s).`,
+          result
+        );
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_analytics_release_impact",
+    {
+      title: "What happened after a release",
+      description: "Compare equal windows either side of a published release: overall metrics, per entry the release touched, per event name, and the bug reports that came in afterwards. This is correlation, not causation \u2014 a release is not the only thing that happened that day \u2014 but it is the whole picture in one call, and it is the fastest way to find out whether a content change moved a number. The `after` window is clamped to now, so a release published yesterday is compared over one day rather than seven.",
+      inputSchema: {
+        ...projectArg,
+        release: z.number().describe("The release number."),
+        windowDays: z.number().optional().describe("Days either side. Defaults to 7, maximum 90.")
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const result = await client.analytics.releaseImpact(project, args.release, {
+          windowDays: args.windowDays
+        });
+        const moved = result.events.filter((e) => e.changePercent !== null && Math.abs(e.changePercent) >= 10).slice(0, 3).map((e) => `${e.name} ${e.changePercent}%`).join(", ");
+        const summary = [
+          `Release #${result.release.number} over ${result.windowDays} day(s):`,
+          `visitors ${result.change.visitors ?? "\u2014"}%`,
+          moved ? `notable: ${moved}` : null,
+          `${result.feedback.after} report(s) since (${result.feedback.before} before)`
+        ].filter(Boolean).join(" ");
+        return ok(summary, result);
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+  server.registerTool(
+    "myna_analytics_person",
+    {
+      title: "One person: what they did and what they said",
+      description: "A single identified user's recent sessions, recent events, and the bug reports they filed, in one response. Only people whose identity the customer's own backend signed appear here \u2014 anonymous visitors have sessions but no profile, deliberately. Use it when a report needs reproducing: the events leading up to it are usually the reproduction steps the reporter did not write down.",
+      inputSchema: {
+        ...projectArg,
+        person: z.string().describe("Myna profile id (apr_...) or the application's own user id.")
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      try {
+        const { client, project } = registry.clientFor(args.project);
+        const person = await client.analytics.profile(project, args.person);
+        return ok(
+          `${person.displayName ?? person.externalId}: ${person.sessions} session(s), ${person.events} event(s), ${person.reports.length} report(s).`,
+          person
+        );
+      } catch (error) {
+        return fail(error);
+      }
+    }
+  );
+}
 
 // src/resources.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -2618,7 +3017,7 @@ function registerResources(server, registry) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.16.1" : "0.0.0-dev";
+var VERSION = true ? "0.17.0" : "0.0.0-dev";
 
 // src/server.ts
 var SERVER_NAME = "myna";