@rustrak/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2026 Abian Suarez
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+For the full license text, see: https://www.gnu.org/licenses/gpl-3.0.txt

package/README.md

@@ -0,0 +1,158 @@
+# @rustrak/mcp
+
+MCP (Model Context Protocol) server for Rustrak. Lets AI assistants (Claude Desktop, Cursor, etc.) manage your error tracking directly — list projects, inspect issues, view stack traces, resolve errors, and manage tokens without leaving your AI tool.
+
+## Features
+
+- **18 tools** covering projects, issues, events, tokens, and alert channels
+- **stdio transport** — runs as a local process, no network port needed
+- **Secure** — API token loaded from env vars, never passed as tool argument
+- **Safe destructive actions** — `delete_issue` and `revoke_token` annotated with `destructiveHint`
+- **Graceful errors** — all API errors returned as `isError: true` content, never thrown
+
+## Quick Start
+
+### 1. Generate an API token
+
+In the Rustrak web UI: **Settings → Tokens → Create token**. Save the full token value — it is shown only once.
+
+### 2. Configure in Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "rustrak": {
+      "command": "npx",
+      "args": ["-y", "@rustrak/mcp"],
+      "env": {
+        "RUSTRAK_API_URL": "https://your-rustrak-instance.example.com",
+        "RUSTRAK_API_TOKEN": "your-40-char-hex-token"
+      }
+    }
+  }
+}
+```
+
+### 3. Local monorepo (development)
+
+Build first, then configure with a `node` command pointing to the dist:
+
+```json
+{
+  "mcpServers": {
+    "rustrak": {
+      "command": "node",
+      "args": ["packages/mcp/dist/index.js"],
+      "env": {
+        "RUSTRAK_API_URL": "http://localhost:8080",
+        "RUSTRAK_API_TOKEN": "your-40-char-hex-token"
+      }
+    }
+  }
+}
+```
+
+Or use the project-level `.mcp.json` at the repo root (Claude Code picks this up automatically).
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `RUSTRAK_API_TOKEN` | ✅ | — | 40-char hex API token. Server exits if missing. |
+| `RUSTRAK_API_URL` | ✅ | — | Base URL of your Rustrak server. Server exits if missing. |
+
+## Available Tools
+
+### Projects
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all projects |
+| `get_project` | Get project details including DSN |
+| `create_project` | Create a new project |
+
+### Issues
+| Tool | Description |
+|------|-------------|
+| `list_issues` | List issues with filters (open / resolved / muted / all) |
+| `get_issue` | Get a single issue with full details |
+| `resolve_issue` | Mark an issue as resolved |
+| `unresolve_issue` | Re-open a resolved issue |
+| `mute_issue` | Mute an issue (silences alerts) |
+| `delete_issue` | ⚠️ Permanently delete an issue and all its events |
+
+### Events
+| Tool | Description |
+|------|-------------|
+| `list_events` | List raw events for an issue (cursor pagination) |
+| `get_event` | Get a single event with full Sentry envelope data |
+
+### Tokens
+| Tool | Description |
+|------|-------------|
+| `list_tokens` | List API tokens (masked) |
+| `create_token` | Create a new API token (full value shown once) |
+| `revoke_token` | ⚠️ Permanently revoke an API token |
+
+### Alerts
+| Tool | Description |
+|------|-------------|
+| `list_alert_channels` | List notification channels (Slack, email, webhook) |
+| `test_alert_channel` | Send a test notification to a channel |
+| `list_alert_rules` | List alert rules for a project |
+
+> ⚠️ Tools marked as destructive will prompt for confirmation in supported clients.
+
+## Example prompts
+
+Once connected, you can ask your AI assistant things like:
+
+- _"List all unresolved issues in project 1"_
+- _"Show me the stack trace for issue abc-123"_
+- _"Resolve all TypeError issues from the last deployment"_
+- _"Create a token called 'CI pipeline' and give me the value"_
+- _"How many events does issue xyz have?"_
+
+## Development
+
+```bash
+# Build
+pnpm --filter @rustrak/mcp build
+
+# Run tests (33 tests)
+pnpm --filter @rustrak/mcp test
+
+# Type check
+pnpm --filter @rustrak/mcp typecheck
+
+# Watch mode
+pnpm --filter @rustrak/mcp dev
+```
+
+## Architecture
+
+```
+AI Client (Claude Desktop / Cursor)
+        │  stdio (JSON-RPC)
+        ▼
+┌─────────────────────┐
+│   @rustrak/mcp      │
+│   McpServer         │
+│   ├── projects      │
+│   ├── issues        │
+│   ├── events        │
+│   ├── tokens        │
+│   └── alerts        │
+└──────────┬──────────┘
+           │  HTTP (Bearer token)
+           ▼
+┌─────────────────────┐
+│   Rustrak Server    │
+│   (Rust/Actix-web)  │
+└─────────────────────┘
+```
+
+## License
+
+GPL-3.0

package/dist/index.js

@@ -0,0 +1,459 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { RustrakClient } from "@rustrak/client";
+
+// src/config.ts
+function loadConfig() {
+  const url = process.env["RUSTRAK_API_URL"];
+  if (!url) {
+    console.error(
+      "[rustrak-mcp] Missing required environment variable: RUSTRAK_API_URL. Set RUSTRAK_API_URL to the base URL of your Rustrak server."
+    );
+    process.exit(1);
+  }
+  const token = process.env["RUSTRAK_API_TOKEN"];
+  if (!token) {
+    console.error(
+      "[rustrak-mcp] Missing required environment variable: RUSTRAK_API_TOKEN. Set RUSTRAK_API_TOKEN to a valid Rustrak API token."
+    );
+    process.exit(1);
+  }
+  return { RUSTRAK_API_URL: url, RUSTRAK_API_TOKEN: token };
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools/alerts.ts
+import { z } from "zod";
+
+// src/errors.ts
+import {
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError,
+  RustrakError
+} from "@rustrak/client";
+function mcpError(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+function toMcpError(err) {
+  if (err instanceof NotFoundError) {
+    return mcpError(`Not found: ${err.message}`);
+  }
+  if (err instanceof RateLimitError) {
+    const after = err.retryAfter !== void 0 ? err.retryAfter : "?";
+    return mcpError(`Rate limited. Retry after: ${after}s`);
+  }
+  if (err instanceof AuthenticationError) {
+    return mcpError("Authentication failed. Check RUSTRAK_API_TOKEN.");
+  }
+  if (err instanceof RustrakError) {
+    return mcpError(`API error: ${err.message}`);
+  }
+  return mcpError(`Unexpected error: ${String(err)}`);
+}
+
+// src/tools/alerts.ts
+function registerAlertTools(server2, client2) {
+  server2.registerTool(
+    "list_alert_channels",
+    {
+      description: "List all configured alert notification channels (Slack, email, webhook, etc.).",
+      inputSchema: {}
+    },
+    async () => {
+      try {
+        const result = await client2.alertChannels.list();
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "test_alert_channel",
+    {
+      description: "Send a test notification to an alert channel to verify it is configured correctly.",
+      inputSchema: {
+        channel_id: z.number().int().describe("Alert channel ID to test")
+      }
+    },
+    async ({ channel_id }) => {
+      try {
+        const result = await client2.alertChannels.test(channel_id);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "list_alert_rules",
+    {
+      description: "List all alert rules configured for a project.",
+      inputSchema: {
+        project_id: z.number().int().describe("Project ID")
+      }
+    },
+    async ({ project_id }) => {
+      try {
+        const result = await client2.alertRules.list(project_id);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+}
+
+// src/tools/events.ts
+import { z as z2 } from "zod";
+function registerEventTools(server2, client2) {
+  server2.registerTool(
+    "list_events",
+    {
+      description: "List raw events for a specific issue. Events are individual error occurrences within a grouped issue.",
+      inputSchema: {
+        project_id: z2.number().int().describe("Project ID"),
+        issue_id: z2.string().describe("Issue ID"),
+        cursor: z2.string().optional().describe("Pagination cursor"),
+        order: z2.enum(["asc", "desc"]).optional().describe("Sort order (default: desc)")
+      }
+    },
+    async ({ project_id, issue_id, cursor, order }) => {
+      try {
+        const result = await client2.events.list(project_id, issue_id, {
+          cursor,
+          order
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "get_event",
+    {
+      description: "Get full detail for a single event, including the complete Sentry envelope data.",
+      inputSchema: {
+        project_id: z2.number().int().describe("Project ID"),
+        issue_id: z2.string().describe("Issue ID"),
+        event_id: z2.string().describe("Event ID")
+      }
+    },
+    async ({ project_id, issue_id, event_id }) => {
+      try {
+        const result = await client2.events.get(project_id, issue_id, event_id);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+}
+
+// src/tools/issues.ts
+import { z as z3 } from "zod";
+function registerIssueTools(server2, client2) {
+  server2.registerTool(
+    "list_issues",
+    {
+      description: "List issues for a Rustrak project. Returns paginated grouped error occurrences.",
+      inputSchema: {
+        project_id: z3.number().int().describe("Project ID"),
+        page: z3.number().int().min(1).optional(),
+        per_page: z3.number().int().min(1).max(100).optional(),
+        filter: z3.enum(["open", "resolved", "muted", "all"]).optional().describe("Filter issues by state (default: open)")
+      }
+    },
+    async ({ project_id, page, per_page, filter }) => {
+      try {
+        const result = await client2.issues.list(project_id, {
+          page,
+          per_page,
+          filter
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "get_issue",
+    {
+      description: "Get a single issue by ID.",
+      inputSchema: {
+        project_id: z3.number().int().describe("Project ID"),
+        issue_id: z3.string().describe("Issue ID")
+      }
+    },
+    async ({ project_id, issue_id }) => {
+      try {
+        const result = await client2.issues.get(project_id, issue_id);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "resolve_issue",
+    {
+      description: "Mark an issue as resolved.",
+      inputSchema: {
+        project_id: z3.number().int().describe("Project ID"),
+        issue_id: z3.string().describe("Issue ID")
+      }
+    },
+    async ({ project_id, issue_id }) => {
+      try {
+        const result = await client2.issues.updateState(project_id, issue_id, {
+          is_resolved: true
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "unresolve_issue",
+    {
+      description: "Mark a resolved issue as unresolved (re-open it).",
+      inputSchema: {
+        project_id: z3.number().int().describe("Project ID"),
+        issue_id: z3.string().describe("Issue ID")
+      }
+    },
+    async ({ project_id, issue_id }) => {
+      try {
+        const result = await client2.issues.updateState(project_id, issue_id, {
+          is_resolved: false
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "mute_issue",
+    {
+      description: "Mute an issue so it no longer triggers alerts.",
+      inputSchema: {
+        project_id: z3.number().int().describe("Project ID"),
+        issue_id: z3.string().describe("Issue ID")
+      }
+    },
+    async ({ project_id, issue_id }) => {
+      try {
+        const result = await client2.issues.updateState(project_id, issue_id, {
+          is_muted: true
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "delete_issue",
+    {
+      description: "Permanently delete an issue and all its events.",
+      inputSchema: {
+        project_id: z3.number().int().describe("Project ID"),
+        issue_id: z3.string().describe("Issue ID")
+      },
+      annotations: { destructiveHint: true }
+    },
+    async ({ project_id, issue_id }) => {
+      try {
+        await client2.issues.delete(project_id, issue_id);
+        return {
+          content: [
+            { type: "text", text: `Issue ${issue_id} deleted successfully.` }
+          ]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+}
+
+// src/tools/projects.ts
+import { z as z4 } from "zod";
+function registerProjectTools(server2, client2) {
+  server2.registerTool(
+    "list_projects",
+    {
+      description: "List all Rustrak projects you have access to.",
+      inputSchema: {
+        page: z4.number().int().min(1).optional().describe("Page number"),
+        per_page: z4.number().int().min(1).max(100).optional().describe("Items per page")
+      }
+    },
+    async ({ page, per_page }) => {
+      try {
+        const result = await client2.projects.list({ page, per_page });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "get_project",
+    {
+      description: "Get details for a single Rustrak project.",
+      inputSchema: {
+        project_id: z4.number().int().describe("Project ID")
+      }
+    },
+    async ({ project_id }) => {
+      try {
+        const result = await client2.projects.get(project_id);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "create_project",
+    {
+      description: "Create a new Rustrak project.",
+      inputSchema: {
+        name: z4.string().min(1).describe("Project name"),
+        slug: z4.string().optional().describe("URL-safe slug (auto-generated if omitted)")
+      }
+    },
+    async ({ name, slug }) => {
+      try {
+        const result = await client2.projects.create({ name, slug });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+}
+
+// src/tools/tokens.ts
+import { z as z5 } from "zod";
+function registerTokenTools(server2, client2) {
+  server2.registerTool(
+    "list_tokens",
+    {
+      description: "List all API tokens. Token values are masked \u2014 only the prefix is shown.",
+      inputSchema: {}
+    },
+    async () => {
+      try {
+        const result = await client2.tokens.list();
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "create_token",
+    {
+      description: "Create a new API token. The full token value is returned ONCE \u2014 save it immediately.",
+      inputSchema: {
+        description: z5.string().min(1).describe("Human-readable label for this token")
+      }
+    },
+    async ({ description }) => {
+      try {
+        const result = await client2.tokens.create({ description });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+  server2.registerTool(
+    "revoke_token",
+    {
+      description: "Permanently revoke an API token. This action cannot be undone.",
+      inputSchema: {
+        token_id: z5.number().int().describe("Token ID to revoke")
+      },
+      annotations: { destructiveHint: true }
+    },
+    async ({ token_id }) => {
+      try {
+        await client2.tokens.delete(token_id);
+        return {
+          content: [
+            { type: "text", text: `Token ${token_id} revoked successfully.` }
+          ]
+        };
+      } catch (err) {
+        return toMcpError(err);
+      }
+    }
+  );
+}
+
+// src/server.ts
+function createServer(client2) {
+  const server2 = new McpServer({
+    name: "rustrak-mcp",
+    version: "0.1.0"
+  });
+  registerProjectTools(server2, client2);
+  registerIssueTools(server2, client2);
+  registerEventTools(server2, client2);
+  registerTokenTools(server2, client2);
+  registerAlertTools(server2, client2);
+  return server2;
+}
+
+// src/index.ts
+var config = loadConfig();
+var client = new RustrakClient({
+  baseUrl: config.RUSTRAK_API_URL,
+  token: config.RUSTRAK_API_TOKEN
+});
+var server = createServer(client);
+var transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[rustrak-mcp] Server started");

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@rustrak/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Rustrak error tracking — wraps @rustrak/client",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "rustrak-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "rustrak",
+    "mcp",
+    "model-context-protocol",
+    "error-tracking",
+    "claude"
+  ],
+  "license": "GPL-3.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "4.4.3",
+    "@rustrak/client": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "25.8.0",
+    "tsup": "8.5.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.6"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}