# mcp-100/mcp-sentry architecture

> Architecture diagram of the GitHub repository mcp-100/mcp-sentry, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mcp-100/mcp-sentry
- Repository: https://github.com/mcp-100/mcp-sentry

## Overview

##### Project Type and Purpose
- This is an open‑source Model Context Protocol (MCP) adapter/server written in Python.
- It exposes two main “tools” (get_sentry_issue, get_list_issues) that query the Sentry REST API and return structured issue data for LLM clients (e.g., Claude Desktop, Zed).
- It can be run via uvx, pip, or Docker and communicates over stdio using the MCP JSON‑RPC protocol.

##### File Structure Analysis
- Top‐level files:
- Dockerfile – containerized entrypoint
- smithery.yaml – packaging for Smithery registry
- pyproject.toml – Python build/config
- README.md – architecture & usage doc
- images/ – screenshot of MCP inspector
- .github/ – CI workflows & issue templates
- src/mcp_sentry/
- __main__.py – CLI entrypoint (invoked by python -m mcp_sentry)
- server.py – core MCP server implementation & command dispatch
- .cursor/ – Zed editor MCP integration example

##### Key Components and Interactions
a. MCP Client Layer
- Claude Desktop or Zed (or direct CLI) invokes the `mcp-sentry` command.
- Uses uvx, python -m, or docker run to launch the server process.
b. MCP Server Process
- __main__.py parses CLI args (auth token, project slug, org slug).
- server.py initializes the MCP protocol handler and registers two commands.
- Maintains a JSON‑RPC channel over stdio (MCP protocol).
c. External Service
- Sentry.io REST API – accessed via HTTP(S) calls (e.g., using requests library).
- Authenticated by the provided token, scoped to project_slug & organization_slug.
d. Optional Tooling
- MCP inspector (Model Context Protocol Inspector) – attached to the running MCP server for live debugging.

##### Architectural Patterns & Design Principles
- Adapter Pattern: the server adapts Sentry HTTP API to the MCP JSON‑RPC protocol.
- Command Pattern: each “tool” (get_sentry_issue, get_list_issues) is registered as a discrete command handler.
- Separation of Concerns:
- CLI parsing in __main__.py
- Protocol handling & dispatch in server.py
- HTTP interactions isolated within command implementations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["MCP Client\n(Claude Desktop / Zed / CLI)"]:::client

    %% Docker Container Boundary
    subgraph "Docker Container"
        direction TB
        subgraph "mcp-sentry Process"
            direction TB
            Main["CLI Entrypoint\n__main__.py"]:::server
            Handler["MCP Protocol Handler\nserver.py"]:::server
            subgraph "Command Modules"
                direction TB
                GetIssue["get_sentry_issue"]:::server
                ListIssues["get_list_issues"]:::server
            end
        end
    end

    %% External Service
    Sentry["Sentry.io REST API"]:::external

    %% Packaging & Tooling
    subgraph "Packaging & Tooling"
        direction TB
        DockerfileNode["Dockerfile"]:::tooling
        Pyproject["pyproject.toml"]:::tooling
        Smithery["smithery.yaml"]:::tooling
        Readme["README.md"]:::tooling
        Inspector[".cursor/mcp.json"]:::tooling
        PublishCI[".github/workflows/publish.yml"]:::tooling
        ChangelogCI[".github/workflows/update_changelog.yaml"]:::tooling
        BugTemplate[".github/ISSUE_TEMPLATE/bug_report.md"]:::tooling
        FeatureTemplate[".github/ISSUE_TEMPLATE/feature_request.md"]:::tooling
        Images["images"]:::tooling
    end

    %% Connections
    Client -->|"MCP request"| Main
    Main -->|"init JSON-RPC"| Handler
    Handler -->|"dispatch get_sentry_issue"| GetIssue
    Handler -->|"dispatch get_list_issues"| ListIssues
    GetIssue -->|"HTTP GET /api/issues"| Sentry
    Sentry -->|"HTTP response"| GetIssue
    ListIssues -->|"HTTP GET /api/issues"| Sentry
    Sentry -->|"HTTP response"| ListIssues
    GetIssue -->|"MCP response"| Handler
    ListIssues -->|"MCP response"| Handler
    Handler -->|"MCP response"| Client

    %% Click Events
    click Main "https://github.com/mcp-100/mcp-sentry/blob/main/src/mcp_sentry/__main__.py"
    click Handler "https://github.com/mcp-100/mcp-sentry/blob/main/src/mcp_sentry/server.py"
    click DockerfileNode "https://github.com/mcp-100/mcp-sentry/tree/main/Dockerfile"
    click Pyproject "https://github.com/mcp-100/mcp-sentry/blob/main/pyproject.toml"
    click Smithery "https://github.com/mcp-100/mcp-sentry/blob/main/smithery.yaml"
    click Readme "https://github.com/mcp-100/mcp-sentry/blob/main/README.md"
    click Inspector "https://github.com/mcp-100/mcp-sentry/blob/main/.cursor/mcp.json"
    click PublishCI "https://github.com/mcp-100/mcp-sentry/blob/main/.github/workflows/publish.yml"
    click ChangelogCI "https://github.com/mcp-100/mcp-sentry/blob/main/.github/workflows/update_changelog.yaml"
    click BugTemplate "https://github.com/mcp-100/mcp-sentry/blob/main/.github/ISSUE_TEMPLATE/bug_report.md"
    click FeatureTemplate "https://github.com/mcp-100/mcp-sentry/blob/main/.github/ISSUE_TEMPLATE/feature_request.md"
    click Images "https://github.com/mcp-100/mcp-sentry/tree/main/images"

    %% Styles
    classDef client fill:#AEDFF7,stroke:#0366d6
    classDef server fill:#DFF7DC,stroke:#228B22
    classDef external fill:#F7E0C5,stroke:#FF8C00
    classDef tooling fill:#E8E8E8,stroke:#666
```
