@rui.branco/sentry-mcp 1.0.0 → 1.0.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rui.branco/sentry-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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"