发布

RSS 订阅源

2.0.17-5167 2d06f73555

比较
[OPIK-6210] [DOCS] feat: set up Sentry MCP (#6505)

frostbyte_neo 发布于 2026-04-28 10:42:43 +00:00
- [OPIK-6210] [INFRA] feat: add Sentry MCP setup
Wire the official Sentry stdio MCP server into .agents/mcp.json so it
flows through make claude into the generated .mcp.json. Auth token is
loaded from .env.local via the existing envFile pattern, keeping it out
of the repo. Adds a developer setup guide alongside the Slack one.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- fix(mcp): handle env files with no trailing newline
The env-file parser used while read -r line which silently drops the
final line when the file lacks a trailing newline — quietly skipping
whichever variable happens to be last. Added the standard || [[ -n "$line" ]]
guard so the last line is still processed.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- docs(sentry-mcp): warn off NL-backed tools, add REST-API helper script
Sentry's NL-backed search tools (search_issues, search_events,
search_issue_events, analyze_issue_with_seer) all route through Sentry's
OpenAI account, which is regularly rate-limited and breaks workflows.
Document the working alternatives (direct MCP tools + Sentry REST API)
and add scripts/analyze_sentry_issue.py as a reference for paginating
events from an issue without LLMs in the loop.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- config(sentry-mcp): switch default to OAuth/remote for zero-setup onboarding
Other developers should not have to create a Sentry user-auth token, copy
it into .env.local, and re-run make claude just to query Sentry from their
agent. The official Sentry remote MCP at https://mcp.sentry.dev/mcp uses
OAuth and is reachable via mcp-remote (the same pattern Notion already
uses in this repo), so a fresh checkout works after a single make claude
- client restart + browser sign-in on first call. The token-based stdio
  path is preserved as an "advanced / scripting" alternative for headless
  environments and for the REST helper script.
Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- Revert "config(sentry-mcp): switch default to OAuth/remote for zero-setup onboarding"
Stick with the .env.local pattern (consistent with GitHub, Jira, Slack
in this repo) and instead make the token discoverable on a fresh checkout
by adding SENTRY_ACCESS_TOKEN to .env.template with the token-creation
URL and required scopes. Doc is rewritten to lead with the .env.local
path; OAuth/mcp-remote is kept as an "alternative" section for folks
who prefer not to manage a token.

This reverts the .agents/mcp.json change in c27463440 and supersedes its
doc rewrite.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- refactor(sentry-mcp): replace ad-hoc analyze script with /analyze-sentry-issue slash command
Drop scripts/analyze_sentry_issue.py and add it as a proper slash command
under .agents/commands/comet/ so it's discoverable, documented, and
synced into .claude/commands/ alongside the other comet:* commands rather
than living as an undocumented utility under scripts/. Updates the Sentry
MCP doc to point at the slash command.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- docs(analyze-sentry-issue): expand into a guided investigation+fix runbook
Restructure /comet:analyze-sentry-issue from a fetch+aggregate+report
template into an 8-phase runbook that drives engineers from raw events
to a concrete fix proposal: locate the emitting code, diagnose the
observability gap and root cause separately, propose fixes in two
layers (observability first, behavior second), and tee up local repro
- ticket/PR scaffolding. Bakes in priors observed during OPIK-6210
  triage (missing exc_info pattern, generic-template fingerprint
  collisions, supervisor log shapes) so future invocations start from
  known patterns instead of rediscovering them each time.
Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- docs(analyze-sentry-issue): generalize across Sentry projects, demote NL-tool framing
- Don't hardcode Python idioms (LOGGER, exc_info=) into the universal
  workflow. Phase 4 now lists Sentry projects with their language and
  codebase, and Phase 5 expresses each observability check in the
  language of the project under triage (Python / Java / TypeScript).
- Drop the "this command exists because NL tools are unreliable" Note
  — present this as the canonical analysis path, not a workaround.
- Move Python-SDK-specific priors into a dedicated section, clearly
  scoped to opik-python-sdk / opik-optimizer projects, so engineers
  triaging Java backend or TS frontend issues don't get misled.
Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- docs(analyze-sentry-issue): tighten default fetch cap to ~3 pages
Pulling up to 1,200 events on every invocation was sized to one specific
case (OPIK-PYTHON-SDK-H35); distinct-message and tag distributions
converge well before that. Drop the default to ~3 pages (300 events) and
spell out the conditions under which bumping the cap is actually
warranted, so the runbook stays cheap by default.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- docs(analyze-sentry-issue): drop internal Sentry org / project / issue identifiers
This file ships in a public repo. Scrub the Sentry-project-slug → repo
mapping table, the comet-or org slug in the example URL, and the
specific Sentry issue short ID example. Replace with generic
descriptions ("backend service", "frontend app") and placeholders
(, -XYZ) that convey the same guidance without exposing
internal infrastructure naming.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- docs(analyze-sentry-issue): drop region-host parameter
Hardcode the SaaS region (us.sentry.io). Self-hosted Sentry isn't a
realistic case for this command, and an optional region arg adds
surface area without value.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- docs(analyze-sentry-issue): clarify Sentry event payload shape
Sentry's /api/0/issues//events/ returns tags as an array of
{key, value} objects, not a {key: value} map; the runbook now spells
that out and tells the engineer to normalize before aggregating. Also
calls out that user.id and release are nullable so per-event
capture handles missing values explicitly.

Addresses Baz reviewer comment on PR #6505.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- docs(sentry-mcp): address review comments from PR #6505
- Fix broken relative link in SENTRY_MCP_SETUP.md (resolved from
  .agents/docs/, not repo root, so it now points to
  ../commands/comet/analyze-sentry-issue.md).
- Add find_teams to the Read-tools list in SENTRY_MCP_SETUP.md so the
  list matches the "non-LLM tools that always work" line below it.
- Add an explicit ⚠️ callout in the analyze-sentry-issue runbook noting
  that the hardcoded us.sentry.io is region-specific to Comet's Sentry
  org; EU / self-hosted users need to swap in $SENTRY_HOST to avoid
  silent misrouting. Keeps the runbook simple (no region parameter) but
  prevents the silent-failure mode flagged in review.
Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

Co-authored-by: Claude Opus 4.7 (1M context) noreply@anthropic.com
下载附件
- 源代码 (ZIP)
- 源代码 (TAR.GZ)

0 发布 8,340 Git 标签

[OPIK-6210] [DOCS] feat: set up Sentry MCP (#6505)