@getsnare/mcp 0.1.0

package/dist/src/tools/workspace.js

@@ -0,0 +1,210 @@
+import { z } from "zod";
+import { DASH, bullets, clip, count, label, num, quantity, toolText, usd, when } from "../format.js";
+import { readOnly, tool } from "../registry.js";
+/**
+ * The workspace itself: projects, people, plan limits, and how things are going.
+ *
+ * NOT IN THE DEFAULT SET, and that is a judgement about attention rather than
+ * about value. Somebody debugging reaches for issues and runs on every turn;
+ * they ask what plan they are on roughly never, and a tool schema registered
+ * for that is schema the model reads on every turn instead.
+ */
+export const workspaceTools = [
+    tool({
+        name: "get_overview",
+        title: "How is the workspace doing",
+        description: "Four numbers: what is open and how severe, how many occurrences arrived recently, how many runs are going, " +
+            "and how many runs have STOPPED and need a person. The last one is the only one that is a task rather than " +
+            "a fact — start there.",
+        scope: "analytics:read",
+        toolset: "workspace",
+        input: {
+            projectId: z.string().optional(),
+            windowHours: z.number().int().min(1).max(720).optional().describe("For the occurrence count. Default 24."),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get("/overview", args);
+            const severities = Object.entries(data.bySeverity)
+                .map(([key, value]) => `${label(key)} ${value}`)
+                .join(", ");
+            return toolText(data.waiting > 0
+                ? `${quantity(data.waiting, "run")} stopped and waiting on a person. ${quantity(data.openIssues, "issue")} open.`
+                : `${quantity(data.openIssues, "issue")} open, nothing waiting on a person.`, `Open by severity: ${severities || DASH}`, `Occurrences in the last ${data.windowHours}h: ${data.recentEvents}`, `Runs going right now: ${data.runningSnares}`, `Projects: ${data.projects.map((project) => project.name).join(", ") || DASH}`);
+        },
+    }),
+    tool({
+        name: "list_projects",
+        title: "List projects",
+        description: "The projects this token can talk about, with the repository each one watches. Most other tools take a " +
+            "project id, and this is where to get one.",
+        scope: "projects:read",
+        toolset: "workspace",
+        input: {},
+        annotations: readOnly(),
+        async run(_args, { client }) {
+            const data = await client.get("/projects");
+            if (data.projects.length === 0)
+                return "No projects in this workspace yet.";
+            return toolText(count(data.projects.length, data.total, "project"), data.projects.map((project) => `${project.name}  ${project.repository ?? DASH}  project ${project.id}`).join("\n"));
+        },
+    }),
+    tool({
+        name: "get_project",
+        title: "Get a project's settings",
+        description: "The settings that change what you should DO: which repository and branch a fix lands on, whether a run " +
+            "opens a pull request or merges on its own, and which sources are wired up. It does not return the SDK key " +
+            "or any integration credential.",
+        scope: "projects:read",
+        toolset: "workspace",
+        input: { projectId: z.string() },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/projects/${encodeURIComponent(args.projectId)}`);
+            const project = data.project;
+            return toolText(project.name, `Repository: ${project.repository ?? DASH} (${project.branch})`, 
+            // Spelled out rather than left as an enum, because the difference
+            // between "opens a pull request" and "merges on its own" is the
+            // difference between a suggestion and a deployment.
+            `When a run finishes: ${project.autonomyMode === "AUTO_DEPLOY"
+                ? "it merges the fix itself"
+                : project.autonomyMode === "FLAG_ONLY"
+                    ? "it only flags the issue and changes nothing"
+                    : "it opens a pull request for somebody to review"}${project.autonomyMode === null ? " (the workspace default, nobody has chosen for this project)" : ""}`, `Wired up: ${project.integrations.map((row) => `${row.type} (${label(row.status)})`).join(", ") || "nothing yet"}`);
+        },
+    }),
+    tool({
+        name: "list_members",
+        title: "List workspace members",
+        description: "Who is in the Snare workspace, for assigning issues and knowing who to escalate to. These are NOT the " +
+            "customer's own users — for those, use list_affected_users.",
+        scope: "members:read",
+        // IN THE ISSUES SET, NOT THE WORKSPACE ONE, because `assign_issue` tells
+        // the model to call this and `assign_issue` is on by default. It was not,
+        // so an agent asked to assign an issue had nowhere to get a name from. It
+        // guessed two — the only name it had seen in a timeline, and the email of
+        // the person it was talking to — and both were refused. A tool that another
+        // default tool's own description points at has to be default too.
+        toolset: "issues",
+        input: {},
+        annotations: readOnly(),
+        async run(_args, { client }) {
+            const data = await client.get("/members");
+            return toolText(count(data.members.length, data.total, "member"), data.members
+                .map((person) => `${person.name ?? person.email}  ${person.email}${person.isOwner ? "  (owner)" : ""}`)
+                .join("\n"));
+        },
+    }),
+    tool({
+        name: "get_usage",
+        title: "What is left on the plan",
+        description: "How much of each allowance this workspace has used and how much is left. Worth checking before " +
+            "launch_snare or start_local_snare, both of which spend one — it is better to say 'you have two left' than " +
+            "to be refused and have to explain why. Note whether a meter overflows: running out either bills the next " +
+            "one or refuses it, and those are opposite outcomes.",
+        scope: "billing:read",
+        // WITH THE TOOLS THAT SPEND, for the same reason. Both `launch_snare`'s
+        // description and the server's own startup instructions tell the model to
+        // check this before spending a Snare, and neither could: it was in a set
+        // nobody turns on.
+        toolset: "snares",
+        input: {},
+        annotations: readOnly(),
+        async run(_args, { client }) {
+            const data = await client.get("/usage");
+            return toolText(
+            // A monthly allowance comes back; a trial's does not. Saying which one
+            // this is answers what somebody about to spend a Snare is asking.
+            data.window === "LIFETIME"
+                ? `On the ${label(data.plan)} plan. These allowances are a one-off grant and do not renew.`
+                : `On the ${label(data.plan)} plan. The allowances below reset ${when(data.periodEnd)}.`, bullets(
+            // What is LEFT comes first, because that is the number the decision
+            // turns on. Used-of-included follows as the detail behind it.
+            data.meters.map((meter) => meter.unlimited
+                ? `${meter.label}: no limit (${num(meter.used)} used)`
+                : `${meter.label}: ${num(meter.remaining)} left of ${num(meter.included)}` +
+                    (meter.overage > 0 ? `, ${num(meter.overage)} over the allowance` : "")), ""), data.overageUsd > 0 ? `Overage so far: ${usd(data.overageUsd)}` : null);
+        },
+    }),
+];
+export const setupTools = [
+    tool({
+        name: "get_sdk_install_prompt",
+        title: "Install the Snare SDK",
+        description: "The instructions for wiring Snare's SDK into a codebase, with this project's real key filled in. Follow " +
+            "them in the repository you have open. Covers every ecosystem Snare supports, so pick the one that matches " +
+            "what you are looking at rather than installing all of them.",
+        scope: "projects:keys",
+        toolset: "setup",
+        input: { projectId: z.string() },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/projects/${encodeURIComponent(args.projectId)}/install-prompt`);
+            return toolText(`Installation instructions for ${data.projectName}.`, data.note ?? null, data.prompt);
+        },
+    }),
+];
+export const feedbackTools = [
+    tool({
+        name: "list_feedback",
+        title: "List bug reports and feature requests",
+        description: "What the customer's own users have sent in, through the feedback widget or the public board. Bug reports " +
+            "can become issues; feature requests have votes and never do. Both come back tagged with `kind`. Spam is " +
+            "filtered out unless you ask for it.",
+        scope: "feedback:read",
+        toolset: "feedback",
+        input: {
+            projectId: z.string(),
+            kind: z.enum(["bug_report", "feature_request"]).optional(),
+            status: z.enum(["OPEN", "PLANNED", "SHIPPED", "DECLINED"]).optional().describe("Feature requests only."),
+            includeSpam: z.boolean().optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get("/feedback", args);
+            if (data.feedback.length === 0)
+                return "Nothing has been sent in for that project.";
+            return toolText(`${quantity(data.feedback.length, "item")}.`, data.feedback
+                .map((item) => item.kind === "feature_request"
+                ? `request  ${quantity(item.votes ?? 0, "vote")}  ${label(item.status ?? "OPEN")}  ${clip(item.title, 80)}  request ${item.id}`
+                : // The issue it was grouped into, by name, so somebody who reads a
+                    // bug report can go straight to the issue it became.
+                    `bug      ${item.issueKey ?? (item.issueId ? "grouped" : "ungrouped")}  ${clip(item.title, 80)}  report ${item.id}`)
+                .join("\n"));
+        },
+    }),
+    tool({
+        name: "get_feature_request",
+        title: "Get a feature request",
+        description: "One feature request in full: what was asked for, how many people voted for it, and where the team has put " +
+            "it. Use it before changing a status, so you can say what you are moving and why rather than acting on a " +
+            "line from a list.",
+        scope: "feedback:read",
+        toolset: "feedback",
+        input: { featureRequestId: z.string() },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/feature-requests/${encodeURIComponent(args.featureRequestId)}`);
+            const request = data.featureRequest;
+            return toolText(`${request.title} — ${label(request.status)}, ${quantity(request.votes, "vote")}`, request.description ?? "No description.", `Asked for ${when(request.createdAt)}.`);
+        },
+    }),
+    tool({
+        name: "update_feature_request_status",
+        title: "Move a feature request along",
+        description: "Set a feature request to open, planned, shipped or declined. Declining does not delete it — somebody asked " +
+            "for this and other people voted for it, and the board should show that the team read it and said no.",
+        scope: "feedback:write",
+        toolset: "feedback",
+        input: {
+            featureRequestId: z.string(),
+            status: z.enum(["OPEN", "PLANNED", "SHIPPED", "DECLINED"]),
+        },
+        annotations: { idempotentHint: true, openWorldHint: true },
+        async run(args, { client }) {
+            const data = await client.patch(`/feature-requests/${encodeURIComponent(args.featureRequestId)}`, { status: args.status });
+            return data.changed ? `Moved to ${label(data.status)}.` : `Already ${label(data.status)} — nothing changed.`;
+        },
+    }),
+];

package/dist/src/toolsets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Which tools a caller is shown.
+ *
+ * A DIFFERENT QUESTION FROM WHAT A TOKEN MAY DO, with a different answer.
+ * Scopes decide what is permitted; tool sets decide what is worth putting in
+ * front of the model. Every registered tool's name, description and input
+ * schema is text the model reads on every turn, so a catalogue of fifty tools
+ * costs real context on a conversation that was only ever going to call three
+ * of them.
+ *
+ * The default is four sets — the ones somebody debugging reaches for. The rest
+ * are there for callers who want them and cost nothing to the ones who do not.
+ */
+export declare const TOOLSETS: readonly ["issues", "events", "snares", "local", "feedback", "memory", "workspace", "setup"];
+export type Toolset = (typeof TOOLSETS)[number];
+/** One line each, for the message the server sends a client at startup. */
+export declare const TOOLSET_SUMMARY: Record<Toolset, string>;

package/dist/src/toolsets.js

@@ -0,0 +1,42 @@
+/**
+ * Which tools a caller is shown.
+ *
+ * A DIFFERENT QUESTION FROM WHAT A TOKEN MAY DO, with a different answer.
+ * Scopes decide what is permitted; tool sets decide what is worth putting in
+ * front of the model. Every registered tool's name, description and input
+ * schema is text the model reads on every turn, so a catalogue of fifty tools
+ * costs real context on a conversation that was only ever going to call three
+ * of them.
+ *
+ * The default is four sets — the ones somebody debugging reaches for. The rest
+ * are there for callers who want them and cost nothing to the ones who do not.
+ */
+export const TOOLSETS = [
+    /** Reading and changing issues. The core of it. */
+    "issues",
+    /** Occurrences, evidence, traces, replays and the people who hit them. */
+    "events",
+    /** Launching, watching, steering and stopping runs in the cloud. */
+    "snares",
+    /** Running a Snare on this machine, with the caller's own agent. */
+    "local",
+    /** Bug reports and feature requests from the customer's own users. */
+    "feedback",
+    /** Project rules, standing instructions and what Snare has learned. */
+    "memory",
+    /** Projects, people, plan limits, and how the workspace is doing. */
+    "workspace",
+    /** Installing the SDK. */
+    "setup",
+];
+/** One line each, for the message the server sends a client at startup. */
+export const TOOLSET_SUMMARY = {
+    issues: "read and change issues",
+    events: "occurrences, evidence, traces and affected users",
+    snares: "launch, watch, steer and stop fix runs",
+    local: "run a Snare here, on your own agent",
+    feedback: "bug reports and feature requests",
+    memory: "project rules, instructions and what Snare has learned",
+    workspace: "projects, people, plan limits and workspace health",
+    setup: "install the SDK",
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@getsnare/mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for Snare. Read and act on issues, events, traces and fix runs from any MCP client, and run a Snare on your own machine.",
+  "homepage": "https://snare.dev",
+  "license": "MIT",
+  "keywords": [
+    "snare",
+    "mcp",
+    "model-context-protocol",
+    "issue-tracking",
+    "ai-agent",
+    "claude",
+    "cursor"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "snare-mcp": "./dist/bin/snare-mcp.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@snare/types": "workspace:*",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.0"
+  }
+}