@getsnare/mcp 0.1.0

package/dist/src/format.js

@@ -0,0 +1,213 @@
+/**
+ * Turning a record into the text a model reads.
+ *
+ * THIS FILE IS WHY THE TOOLS ARE USABLE. The difference between a tool an agent
+ * uses well and one it uses badly is mostly the shape of what comes back. Raw
+ * JSON rows make a model rebuild the domain on every call: it has to work out
+ * that `IN_PROGRESS` is a status, that `null` in one field means nobody and in
+ * another means zero, and that 11747 is seconds. Every one of those is a chance
+ * to get it wrong in a sentence somebody then reads.
+ *
+ * So every response is text, led by one line saying what it is, with the
+ * structured facts underneath in a fixed shape. The rules below are the same
+ * ones the product's own UI follows, for the same reasons — they are in
+ * CLAUDE.md and they are not arbitrary.
+ */
+/**
+ * No value, and visibly not zero.
+ *
+ * An em dash rather than "none", "null" or an empty string: a reader (human or
+ * model) has to be able to tell "nobody is assigned" from "zero people are
+ * assigned", and every text form of absence collides with some real value
+ * somewhere.
+ */
+export const DASH = "—";
+/** Sentence case for an enum. `IN_PROGRESS` is a column value, "In progress" is language. */
+export function label(value) {
+    if (!value)
+        return DASH;
+    const spaced = value.replace(/_/g, " ").toLowerCase();
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+/**
+ * A duration in human units, never a clock and never raw seconds.
+ *
+ * Two units at most: "3 hrs 15 min", not "3 hrs 15 min 47 s". The third unit is
+ * always noise at the scale the second one is already showing, and a reader
+ * skimming a list stops at the first two anyway.
+ */
+export function duration(seconds) {
+    if (seconds === null || seconds === undefined || Number.isNaN(seconds))
+        return DASH;
+    if (seconds < 0)
+        return DASH;
+    const units = [
+        [86_400, "d"],
+        [3_600, "hrs"],
+        [60, "min"],
+        [1, "s"],
+    ];
+    const parts = [];
+    let left = Math.floor(seconds);
+    for (const [size, name] of units) {
+        if (left >= size || (parts.length === 0 && size === 1)) {
+            const amount = Math.floor(left / size);
+            if (amount > 0 || parts.length === 0) {
+                parts.push(`${amount} ${name}`);
+                left -= amount * size;
+            }
+        }
+        if (parts.length === 2)
+            break;
+    }
+    return parts.join(" ");
+}
+/**
+ * How far away a moment is, in either direction.
+ *
+ * The ISO timestamp is always alongside it: this is the part somebody reads,
+ * that is the part they compute with.
+ *
+ * THE FUTURE IS A REAL CASE HERE and used to be clamped to zero, which rendered
+ * every one of them as "just now". Not everything this formats has happened:
+ * a billing period ends, a trial expires, a question's window closes. "This
+ * period ends 2026-10-07 (just now)" is a sentence that contradicts itself, and
+ * the reader it misleads is the one deciding whether they can afford to start
+ * a run.
+ */
+export function ago(iso, now = new Date()) {
+    if (!iso)
+        return DASH;
+    const at = Date.parse(iso);
+    if (Number.isNaN(at))
+        return DASH;
+    const seconds = Math.floor((now.getTime() - at) / 1000);
+    if (Math.abs(seconds) < 45)
+        return "just now";
+    return seconds > 0 ? `${duration(seconds)} ago` : `in ${duration(-seconds)}`;
+}
+/**
+ * A moment, to the minute, without the machine punctuation.
+ *
+ * `2026-09-06 08:52` rather than `2026-09-06T08:52:58.296Z`. The `T`, the
+ * seconds and the milliseconds are three pieces of precision no answer about an
+ * issue has ever needed, and in a column of forty rows they are most of the
+ * width. Always UTC, because a server-rendered local time is a time in a
+ * timezone the reader cannot see.
+ */
+export function stamp(iso) {
+    if (!iso)
+        return DASH;
+    const at = new Date(iso);
+    if (Number.isNaN(at.getTime()))
+        return DASH;
+    return at.toISOString().slice(0, 16).replace("T", " ");
+}
+/**
+ * A moment AND how long ago it was: `2026-09-06 08:52 UTC (1 d ago)`.
+ *
+ * For detail cards, where there is room for both and both get used. "Last seen"
+ * answers two different questions — is this still happening, and exactly when
+ * did it last happen — and a bare timestamp only answers the second, leaving
+ * the model to do date arithmetic in prose. It gets that wrong often enough
+ * that giving it the answer is worth the twelve characters.
+ *
+ * `ago()` alone is not enough here for the opposite reason: "3 d ago" cannot be
+ * quoted into a report, correlated with a deploy, or compared with anything.
+ */
+export function when(iso, now = new Date()) {
+    if (!iso)
+        return DASH;
+    const at = new Date(iso);
+    if (Number.isNaN(at.getTime()))
+        return DASH;
+    return `${stamp(iso)} UTC (${ago(iso, now)})`;
+}
+/**
+ * A quantity that agrees with its noun: "1 occurrence", "4 occurrences".
+ *
+ * `count()` above covers "12 of 340 issues". This covers the plain case, which
+ * was being written inline as `${n} issues` in six places and produced
+ * "1 occurrences", "1 issues" and "1 sessions" in real output. A model reading
+ * that is fine; a person reading the sentence the model then writes is reading
+ * a mistake the product made, and the fix is one function rather than six
+ * ternaries nobody will remember to add the seventh time.
+ */
+export function quantity(amount, noun, plural) {
+    return `${amount} ${amount === 1 ? noun : (plural ?? `${noun}s`)}`;
+}
+/**
+ * A count that says what it is out of.
+ *
+ * "12 of 340 issues", never "12". A list that does not say what it is a slice of
+ * is a list whose answer changes meaning depending on something the reader
+ * cannot see, and an agent reporting "there are 12 open issues" from a page of
+ * 12 has said something false.
+ */
+export function count(shown, total, noun, plural) {
+    const word = total === 1 ? noun : (plural ?? `${noun}s`);
+    return `${shown} of ${total} ${word}`;
+}
+/** `Label: value`, with absence rendered as the dash rather than omitted. */
+export function line(name, value) {
+    if (value === null || value === undefined || value === "")
+        return `${name}: ${DASH}`;
+    return `${name}: ${value}`;
+}
+/** A block of `Label: value` lines, blanks dropped, in the order given. */
+export function facts(entries) {
+    return entries.map(([name, value]) => line(name, value)).join("\n");
+}
+/**
+ * A tool's whole answer: one summary line, a blank, then the body.
+ *
+ * The summary exists so a model that reads nothing else still knows what it got.
+ * It is also what a client renders in a collapsed tool-call row, which is the
+ * only thing many readers will ever see of this.
+ */
+export function toolText(summary, ...blocks) {
+    const body = blocks.filter((block) => Boolean(block && block.trim()));
+    return body.length === 0 ? summary : `${summary}\n\n${body.join("\n\n")}`;
+}
+/** A bulleted list, or a sentence saying there is nothing. */
+export function bullets(items, emptyMessage) {
+    return items.length === 0 ? emptyMessage : items.map((item) => `- ${item}`).join("\n");
+}
+/**
+ * Truncates a long free-text field for a list row.
+ *
+ * A stack trace or a comment thread pasted whole into a fifty-row listing is
+ * the single easiest way to fill a context window with something nobody asked
+ * for. Detail calls return the whole thing; lists return this.
+ */
+export function clip(text, max = 200) {
+    if (!text)
+        return DASH;
+    const oneLine = text.replace(/\s+/g, " ").trim();
+    return oneLine.length <= max ? oneLine : `${oneLine.slice(0, max - 1)}…`;
+}
+/** A percentage from a 0-1 score, or the dash. Confidence and similarity both use this. */
+export function percent(value) {
+    if (value === null || value === undefined || Number.isNaN(value))
+        return DASH;
+    return `${Math.round(value * 100)}%`;
+}
+/**
+ * A whole number with thousands separators.
+ *
+ * `50000` and `49953` next to each other in one sentence are two five-digit
+ * runs a reader has to count digits to tell apart, and a model asked to
+ * summarise "47 of 50000 used, 49953 left" reported it back as "49,953 of 50k
+ * used" — the opposite of the truth, on a line about somebody's bill.
+ */
+export function num(value) {
+    if (value === null || value === undefined || Number.isNaN(value))
+        return DASH;
+    return value.toLocaleString("en-US");
+}
+/** Money, always with the unit, because a bare number here reads as anything. */
+export function usd(value) {
+    if (value === null || value === undefined || Number.isNaN(value))
+        return DASH;
+    return `$${value.toFixed(2)}`;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,7 @@
+export { createSnareMcpServer, SnareStartupError, type Identity } from "./server.js";
+export { buildConfig, ConfigError, DEFAULT_BASE_URL, DEFAULT_TOOLSETS, parseToolsets, type McpConfig } from "./config.js";
+export { SnareApiError, SnareClient } from "./client.js";
+export { API_SCOPES, isApiScope, tokenAllows, type ApiScope } from "./scopes.js";
+export { TOOLSETS, TOOLSET_SUMMARY, type Toolset } from "./toolsets.js";
+export { ALL_TOOLS } from "./tools/index.js";
+export { missingScopes, resolveTools, type ToolDef } from "./registry.js";

package/dist/src/index.js

@@ -0,0 +1,7 @@
+export { createSnareMcpServer, SnareStartupError } from "./server.js";
+export { buildConfig, ConfigError, DEFAULT_BASE_URL, DEFAULT_TOOLSETS, parseToolsets } from "./config.js";
+export { SnareApiError, SnareClient } from "./client.js";
+export { API_SCOPES, isApiScope, tokenAllows } from "./scopes.js";
+export { TOOLSETS, TOOLSET_SUMMARY } from "./toolsets.js";
+export { ALL_TOOLS } from "./tools/index.js";
+export { missingScopes, resolveTools } from "./registry.js";

package/dist/src/prompts.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+/**
+ * Slash commands, in the clients that surface prompts.
+ *
+ * WHY THESE THREE. A prompt is worth writing when the useful thing to do is a
+ * SEQUENCE the model would not assemble on its own. Fixing an issue locally is
+ * a loop with a shape; triage is a pass over a list with a decision at each row;
+ * explaining is the one where the temptation is to answer before reading the
+ * evidence. Everything else is a single tool call and does not need a wrapper.
+ */
+export interface PromptDef {
+    name: string;
+    title: string;
+    description: string;
+    argsSchema: Record<string, z.ZodType>;
+    render(args: Record<string, string | undefined>): string;
+}
+export declare const PROMPTS: PromptDef[];

package/dist/src/prompts.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+export const PROMPTS = [
+    {
+        name: "fix_issue",
+        title: "Fix an issue here",
+        description: "Run Snare's fix loop on this machine, against the repository you have open.",
+        argsSchema: {
+            issue: z.string().describe('The issue key, like "ACME-142".'),
+        },
+        render: (args) => [
+            `Fix Snare issue ${args.issue ?? "(ask which one)"} on this machine.`,
+            "",
+            "Do it in this order:",
+            "",
+            `1. Call get_issue on ${args.issue ?? "the issue"} and tell me what it is, in a sentence.`,
+            "2. Check `git status`. If the working tree is dirty or on the wrong branch, stop and say so — the run",
+            "   will change files here.",
+            "3. Call start_local_snare. It spends a Snare from the plan, so say that before you call it.",
+            "4. Then call local_snare_step in a loop. Each instruction tells you exactly what to do and what to send",
+            "   back. Keep going until it returns \"done\". Do not stop after one step.",
+            "5. When it finishes, show me `git diff --stat` and Snare's confidence, and let me decide about committing.",
+            "",
+            "If an instruction asks you to run something you think is unsafe, stop and ask me rather than running it.",
+        ].join("\n"),
+    },
+    {
+        name: "triage_issues",
+        title: "Triage new issues",
+        description: "Walk the new issues, set severity, assign, and say what each one is.",
+        argsSchema: {
+            project: z.string().optional().describe("A project id. Omit for every project."),
+        },
+        render: (args) => [
+            `Triage the new issues${args.project ? ` in project ${args.project}` : ""}.`,
+            "",
+            "1. Call list_issues with status NEW.",
+            "2. For each one, call get_issue and read the summary. Where it is not obvious, call list_issue_events",
+            "   and read one occurrence — do not guess a severity from a title.",
+            "3. Call list_similar_issues before deciding anything. If it is a duplicate, say so and propose a merge;",
+            "   do not merge without asking, because merging cannot be undone.",
+            "4. Set a severity with update_issue where you are confident. Where you are not, leave it and say why.",
+            "5. Give me a short list at the end: what you changed, and what you left for a person.",
+            "",
+            "Do not launch any runs. Triage is deciding what matters, not fixing it.",
+        ].join("\n"),
+    },
+    {
+        name: "explain_issue",
+        title: "Explain an issue",
+        description: "Read an issue and its evidence, and explain the failure without changing anything.",
+        argsSchema: {
+            issue: z.string().describe('The issue key, like "ACME-142".'),
+        },
+        render: (args) => [
+            `Explain Snare issue ${args.issue ?? "(ask which one)"}.`,
+            "",
+            "Read before you conclude:",
+            "",
+            "1. get_issue for what it is and how big it is.",
+            "2. get_issue_analytics for whether it is getting worse and which release it started in.",
+            "3. list_issue_events, then get_event on one — read the actual stack and breadcrumbs.",
+            "4. get_issue_timeline for what anybody has already worked out about it.",
+            "",
+            "Then explain what is failing and why, citing the file and line from the stack. If the evidence does not",
+            "support a cause, say that instead of picking the most likely one — a confident wrong answer here costs",
+            "more than no answer.",
+            "",
+            "Change nothing. No status, no severity, no comment, no run.",
+        ].join("\n"),
+    },
+];

package/dist/src/registry.d.ts

@@ -0,0 +1,86 @@
+import type { ZodRawShape, z } from "zod";
+import type { SnareClient } from "./client.js";
+import type { McpConfig } from "./config.js";
+import type { ApiScope } from "./scopes.js";
+import type { Toolset } from "./toolsets.js";
+/**
+ * What a tool is, in this package.
+ *
+ * A PLAIN OBJECT RATHER THAN A CALL TO THE SDK, so the catalogue can be
+ * inspected before anything is registered. That is what lets the tests assert
+ * things about all fifty at once — that every one names a real scope, sits in
+ * exactly one set, and carries the right annotations — rather than each tool
+ * being a side effect that happened during startup.
+ */
+/** Hints a client uses to decide whether to ask the human before calling. */
+export interface ToolAnnotations {
+    /** Reads and changes nothing. A client may auto-approve these. */
+    readOnlyHint?: boolean;
+    /** Not undone by calling the opposite tool. A client should ask. */
+    destructiveHint?: boolean;
+    /** Calling it twice has the same effect as once. */
+    idempotentHint?: boolean;
+    /** Reaches a hosted service rather than a closed world. True for all of these. */
+    openWorldHint?: boolean;
+}
+export interface ToolContext {
+    client: SnareClient;
+    config: McpConfig;
+}
+export interface ToolDef<Shape extends ZodRawShape = ZodRawShape> {
+    name: string;
+    /** A short human title for a client's tool list. */
+    title: string;
+    /**
+     * Written for a model deciding whether to call THIS one rather than the
+     * neighbour that sounds similar. With a catalogue this size the failure mode
+     * is never a missing tool, it is four plausible ones — so every description
+     * says when to reach for it instead of the others.
+     */
+    description: string;
+    scope: ApiScope;
+    toolset: Toolset;
+    input: Shape;
+    annotations: ToolAnnotations;
+    run(args: z.objectOutputType<Shape, z.ZodTypeAny>, context: ToolContext): Promise<string>;
+}
+/** Convenience for declaring a tool without losing the shape's inference. */
+export declare function tool<Shape extends ZodRawShape>(def: ToolDef<Shape>): ToolDef<ZodRawShape>;
+/**
+ * Which tools this caller actually gets.
+ *
+ * SET FIRST, THEN SCOPE. A tool the caller has not enabled is not theirs to see
+ * even if their token would allow it, and a tool their token cannot use is
+ * noise in every prompt for the rest of the session.
+ *
+ * HIDDEN, NOT DISABLED. A tool that is registered and then refuses is a control
+ * that cannot say why — the model calls it, gets a 403, and has no way to tell
+ * that from a transient failure. Leaving it out and naming the missing scope in
+ * the server's instructions gives the model something it can actually say to
+ * the person. This is CLAUDE.md's "a control nobody can use has to say why",
+ * applied to a machine reader.
+ */
+export declare function resolveTools(all: readonly ToolDef[], enabled: readonly Toolset[], granted: readonly string[]): ToolDef[];
+/** The scopes a caller would need to unlock everything they have enabled but cannot use. */
+export declare function missingScopes(all: readonly ToolDef[], enabled: readonly Toolset[], granted: readonly string[]): ApiScope[];
+/**
+ * Annotation defaults by name, so the whole catalogue cannot disagree with
+ * itself.
+ *
+ * A tool called `list_*`, `get_*` or `search_*` reads. Anything else does not.
+ * Stating it once here and asserting it in a test is what stops the fortieth
+ * tool being marked read-only because it was copied from the one above it.
+ */
+export declare function readOnly(): ToolAnnotations;
+/** Sets a value rather than appending one, and is safe to repeat. */
+export declare function idempotentWrite(): ToolAnnotations;
+/**
+ * Appends, spends money, or is visible to somebody else's team.
+ *
+ * Deliberately NOT idempotent even where the underlying call is: a client that
+ * auto-approves idempotent tools should stop at anything that costs a Snare or
+ * puts a sentence on a thread other people read.
+ */
+export declare function write(): ToolAnnotations;
+/** Not undone by calling the opposite tool. Four tools qualify. */
+export declare function destructive(): ToolAnnotations;

package/dist/src/registry.js

@@ -0,0 +1,62 @@
+import { tokenAllows } from "./scopes.js";
+/** Convenience for declaring a tool without losing the shape's inference. */
+export function tool(def) {
+    return def;
+}
+/**
+ * Which tools this caller actually gets.
+ *
+ * SET FIRST, THEN SCOPE. A tool the caller has not enabled is not theirs to see
+ * even if their token would allow it, and a tool their token cannot use is
+ * noise in every prompt for the rest of the session.
+ *
+ * HIDDEN, NOT DISABLED. A tool that is registered and then refuses is a control
+ * that cannot say why — the model calls it, gets a 403, and has no way to tell
+ * that from a transient failure. Leaving it out and naming the missing scope in
+ * the server's instructions gives the model something it can actually say to
+ * the person. This is CLAUDE.md's "a control nobody can use has to say why",
+ * applied to a machine reader.
+ */
+export function resolveTools(all, enabled, granted) {
+    const sets = new Set(enabled);
+    return all.filter((def) => sets.has(def.toolset) && tokenAllows(granted, def.scope));
+}
+/** The scopes a caller would need to unlock everything they have enabled but cannot use. */
+export function missingScopes(all, enabled, granted) {
+    const sets = new Set(enabled);
+    const missing = new Set();
+    for (const def of all) {
+        if (sets.has(def.toolset) && !tokenAllows(granted, def.scope))
+            missing.add(def.scope);
+    }
+    return [...missing].sort();
+}
+/**
+ * Annotation defaults by name, so the whole catalogue cannot disagree with
+ * itself.
+ *
+ * A tool called `list_*`, `get_*` or `search_*` reads. Anything else does not.
+ * Stating it once here and asserting it in a test is what stops the fortieth
+ * tool being marked read-only because it was copied from the one above it.
+ */
+export function readOnly() {
+    return { readOnlyHint: true, openWorldHint: true };
+}
+/** Sets a value rather than appending one, and is safe to repeat. */
+export function idempotentWrite() {
+    return { idempotentHint: true, openWorldHint: true };
+}
+/**
+ * Appends, spends money, or is visible to somebody else's team.
+ *
+ * Deliberately NOT idempotent even where the underlying call is: a client that
+ * auto-approves idempotent tools should stop at anything that costs a Snare or
+ * puts a sentence on a thread other people read.
+ */
+export function write() {
+    return { openWorldHint: true };
+}
+/** Not undone by calling the opposite tool. Four tools qualify. */
+export function destructive() {
+    return { destructiveHint: true, openWorldHint: true };
+}

package/dist/src/render.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The shapes the API returns, rendered for a model.
+ *
+ * TYPED LOOSELY ON PURPOSE. These mirror `/api/v1` responses, and duplicating
+ * the server's exact types here would be a second definition to keep in step
+ * for no benefit — nothing in this package constructs one, it only reads what
+ * came back. What matters is that every field this file names actually exists,
+ * which the real-client verification exercises end to end.
+ */
+export interface IssueSummary {
+    id: string;
+    key?: string | null;
+    title: string;
+    status: string;
+    severity: string | null;
+    projectId?: string;
+    projectName?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface IssueDetail extends IssueSummary {
+    key: string;
+    assignees: Array<{
+        id: string;
+        name: string | null;
+        email: string;
+    }>;
+    eventCount: number;
+    affectedUsers: number;
+    firstSeenAt: string | null;
+    lastSeenAt: string | null;
+    starred: boolean;
+    archived: boolean;
+    excluded: boolean;
+    problemSummary: string | null;
+    impactSummary: string | null;
+    latestRun: {
+        id: string;
+        mode: string;
+        status: string;
+        stage: string | null;
+        confidence: number | null;
+    } | null;
+    pullRequests: Array<{
+        url: string;
+        number: number;
+        summary: string;
+    }>;
+    url: string;
+}
+/**
+ * One issue on one line.
+ *
+ * THE KEY LEADS, because it is the name a person uses and the thing a caller
+ * will be given back. Severity next, because it is the first thing anybody
+ * sorts by. The title last, because it is the only variable-length part and a
+ * column of rows is only scannable if what precedes the ragged part is fixed.
+ */
+export declare function issueLine(issue: IssueSummary): string;
+export declare function issueList(issues: readonly IssueSummary[], total: number, scope: string): string;
+/** The whole detail card, in the order somebody asks the questions. */
+export declare function issueDetail(issue: IssueDetail): string;
+export interface SnareRun {
+    id: string;
+    issueId: string;
+    issueKey: string | null;
+    issueTitle: string;
+    mode: string;
+    origin: string;
+    status: string;
+    running: boolean;
+    stage: string | null;
+    stageIteration: number | null;
+    confidence: number | null;
+    costUsd: number | null;
+    filesTouched: string[];
+    haltReason: string | null;
+    escalationAction: string | null;
+    startedAt: string;
+    completedAt: string | null;
+    waitingOn: {
+        kind: "question" | "approval";
+        id: string;
+        prompt: string;
+    } | null;
+    pullRequest: {
+        url: string;
+        number: number;
+        summary: string;
+        status: string;
+    } | null;
+}
+/**
+ * A run, with the thing to do about it first.
+ *
+ * `waitingOn` IS RENDERED AT THE TOP AND AS AN INSTRUCTION, not as a field
+ * among fields. A run that has stopped to ask a question will otherwise sit
+ * there while an agent polls it, and the two facts that matter — that it is
+ * waiting, and which tool answers it — have to be impossible to skim past.
+ */
+export declare function snareRun(run: SnareRun): string;