# errorwatch

errorwatch keeps an eye on a Sentry account from one small bin. An
agent can confirm who a token belongs to, walk organizations,
projects, and releases, search the issue stream with Sentry's own
query syntax, open an issue and its latest event, change the issue's
status, and read or leave comments on it. It runs from the command
line or as an MCP server for agents.

A Sentry auth token is required. Put it in the `SENTRY_AUTH_TOKEN`
environment variable; it is sent to the API as a Bearer token and
never appears in output. When the variable is missing, every call
fails with an error that names it.

This is a core subset of the Sentry API, not the whole surface: the
hosted documentation search tools, the AI autofix (Seer) tools,
profiling / traces / spans search, DSN and project creation and
other admin operations, and organization statistics beyond issues
are out of scope.

## Install

```bash
npx @reneturcios/errorwatch list-organizations
```

Or run the container image:

```bash
docker run -i -e SENTRY_AUTH_TOKEN ghcr.io/cloudcorprecords/errorwatch
```

The container defaults to the MCP server (see below). Pass CLI
arguments to use it as a CLI instead.

## CLI

```bash
export SENTRY_AUTH_TOKEN="your auth token"

errorwatch whoami
errorwatch list-organizations
errorwatch list-projects --org acme
errorwatch list-releases --org acme --project web
errorwatch search-issues --org acme --query "is:unresolved TypeError"
errorwatch get-issue --issue-id 123456

errorwatch --version
```

Exit codes: `0` on success, `1` when an API call fails (including a
missing `SENTRY_AUTH_TOKEN`), `2` for usage errors.

## MCP server

One bin serves both faces. The `mcp` subcommand starts a stdio MCP
server:

```bash
npx -y @reneturcios/errorwatch mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "errorwatch": {
      "command": "npx",
      "args": ["-y", "@reneturcios/errorwatch", "mcp"],
      "env": { "SENTRY_AUTH_TOKEN": "your auth token" }
    }
  }
}
```

### Tools

| Tool | Input | What it returns |
| --- | --- | --- |
| `whoami` | (none) | The authenticated user or token identity (`GET /auth/`). |
| `list_organizations` | (none) | Organizations the token can access. |
| `list_projects` | `organization_slug` (required) | Projects in the organization. |
| `get_project` | `organization_slug`, `project_slug` (required) | One project's details. |
| `list_releases` | `organization_slug`, `project_slug` (required) | Releases for the project. |
| `search_issues` | `organization_slug` (required), `project_slug`, `query`, `limit` (optional) | Issues matching the Sentry search query; uses the project issues endpoint when a project is given. |
| `get_issue` | `issue_id` (required) | One issue's details. |
| `get_issue_event` | `issue_id` (required), `event_id` (optional, defaults to `latest`) | One event belonging to the issue. |
| `update_issue` | `issue_id` (required), `status`, `resolved_in_next_release`, `assigned_to`, `has_seen`, `is_bookmarked`, `is_subscribed` (optional) | The updated issue; only the fields given are sent. |
| `list_issue_comments` | `issue_id` (required) | Comments (notes) on the issue. |
| `create_issue_comment` | `issue_id`, `text` (required) | The created comment. |

Failed API calls are reported as tool errors carrying the HTTP status
and, when Sentry provides one, its `detail` message.

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx
```

## License

MIT — see `LICENSE`.