Merge origin/main into seer-search-agent-nlq

Resolve conflicts from the searchable tool catalog refactor (#1041):
- Port the Seer translation branch from search-events/handler.ts into
  tools/catalog/search-events.ts and skip it on the no-agent fast path
- Move seer.ts to tools/support/search-events/
- Move the Seer tests into tools/catalog/search-events.test.ts and
  expect unrewritten aggregate sorts, matching main
- Use apiPath for getOrganization and the search-agent endpoints
- Regenerate toolDefinitions.json

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: DominikB2014

.agents/skills/issue-triage/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: mcp-qa
+description: QA MCP tool changes with local CLI and real agent clients. Use when explicitly invoked via /mcp-qa or when asked to QA MCP tool changes end-to-end.
+---
+
+Verify MCP tool behavior end-to-end before committing or creating a PR. Prefer
+agent-callable paths over browser or inspector workflows.
+
+## 1. Quality Gate
+
+```bash
+pnpm run tsc && pnpm run lint && pnpm run test
+```
+
+Fix any failures before proceeding.
+
+## 2. Stdio CLI
+
+This is the primary QA path for tool behavior. Stdio runs the local MCP server
+against prod Sentry without depending on the Cloudflare worker, local `/mcp`
+route, or Cloudflare OAuth configuration.
+When validating code or tool changes, build first because the test client
+launches `packages/mcp-server/dist/index.js`:
+
+```bash
+pnpm -w run build
+```
+
+Check auth first:
+
+```bash
+pnpm --filter @sentry/mcp-server start auth status
+```
+
+If no cache exists, warm the device-code cache:
+
+```bash
+pnpm --filter @sentry/mcp-server start auth login
+```
+
+Device-code auth uses the bundled stdio public client ID, requires no client
+secret, is separate from the Cloudflare OAuth app, and caches the token in
+`~/.sentry/mcp.json`.
+
+First prove startup and auth:
+
+```bash
+pnpm -w run cli --transport stdio --list-tools
+pnpm -w run cli --transport stdio "who am I?"
+```
+
+Then prove the changed behavior with a realistic prod prompt. Choose a prompt
+that requires the new or modified tool path, uses real org/project/resource
+inputs, and asks for enough detail to prove the endpoint response is usable.
+
+```bash
+pnpm -w run cli --transport stdio \
+  "<prompt that exercises the changed MCP behavior against prod data>"
+```
+
+Passing QA means the local CLI prints `Connected to MCP server (stdio)`, uses
+the expected MCP tool path, and returns real prod data that demonstrates the
+behavior. For catalog tools, expect `search_sentry_tools` followed by
+`execute_sentry_tool(name: <changed_tool>)`. For direct tools, expect the tool name in
+the transcript. `--list-tools` alone is not QA.
+
+For mutating catalog-only tools, avoid live prod changes unless there is a
+disposable resource prepared for the test. Add or run a server-level
+`execute_sentry_tool` dispatch test with MSW coverage to prove catalog
+discovery, generated schema exposure, constraint injection, and tool dispatch
+without changing real Sentry data.
+
+For output-format changes, also inspect the raw MCP tool result when possible,
+not only the LLM's final answer. The final answer can add model-specific text
+that is not part of the tool response. Review raw tool output against
+`docs/contributing/tool-responses.md`: it should be user-facing, structured,
+and free of raw API JSON, internal implementation IDs, empty placeholders, and
+unrelated instructions.
+
+
+## 3. Real Agent Clients
+
+Use these when validating Claude Code, Codex, or behavior that only reproduces
+in a real agent client:
+
+```bash
+pnpm -w run build
+```
+
+What this verifies:
+- The CLI is installed and can see the named MCP server
+- The provider can run a connectivity prompt against Sentry MCP
+- The final answer includes the authenticated email from `whoami`
+
+For agent-client-specific behavior, replace the default harness prompt with the
+same realistic prod prompt used for stdio QA. Passing QA requires the same
+changed-tool transcript evidence, not only `whoami`.
+
+as an isolated auth cache. Real clients do not give stdio subprocesses a TTY,
+so warm the cache before running the harness. It also runs the built
+`packages/mcp-server/dist/index.js`, so build first to avoid stale code.
+
+## 4. Cloudflare HTTP Only When Relevant
+
+Run this only when changes touch Cloudflare, HTTP transport, `/mcp`
+routing, OAuth, web UI, or hosted-server compatibility. It is not required for
+ordinary tool handler changes.
+
+Start the dev server in a separate terminal or background process:
+
+```bash
+pnpm dev
+```
+
+Then verify it is reachable:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" http://localhost:5173/
+```
+
+If `pnpm dev` fails because local Cloudflare/Wrangler is not configured, note
+the failure and continue with stdio QA for tool behavior.
+
+```bash
+pnpm -w run cli "who am I?"
+pnpm -w run cli "list all available tools"
+pnpm -w run cli "<same realistic prod prompt used for stdio QA>"
+pnpm -w run cli --mcp-host=http://localhost:5173/mcp/<org> \
+  "<same realistic prod prompt used for stdio QA>"
+pnpm -w run cli --mcp-host=http://localhost:5173/mcp/<org>/<project> \
+  "<same realistic prod prompt used for stdio QA>"
+```
+
+Look for `Connected to MCP server (<resolved MCP URL>)` to confirm HTTP
+transport, plus the same changed-tool transcript evidence required for stdio
+QA. Use scoped `/mcp/<org>` or `/mcp/<org>/<project>` URLs when validating
+routing, OAuth, or resource-scope behavior. Use `--setup repo --server sentry`
+to test the hosted server instead.
+
+## 5. Source Build Stdio Only When Relevant
+
+Use this when specifically checking the built local stdio server rather than
+dev-time source execution:
+
+```bash
+pnpm -w run build
+pnpm --filter @sentry/mcp-server start auth status
+pnpm -w run cli --transport stdio "who am I?"
+```
+
+Look for `Connected to MCP server (stdio)` to confirm stdio transport.