@getsnare/mcp 0.1.0

package/dist/src/render.js

@@ -0,0 +1,111 @@
+import { DASH, bullets, clip, count, facts, label, percent, usd, when } from "./format.js";
+/**
+ * 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 function issueLine(issue) {
+    const key = issue.key ?? issue.id;
+    const severity = issue.severity ? label(issue.severity) : DASH;
+    return `${key}  ${severity}  ${label(issue.status)}  ${clip(issue.title, 100)}`;
+}
+export function issueList(issues, total, scope) {
+    if (issues.length === 0) {
+        // Names the scope that produced it, because the scope is the thing the
+        // reader can change. "No issues" is a fact about the filter as often as it
+        // is a fact about the workspace.
+        return `No issues ${scope}.`;
+    }
+    return `${count(issues.length, total, "issue")} ${scope}\n\n${issues.map(issueLine).join("\n")}`;
+}
+/** The whole detail card, in the order somebody asks the questions. */
+export function issueDetail(issue) {
+    const people = issue.assignees.length === 0
+        ? DASH
+        : issue.assignees.map((person) => person.name ?? person.email).join(", ");
+    const run = issue.latestRun
+        ? `${label(issue.latestRun.mode)} run, ${label(issue.latestRun.status)}` +
+            (issue.latestRun.stage ? ` at ${label(issue.latestRun.stage)}` : "") +
+            (issue.latestRun.confidence !== null ? `, confidence ${percent(issue.latestRun.confidence)}` : "")
+        : DASH;
+    const state = [
+        issue.excluded ? "in the exclusion zone" : null,
+        issue.archived ? "archived" : null,
+        issue.starred ? "starred" : null,
+    ].filter(Boolean);
+    return [
+        `${issue.key}  ${issue.title}`,
+        "",
+        facts([
+            ["Severity", issue.severity ? label(issue.severity) : null],
+            ["Status", label(issue.status)],
+            ["Assigned to", people],
+            ["Events", issue.eventCount],
+            ["Affected users", issue.affectedUsers],
+            ["First seen", when(issue.firstSeenAt)],
+            ["Last seen", when(issue.lastSeenAt)],
+            ["Project", issue.projectName ?? issue.projectId ?? null],
+            ["Latest run", run],
+            ["Also", state.length > 0 ? state.join(", ") : null],
+            ["Link", issue.url],
+        ]),
+        issue.problemSummary ? `\nWhat is happening\n${issue.problemSummary}` : "",
+        issue.impactSummary ? `\nWho it affects\n${issue.impactSummary}` : "",
+        issue.pullRequests.length > 0
+            ? `\nPull requests\n${bullets(issue.pullRequests.map((pr) => `#${pr.number} ${clip(pr.summary, 80)} — ${pr.url}`), "")}`
+            : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+/**
+ * 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 function snareRun(run) {
+    const heading = run.waitingOn
+        ? run.waitingOn.kind === "question"
+            ? `WAITING FOR AN ANSWER. Snare asked: "${run.waitingOn.prompt}"\nAnswer it with answer_snare_question (id ${run.waitingOn.id}), or it will proceed on its own default.`
+            : `WAITING FOR APPROVAL to ${run.waitingOn.prompt}\nDecide it with decide_snare_approval (id ${run.waitingOn.id}), or it will proceed without.`
+        : run.running
+            ? `Running${run.stage ? `, at ${label(run.stage)}` : ""}.`
+            : `Finished: ${label(run.status)}.`;
+    return [
+        heading,
+        "",
+        facts([
+            ["Run", run.id],
+            ["Issue", `${run.issueTitle} (${run.issueKey ?? run.issueId})`],
+            ["Mode", label(run.mode)],
+            // Said plainly, because the cost below means something different for each
+            // and a reader seeing a near-zero figure on a local run would otherwise
+            // conclude the run was free rather than that it was theirs to pay for.
+            ["Ran", run.origin === "LOCAL" ? "on this machine" : "in Snare's cloud"],
+            ["Stage", run.stage ? `${label(run.stage)}${run.stageIteration ? ` (pass ${run.stageIteration})` : ""}` : null],
+            ["Confidence", run.confidence !== null ? percent(run.confidence) : null],
+            [
+                run.origin === "LOCAL" ? "Snare's own cost" : "Cost",
+                run.costUsd !== null ? usd(run.costUsd) : null,
+            ],
+            ["Started", when(run.startedAt)],
+            ["Finished", when(run.completedAt)],
+            ["Stopped because", run.haltReason],
+            ["Needs a person to", run.escalationAction],
+        ]),
+        run.filesTouched.length > 0
+            ? `\nFiles changed\n${bullets(run.filesTouched, "")}`
+            : "",
+        run.pullRequest
+            ? `\nPull request\n#${run.pullRequest.number} (${label(run.pullRequest.status)}) ${run.pullRequest.url}\n${clip(run.pullRequest.summary, 300)}`
+            : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}

package/dist/src/scopes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What a token is allowed to do — a copy, kept honest by a test.
+ *
+ * WHY A COPY. This package is published to npm and installed on customers'
+ * machines. `@snare/types` is a private workspace package, so importing it here
+ * would either break `npm install` or force a bundler into a repo that has
+ * deliberately never had one. Everything else in this package obeys the same
+ * rule: `@modelcontextprotocol/sdk` and `zod` are the only runtime
+ * dependencies, and nothing here can reach a database.
+ *
+ * WHY THE COPY IS SAFE. `scopes-parity.test.ts` imports both this list and the
+ * canonical one and asserts they are identical, in order. That test runs in the
+ * monorepo and never ships, so drift is a failed build rather than a token that
+ * silently loses a capability.
+ */
+export declare const API_SCOPES: readonly ["issues:read", "issues:write", "issues:comment", "issues:assign", "issues:group", "issues:delete", "projects:read", "projects:memory", "projects:keys", "analytics:read", "snares:read", "snares:launch", "snares:respond", "snares:local", "feedback:read", "feedback:write", "members:read", "billing:read", "reports:write", "releases:write"];
+export type ApiScope = (typeof API_SCOPES)[number];
+/** Exact match, no hierarchy — the same rule the server enforces. */
+export declare function tokenAllows(scopes: readonly string[], required: ApiScope): boolean;
+export declare function isApiScope(value: string): value is ApiScope;

package/dist/src/scopes.js

@@ -0,0 +1,44 @@
+/**
+ * What a token is allowed to do — a copy, kept honest by a test.
+ *
+ * WHY A COPY. This package is published to npm and installed on customers'
+ * machines. `@snare/types` is a private workspace package, so importing it here
+ * would either break `npm install` or force a bundler into a repo that has
+ * deliberately never had one. Everything else in this package obeys the same
+ * rule: `@modelcontextprotocol/sdk` and `zod` are the only runtime
+ * dependencies, and nothing here can reach a database.
+ *
+ * WHY THE COPY IS SAFE. `scopes-parity.test.ts` imports both this list and the
+ * canonical one and asserts they are identical, in order. That test runs in the
+ * monorepo and never ships, so drift is a failed build rather than a token that
+ * silently loses a capability.
+ */
+export const API_SCOPES = [
+    "issues:read",
+    "issues:write",
+    "issues:comment",
+    "issues:assign",
+    "issues:group",
+    "issues:delete",
+    "projects:read",
+    "projects:memory",
+    "projects:keys",
+    "analytics:read",
+    "snares:read",
+    "snares:launch",
+    "snares:respond",
+    "snares:local",
+    "feedback:read",
+    "feedback:write",
+    "members:read",
+    "billing:read",
+    "reports:write",
+    "releases:write",
+];
+/** Exact match, no hierarchy — the same rule the server enforces. */
+export function tokenAllows(scopes, required) {
+    return scopes.includes(required);
+}
+export function isApiScope(value) {
+    return API_SCOPES.includes(value);
+}

package/dist/src/server.d.ts

@@ -0,0 +1,44 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpConfig } from "./config.js";
+/** What the token turned out to be, learned once at startup. */
+export interface Identity {
+    scopes: string[];
+    organization: {
+        id: string;
+        name: string;
+        slug: string;
+        plan: string;
+    } | null;
+}
+/**
+ * Why the server could not be built.
+ *
+ * TWO CAUSES THAT NEED DIFFERENT ANSWERS. `token` means the credential is bad
+ * and the person has to make a new one. `unreachable` means Snare could not be
+ * called at all, which is a server-side problem and one the caller should
+ * retry. The remote transport used to answer 401 for both, on the reasoning
+ * that neither is retryable — which is exactly backwards for the second, and a
+ * 401 makes an MCP client prompt for re-authentication that can never help.
+ */
+export declare class SnareStartupError extends Error {
+    readonly reason: "token" | "unreachable";
+    constructor(reason: "token" | "unreachable", message: string);
+}
+/**
+ * Builds the server this token should see.
+ *
+ * IT ASKS THE API WHO IT IS FIRST. That one call is what makes the catalogue
+ * honest: a tool whose scope the token lacks is never registered, so the model
+ * never chooses it, never gets a 403 back, and never has to guess whether that
+ * 403 was permanent or a blip. The alternative — register everything and refuse
+ * at call time — is a control that cannot say why.
+ *
+ * A FAILURE HERE IS FATAL AND SAYS SO. If the token is bad or the API is
+ * unreachable, there is no useful degraded mode: a server with no tools is
+ * indistinguishable from a broken client, and the person is better served by
+ * one clear line on stderr.
+ */
+export declare function createSnareMcpServer(config: McpConfig, fetchImpl?: typeof globalThis.fetch): Promise<{
+    server: McpServer;
+    identity: Identity;
+}>;

package/dist/src/server.js

@@ -0,0 +1,241 @@
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SnareApiError, SnareClient } from "./client.js";
+import { label } from "./format.js";
+import { PROMPTS } from "./prompts.js";
+import { missingScopes, resolveTools } from "./registry.js";
+import { TOOLSET_SUMMARY, TOOLSETS } from "./toolsets.js";
+import { ALL_TOOLS } from "./tools/index.js";
+/**
+ * Why the server could not be built.
+ *
+ * TWO CAUSES THAT NEED DIFFERENT ANSWERS. `token` means the credential is bad
+ * and the person has to make a new one. `unreachable` means Snare could not be
+ * called at all, which is a server-side problem and one the caller should
+ * retry. The remote transport used to answer 401 for both, on the reasoning
+ * that neither is retryable — which is exactly backwards for the second, and a
+ * 401 makes an MCP client prompt for re-authentication that can never help.
+ */
+export class SnareStartupError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "SnareStartupError";
+    }
+}
+/**
+ * Builds the server this token should see.
+ *
+ * IT ASKS THE API WHO IT IS FIRST. That one call is what makes the catalogue
+ * honest: a tool whose scope the token lacks is never registered, so the model
+ * never chooses it, never gets a 403 back, and never has to guess whether that
+ * 403 was permanent or a blip. The alternative — register everything and refuse
+ * at call time — is a control that cannot say why.
+ *
+ * A FAILURE HERE IS FATAL AND SAYS SO. If the token is bad or the API is
+ * unreachable, there is no useful degraded mode: a server with no tools is
+ * indistinguishable from a broken client, and the person is better served by
+ * one clear line on stderr.
+ */
+export async function createSnareMcpServer(config, fetchImpl) {
+    const client = new SnareClient(config, fetchImpl);
+    let identity;
+    try {
+        identity = await client.get("/me");
+    }
+    catch (err) {
+        if (err instanceof SnareApiError && err.status === 401) {
+            throw new SnareStartupError("token", "Snare rejected that token. Check SNARE_API_TOKEN, or make a new one at " +
+                `${config.dashboardUrl}/settings/api-tokens.`);
+        }
+        // The underlying message only when it adds something. The client's own
+        // wording for a dead socket is "Could not reach Snare.", so appending it
+        // here printed that sentence twice in a row on the one failure a person is
+        // most likely to hit — a wrong address in their config.
+        const detail = err instanceof Error ? err.message : "";
+        const adds = detail && !detail.startsWith("Could not reach Snare");
+        throw new SnareStartupError("unreachable", `Could not reach Snare at ${config.baseUrl}.${adds ? ` ${detail}` : ""} Check SNARE_BASE_URL, or try again.`);
+    }
+    const tools = resolveTools(ALL_TOOLS, config.toolsets, identity.scopes);
+    const missing = missingScopes(ALL_TOOLS, config.toolsets, identity.scopes);
+    const server = new McpServer({ name: "snare", version: "0.1.0" }, { instructions: instructionsFor(identity, config, tools.length, missing) });
+    for (const def of tools) {
+        server.registerTool(def.name, {
+            title: def.title,
+            description: def.description,
+            inputSchema: def.input,
+            annotations: def.annotations,
+        }, 
+        // Cast because each tool declares its own shape and the SDK's callback
+        // type is generic over one shape at a time. The shape is enforced by the
+        // SDK before this runs, so the argument really is what the tool declared.
+        (async (args) => {
+            try {
+                const text = await def.run(args, { client, config });
+                return { content: [{ type: "text", text }] };
+            }
+            catch (err) {
+                // The server's own sentence, marked as an error so the model treats
+                // it as a failed call rather than as content. Routes are written to
+                // be read — a missing scope names the scope, a conflict says what is
+                // in the way — so replacing this with a generic message would throw
+                // away the only useful part.
+                const message = err instanceof SnareApiError
+                    ? err.message
+                    : err instanceof Error
+                        ? err.message
+                        : "Something went wrong.";
+                return { content: [{ type: "text", text: message }], isError: true };
+            }
+        }));
+    }
+    for (const prompt of PROMPTS) {
+        server.registerPrompt(prompt.name, {
+            title: prompt.title,
+            description: prompt.description,
+            argsSchema: prompt.argsSchema,
+        }, ((args) => ({
+            messages: [
+                {
+                    role: "user",
+                    content: { type: "text", text: prompt.render(args ?? {}) },
+                },
+            ],
+        })));
+    }
+    registerResources(server, client, identity.scopes);
+    return { server, identity };
+}
+/** How many issues the resource listing offers. See `registerResources`. */
+const LISTED_ISSUES = 20;
+/**
+ * An addressable issue, so a client that lets somebody attach context by URI
+ * can reach the thing people paste links to.
+ *
+ * A `ResourceTemplate`, NOT the template string. `registerResource` has two
+ * overloads and they differ by exactly this: given a string it registers a
+ * FIXED resource at that literal URI, so passing `"snare://issue/{key}"`
+ * published a resource whose address was those characters, braces included.
+ * Nothing matched `snare://issue/ACME-142`, and reading the one that was
+ * published asked the API for an issue called `{key}`. It typechecked, it
+ * connected, and the stdio verification passed, because that pass only ever
+ * looked at tools and prompts. It looks at resources now.
+ *
+ * IT LISTS A HANDFUL, AND THAT IS NOT DECORATION. `list` was `undefined` on
+ * the reasoning that the set is every issue in the workspace and a listing
+ * would be a second unpaginated `list_issues` on connect. What that overlooked
+ * is where a template is published: `resources/templates/list`, a different
+ * call from `resources/list`. A client that only makes the second one — Claude
+ * Code is one — shows "No resources found", so the resource existed and
+ * nothing could discover it. Watched live: reading `snare://issue/ACME-1`
+ * worked while listing resources returned zero.
+ *
+ * So it lists the twenty most recent issues, which is one bounded call to the
+ * same route `list_issues` uses, and keeps the template for every other key.
+ * Twenty is an entry point rather than an inventory: a client that wants the
+ * rest has a tool for it, and a workspace with four thousand issues must not
+ * turn a connect into a four-thousand-row fetch.
+ *
+ * A FAILED LISTING IS AN EMPTY LISTING. This runs whenever a client feels like
+ * it, including at connect, and a workspace that cannot be read right now is
+ * not a reason to fail the whole connection.
+ *
+ * Deliberately thin: it returns what `get_issue` returns. A resource that
+ * answered differently from the tool covering the same thing would be a second
+ * source of truth for no benefit.
+ *
+ * NOT REGISTERED AT ALL WITHOUT `issues:read`, for the same reason a tool whose
+ * scope is missing is never registered: a resource that is advertised and then
+ * refuses is a control that cannot say why.
+ */
+function registerResources(server, client, scopes) {
+    if (!scopes.includes("issues:read"))
+        return;
+    server.registerResource("issue", new ResourceTemplate("snare://issue/{key}", {
+        list: async () => {
+            try {
+                const data = await client.get("/issues", { limit: LISTED_ISSUES });
+                return {
+                    resources: data.issues
+                        // An issue with no key cannot be addressed, so it is not offered.
+                        .filter((issue) => Boolean(issue.key))
+                        .map((issue) => ({
+                        uri: `snare://issue/${issue.key}`,
+                        name: `${issue.key} ${issue.title}`,
+                        description: `${label(issue.status)}${issue.severity ? `, ${label(issue.severity)} severity` : ""}.`,
+                        mimeType: "application/json",
+                    })),
+                };
+            }
+            catch {
+                return { resources: [] };
+            }
+        },
+    }), {
+        title: "Snare issue",
+        description: "One issue by its key, like snare://issue/ACME-142.",
+        mimeType: "application/json",
+    }, (async (uri, variables) => {
+        const raw = variables.key;
+        const key = Array.isArray(raw) ? raw[0] : raw;
+        if (!key)
+            throw new Error("That URI names no issue. Use snare://issue/ACME-142.");
+        const data = await client.get(`/issues/${encodeURIComponent(key)}`);
+        return {
+            contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(data, null, 2) }],
+        };
+    }));
+}
+/**
+ * What the client is told about this server before anything is called.
+ *
+ * NAMES WHAT IS MISSING. A model that expected a tool and cannot find it will
+ * otherwise say "Snare does not support that", which is wrong and unhelpful.
+ * Told which scope is absent, it can say "this token cannot change issues; add
+ * issues:write to it" — which is the actual answer.
+ *
+ * IT ALSO SAYS WHAT THE RESOURCE LIST IS NOT. That list is the twenty most
+ * recent issues, and a client shows it without saying so, which reads as the
+ * whole workspace. A model that believes it has seen every issue will answer
+ * questions about the set from twenty rows. One sentence here is the difference
+ * between an entry point and a wrong answer.
+ */
+function instructionsFor(identity, config, toolCount, missing) {
+    const org = identity.organization;
+    const sets = config.toolsets.map((set) => `${set} (${TOOLSET_SUMMARY[set]})`).join(", ");
+    const off = TOOLSETS.filter((set) => !config.toolsets.includes(set)).map((set) => `${set} (${TOOLSET_SUMMARY[set]})`);
+    return [
+        `Snare${org ? ` — the ${org.name} workspace` : ""}.`,
+        "",
+        "Snare tracks ISSUES. One occurrence of an issue is an EVENT; the set of events sharing an id is a TRACE.",
+        "Use those words rather than calling any of them an error.",
+        "",
+        `${toolCount} tools available, from these sets: ${sets}.`,
+        // NAMING WHAT IS OFF, because a model cannot tell "Snare does not do this"
+        // from "this set is not switched on", and will say the first. Asked what
+        // people were requesting, an agent answered "there is no feature-request or
+        // voting surface in Snare" — a false statement about the product, made
+        // confidently, because the feedback set was off and nothing said so.
+        ...(off.length > 0
+            ? [
+                `Switched off, but Snare HAS them: ${off.join(", ")}. If somebody asks for one of these, say it needs ` +
+                    `turning on rather than that Snare cannot do it — SNARE_MCP_TOOLSETS=all, or add the set by name.`,
+            ]
+            : []),
+        missing.length > 0
+            ? `Some tools are hidden because this token lacks: ${missing.join(", ")}. If somebody asks for something ` +
+                `you cannot do, name the scope rather than saying Snare cannot do it. Tokens are managed at ` +
+                `${config.dashboardUrl}/settings/api-tokens.`
+            : "This token has every scope the enabled sets need.",
+        "",
+        ...(identity.scopes.includes("issues:read")
+            ? [
+                `The resource list holds the ${LISTED_ISSUES} most recent issues, not all of them. Use list_issues or ` +
+                    "search_issues to reach the rest, and snare://issue/<key> to address any one.",
+                "",
+            ]
+            : []),
+        "Two tools spend money from the workspace's plan: launch_snare and start_local_snare. Say so before calling",
+        "either, and check get_usage if you are unsure there is allowance left.",
+    ].join("\n");
+}

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

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