@getsnare/mcp 0.1.0

package/dist/src/tools/events.js

@@ -0,0 +1,215 @@
+import { z } from "zod";
+import { DASH, bullets, clip, count, duration, facts, label, quantity, stamp, toolText, when } from "../format.js";
+import { readOnly, tool } from "../registry.js";
+/**
+ * Occurrences, evidence, traces and the people who hit them.
+ *
+ * THE VOCABULARY IS FIXED AND THESE TOOLS ARE WHERE IT MATTERS MOST. An ISSUE
+ * is the tracked thing. An EVENT is one occurrence of it. A TRACE is the set of
+ * events sharing an id, which is one request or one page load. The word "error"
+ * does not appear in any name, description or field here, and a test in this
+ * package fails the build if it is reintroduced.
+ */
+const issueRef = z.string().describe('The issue, as its key ("ACME-142") or its id.');
+export const eventTools = [
+    tool({
+        name: "list_issue_events",
+        title: "List an issue's occurrences",
+        description: "The individual times this issue happened, newest first, one line each. Use it to see WHEN something " +
+            "started, whether it is still happening, and which releases it appears in. One line per occurrence and no " +
+            "stack traces — for the stack, breadcrumbs and console of one occurrence, call get_event with an id from " +
+            "here. A row ending in a replay id has a session recording; get_session_replay takes that id. THIS IS THE " +
+            "ONLY PLACE A REPLAY ID COMES FROM.",
+        scope: "issues:read",
+        toolset: "events",
+        input: {
+            issue: issueRef,
+            release: z.string().optional().describe("Only occurrences from this build."),
+            limit: z.number().int().min(1).max(100).optional(),
+            cursor: z.string().optional(),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const { issue, ...query } = args;
+            const data = await client.get(`/issues/${encodeURIComponent(issue)}/events`, query);
+            if (data.events.length === 0)
+                return "No occurrences recorded for that issue.";
+            // EVERY IDENTIFIER IS LABELLED WITH WHAT IT IDENTIFIES. A bare cuid at
+            // the end of a row is a string of characters, and a real model reading a
+            // row that ended in one reported it as the trace id — it was the event
+            // id, and the two go to different tools. There are no column headings
+            // here to disambiguate them, so the word travels with the value.
+            const lines = data.events.map((event) => `${stamp(event.at)}  ${event.source}  ${event.release ?? DASH}  ` +
+                `${event.endUserId ? `user ${event.endUserId}` : "anonymous"}  event ${event.id}` +
+                // Only when there is one. A column of dashes under a heading nobody
+                // asked for is worse than the fact being absent.
+                (event.replayId ? `  replay ${event.replayId}` : "") +
+                (event.traceId ? `  trace ${event.traceId}` : ""));
+            return toolText(count(data.events.length, data.total, "occurrence"), lines.join("\n"), data.nextCursor ? `More: call again with cursor "${data.nextCursor}".` : null);
+        },
+    }),
+    tool({
+        name: "get_event",
+        title: "Get one occurrence in full",
+        description: "The evidence for a single occurrence: the exception and its stack with source lines where a sourcemap " +
+            "resolved them, the breadcrumbs leading up to it, the request, the console output, the tags and the " +
+            "platform. This is what to read before saying anything about a cause — it is the difference between a claim " +
+            "and a claim somebody can check.",
+        scope: "issues:read",
+        toolset: "events",
+        input: {
+            issue: issueRef,
+            eventId: z.string().describe("From list_issue_events."),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/issues/${encodeURIComponent(args.issue)}/events/${encodeURIComponent(args.eventId)}`);
+            const event = data.event;
+            const stack = event.exception
+                ? event.exception.frames
+                    .map((frame) => {
+                    const where = `${frame.file ?? DASH}:${frame.line ?? DASH}${frame.column ? `:${frame.column}` : ""}`;
+                    const inApp = frame.inApp ? "" : "  (library)";
+                    const source = frame.code ? `\n    ${frame.code.trim()}` : "";
+                    return `  at ${frame.function ?? "(anonymous)"} — ${where}${inApp}${source}`;
+                })
+                    .join("\n")
+                : null;
+            return toolText(event.exception?.type
+                ? `${event.exception.type}: ${clip(event.exception.value, 200)}`
+                : clip(event.title, 200), facts([
+                ["When", when(event.at)],
+                ["Source", event.source],
+                ["Release", event.release],
+                ["Environment", event.environment],
+                ["Person", event.endUserId],
+                ["Trace", event.traceId],
+                ["Session", event.sessionId],
+                // Only when it is actually a boolean. `String(undefined)` printed the
+                // word "undefined" on every event with no exception attached, which
+                // is a fact about JavaScript rather than about the occurrence. Absent
+                // means the dash, like every other unknown in this block.
+                [
+                    "Handled",
+                    typeof event.exception?.handled === "boolean" ? (event.exception.handled ? "Yes" : "No") : null,
+                ],
+                ["Request", event.request?.url ? `${event.request.method ?? ""} ${event.request.url}`.trim() : null],
+            ]), stack ? `Stack\n${stack}` : event.rawStack ? `Stack\n${event.rawStack}` : null, event.breadcrumbs.length > 0
+                ? `Leading up to it\n${bullets(event.breadcrumbs
+                    .slice(-20)
+                    .map((crumb) => `${stamp(crumb.at)}  ${crumb.category ?? DASH}  ${clip(crumb.message, 160)}`), "")}`
+                : null, event.tags.length > 0 ? `Tags\n${event.tags.map(([key, value]) => `${key}=${value}`).join("  ")}` : null, event.consoleLog ? `Console\n${clip(event.consoleLog, 2000)}` : null, event.body ? `Body\n${clip(event.body, 1000)}` : null);
+        },
+    }),
+    tool({
+        name: "list_traces",
+        title: "List traces",
+        description: "One row per request or page load that produced at least one event. A trace answers a question an issue " +
+            "cannot: an issue groups the same failure across time, a trace groups DIFFERENT failures within one instant. " +
+            "Use it when you suspect several things go wrong together.",
+        scope: "issues:read",
+        toolset: "events",
+        input: {
+            projectId: z.string().describe("Required — traces are per project."),
+            rangeMinutes: z.number().int().min(1).optional().describe("How far back. Omit for the default window."),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get("/traces", args);
+            if (data.traces.length === 0)
+                return "No traces in that window.";
+            return toolText(count(data.traces.length, data.total, "trace"), data.traces
+                .map((row) => `${stamp(row.firstSeen)}  ${quantity(row.issueCount, "issue")} / ${quantity(row.eventCount, "event")}  ` +
+                `${row.issueKey ?? DASH}  ${clip(row.issueTitle ?? row.url, 80)}  trace ${row.traceId}`)
+                .join("\n"));
+        },
+    }),
+    tool({
+        name: "get_trace",
+        title: "Get one trace",
+        description: "Everything that happened inside one request, in order, with how long after the first event each one " +
+            "occurred. The ordering is usually the diagnosis: knowing the token refresh failed 40ms before the request " +
+            "that used it is most of the answer.",
+        scope: "issues:read",
+        toolset: "events",
+        input: {
+            traceId: z.string(),
+            projectId: z.string().describe("Required — traces are per project."),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/traces/${encodeURIComponent(args.traceId)}`, { projectId: args.projectId });
+            return toolText(`Issues ${data.issueCount} / Events ${data.eventCount}, starting ${when(data.startedAt)}.`, data.spans
+                .map((span) => `+${span.offsetMs}ms  ${clip(span.title, 90)}  ${span.issue ? `→ ${span.issue.key ?? span.issue.id}` : "(not yet grouped)"}`)
+                .join("\n"));
+        },
+    }),
+    tool({
+        name: "get_session_replay",
+        title: "Get a session recording",
+        description: "How long a recording is and where a person can watch it. It does NOT return the recording itself — that is " +
+            "a stream of DOM mutations, routinely megabytes, and of no use to you. Hand the link to whoever asked.",
+        scope: "analytics:read",
+        toolset: "events",
+        input: { replayId: z.string() },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/session-replays/${encodeURIComponent(args.replayId)}`);
+            return facts([
+                ["Recorded", when(data.replay.recordedAt)],
+                ["Length", duration(data.replay.durationSeconds)],
+                ["Session", data.replay.sessionId],
+                ["Issue", data.replay.issueKey ?? data.replay.issueId],
+                ["Watch it", data.replay.url],
+            ]);
+        },
+    }),
+    tool({
+        name: "list_affected_users",
+        title: "List the customer's own users",
+        description: "People the customer's app has identified, most recently active first. These are NOT members of the Snare " +
+            "workspace — for those, use list_members. Use this when somebody asks about a specific customer by name or " +
+            "id.",
+        scope: "analytics:read",
+        toolset: "events",
+        input: {
+            projectId: z.string().optional(),
+            search: z.string().optional().describe("Matches the id and the traits people search by."),
+            limit: z.number().int().min(1).max(100).optional(),
+            cursor: z.string().optional(),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get("/end-users", args);
+            if (data.endUsers.length === 0)
+                return "Nobody matches. Identification is opt-in, so a project that never calls identify has none.";
+            return toolText(`${quantity(data.endUsers.length, "person", "people")}.`, data.endUsers
+                .map((person) => `${person.distinctId}  ${quantity(person.issueCount, "issue")}  ${quantity(person.sessionCount, "session")}  ` +
+                `last seen ${stamp(person.lastSeenAt)}  person ${person.id}`)
+                .join("\n"), data.nextCursor ? `More: call again with cursor "${data.nextCursor}".` : null);
+        },
+    }),
+    tool({
+        name: "get_affected_user",
+        title: "Get one of the customer's users",
+        description: "What one identified person has run into: the issues they hit and how many times each, and their recent " +
+            "sessions. Use this when somebody says 'this customer is complaining' — it turns a name into a list of real " +
+            "problems, and the counts are theirs rather than the issues' global ones.",
+        scope: "analytics:read",
+        toolset: "events",
+        input: {
+            endUserId: z.string().describe("The id from list_affected_users, not the customer's own distinct id."),
+            sessionLimit: z.number().int().min(1).max(100).optional(),
+            issueLimit: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const { endUserId, ...query } = args;
+            const data = await client.get(`/end-users/${encodeURIComponent(endUserId)}`, query);
+            return toolText(`${data.endUser.distinctId} in ${data.endUser.projectName}, last seen ${when(data.endUser.lastSeenAt)}.`, data.issues.length > 0
+                ? `${count(data.issuesShown, data.issuesTotal, "issue")} they have hit\n${bullets(data.issues.map((row) => `${row.hitCount}×  ${row.severity ? label(row.severity) : DASH}  ${clip(row.title, 80)}  (${row.issueKey ?? row.issueId})`), "")}`
+                : "They have not hit any issues.", `${count(data.sessionsShown, data.sessionsTotal, "session")} recorded.`);
+        },
+    }),
+];

package/dist/src/tools/index.d.ts

@@ -0,0 +1,11 @@
+import type { ToolDef } from "../registry.js";
+/**
+ * Every tool this server can offer.
+ *
+ * ONE FLAT LIST, because everything that reasons about the catalogue — which
+ * tools a token unlocks, which sets they belong to, whether any of them
+ * contradicts the naming rules — reasons about all of them at once. Grouping
+ * lives in each tool's `toolset` field rather than in the shape of this array,
+ * so a tool cannot be in two groups or in none.
+ */
+export declare const ALL_TOOLS: ToolDef[];

package/dist/src/tools/index.js

@@ -0,0 +1,25 @@
+import { eventTools } from "./events.js";
+import { issueTools } from "./issues.js";
+import { localTools } from "./local.js";
+import { memoryTools } from "./memory.js";
+import { snareTools } from "./snares.js";
+import { feedbackTools, setupTools, workspaceTools } from "./workspace.js";
+/**
+ * Every tool this server can offer.
+ *
+ * ONE FLAT LIST, because everything that reasons about the catalogue — which
+ * tools a token unlocks, which sets they belong to, whether any of them
+ * contradicts the naming rules — reasons about all of them at once. Grouping
+ * lives in each tool's `toolset` field rather than in the shape of this array,
+ * so a tool cannot be in two groups or in none.
+ */
+export const ALL_TOOLS = [
+    ...issueTools,
+    ...eventTools,
+    ...snareTools,
+    ...localTools,
+    ...feedbackTools,
+    ...memoryTools,
+    ...workspaceTools,
+    ...setupTools,
+];

package/dist/src/tools/issues.d.ts

@@ -0,0 +1,2 @@
+import { type ToolDef } from "../registry.js";
+export declare const issueTools: ToolDef[];

package/dist/src/tools/issues.js

@@ -0,0 +1,310 @@
+import { z } from "zod";
+import { DASH, clip, count, label, quantity, stamp, toolText } from "../format.js";
+import { issueDetail, issueList } from "../render.js";
+import { destructive, idempotentWrite, readOnly, tool, write } from "../registry.js";
+/**
+ * Issues: the ones an agent reaches for most.
+ *
+ * THE DESCRIPTIONS DO REAL WORK HERE. Thirteen tools about the same noun is
+ * exactly the shape that makes a model pick the wrong one, so each says when to
+ * use it INSTEAD OF its neighbour — list versus search, get versus timeline,
+ * update versus assign. That sentence is worth more than any amount of schema.
+ */
+const issueRef = z
+    .string()
+    .describe('The issue, as its workspace key ("ACME-142") or its id. Keys are what people use.');
+export const issueTools = [
+    tool({
+        name: "list_issues",
+        title: "List issues",
+        description: "Browse issues by filter: status, severity, project. Use this to answer questions about a GROUP of issues " +
+            '("what is open and critical", "what has Snare fixed this week"). If you already know roughly what the issue ' +
+            "is CALLED, use search_issues instead — this tool has no text matching and will make you page through everything.",
+        scope: "issues:read",
+        toolset: "issues",
+        input: {
+            projectId: z.string().optional().describe("Narrow to one project. Omit for every project in the workspace."),
+            status: z
+                .enum(["NEW", "IN_PROGRESS", "FIXED", "REGRESSED", "ATTEMPTED_RECOVERY_DETECTED", "FIXED_MODIFIED"])
+                .optional(),
+            severity: z.enum(["LOW", "MEDIUM", "HIGH", "CRITICAL"]).optional(),
+            limit: z.number().int().min(1).max(100).optional().describe("Default 50."),
+            cursor: z.string().optional().describe("From a previous call's nextCursor."),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get("/issues", args);
+            const scope = [
+                args.severity ? `at ${label(args.severity)} severity` : null,
+                args.status ? `with status ${label(args.status)}` : null,
+                args.projectId ? "in this project" : "in this workspace",
+            ]
+                .filter(Boolean)
+                .join(" ");
+            return toolText(issueList(data.issues, data.total, scope), data.nextCursor ? `More: call again with cursor "${data.nextCursor}".` : null);
+        },
+    }),
+    tool({
+        name: "search_issues",
+        title: "Search issues",
+        description: "Find an issue by words in its title. Use this when you have a name or a phrase and want THE issue " +
+            '("the checkout timeout one"). It searches titles only — not comments, stack traces or event bodies — so an ' +
+            "empty result means no issue is CALLED that, not that the problem does not exist. For browsing by status or " +
+            "severity, use list_issues.",
+        scope: "issues:read",
+        toolset: "issues",
+        input: {
+            q: z.string().min(1).describe("Words from the title."),
+            projectId: z.string().optional(),
+            includeArchived: z
+                .boolean()
+                .optional()
+                .describe("Archived and excluded issues are left out unless this is true."),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get("/issues/search", args);
+            return issueList(data.results, data.total, `matching "${args.q}"`);
+        },
+    }),
+    tool({
+        name: "get_issue",
+        title: "Get an issue",
+        description: "Everything about one issue in a single call: severity, status, who it is assigned to, how many events, how " +
+            "many people it has affected, when it started, the latest run and any pull request. Start here for any " +
+            "question about a specific issue — you should not need a follow-up call for the basics. For WHO SAID WHAT " +
+            "about it, use get_issue_timeline; for individual occurrences, use list_issue_events.",
+        scope: "issues:read",
+        toolset: "issues",
+        input: { issue: issueRef },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/issues/${encodeURIComponent(args.issue)}`);
+            return issueDetail(data.issue);
+        },
+    }),
+    tool({
+        name: "get_issue_timeline",
+        title: "Get an issue's history",
+        description: "Who has worked on this issue and what has happened to it: every comment, every status and severity change " +
+            "with who made it, every run and how it ended. Use this to answer 'is somebody already on this', 'why was " +
+            "this closed', or 'what did they decide'. Oldest first.",
+        scope: "issues:read",
+        toolset: "issues",
+        input: {
+            issue: issueRef,
+            limit: z.number().int().min(1).max(100).optional().describe("Default 100. The most recent are kept."),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/issues/${encodeURIComponent(args.issue)}/timeline`, { limit: args.limit });
+            if (data.entries.length === 0)
+                return "Nothing has happened to this issue yet.";
+            const lines = data.entries.map((entry) => {
+                const who = entry.actor.kind === "snare"
+                    ? "Snare"
+                    : entry.actor.kind === "system"
+                        ? "Snare (automatic)"
+                        : (entry.actor.name ?? "Someone");
+                const via = entry.via ? ` (via ${entry.via})` : "";
+                return `${stamp(entry.at)}  ${who}${via}: ${clip(entry.text, 400)}`;
+            });
+            return toolText(count(data.entries.length, data.total, "entry", "entries"), lines.join("\n"), 
+            // Said rather than left to be inferred. A caller reading the last
+            // hundred entries of a busy issue is looking at a window, and reporting
+            // "nobody has commented" from it would be wrong.
+            data.truncated ? "There is more history than this. Only the most recent entries are shown." : null);
+        },
+    }),
+    tool({
+        name: "update_issue",
+        title: "Change an issue",
+        description: "Set an issue's status, severity or title, or move it to the archive or the exclusion zone. Send only the " +
+            "fields you are changing. Setting a value it already has writes nothing and says so, so this is safe to call " +
+            "without reading first. To change who is on it, use assign_issue.",
+        scope: "issues:write",
+        toolset: "issues",
+        input: {
+            issue: issueRef,
+            status: z.enum(["NEW", "IN_PROGRESS", "FIXED", "REGRESSED"]).optional(),
+            severity: z.enum(["LOW", "MEDIUM", "HIGH", "CRITICAL"]).optional(),
+            title: z.string().min(1).max(300).optional(),
+            archived: z.boolean().optional().describe("Archiving takes it off the list without saying it is fixed."),
+            excluded: z
+                .boolean()
+                .optional()
+                .describe("The exclusion zone is for issues nobody wants Snare to look at. Needs the issues:delete scope."),
+        },
+        annotations: idempotentWrite(),
+        async run(args, { client }) {
+            const { issue, ...patch } = args;
+            const data = await client.patch(`/issues/${encodeURIComponent(issue)}`, patch);
+            return toolText(data.changed.length === 0
+                ? "Nothing changed — it already had those values."
+                : `Changed ${data.changed.join(", ")}.`, issueDetail(data.issue));
+        },
+    }),
+    tool({
+        name: "assign_issue",
+        title: "Assign an issue",
+        description: "Set exactly who is on an issue. This REPLACES the current assignees with the list you send, so include " +
+            "everybody who should be on it, and send an empty list to unassign everyone. Accepts email addresses as well " +
+            "as user ids. Use list_members to see who is in the workspace.",
+        scope: "issues:assign",
+        toolset: "issues",
+        input: {
+            issue: issueRef,
+            assignees: z
+                .array(z.string())
+                .max(50)
+                .describe("Emails or user ids. The complete list, not the ones to add."),
+        },
+        annotations: idempotentWrite(),
+        async run(args, { client }) {
+            const data = await client.put(`/issues/${encodeURIComponent(args.issue)}/assignees`, { assignees: args.assignees });
+            const names = data.issue.assignees.map((person) => person.name ?? person.email);
+            return toolText(names.length === 0 ? "Nobody is assigned now." : `Assigned to ${names.join(", ")}.`, issueDetail(data.issue));
+        },
+    }),
+    tool({
+        name: "comment_on_issue",
+        title: "Comment on an issue",
+        description: "Post a comment on an issue's thread. Everyone watching the issue sees it and it appears in the product as " +
+            "written by an agent, not by you personally and not by Snare. Use it to record what you found or what you " +
+            "did. It is not a way to talk to a running Snare — for that, use send_snare_directive.",
+        scope: "issues:comment",
+        toolset: "issues",
+        input: {
+            issue: issueRef,
+            body: z.string().min(1).max(10_000),
+            replyTo: z.string().optional().describe("The id of a comment to reply to."),
+        },
+        annotations: write(),
+        async run(args, { client }) {
+            const data = await client.post(`/issues/${encodeURIComponent(args.issue)}/comments`, { body: args.body, replyTo: args.replyTo });
+            return `Posted. Comment ${data.comment.id}.`;
+        },
+    }),
+    tool({
+        name: "star_issue",
+        title: "Star an issue",
+        description: "Flag an issue to come back to. The star is visible to the whole workspace and changes nothing about the " +
+            "issue itself — it does not assign, prioritise or notify anybody.",
+        scope: "issues:read",
+        toolset: "issues",
+        input: { issue: issueRef, starred: z.boolean() },
+        annotations: idempotentWrite(),
+        async run(args, { client }) {
+            const data = await client.put(`/issues/${encodeURIComponent(args.issue)}/star`, {
+                starred: args.starred,
+            });
+            return `${data.issue.key} ${args.starred ? "starred" : "unstarred"}.`;
+        },
+    }),
+    tool({
+        name: "update_issues",
+        title: "Change several issues",
+        description: "Apply one change — a status, archiving, or the exclusion zone — to a list of issues at once. Reports which " +
+            "ones it applied to and which references it could not find, so check both. Use update_issue for a single one.",
+        scope: "issues:write",
+        toolset: "issues",
+        input: {
+            issues: z.array(z.string()).min(1).max(200).describe("Keys or ids."),
+            status: z.enum(["NEW", "IN_PROGRESS", "FIXED", "REGRESSED"]).optional(),
+            archived: z.boolean().optional(),
+            excluded: z.boolean().optional().describe("Needs the issues:delete scope."),
+        },
+        annotations: idempotentWrite(),
+        async run(args, { client }) {
+            const data = await client.post("/issues/bulk", args);
+            return toolText(`Changed ${data.applied.length} of ${data.total}.`, data.notFound.length > 0 ? `Could not find: ${data.notFound.join(", ")}.` : null);
+        },
+    }),
+    tool({
+        name: "merge_issues",
+        title: "Merge issues",
+        description: "Declare that several issues are the same bug. Their occurrences move onto one surviving issue and the " +
+            "others become pointers to it. The oldest survives unless you name one with `into`, because it owns the key " +
+            "people have already linked to. THIS CANNOT BE UNDONE — check with list_similar_issues first if you are not " +
+            "certain.",
+        scope: "issues:group",
+        toolset: "issues",
+        input: {
+            issues: z.array(z.string()).min(2).max(50).describe("Keys or ids. At least two."),
+            into: z.string().optional().describe("Which one survives. Must be one of the above. Defaults to the oldest."),
+        },
+        annotations: destructive(),
+        async run(args, { client }) {
+            const data = await client.post("/issues/merge", args);
+            return toolText(`Merged ${data.mergedIssueIds.length} issues into ${data.issue.key}, moving ${data.movedEventCount} events.`, issueDetail(data.issue));
+        },
+    }),
+    tool({
+        name: "split_issue",
+        title: "Move an occurrence out of an issue",
+        description: "Say that one occurrence does not belong in the issue it was grouped into. It moves to a new issue of its " +
+            "own, and Snare's grouping learns from it: the next occurrence that looks like it lands in the new issue " +
+            "rather than back here. Use it when you have READ an occurrence and can see it is a different bug. THIS " +
+            "CANNOT BE UNDONE by merging them back.",
+        scope: "issues:group",
+        toolset: "issues",
+        input: {
+            issue: issueRef,
+            eventId: z.string().describe("From list_issue_events."),
+        },
+        annotations: destructive(),
+        async run(args, { client }) {
+            const data = await client.post(`/issues/${encodeURIComponent(args.issue)}/split`, { eventId: args.eventId });
+            return `Moved that occurrence out of ${data.issue.key} into ${data.newIssue.key}.\n\n${issueDetail(data.newIssue)}`;
+        },
+    }),
+    tool({
+        name: "list_similar_issues",
+        title: "Find issues like this one",
+        description: "Issues that resemble this one, by how alike their occurrences are. Worth calling BEFORE fixing anything: " +
+            "the most expensive mistake is fixing a bug that is already fixed, or fixing one instance of a shape that " +
+            "appears four times. An empty result means nothing genuinely resembles it, not that the comparison failed.",
+        scope: "issues:read",
+        toolset: "issues",
+        input: { issue: issueRef, limit: z.number().int().min(1).max(20).optional() },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/issues/${encodeURIComponent(args.issue)}/similar`, { limit: args.limit });
+            if (data.similar.length === 0)
+                return "Nothing in this workspace closely resembles that issue.";
+            return data.similar
+                .map((row) => `${row.issueKey ?? row.issueId}  ${Math.round(row.similarity * 100)}% alike  ${label(row.status)}  ${row.severity ? label(row.severity) : DASH}  ${clip(row.title, 90)}`)
+                .join("\n");
+        },
+    }),
+    tool({
+        name: "get_issue_analytics",
+        title: "How often, and to how many people",
+        description: "Volume and reach for one issue: occurrences per day, distinct affected users, and a breakdown by release " +
+            "and source. Use it to decide whether an issue matters, and to spot the release that introduced it. Note " +
+            "that affected users counts only people the customer's app has identified, and the response says what share " +
+            "that is.",
+        scope: "issues:read",
+        toolset: "issues",
+        input: {
+            issue: issueRef,
+            days: z.number().int().min(1).max(90).optional().describe("Default 30."),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/issues/${encodeURIComponent(args.issue)}/analytics`, { days: args.days });
+            const identified = data.identifiedShare === null
+                ? "no occurrences in this window"
+                : data.identifiedShare === 0
+                    ? "none of these occurrences identified a person, so the affected-user count is zero for that reason rather than because nobody was affected"
+                    : `${Math.round(data.identifiedShare * 100)}% of occurrences identified a person`;
+            return toolText(`${quantity(data.events, "occurrence")} in the last ${quantity(data.windowDays, "day")}, ` +
+                `${quantity(data.affectedUsers, "identified person", "identified people")} affected.`, `Identification: ${identified}.`, `By day\n${data.eventsByDay.map((row) => `${row.day}  ${row.events}`).join("\n")}`, data.byRelease.length > 0
+                ? `By release\n${data.byRelease.map((row) => `${row.release ?? DASH}  ${row.events}`).join("\n")}`
+                : null, data.bySource.length > 0
+                ? `By source\n${data.bySource.map((row) => `${row.source}  ${row.events}`).join("\n")}`
+                : null);
+        },
+    }),
+];

package/dist/src/tools/local.d.ts

@@ -0,0 +1,2 @@
+import { type ToolDef } from "../registry.js";
+export declare const localTools: ToolDef[];