@rui.branco/sentry-mcp 1.0.6 → 1.0.7

package/README.md

@@ -1,246 +1,246 @@
-# Sentry MCP Server
-
-A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that brings Sentry error tracking context directly into any MCP-compatible AI client — Claude Code, Codex CLI, Google's Antigravity (Gemini), Cursor, Windsurf, Zed, and others. 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 your AI client
-- **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 |
-| Attachments | List and download event attachments (minidumps, screenshots, logs) to disk |
-| Search | Full Sentry search syntax support |
-| Multi-Instance | Support for multiple Sentry organizations/instances |
-
-## Installation
-
-### Prerequisites
-
-- Node.js 18+
-- An MCP-compatible AI client (see [Step 1](#step-1-register-with-your-mcp-client) below)
-- Sentry account with API access
-
-### Step 1: Register with your MCP client
-
-Pick the snippet for your client. All of them launch the server over stdio.
-
-**Claude Code:**
-
-```bash
-claude mcp add --transport stdio sentry -- npx -y @rui.branco/sentry-mcp
-```
-
-**Codex CLI:** add to `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.sentry]
-command = "npx"
-args = ["-y", "@rui.branco/sentry-mcp"]
-```
-
-**Google Antigravity / Gemini CLI:** add to `~/.gemini/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "sentry": { "command": "npx", "args": ["-y", "@rui.branco/sentry-mcp"] }
-  }
-}
-```
-
-**Cursor, Windsurf, Zed, Cline, Continue, etc.:** add the same `command`/`args` pair to whatever JSON config that client uses for MCP servers (the exact path varies, but the shape is standard across clients).
-
-### 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 your AI client and check its MCP status (e.g. `/mcp` in Claude Code, `mcp` in Codex CLI, or the equivalent panel in your client) 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 register the local entry point with your MCP client (replace the `npx -y @rui.branco/sentry-mcp` command from Step 1 with `node $HOME/.config/sentry-mcp/index.js`). Example for 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_event_attachments` | List attachments (minidumps, screenshots, logs) stored on an event | `eventId` or `issueId`, `instance` |
-| `sentry_download_event_attachment` | Download an event attachment to disk and return the saved path | `attachmentId` (required), `eventId` or `issueId`, `outputPath`, `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 (works with any MCP-compatible AI client)
-- [figma-mcp](https://github.com/rui-branco/figma-mcp) - Figma MCP server (works with any MCP-compatible AI client)
-- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
+# Sentry MCP Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that brings Sentry error tracking context directly into any MCP-compatible AI client — Claude Code, Codex CLI, Google's Antigravity (Gemini), Cursor, Windsurf, Zed, and others. 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 your AI client
+- **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 |
+| Attachments | List and download event attachments (minidumps, screenshots, logs) to disk |
+| Search | Full Sentry search syntax support |
+| Multi-Instance | Support for multiple Sentry organizations/instances |
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+
+- An MCP-compatible AI client (see [Step 1](#step-1-register-with-your-mcp-client) below)
+- Sentry account with API access
+
+### Step 1: Register with your MCP client
+
+Pick the snippet for your client. All of them launch the server over stdio.
+
+**Claude Code:**
+
+```bash
+claude mcp add --transport stdio sentry -- npx -y @rui.branco/sentry-mcp
+```
+
+**Codex CLI:** add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.sentry]
+command = "npx"
+args = ["-y", "@rui.branco/sentry-mcp"]
+```
+
+**Google Antigravity / Gemini CLI:** add to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "sentry": { "command": "npx", "args": ["-y", "@rui.branco/sentry-mcp"] }
+  }
+}
+```
+
+**Cursor, Windsurf, Zed, Cline, Continue, etc.:** add the same `command`/`args` pair to whatever JSON config that client uses for MCP servers (the exact path varies, but the shape is standard across clients).
+
+### 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 your AI client and check its MCP status (e.g. `/mcp` in Claude Code, `mcp` in Codex CLI, or the equivalent panel in your client) 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 register the local entry point with your MCP client (replace the `npx -y @rui.branco/sentry-mcp` command from Step 1 with `node $HOME/.config/sentry-mcp/index.js`). Example for 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_event_attachments` | List attachments (minidumps, screenshots, logs) stored on an event | `eventId` or `issueId`, `instance` |
+| `sentry_download_event_attachment` | Download an event attachment to disk and return the saved path | `attachmentId` (required), `eventId` or `issueId`, `outputPath`, `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 (works with any MCP-compatible AI client)
+- [figma-mcp](https://github.com/rui-branco/figma-mcp) - Figma MCP server (works with any MCP-compatible AI client)
+- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification