@rui.branco/sentry-mcp 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,219 @@
+# Sentry MCP Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that brings Sentry error tracking context directly into Claude Code. Fetch issues, inspect stack traces, manage issue status, and search errors without leaving your development environment.
+
+## Overview
+
+When debugging production errors, context switching between Sentry and your code editor breaks flow and wastes time. This MCP server solves that by:
+
+- **Fetching full issue details** - Get error metadata, event counts, assignment, and status instantly
+- **Inspecting stack traces** - View full stack traces with in-app frame markers, breadcrumbs, and HTTP request context
+- **Managing issues** - Resolve, reopen, ignore, and assign issues directly from Claude Code
+- **Searching errors** - Use Sentry's search syntax to find issues across your project
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| Issue Details | Title, level, status, event count, user count, culprit, assignee |
+| Stack Traces | Full exception chain with in-app frames highlighted |
+| Breadcrumbs | Last N events leading up to the error |
+| HTTP Request | Method, URL, headers from the request that triggered the error |
+| Tags & Contexts | Device, browser, OS, user info, and custom tags |
+| Search | Full Sentry search syntax support |
+| Multi-Instance | Support for multiple Sentry organizations/instances |
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+
+- [Claude Code](https://claude.ai/code) CLI
+- Sentry account with API access
+
+### Step 1: Add to Claude Code
+
+```bash
+claude mcp add --transport stdio sentry -- npx -y @rui.branco/sentry-mcp
+```
+
+### Step 2: Get Your Sentry API Token
+
+1. Go to [Sentry Auth Tokens](https://sentry.io/settings/account/api/auth-tokens/) (or your self-hosted Sentry equivalent)
+2. Click **"Create New Token"**
+3. Select scopes: `event:read`, `project:read`, `org:read`, `member:read`
+4. Click **"Create Token"**
+5. Copy the token
+
+### Step 3: Configure Credentials
+
+Run the setup with your credentials:
+
+```bash
+npx @rui.branco/sentry-mcp setup "YOUR_AUTH_TOKEN" "https://sentry.io" "your-org-slug" "your-project-slug"
+```
+
+| Parameter | Description | Example |
+|-----------|-------------|---------|
+| Auth Token | The token you created in Step 2 | `sntrys_eyJpYX...` |
+| Base URL | Your Sentry instance URL | `https://sentry.io` or `https://my-org.sentry.io` |
+| Org Slug | Your Sentry organization slug | `my-company` |
+| Project Slug | Default project slug (optional) | `frontend` |
+
+Or run interactively (will prompt for each value):
+
+```bash
+npx @rui.branco/sentry-mcp setup
+```
+
+### Step 4: Verify
+
+Restart Claude Code and run `/mcp` to verify the server is connected.
+
+### Alternative: Manual Installation
+
+If you prefer to install manually:
+
+```bash
+git clone https://github.com/rui-branco/sentry-mcp.git ~/.config/sentry-mcp
+cd ~/.config/sentry-mcp && npm install
+node setup.js
+```
+
+Then add to Claude Code:
+
+```bash
+claude mcp add --transport stdio sentry -- node $HOME/.config/sentry-mcp/index.js
+```
+
+## Usage
+
+### List Issues
+
+```
+> Show me unresolved Sentry issues
+
+# Returns all unresolved issues with metadata
+```
+
+### Inspect an Error
+
+```
+> Get the latest event for Sentry issue 12345
+
+# Returns full stack trace, breadcrumbs, HTTP request, tags, and contexts
+```
+
+### Resolve After Fixing
+
+```
+> Resolve Sentry issue 12345
+
+# Marks the issue as resolved in Sentry
+```
+
+### Search Issues
+
+```
+> Search Sentry for "TypeError" errors in the last 24 hours
+
+# Uses Sentry search: is:unresolved TypeError lastSeen:-24h
+```
+
+### Example Output
+
+```
+## Stack Trace
+
+**TypeError:** Cannot read properties of undefined (reading 'map')
+
+```
+-> renderItems (src/components/List.tsx:42:15)
+-> List (src/components/List.tsx:28:3)
+   React.createElement (react-dom.js:1234)
+```
+
+## Breadcrumbs (last 5)
+
+- **navigation** [info] /dashboard -> /items
+- **http** [info] GET /api/items (200)
+- **ui.click** [info] button.load-more
+- **http** [error] GET /api/items?page=2 (500)
+- **console** [error] Unhandled error in component
+
+## HTTP Request
+
+`GET /api/items?page=2`
+```
+
+## Multi-Instance Setup
+
+For multiple Sentry organizations, add instances via setup:
+
+```bash
+npx @rui.branco/sentry-mcp setup add "work" "TOKEN_1" "https://sentry.io" "work-org" "work-project"
+npx @rui.branco/sentry-mcp setup add "personal" "TOKEN_2" "https://sentry.io" "personal-org" "side-project"
+```
+
+Or via MCP tool at runtime:
+
+```
+> Add a new Sentry instance called "work" with org "my-company"
+```
+
+Use the `instance` parameter on any tool to target a specific instance, or omit it to use the default.
+
+## API Reference
+
+### Tools
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `sentry_list_projects` | List all Sentry projects accessible by the token | `instance` |
+| `sentry_get_issues` | Get unresolved issues for the configured project | `query`, `instance` |
+| `sentry_get_issue` | Get full details for a specific issue | `issueId` (required), `instance` |
+| `sentry_get_latest_event` | Get latest event with stack trace, breadcrumbs, HTTP request | `issueId` (required), `instance` |
+| `sentry_resolve_issue` | Mark an issue as resolved | `issueId` (required), `instance` |
+| `sentry_unresolve_issue` | Reopen a resolved issue | `issueId` (required), `instance` |
+| `sentry_ignore_issue` | Ignore/snooze an issue | `issueId` (required), `instance` |
+| `sentry_search_issues` | Search with custom Sentry query | `query` (required), `instance` |
+| `sentry_assign_issue` | Assign an issue to a user or team | `issueId` (required), `assignee` (required), `instance` |
+| `sentry_list_instances` | List all configured instances | none |
+| `sentry_add_instance` | Add or update an instance at runtime | `name`, `token`, `baseUrl`, `orgSlug` (all required), `projectSlug`, `projects`, `setDefault` |
+| `sentry_remove_instance` | Remove an instance | `name` (required) |
+
+### Configuration
+
+Config stored at `~/.config/sentry-mcp/config.json`:
+
+```json
+{
+  "instances": [
+    {
+      "name": "work",
+      "token": "YOUR_AUTH_TOKEN",
+      "baseUrl": "https://sentry.io",
+      "orgSlug": "my-company",
+      "projectSlug": "frontend",
+      "projects": ["frontend", "backend"]
+    }
+  ],
+  "defaultInstance": "work"
+}
+```
+
+## Security
+
+- API tokens are stored locally in `~/.config/sentry-mcp/config.json`
+- Config files are excluded from git via `.gitignore`
+- Tokens are never logged or transmitted except to the Sentry API
+
+## License
+
+MIT
+
+## Related
+
+- [jira-mcp](https://github.com/rui-branco/jira-mcp) - Jira MCP server for Claude Code
+- [figma-mcp](https://github.com/rui-branco/figma-mcp) - Figma MCP server for Claude Code
+- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification

package/index.js

@@ -156,7 +156,26 @@ async function fetchSentry(apiPath, instance, options = {}) {
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
-function formatIssue(issue) {
+// Strip noisy/internal fields that waste context but keep everything useful
+function cleanIssueData(issue) {
+  const skip = new Set(["pluginActions", "pluginContexts", "pluginIssues", "activity", "seenBy", "stats"]);
+  const cleaned = {};
+  for (const [k, v] of Object.entries(issue)) {
+    if (!skip.has(k) && v != null && v !== "") cleaned[k] = v;
+  }
+  return cleaned;
+}
+
+function cleanEventData(event) {
+  const skip = new Set(["_meta", "groupID", "eventID", "sdk", "dist", "fingerprints"]);
+  const cleaned = {};
+  for (const [k, v] of Object.entries(event)) {
+    if (!skip.has(k) && v != null && v !== "") cleaned[k] = v;
+  }
+  return cleaned;
+}
+
+function formatIssueSummary(issue) {
   const meta = issue.metadata || {};
   const lines = [];
   lines.push(`**${issue.title}**`);
@@ -175,98 +194,6 @@ function formatIssue(issue) {
   return lines.join("\n");
 }
 
-function formatEvent(event) {
-  const lines = [];
-
-  // Stack traces
-  const exceptions =
-    event.entries?.find((e) => e.type === "exception")?.data?.values || [];
-  if (exceptions.length) {
-    lines.push("## Stack Trace\n");
-    for (const ex of exceptions) {
-      if (ex.type || ex.value) lines.push(`**${ex.type || "Exception"}:** ${ex.value || ""}\n`);
-      const frames = ex.stacktrace?.frames;
-      if (frames?.length) {
-        lines.push("```");
-        for (const f of frames) {
-          const loc = f.lineNo ? `:${f.lineNo}${f.colNo ? ":" + f.colNo : ""}` : "";
-          const marker = f.inApp ? "-> " : "   ";
-          lines.push(`${marker}${f.function || "?"} (${f.filename || "?"}${loc})`);
-        }
-        lines.push("```\n");
-      }
-    }
-  }
-
-  // Breadcrumbs
-  const breadcrumbs =
-    event.entries?.find((e) => e.type === "breadcrumbs")?.data?.values || [];
-  if (breadcrumbs.length) {
-    const last = breadcrumbs.slice(-20);
-    lines.push(`## Breadcrumbs (last ${last.length})\n`);
-    for (const bc of last) {
-      const msg = bc.message || bc.data?.url || bc.data?.to || "";
-      lines.push(`- **${bc.category || "?"}** [${bc.level || "info"}] ${msg}`);
-    }
-    lines.push("");
-  }
-
-  // HTTP Request
-  const httpReq =
-    event.entries?.find((e) => e.type === "request")?.data;
-  if (httpReq) {
-    lines.push("## HTTP Request\n");
-    lines.push(`\`${httpReq.method || "GET"} ${httpReq.url || ""}\``);
-    if (httpReq.headers) {
-      lines.push("\n```");
-      for (const [k, v] of httpReq.headers) {
-        lines.push(`${k}: ${v}`);
-      }
-      lines.push("```");
-    }
-    lines.push("");
-  }
-
-  // Tags
-  if (event.tags?.length) {
-    lines.push("## Tags\n");
-    lines.push("| Key | Value |");
-    lines.push("|-----|-------|");
-    for (const t of event.tags) {
-      lines.push(`| ${t.key} | ${t.value} |`);
-    }
-    lines.push("");
-  }
-
-  // Contexts
-  if (event.contexts) {
-    lines.push("## Contexts\n");
-    for (const [name, ctx] of Object.entries(event.contexts)) {
-      if (name === "trace" || name === "replay" || !ctx || typeof ctx !== "object") continue;
-      const entries = Object.entries(ctx).filter(([k, v]) => k !== "type" && v != null && v !== "");
-      if (!entries.length) continue;
-      const title = name.charAt(0).toUpperCase() + name.slice(1).replace(/_/g, " ");
-      lines.push(`**${title}:**`);
-      for (const [k, v] of entries.slice(0, 15)) {
-        const display = typeof v === "object" ? JSON.stringify(v) : String(v);
-        lines.push(`- ${k}: ${display}`);
-      }
-      lines.push("");
-    }
-  }
-
-  // User
-  if (event.user) {
-    const u = event.user;
-    lines.push("## User\n");
-    lines.push(`${u.username || u.name || u.email || u.id || "unknown"}${u.email ? " (" + u.email + ")" : ""}`);
-    if (u.ip_address) lines.push(`IP: ${u.ip_address}`);
-    lines.push("");
-  }
-
-  return lines.join("\n") || "No event data available.";
-}
-
 // ── MCP Server ──────────────────────────────────────────────────────────────
 
 const server = new Server(
@@ -573,7 +500,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           content: [{ type: "text", text: `No issues found for query: ${query}` }],
         };
       }
-      const formatted = data.map(formatIssue);
+      const formatted = data.map(formatIssueSummary);
       return {
         content: [
           {
@@ -591,7 +518,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         inst,
       );
       return {
-        content: [{ type: "text", text: formatIssue(data) }],
+        content: [{ type: "text", text: JSON.stringify(cleanIssueData(data), null, 2) }],
       };
 
     } else if (name === "sentry_get_latest_event") {
@@ -602,7 +529,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         inst,
       );
       return {
-        content: [{ type: "text", text: formatEvent(data) }],
+        content: [{ type: "text", text: JSON.stringify(cleanEventData(data), null, 2) }],
       };
 
     } else if (name === "sentry_resolve_issue") {
@@ -659,7 +586,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           content: [{ type: "text", text: `No issues found for query: ${args.query}` }],
         };
       }
-      const formatted = data.map(formatIssue);
+      const formatted = data.map(formatIssueSummary);
       return {
         content: [
           {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rui.branco/sentry-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Sentry MCP server for Claude Code - fetch issues, search errors, resolve/ignore issues, get stack traces and breadcrumbs",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "index.js",
-    "setup.js"
+    "setup.js",
+    "README.md"
   ],
   "scripts": {
     "setup": "node setup.js"