Sentry MCP

# CLAUDE.md ## 🔴 CRITICAL Requirements **MANDATORY before ANY code:** 1. TypeScript: NEVER use `any`. Use `unknown` or proper types 2. Security: NO API keys in logs. NO vulnerabilities 3. Validation: `pnpm run tsc && pnpm run lint && pnpm run test` 4. Tools limit: ≤20 (hard limit: 25) **MANDATORY reads:** - Start here: CLAUDE.md — Contributor doc map - Tools → @docs/adding-tools.mdc - Prompts → @docs/adding-prompts.mdc - Resources → @docs/adding-resources.mdc - Testing → @docs/testing.mdc - PRs → @docs/pr-management.mdc ## 🟡 MANDATORY Workflow ```bash # BEFORE coding (parallel execution) cat docs/[component].mdc & ls -la neighboring-files & git status # AFTER coding (sequential - fail fast) pnpm run tsc && pnpm run lint && pnpm run test # ALL must pass ``` ## Repository Map ``` sentry-mcp/ ├── packages/ │ ├── mcp-server/ # Main MCP server │ │ ├── src/ │ │ │ ├── tools/ # 19 tool modules │ │ │ ├── prompts.ts # MCP prompts │ │ │ ├── resources.ts # MCP resources │ │ │ ├── server.ts # MCP protocol │ │ │ ├── api-client/ # Sentry API │ │ │ └── internal/ # Shared utils │ │ └── scripts/ # Build scripts │ ├── mcp-cloudflare/ # Web app │ ├── mcp-server-evals/ # AI tests │ ├── mcp-server-mocks/ # MSW mocks │ └── mcp-test-client/ # Test client └── docs/ # All docs ``` ## AI-Powered Search Tools **search_events** (`packages/mcp-server/src/tools/search-events/`): - Natural language → DiscoverQL queries - GPT-4o agent with structured outputs - Tools: `datasetAttributes`, `otelSemantics`, `whoami` - Requires: `OPENAI_API_KEY` **search_issues** (`packages/mcp-server/src/tools/search-issues/`): - Natural language → issue search syntax - GPT-4o agent with structured outputs - Tools: `issueFields`, `whoami` - Requires: `OPENAI_API_KEY` ## 🟢 Key Commands ```bash # Development pnpm run dev # Start development pnpm run build # Build all packages pnpm run generate-otel-namespaces # Update OpenTelemetry docs # Quality checks (combine for speed) pnpm run tsc && pnpm run lint && pnpm run test # Common workflows pnpm run build && pnpm run test # Before PR grep -r "TODO\|FIXME" src/ # Find tech debt ``` ## Quick Reference **Defaults:** - Organization: `sentry` - Project: `mcp-server` - Transport: stdio - Auth: access tokens (NOT OAuth) **Doc Index:** - Core Guidelines - @docs/coding-guidelines.mdc — Code standards and patterns - @docs/common-patterns.mdc — Reusable patterns and conventions - @docs/quality-checks.mdc — Required checks before changes - @docs/error-handling.mdc — Error handling patterns - API and Tools - @docs/adding-tools.mdc — Add new MCP tools - @docs/adding-prompts.mdc — Add prompts - @docs/adding-resources.mdc — Add resources - @docs/api-patterns.mdc — Sentry API usage - @docs/search-events-api-patterns.md — search_events specifics - Infrastructure and Operations - @docs/architecture.mdc — System design - @docs/deployment.mdc — Deploy (Cloudflare) - @docs/monitoring.mdc — Monitoring/telemetry - @docs/security.mdc — Security and authentication - @docs/cursor.mdc — Cursor IDE integration - LLM-Specific - @docs/llms/documentation-style-guide.mdc — How to write LLM docs - @docs/llms/document-scopes.mdc — Doc scopes and purposes ## Rules 1. **Code**: Follow existing patterns. Check adjacent files 2. **Errors**: Try/catch all async. Log: `console.error('[ERROR]', error.message, error.stack)` - Sentry API 429: Retry with exponential backoff - Sentry API 401/403: Check token permissions 3. **Docs**: Update when changing functionality 4. **PR**: Follow `docs/pr-management.mdc` for commit/PR guidelines (includes AI attribution) 5. **Tasks**: Use TodoWrite for 3+ steps. Batch tool calls when possible --- *Optimized for Codex CLI (OpenAI) and Claude Code*